@exponential-at/ui-element 0.0.0-stage → 0.1.0

package/dist/types/define.d.ts

@@ -0,0 +1 @@
+export * from "./index.js";

package/dist/types/element.d.ts

@@ -0,0 +1,91 @@
+import type { ExponentialHost, ModeName, ScrollAlign, SurfaceCommand, TransportStatus, UiNode } from "@exponential-at/ui";
+import { type DataModel } from "@exponential-at/ui/web";
+import type { A2uiMessage, ExponentialSurfaceProps, HostPlugin, SolidExtension, SurfaceHandle, SurfaceState, ThemeInput } from "@exponential-at/ui-solid";
+export declare const TAG = "exponential-surface";
+type Density = NonNullable<ExponentialSurfaceProps[`density`]>;
+type Contrast = NonNullable<ExponentialSurfaceProps[`contrast`]>;
+type Mode = ModeName | `system`;
+type Direction = `ltr` | `rtl`;
+/** A numeric string = px, any other string = a CSS length. */
+export declare function lengthOf(value: number | string | null | undefined): number | string | undefined;
+export declare class ExponentialSurfaceElement extends HTMLElement {
+    #private;
+    static get observedAttributes(): string[];
+    attributeChangedCallback(name: string, _old: string | null, value: string | null): void;
+    get theme(): ThemeInput | undefined;
+    set theme(v: ThemeInput | undefined | null);
+    get mode(): Mode | undefined;
+    set mode(v: Mode | undefined | null);
+    get density(): Density | undefined;
+    set density(v: Density | undefined | null);
+    get contrast(): Contrast | undefined;
+    set contrast(v: Contrast | undefined | null);
+    get locale(): string | undefined;
+    set locale(v: string | undefined | null);
+    get timeZone(): string | undefined;
+    set timeZone(v: string | undefined | null);
+    get direction(): Direction | undefined;
+    set direction(v: Direction | undefined | null);
+    get width(): number | string | undefined;
+    set width(v: number | string | undefined | null);
+    get height(): number | string | undefined;
+    set height(v: number | string | undefined | null);
+    /** The surface id (`surface-id`, default `main`). */
+    get surfaceId(): string;
+    set surfaceId(v: string | undefined | null);
+    get src(): string | undefined;
+    set src(v: string | undefined | null);
+    get post(): string | undefined;
+    set post(v: string | undefined | null);
+    get transport(): string | undefined;
+    set transport(v: string | undefined | null);
+    get surface(): SurfaceState | undefined;
+    set surface(v: SurfaceState | undefined | null);
+    get root(): UiNode | null | undefined;
+    set root(v: UiNode | null | undefined);
+    get templates(): Readonly<Record<string, UiNode>> | undefined;
+    set templates(v: Readonly<Record<string, UiNode>> | undefined | null);
+    get data(): DataModel | undefined;
+    set data(v: DataModel | undefined | null);
+    get host(): ExponentialHost | undefined;
+    set host(v: ExponentialHost | undefined | null);
+    get plugin(): HostPlugin | undefined;
+    set plugin(v: HostPlugin | undefined | null);
+    get extensions(): readonly SolidExtension[] | undefined;
+    set extensions(v: readonly SolidExtension[] | undefined | null);
+    get strings(): Record<string, string> | undefined;
+    set strings(v: Record<string, string> | undefined | null);
+    get states(): readonly string[] | undefined;
+    set states(v: readonly string[] | undefined | null);
+    get measure(): ExponentialSurfaceProps[`measure`];
+    set measure(v: ExponentialSurfaceProps[`measure`] | null);
+    get viewportHeight(): number | undefined;
+    set viewportHeight(v: number | undefined | null);
+    /** The painted surface's handle; null until the first paint. */
+    get handle(): SurfaceHandle | null;
+    /** The active store's reduce issues. */
+    get issues(): SurfaceState[`issues`];
+    /** The host's transport state (a host property or one built from `src`);
+     *  `closed` when the URL policy denied `src`/`post` (see `statusDetail`). */
+    get status(): TransportStatus | undefined;
+    /** The transport's detail (an error, or `src denied by the URL policy (private)`). */
+    get statusDetail(): string | undefined;
+    /** The state painted: the `surface` property, the host's surface, or the
+     *  store `apply()` made. */
+    get surfaceState(): SurfaceState | null;
+    /** One A2UI server message: to the `surface` property, else the host,
+     *  else a store made on first use (surface id = `surfaceId`). */
+    apply(message: A2uiMessage): void;
+    /** Write the data model (the active store's; in fixture mode a new `data`). */
+    setData(pointer: string, value: unknown): void;
+    /** Back to the store's initial state (a host surface ignores it). */
+    reset(): void;
+    run(command: SurfaceCommand): void;
+    focus(id?: string | FocusOptions): boolean;
+    announce(text: string, live?: `polite` | `assertive`): void;
+    scrollIntoView(id?: string | boolean | ScrollIntoViewOptions): boolean;
+    scrollToIndex(id: string, index: number, align?: ScrollAlign): boolean;
+    connectedCallback(): void;
+    disconnectedCallback(): void;
+}
+export {};

