@adia-ai/web-components 0.4.5 → 0.4.6

package/core/element.d.ts

@@ -0,0 +1,174 @@
+/**
+ * UIElement — light-DOM reactive base class.
+ *
+ * Every primitive in `@adia-ai/web-components` extends this (or `UIFormElement`
+ * for form-bearing primitives). Provides signal-backed property reactivity,
+ * lifecycle hooks (`connected`/`render`/`updated`/`disconnected`), and
+ * tagged-template rendering.
+ *
+ * @see ../USAGE.md#lifecycle
+ * @see ../USAGE.md#property-reactivity-signal-backed
+ */
+
+import type { ReadonlySignal, Signal } from './signals.js';
+import type { TemplateResult } from './template.js';
+
+/** Property declaration in a component's `static properties = { … }` map. */
+export interface PropertyConfig<T = unknown> {
+  /** Coercion target — `Boolean`, `Number`, `String`, or custom. */
+  type?: BooleanConstructor | NumberConstructor | StringConstructor | (new (...args: unknown[]) => T);
+  /** Initial value. Defaults to `undefined`. */
+  default?: T;
+  /** Mirror property changes to an HTML attribute. */
+  reflect?: boolean;
+  /** Custom attribute name. Default: kebab-case of property key. */
+  attribute?: string;
+}
+
+/** Map of property name → config. The shape consumed by `static properties`. */
+export type PropertiesMap = Record<string, PropertyConfig>;
+
+/** Trait name + config tuple passed via `static traits`. */
+export type TraitDeclaration = string | { name: string; [opt: string]: unknown };
+
+/** Map of slot name → markup string. Consumed by `static parts`. */
+export type PartsMap = Record<string, string>;
+
+/**
+ * Light-DOM reactive base class. Subclass to author a primitive.
+ *
+ * @example
+ *   class MyWidget extends UIElement {
+ *     static properties = { label: { type: String, default: '' } };
+ *     render() { this.textContent = this.label; }
+ *   }
+ *   customElements.define('my-widget', MyWidget);
+ */
+export class UIElement extends HTMLElement {
+  /**
+   * Property declarations — signal-backed getters/setters wired by the
+   * constructor. Override in subclasses.
+   */
+  static properties: PropertiesMap;
+
+  /** Trait declarations — applied during `connectedCallback`. */
+  static traits: readonly TraitDeclaration[];
+
+  /** Slot blueprints used by `ensure(slotName)`. */
+  static parts?: PartsMap;
+
+  /** Stylesheets to adopt onto the document on first render. */
+  static styles?: CSSStyleSheet | readonly CSSStyleSheet[];
+
+  /**
+   * Pure-function template — called inside the host's render effect. Reading
+   * `this.foo` inside subscribes the effect to the `foo` signal.
+   *
+   * Override OR return `null` and update DOM imperatively in `render()`.
+   */
+  static template: <T extends UIElement>(host: T) => TemplateResult | null;
+
+  /** Observed attribute names — derived from `static properties`. */
+  static readonly observedAttributes: readonly string[];
+
+  /** ElementInternals — attached in the constructor; carries form state etc. */
+  readonly internals: ElementInternals;
+
+  /**
+   * Setup hook — called after construction + insertion, before the first render
+   * effect installs. Set up listeners on document / external targets here.
+   *
+   * Override in subclasses; default is a no-op. Runs inside `untracked()` so
+   * reads don't leak subscriptions to outer effects.
+   */
+  connected(): void;
+
+  /**
+   * Imperative update hook — called every time any property signal mutates.
+   * Reading `this.foo` here subscribes the effect to `foo`.
+   *
+   * Override in subclasses; default is a no-op.
+   */
+  render(): void;
+
+  /**
+   * Post-render hook — called after `render()`. `changed` is a map of every
+   * property that mutated this tick, keyed by property name with old value.
+   *
+   * Override in subclasses; default is a no-op.
+   */
+  updated(changed: ReadonlyMap<string, unknown>): void;
+
+  /**
+   * Teardown hook — called on element removal. Clean up listeners + intervals
+   * + observers here.
+   *
+   * Override in subclasses; default is a no-op.
+   */
+  disconnected(): void;
+
+  /**
+   * Error hook — called when the host's render effect throws. Receives the
+   * thrown value. Default behavior: rethrow.
+   */
+  onError?(err: unknown): void;
+
+  // ── Standard custom-element callbacks (overridable but rarely needed) ──
+
+  connectedCallback(): void;
+  disconnectedCallback(): void;
+  attributeChangedCallback(name: string, oldValue: string | null, newValue: string | null): void;
+
+  // ── Convenience helpers ──
+
+  /**
+   * Create a local signal bound to this element's lifetime. Disposed on
+   * `disconnectedCallback`.
+   */
+  signal<T>(initial: T): Signal<T>;
+
+  /**
+   * Get or stamp a slot child by name. If a `[slot="name"]` child exists,
+   * returns it; otherwise stamps the blueprint from `static parts[name]`,
+   * appends it, and returns the new node.
+   */
+  ensure(slotName: string): Element | null;
+
+  /** Remove the `[slot="name"]` child if present. */
+  drop(slotName: string): void;
+
+  /**
+   * Keyed-reconcile a parent's children against `items`. Used internally by
+   * the `repeat` directive; consumers rarely call directly.
+   */
+  reconcile<T>(
+    parent: Element,
+    items: readonly T[],
+    keyFn: (item: T, i: number) => string | number,
+    stampFn: (item: T, i: number, existing: Element | null) => Element,
+  ): void;
+
+  // ── Controller pattern (optional advanced) ──
+
+  /** Set the controller; calls connect/disconnect on it through lifecycle. */
+  set controller(c: UIController | null);
+  get controller(): UIController | null;
+
+  /**
+   * Factory — create an instance of this element with the given props applied.
+   * Tag must already be registered.
+   */
+  static create<T extends typeof UIElement>(
+    this: T,
+    props?: Partial<InstanceType<T>>,
+  ): InstanceType<T>;
+}
+
+/**
+ * Controller — optional pluggable behavior attached to a UIElement via
+ * `element.controller = …`. Lifecycle mirrors the host.
+ */
+export interface UIController {
+  connect?(host: UIElement): void;
+  disconnect?(host: UIElement): void;
+}

