paralleldrive/aidd/aidd-react

Constraints {
  Binding components must call useDatabase to obtain the main service context
  Do not access any other React context
  All other services and state reachable from database (db.services, db.observe, db.transactions)
  Single context is sufficient
}

BindingComponent {
  injects: "observed values via useObservableValues"
  triggers: "re-render when those values change"
  binds: "action callbacks to the presentation"
}
 
Presentation {
  type: "pure function (no hooks)"
  receives: "data and action callbacks as props"
  returns: "JSX"
  constraint: "Keep reactive logic in binding component; presentation stays pure"
}

// Parent: passes entity so child knows which record to bind to
{values.sprites.map((entity) => (
  <Sprite key={entity} entity={entity} />
))}
// Child: uses entity prop to observe the right record
function Sprite({ entity }: { entity: Entity }) {
  const db = useDatabase();
  const values = useObservableValues(
    () => ({ sprite: db.observe.entity(entity, db.archetypes.Sprite) }),
    [entity],
  );
  // ...
}

function Counter() {
  const db = useDatabase(counterPlugin);
  const values = useObservableValues(() => ({
    count: db.observe.resources.count,
  }));
  if (!values) return null;
  return presentation.render({ ...values, increment: db.transactions.increment });
}

Constraints {
  Presentation files ONLY export render (and localization bundles where appropriate)
  Nothing else
  For render args type externally (storybook, testing): use Parameters<typeof render>[0]
}

PresentationCallbacks {
  are: "action calls, not events"
  semantics: "verbNoun — not onClick/onToggle/onSignOut style"
  bindingComponent: "passes action callbacks (e.g. toggleView, signOut) as props"
  presentation: "invokes them when user intent occurs"
  passFunctionReferencesDirectly: true
  reason: "All actions are pure functions with no this binding"
}

// Binding component: pass the function reference (no arrow wrapper)
increment: db.transactions.increment
// When the action needs arguments, wrap to supply them
toggleSprite: () => db.transactions.toggleSpriteActive({ entity })
// Presentation: receives and invokes when user acts
<button onClick={props.increment}>Increment</button>

Testing {
  presentation: "add *-presentation.test.tsx when appropriate; unit test the presentation"
  bindingComponent: "not unit tested — no business logic; uses Database service (already unit tested)"
}

fn whenCreatingOrModifyingReactComponent() {
  Constraints {
    Call useDatabase for main service context; do not use any other React context
    Split into binding component (reactive) and presentation (pure)
    Use single useObservableValues in binding component; Observe only minimal values; use Observe.withDefault for slow-resolving values
    Pass observed values and action callbacks to presentation; pass function references directly when signature matches; wrap only when supplying arguments
    Pass entity (or identifying value) from parent only when child must bind to specific database record
    Keep presentation pure — no hooks
    Presentation exports only render (and localization bundles where appropriate)
    Add *-presentation.test.tsx for presentation when appropriate; do not unit test binding components
    Never include business logic within binding components — move into computed values or action handlers
    Good binding components should be extremely small
  }
}