package/dist/types/events.d.ts

@@ -0,0 +1,71 @@
+import type { FunctionCallInfo, ThemeIssue, TransportStatus, UiNode } from "@exponential-at/ui";
+import type { PaintError, SurfaceActionEvent, SurfaceHandle, SurfaceInputEvent } from "@exponential-at/ui-solid";
+import type { ExponentialSurfaceElement } from "./element.js";
+/** Keeps the source control pending until `promise` settles. */
+export interface WaitUntil {
+    waitUntil: (promise: Promise<unknown>) => void;
+}
+export type SurfaceActionDetail = SurfaceActionEvent & WaitUntil;
+/** `waitUntil` acknowledges the input's revision when it settles. */
+export type SurfaceInputDetail = SurfaceInputEvent & WaitUntil;
+export interface FunctionCallDetail {
+    call: FunctionCallInfo;
+    /** The call's result (the first `respond` wins; none = the plugin's
+     *  `onFunctionCall` result, else undefined). A promise keeps the source
+     *  control pending. */
+    respond: (value: unknown) => void;
+}
+/** Cancelable: `preventDefault()` = the page opens it (or not) itself. */
+export interface OpenUrlDetail {
+    url: string;
+}
+export interface UploadDetail extends WaitUntil {
+    files: File[];
+    target: {
+        nodeId: string;
+        name: string;
+    };
+}
+export interface StatusDetail {
+    status: TransportStatus;
+    detail?: string;
+}
+export interface ExponentialSurfaceEventMap {
+    "xui-action": CustomEvent<SurfaceActionDetail>;
+    "xui-input": CustomEvent<SurfaceInputDetail>;
+    "xui-function-call": CustomEvent<FunctionCallDetail>;
+    "xui-open-url": CustomEvent<OpenUrlDetail>;
+    "xui-upload": CustomEvent<UploadDetail>;
+    "xui-paint-error": CustomEvent<{
+        error: PaintError;
+    }>;
+    "xui-theme-issues": CustomEvent<{
+        issues: ThemeIssue[];
+    }>;
+    "xui-unknown": CustomEvent<{
+        node: UiNode;
+    }>;
+    "xui-status": CustomEvent<StatusDetail>;
+    "xui-ready": CustomEvent<{
+        handle: SurfaceHandle;
+    }>;
+}
+export type ExponentialSurfaceEventName = keyof ExponentialSurfaceEventMap;
+declare global {
+    interface HTMLElementTagNameMap {
+        "exponential-surface": ExponentialSurfaceElement;
+    }
+    interface HTMLElementEventMap extends ExponentialSurfaceEventMap {
+    }
+}
+type DetailOf<K extends ExponentialSurfaceEventName> = ExponentialSurfaceEventMap[K] extends CustomEvent<infer D> ? D : never;
+/** Dispatch one event; returns false when a listener cancelled it. */
+export declare function emit<K extends ExponentialSurfaceEventName>(target: EventTarget, name: K, detail: DetailOf<K>, cancelable?: boolean): boolean;
+/** The plugin's result and every `waitUntil` promise, joined: undefined when
+ *  none is a promise (the painter acknowledges at once), else one promise
+ *  that settles with all of them (and rejects with the first rejection). */
+export declare function joinPending(results: readonly unknown[]): Promise<void> | undefined;
+/** Dispatch a waiting event: `base` + `waitUntil`; returns the promises the
+ *  listeners handed over. */
+export declare function emitWaiting<K extends `xui-action` | `xui-input` | `xui-upload`>(target: EventTarget, name: K, base: Omit<DetailOf<K>, `waitUntil`>): Promise<unknown>[];
+export {};