package/core/form.d.ts

@@ -0,0 +1,108 @@
+/**
+ * UIFormElement — base class for form-bearing primitives.
+ *
+ * Extends UIElement with `ElementInternals` form participation, value sync,
+ * constraint validation, and the standard validity surface. 15 primitives
+ * extend this: input, select, slider, switch, segmented, check, radio,
+ * textarea, range, color-picker, rating, option-card, search, otp-input, code.
+ *
+ * @see ../USAGE.md#form-participation
+ */
+
+import { UIElement, type PropertiesMap } from './element.js';
+
+/**
+ * Form-participating reactive base class. Subclass to author a form-bearing
+ * primitive. `static formAssociated = true` is already set; consumer subclasses
+ * shouldn't override it.
+ *
+ * @example
+ *   class MyField extends UIFormElement {
+ *     static properties = {
+ *       ...UIFormElement.properties,
+ *       maxItems: { type: Number, default: 10 },
+ *     };
+ *   }
+ */
+export class UIFormElement extends UIElement {
+  /** Marks the element as form-associated. Do not override. */
+  static readonly formAssociated: true;
+
+  /**
+   * Base property set inherited by every form-bearing primitive. Subclasses
+   * spread this into their own `static properties`.
+   */
+  static properties: PropertiesMap & {
+    name: { type: StringConstructor; default: ''; reflect: true };
+    value: { type: StringConstructor; default: ''; reflect: true };
+    disabled: { type: BooleanConstructor; default: false; reflect: true };
+    required: { type: BooleanConstructor; default: false; reflect: true };
+    readonly: { type: BooleanConstructor; default: false; reflect: true };
+    error: { type: StringConstructor; default: ''; reflect: true };
+    hint: { type: StringConstructor; default: ''; reflect: true };
+    pattern: { type: StringConstructor; default: ''; reflect: true };
+    minlength: { type: NumberConstructor; default: null; reflect: true };
+    maxlength: { type: NumberConstructor; default: null; reflect: true };
+  };
+
+  // ── Inherited UIFormElement properties (typed) ──
+  /** Form field name — submitted as key in FormData. */
+  name: string;
+  /** Submitted value. Subclasses may narrow the type (e.g. `slider-ui` to `number`). */
+  value: string;
+  /** Disabled state — reflected, blocks interaction. */
+  disabled: boolean;
+  /** Required state — checked against value emptiness on validation. */
+  required: boolean;
+  /** Read-only state — reflected, blocks user input but submits value. */
+  readonly: boolean;
+  /** Current error message — surfaces via `:invalid` + reportValidity. */
+  error: string;
+  /** Hint text — usually rendered below the control. */
+  hint: string;
+  /** Regex pattern — value must match if set. */
+  pattern: string;
+  /** Minimum length — `null` to disable. */
+  minlength: number | null;
+  /** Maximum length — `null` to disable. */
+  maxlength: number | null;
+
+  // ── ElementInternals accessors ──
+
+  /** The form this element is associated with, or `null` if not in a form. */
+  readonly form: HTMLFormElement | null;
+  /** Labels associated with this element via `for` / wrapping. */
+  readonly labels: NodeList;
+  /** Current validity state. */
+  readonly validity: ValidityState;
+  /** Localized validation message. */
+  readonly validationMessage: string;
+  /** Whether the element will be validated when its form is submitted. */
+  readonly willValidate: boolean;
+
+  /** Returns true if the element passes all constraint validations. */
+  checkValidity(): boolean;
+
+  /** Like `checkValidity()` but also surfaces error UI if invalid. */
+  reportValidity(): boolean;
+
+  // ── Manual validation control ──
+
+  /**
+   * Run constraint validation against the current value. Returns true if valid.
+   * Sets `error` + surfaces UI if invalid.
+   */
+  validate(): boolean;
+
+  /** Mark the element invalid with a custom error message. */
+  setInvalid(message: string): void;
+
+  /** Clear the invalid state. */
+  setValid(): void;
+
+  /**
+   * Update the form-submission value + run constraint checks. Called internally
+   * on input/change; consumers rarely call directly.
+   */
+  syncValue(value: string): void;
+}

