@adia-ai/web-components 0.4.4 → 0.4.6

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;

package/index.d.ts

@@ -0,0 +1,161 @@
+/**
+ * `@adia-ai/web-components` — public TypeScript declarations.
+ *
+ * Re-exports the core types + augments `HTMLElementTagNameMap` so
+ * `document.querySelector('slider-ui')` returns `UISlider` (typed),
+ * not `Element`.
+ *
+ * @see ./USAGE.md
+ */
+
+// ── Core utilities ──────────────────────────────────────────────────
+export * from './core/index.js';
+
+// ── Form-bearing primitives (typed) ─────────────────────────────────
+export type {
+  UIInput,
+  UIInputType,
+  InputChangeEvent,
+  InputInputEvent,
+  InputChangeEventDetail,
+} from './components/input/input.js';
+
+export type {
+  UISelect,
+  SelectOption,
+  SelectChangeEvent,
+  SelectActionEvent,
+  SelectChangeEventDetail,
+  SelectActionEventDetail,
+} from './components/select/select.js';
+
+export type {
+  UISlider,
+  SliderChangeEvent,
+  SliderInputEvent,
+  SliderChangeEventDetail,
+} from './components/slider/slider.js';
+
+export type {
+  UIRange,
+  RangeChangeEvent,
+  RangeInputEvent,
+  RangeChangeEventDetail,
+} from './components/range/range.js';
+
+export type {
+  UITextarea,
+  TextareaChangeEvent,
+  TextareaInputEvent,
+  TextareaChangeEventDetail,
+} from './components/textarea/textarea.js';
+
+export type {
+  UISwitch,
+  SwitchChangeEvent,
+  SwitchChangeEventDetail,
+} from './components/switch/switch.js';
+
+export type {
+  UICheck,
+  CheckChangeEvent,
+  CheckChangeEventDetail,
+} from './components/check/check.js';
+
+export type {
+  UIRadio,
+  RadioChangeEvent,
+  RadioChangeEventDetail,
+} from './components/radio/radio.js';
+
+export type {
+  UISegmented,
+  SegmentedChangeEvent,
+  SegmentedChangeEventDetail,
+} from './components/segmented/segmented.js';
+
+export type {
+  UISearch,
+  SearchInputEvent,
+  SearchEvent,
+  SearchInputEventDetail,
+  SearchEventDetail,
+} from './components/search/search.js';
+
+export type {
+  UIOtpInput,
+  OtpInputEvent,
+  OtpInputEventDetail,
+} from './components/otp-input/otp-input.js';
+
+export type {
+  UIOptionCard,
+  OptionCardChangeEvent,
+  OptionCardChangeEventDetail,
+} from './components/option-card/option-card.js';
+
+export type {
+  UIColorPicker,
+  ColorFormat,
+  ColorPickerChangeEvent,
+  ColorPickerInputEvent,
+  ColorPickerFormatChangeEvent,
+  ColorPickerChangeEventDetail,
+  ColorPickerFormatChangeEventDetail,
+} from './components/color-picker/color-picker.js';
+
+export type {
+  UIRating,
+  RatingChangeEvent,
+  RatingChangeEventDetail,
+} from './components/rating/rating.js';
+
+export type {
+  UICode,
+  CodeChangeEvent,
+  CodeInputEvent,
+  CodeChangeEventDetail,
+} from './components/code/code.js';
+
+export type {
+  UICalendarPicker,
+  CalendarPickerChangeEvent,
+  CalendarPickerChangeEventDetail,
+} from './components/calendar-picker/calendar-picker.js';
+
+export type {
+  UIUpload,
+  UploadChangeEvent,
+  UploadChangeEventDetail,
+} from './components/upload/upload.js';
+
+// ── Global HTMLElementTagNameMap augmentation ───────────────────────
+//
+// Tells TypeScript that `document.querySelector('slider-ui')` returns
+// `UISlider`, that `createElement('input-ui')` returns `UIInput`, etc.
+//
+// Note: only the typed primitives are listed here. Non-form primitives
+// (button-ui, card-ui, table-ui, etc.) will be added in subsequent
+// arcs as their .d.ts files land. Until then, querying for those tags
+// returns the base `HTMLElement` type.
+declare global {
+  interface HTMLElementTagNameMap {
+    'input-ui':           import('./components/input/input.js').UIInput;
+    'select-ui':          import('./components/select/select.js').UISelect;
+    'slider-ui':          import('./components/slider/slider.js').UISlider;
+    'range-ui':           import('./components/range/range.js').UIRange;
+    'textarea-ui':        import('./components/textarea/textarea.js').UITextarea;
+    'switch-ui':          import('./components/switch/switch.js').UISwitch;
+    'check-ui':           import('./components/check/check.js').UICheck;
+    'radio-ui':           import('./components/radio/radio.js').UIRadio;
+    'segmented-ui':       import('./components/segmented/segmented.js').UISegmented;
+    'search-ui':          import('./components/search/search.js').UISearch;
+    'otp-input-ui':       import('./components/otp-input/otp-input.js').UIOtpInput;
+    'option-card-ui':     import('./components/option-card/option-card.js').UIOptionCard;
+    'color-picker-ui':    import('./components/color-picker/color-picker.js').UIColorPicker;
+    'rating-ui':          import('./components/rating/rating.js').UIRating;
+    'code-ui':            import('./components/code/code.js').UICode;
+    'calendar-picker-ui': import('./components/calendar-picker/calendar-picker.js').UICalendarPicker;
+    'upload-ui':          import('./components/upload/upload.js').UIUpload;
+  }
+}

package/package.json

@@ -1,15 +1,29 @@
 {
   "name": "@adia-ai/web-components",
-  "version": "0.4.4",
+  "version": "0.4.6",
   "description": "AdiaUI web components — vanilla custom elements. A2UI runtime (renderer, registry, streams, wiring) lives in @adia-ai/a2ui-runtime.",
   "type": "module",
+  "types": "./index.d.ts",
   "exports": {
-    ".": "./index.js",
+    ".": {
+      "types": "./index.d.ts",
+      "default": "./index.js"
+    },
     "./css": "./index.css",
-    "./core": "./core/index.js",
-    "./core/*": "./core/*.js",
+    "./core": {
+      "types": "./core/index.d.ts",
+      "default": "./core/index.js"
+    },
+    "./core/*": {
+      "types": "./core/*.d.ts",
+      "default": "./core/*.js"
+    },
     "./components": "./components/index.js",
-    "./components/*": "./components/*/*.js",
+    "./components/*": {
+      "types": "./components/*/*.d.ts",
+      "default": "./components/*/*.js"
+    },
+    "./components/*.css": "./components/*/*.css",
     "./styles/*": "./styles/*",
     "./traits": "./traits/index.js",
     "./traits/*": "./traits/*.js",
@@ -28,7 +42,9 @@
     "!traits/**/*.examples.js",
     "!traits/_api-table.js",
     "index.js",
-    "index.css"
+    "index.css",
+    "index.d.ts",
+    "USAGE.md"
   ],
   "sideEffects": [
     "*.css",