package/dist/types/extensions.d.ts

@@ -0,0 +1,39 @@
+import type { ExtensionDef, ModeName, ResolvedTheme, UiNode } from "@exponential-at/ui";
+import { type RegisterExtensionOptions, type SolidExtension } from "@exponential-at/ui-solid";
+export interface ElementPaintContext {
+    node: UiNode;
+    /** The node's props, resolved against the data model. */
+    props: Record<string, unknown>;
+    theme: ResolvedTheme;
+    mode: ModeName;
+    tokens: ResolvedTheme[`tokens`];
+    /** Fire one of the node's `on` handlers (`own` = what the element just
+     *  wrote, by prop). A promise = the host is still handling it. */
+    emit: (event: string, payload?: Record<string, unknown>, own?: Record<string, unknown>) => Promise<void> | void;
+    /** What the renderer wants on the root: `class`, `data-xui-id`,
+     *  `data-xui-c`, recipe `data-r-*`/`data-m-*`, `data-xs`, aria, `dir`,
+     *  `style` (kebab-case keys). */
+    rootProps: Record<string, unknown>;
+    /** Sets `rootProps` on `el` (classes added to its own). */
+    applyRootProps: (el: Element) => void;
+    /** The node's painted children (append them where they belong). */
+    children: () => Node[];
+    /** One slot's painted nodes (empty when the node has no such slot). */
+    slot: (name: string) => Node[];
+}
+export type ElementPainter = (ctx: ElementPaintContext) => Element;
+/** `rootProps` onto an element: classes merge, `style` entries are set one
+ *  by one, null/undefined skip, everything else as a string. */
+export declare function applyRootProps(el: Element, rootProps: Record<string, unknown>): void;
+/** A per-surface extension (the `extensions` property) or, through
+ *  `registerExtension`, a page-wide one, painted by vanilla painters. A
+ *  `components` key naming a core native OVERRIDES its painter. */
+export declare function defineElementExtension(options: {
+    catalog?: ExtensionDef | unknown;
+    components: Record<string, ElementPainter>;
+}): SolidExtension;
+/** Register an extension for every surface on the page (Solid's
+ *  `registerExtension`), taking a `defineElementExtension` /
+ *  `defineSolidExtension` result as well as the raw options. Returns the
+ *  unregister function. */
+export declare function registerExtension(extension: SolidExtension | RegisterExtensionOptions): () => void;

package/dist/types/icons.d.ts

@@ -0,0 +1,7 @@
+import type { IconComponent, IconMap } from "@exponential-at/ui-solid";
+/** One SVG markup string as an icon component. */
+export declare function svgIcon(markup: string): IconComponent;
+/** A registry name → SVG markup lookup, as the icon map `plugin.icons`
+ *  takes. A name it has no markup for falls through to the renderer's own
+ *  glyphs (then the placeholder). One component per distinct markup. */
+export declare function iconsFromSvg(resolve: (name: string) => string | undefined): IconMap;

package/dist/types/index.d.ts