package/core/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Core types — re-exports the public API surface from `core/`.
+ *
+ * @see ../USAGE.md
+ */
+
+export * from './signals.js';
+export * from './template.js';
+export * from './element.js';
+export * from './form.js';
+export * from './register.js';

package/core/index.js

@@ -16,6 +16,7 @@ export * from './element.js';
 export * from './form.js';
 export * from './signals.js';
 export * from './template.js';
+export * from './register.js';
 export * from './controller.js';
 export * from './provider.js';
 export * from './anchor.js';

package/core/register.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Custom-element registration helpers.
+ *
+ * @see ../USAGE.md#registration--auto-vs-explicit
+ */
+
+/**
+ * Register a custom element. Same semantics as `customElements.define` — throws
+ * if `tagName` is already registered.
+ */
+export function register(tagName: string, ctor: CustomElementConstructor): void;
+
+/**
+ * Register a custom element only if the tag isn't already taken. Useful when
+ * multiple sources may try to register the same tag (e.g. when a host page
+ * imports the AdiaUI bundle AND a downstream consumer imports per-component
+ * subpaths). Without this, the second `customElements.define` throws.
+ *
+ * Returns `true` if registration happened, `false` if the tag was already
+ * registered.
+ */
+export function defineIfFree(tagName: string, ctor: CustomElementConstructor): boolean;
+
+/** Returns true if the given tag is already registered. */
+export function isRegistered(tagName: string): boolean;

package/core/register.js

