aidd-lit

Lit element authoring

Lit elements live in the components/ layer per structure. Consume Observe and void actions from plugins per service.

---

Extending DatabaseElement

Binding elements extend DatabaseElement<typeof myPlugin> — either directly or via an intermediate base class. The required plugin must be specified in the generic.

This ensures the plugin's services are extended onto the main database before the element renders, so this.service exposes the correct Observe APIs and actions.

// Direct
export class HelloWorldElement extends DatabaseElement<typeof helloWorldPlugin> {
  get plugin() { return helloWorldPlugin; }
}

// Indirect — base extends DatabaseElement, leaf specifies plugin
export class LayoutElement<T extends MyApplicationPlugin = MyApplicationPlugin> extends CoreApplicationElement<T> { }
export class ToolbarElement extends LayoutElement<typeof toolbarPlugin> { }

---

Binding element vs presentation

BindingElement {
  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: "TemplateResult"
  constraint: "Keep reactive logic in binding element; presentation stays pure"
}

---

Testing

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

---

useObservableValues

Most binding elements use a single useObservableValues call. Collect all observed values in one object.

Observe only what you need — the minimal values required for rendering. For values that may resolve slowly, wrap with Observe.withDefault so you can render a skeleton (or placeholder) immediately while waiting. See observe.