@@ -0,0 +1,17 @@
+export { ExponentialSurfaceElement, TAG, lengthOf } from "./element.js";
+export { iconsFromSvg, svgIcon } from "./icons.js";
+export { defineElementExtension, registerExtension, applyRootProps } from "./extensions.js";
+export type { ElementPainter, ElementPaintContext } from "./extensions.js";
+export { createHost, createTransport, transportKind, decideTransport, transportSchemes } from "./transport.js";
+export type { TransportKind, TransportAttributes, TransportDecision } from "./transport.js";
+export type { SurfaceActionDetail, SurfaceInputDetail, FunctionCallDetail, OpenUrlDetail, UploadDetail, StatusDetail, WaitUntil, ExponentialSurfaceEventMap, ExponentialSurfaceEventName } from "./events.js";
+export { defineSolidExtension, createSurface } from "@exponential-at/ui-solid";
+export type { A2uiMessage, SurfaceState, SurfaceHandle, HostPlugin, IconMap, IconComponent, ThemeInput, SolidExtension } from "@exponential-at/ui-solid";
+/** Register the element under `tag` (default `exponential-surface`).
+ *  Idempotent; a tag already taken by another class throws. Another tag
+ *  gets its own subclass (one constructor per tag). */
+export declare function define(tag?: string): void;
+/** ONE document rule per tag, `:where(<tag>){display:contents}` (specificity
+ *  0: any author rule wins): the element is no box of its own, the surface's
+ *  `.xui-surface` root is. Idempotent; nothing without a document. */
+export declare function installHostRule(tag: string): void;

package/dist/types/standalone.d.ts

@@ -0,0 +1,2 @@
+import "./define.js";
+export * from "./index.js";

package/dist/types/transport.d.ts

@@ -0,0 +1,34 @@
+import { ExponentialHost } from "@exponential-at/ui";
+import type { ExtensionDef, Transport, UrlDecision, UrlPolicy } from "@exponential-at/ui";
+export type TransportKind = `jsonl` | `sse` | `ws`;
+export interface TransportAttributes {
+    src: string;
+    post?: string | null;
+    transport?: string | null;
+}
+/** Which transport the attributes name. */
+export declare function transportKind(attrs: TransportAttributes): TransportKind;
+export declare function createTransport(attrs: TransportAttributes): Transport;
+/** The decision for `src` and `post` under the page's URL policy. */
+export interface TransportDecision {
+    allowed: boolean;
+    src: UrlDecision;
+    /** Only when `post` is set. */
+    post?: UrlDecision;
+    /** Why not, for the element's status (`src denied by the URL policy (private)`). */
+    reason?: string;
+}
+/** The transport schemes a URL policy allows: its http(s) entries (default
+ *  both) and their ws(s) twins; nothing else (mailto, tel, javascript,
+ *  file, data never carry a transport). */
+export declare function transportSchemes(policy: UrlPolicy | undefined): string[];
+/** VAPP-107: `src` (and `post` when set) under the page's URL policy. */
+export declare function decideTransport(attrs: TransportAttributes, policy?: UrlPolicy): TransportDecision;
+/** A host over the attributes' transport (not connected yet). `extensions`
+ *  = the catalogs of the element's `extensions` at build time (the host's
+ *  reducer must know them, or an extension component reduces to Unknown).
+ *  VAPP-107: `policy` (the page's URL policy, default the SDK's) decides
+ *  `src` and `post` first; a denied one throws before any transport exists. */
+export declare function createHost(attrs: TransportAttributes, extensions?: readonly ExtensionDef[], policy?: UrlPolicy): ExponentialHost;
+/** The identity of a built host: a change rebuilds it. */
+export declare const transportKey: (attrs: TransportAttributes) => string;

package/package.json

@@ -1,6 +1,54 @@
 {
   "name": "@exponential-at/ui-element",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Exponential UI as a custom element: <exponential-surface> paints a core A2UI surface with no framework in the host page, on the Solid painter and the shared web layer, with the same DOM, the same compiled stylesheet and the same runtime themes as the React renderer, run through the conformance suite and the web-parity check.",
+  "license": "Apache-2.0",
+  "homepage": "https://ui.exponential.at",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Niach/exponential.git",
+    "directory": "packages/exponential-ui-element"
+  },
+  "keywords": [
+    "a2ui",
+    "generative-ui",
+    "exponential-ui"
+  ],
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/types/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/types/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    },
+    "./define": {
+      "types": "./dist/types/define.d.ts",
+      "import": "./dist/define.js",
+      "default": "./dist/define.js"
+    },
+    "./standalone": "./dist/standalone.js",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "NOTICE"
+  ],
+  "sideEffects": [
+    "./dist/define.js",
+    "./dist/standalone.js"
+  ],
+  "dependencies": {
+    "@exponential-at/ui": "^0.1.0",
+    "@exponential-at/ui-solid": "^0.1.0",
+    "solid-js": "^1.9.17"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  }
+}