@@ -0,0 +1,58 @@
+/**
+ * Custom-element registration helpers.
+ *
+ * The package's components auto-register their tags at the bottom of each
+ * component `.js` file (the de-facto web-components convention). These
+ * helpers give consumers controllable alternatives:
+ *
+ * - `register(tagName, ctor)` — direct alias for `customElements.define`.
+ *   No magic; provided so consumers can write the registration call without
+ *   importing the constructor globally.
+ *
+ * - `defineIfFree(tagName, ctor)` — no-op if the tag is already registered.
+ *   Use this when multiple packages may try to register the same tag (e.g.
+ *   when a host page imports the AdiaUI bundle AND a downstream consumer
+ *   also imports per-component subpaths). Without this, the second
+ *   `customElements.define` throws `NotSupportedError`.
+ *
+ * @see ../USAGE.md#registration--auto-vs-explicit
+ */
+
+/**
+ * Register a custom element. Same semantics as `customElements.define`;
+ * throws if `tagName` is already registered.
+ *
+ * @param {string} tagName  The kebab-case tag name (e.g. `'my-slider'`)
+ * @param {CustomElementConstructor} ctor  The class to register
+ */
+export function register(tagName, ctor) {
+  customElements.define(tagName, ctor);
+}
+
+/**
+ * Register a custom element only if the tag isn't already taken. Useful for
+ * conflict-safe registration when multiple sources may want to register the
+ * same tag.
+ *
+ * Returns `true` if registration happened, `false` if the tag was already
+ * registered.
+ *
+ * @param {string} tagName  The kebab-case tag name
+ * @param {CustomElementConstructor} ctor  The class to register
+ * @returns {boolean}
+ */
+export function defineIfFree(tagName, ctor) {
+  if (customElements.get(tagName)) return false;
+  customElements.define(tagName, ctor);
+  return true;
+}
+
+/**
+ * Check whether a tag is already registered.
+ *
+ * @param {string} tagName
+ * @returns {boolean}
+ */
+export function isRegistered(tagName) {
+  return Boolean(customElements.get(tagName));
+}

package/core/signals.d.ts

@@ -0,0 +1,94 @@
+/**
+ * Reactive signals — the primitive that UIElement's property system is built on.
+ *
+ * @see ../USAGE.md#property-reactivity-signal-backed
+ */
+
+/** Read-only signal. Reading `.value` inside an `effect()` subscribes that effect. */
+export interface ReadonlySignal<T> {
+  readonly value: T;
+  /** Read without creating a subscription. */
+  peek(): T;
+}
+
+/** Mutable signal. Writing `.value` notifies all subscribers. */
+export interface Signal<T> extends ReadonlySignal<T> {
+  value: T;
+}
+
+/** Computed signal — derived from other signals; recomputes lazily. */
+export type ComputedSignal<T> = ReadonlySignal<T>;
+
+/** Effect options. */
+export interface EffectOptions {
+  /** Host tag name for diagnostic logging. */
+  host?: string;
+  /** Called when the effect body throws. Receives the error. */
+  onError?: ((err: unknown) => void) | null;
+}
+
+/** Cleanup function returned by `effect()`. Call to dispose the subscription. */
+export type EffectDisposer = () => void;
+
+/**
+ * Create a mutable signal. Reading `.value` inside an `effect()` subscribes it.
+ *
+ * @example
+ *   const count = signal(0);
+ *   effect(() => console.log(count.value));  // subscribes
+ *   count.value = 1;                          // logs 1
+ */
+export function signal<T>(initial: T): Signal<T>;
+export function signal<T = undefined>(): Signal<T | undefined>;
+
+/**
+ * Create a computed signal — re-derives when any dependency changes. Lazy:
+ * recomputes only when read.
+ *
+ * @example
+ *   const a = signal(2);
+ *   const b = signal(3);
+ *   const sum = computed(() => a.value + b.value);
+ *   sum.value;  // 5
+ */
+export function computed<T>(fn: () => T): ComputedSignal<T>;
+
+/**
+ * Run `fn` inside a reactive context. Re-runs when any signal read during the
+ * last run changes. Returns a disposer.
+ *
+ * @example
+ *   const dispose = effect(() => console.log(count.value));
+ *   // later
+ *   dispose();
+ */
+export function effect(fn: () => void, opts?: EffectOptions): EffectDisposer;
+
+/**
+ * Batch multiple signal mutations into one effect re-run. Useful for atomic
+ * updates that touch several signals.
+ *
+ * @example
+ *   batch(() => {
+ *     a.value = 1;
+ *     b.value = 2;
+ *   });  // effect runs once after both mutations
+ */
+export function batch(fn: () => void): void;
+
+/**
+ * Read signals inside `fn` without subscribing the surrounding effect.
+ *
+ * @example
+ *   effect(() => {
+ *     const snapshot = untracked(() => other.value);  // does NOT subscribe
+ *     console.log(active.value, snapshot);            // only `active` subscribes
+ *   });
+ */
+export function untracked<T>(fn: () => T): T;
+
+/** Type guard — true if `v` looks like a signal. */
+export function isSignal(v: unknown): v is ReadonlySignal<unknown>;
+
+/** Brand symbol — identifies signal objects. Exported for advanced introspection. */
+export const SIGNAL: unique symbol;

package/core/template.d.ts

@@ -0,0 +1,70 @@
+/**
+ * Lightweight tagged-template rendering — `html`, `css`, `repeat`, `stamp`.
+ *
+ * Detects signal/function bound values and wraps them in `effect()` so the
+ * binding re-fires on dependency change. Static values bypass — see USAGE.md
+ * § property-binding-patterns for the eager-evaluation trap.
+ */
+
+import type { ReadonlySignal } from './signals.js';
+
+/** Result of an `html\`…\`` call — pass to `stamp()` to mount in a container. */
+export interface TemplateResult {
+  readonly strings: TemplateStringsArray;
+  readonly values: readonly unknown[];
+}
+
+/**
+ * Tagged template for HTML — returns a `TemplateResult` that `stamp()` mounts.
+ *
+ * - `attr=${value}` — attribute binding (string-coerced, removed if null/false)
+ * - `.prop=${value}` — JS property binding (signal/function = reactive)
+ * - `@event=${handler}` — event listener binding
+ *
+ * @example
+ *   html`<button-ui .disabled=${isLoading} @click=${onSave}>Save</button-ui>`
+ */
+export function html(strings: TemplateStringsArray, ...values: unknown[]): TemplateResult;
+
+/**
+ * Tagged template for CSS — returns a `CSSStyleSheet`. Use as `static styles =
+ * css\`…\`` on a component or feed to `document.adoptedStyleSheets`.
+ *
+ * @example
+ *   const sheet = css`button { color: red; }`;
+ *   document.adoptedStyleSheets = [...document.adoptedStyleSheets, sheet];
+ */
+export function css(strings: TemplateStringsArray, ...values: unknown[]): CSSStyleSheet;
+
+/**
+ * Mount or update a `TemplateResult` inside a container. Re-running with a
+ * different result with the same `strings` reuses the template; different
+ * `strings` re-mounts.
+ */
+export function stamp(result: TemplateResult, container: Element): void;
+
+/**
+ * Internal — disposes effects attached to template parts. You won't call this
+ * directly unless implementing a custom directive.
+ */
+export function disposeParts(parts: readonly unknown[]): void;
+
+/**
+ * Keyed list directive — minimal-ops re-render of dynamic lists. Reuses DOM
+ * elements across re-renders by `key`.
+ *
+ * @example
+ *   html`<ul>${repeat(
+ *     items.value,
+ *     (item) => item.id,
+ *     (item) => html`<li>${item.name}</li>`
+ *   )}</ul>`
+ */
+export function repeat<T>(
+  items: readonly T[],
+  keyFn: (item: T, index: number) => string | number,
+  tplFn: (item: T, index: number) => TemplateResult,
+): unknown;
+
+/** Internal symbol — key-map storage on container nodes for `repeat()`. */
+export const KEY_MAP: unique symbol;