uidex 0.2.1 → 0.3.0

package/dist/headless/index.d.ts

@@ -0,0 +1,214 @@
+import { StoreApi } from 'zustand/vanilla';
+
+declare const ENTITY_KINDS: readonly ["route", "page", "feature", "widget", "region", "element", "primitive", "flow"];
+type EntityKind = (typeof ENTITY_KINDS)[number];
+type Scope = string;
+interface Location {
+    file: string;
+    line?: number;
+    column?: number;
+}
+interface EntityRef {
+    kind: EntityKind;
+    id: string;
+}
+interface Metadata {
+    name?: string;
+    description?: string;
+    acceptance?: string[];
+    notes?: string;
+    composes?: EntityRef[];
+    flows?: readonly string[];
+    features?: string[];
+    widgets?: string[];
+}
+interface EntityWithMetaBase {
+    id: string;
+    loc?: Location;
+    scopes?: Scope[];
+    meta?: Metadata;
+}
+interface Route {
+    kind: "route";
+    path: string;
+    page: string;
+}
+interface Flow {
+    kind: "flow";
+    id: string;
+    loc: Location;
+    touches: string[];
+}
+interface Page extends EntityWithMetaBase {
+    kind: "page";
+}
+interface Feature extends EntityWithMetaBase {
+    kind: "feature";
+}
+interface Widget extends EntityWithMetaBase {
+    kind: "widget";
+}
+interface Region extends EntityWithMetaBase {
+    kind: "region";
+}
+interface Element$1 extends EntityWithMetaBase {
+    kind: "element";
+}
+interface Primitive extends EntityWithMetaBase {
+    kind: "primitive";
+}
+type Entity = Route | Page | Feature | Widget | Region | Element$1 | Primitive | Flow;
+type EntityByKind<K extends EntityKind> = Extract<Entity, {
+    kind: K;
+}>;
+
+interface Registry {
+    add(entity: Entity): void;
+    get<K extends EntityKind>(kind: K, id: string): EntityByKind<K> | undefined;
+    list<K extends EntityKind>(kind: K): ReadonlyArray<EntityByKind<K>>;
+    query(predicate: (entity: Entity) => boolean): Entity[];
+    byScope(scope: Scope): Entity[];
+    touchedBy(flowId: string): Entity[];
+}
+
+type ThemePreference = "light" | "dark" | "auto";
+type ResolvedTheme = "light" | "dark";
+interface ViewStackEntry {
+    id: string;
+    ref: EntityRef | null;
+}
+interface SessionSnapshot {
+    hover: EntityRef | null;
+    selection: EntityRef | null;
+    stack: ViewStackEntry[];
+    /** Sticky overlay highlight. Set by "Highlight Element" actions; cleared on Esc. */
+    pinnedHighlight: EntityRef | null;
+    inspectorActive: boolean;
+    theme: ThemePreference;
+    resolvedTheme: ResolvedTheme;
+    ingestActive: boolean;
+}
+interface SessionActions {
+    hover(ref: EntityRef | null): void;
+    select(ref: EntityRef | null): void;
+    /**
+     * Append a view onto the view stack. Pure: never resolves defaults.
+     */
+    pushStack(entry: ViewStackEntry): void;
+    /**
+     * Remove the top entry from the view stack. No-op when the stack is empty.
+     */
+    popStack(): void;
+    /**
+     * Empty the view stack.
+     */
+    clearStack(): void;
+    /**
+     * Open a view by id. If `ref` is omitted, the current `selection` is captured;
+     * pass `null` explicitly to open the view with no ref context. Thin wrapper
+     * around `pushStack`.
+     */
+    openView(id: string, ref?: EntityRef | null): void;
+    /**
+     * Clear the entire view stack. Thin wrapper around `clearStack`.
+     */
+    closeView(): void;
+    setInspectorActive(active: boolean): void;
+    toggleInspector(): void;
+    /** Pin the overlay to `ref` until `clearPinnedHighlight` is called. */
+    pinHighlight(ref: EntityRef): void;
+    clearPinnedHighlight(): void;
+    setTheme(theme: ThemePreference, resolved?: ResolvedTheme): void;
+    setIngest(active: boolean): void;
+}
+interface SessionState extends SessionSnapshot {
+    actions: SessionActions;
+}
+
+type SurfaceEvent = {
+    type: "TOGGLE_INSPECTOR";
+} | {
+    type: "OPEN_PALETTE";
+} | {
+    type: "PUSH_VIEW";
+    entry: ViewStackEntry;
+} | {
+    type: "POP_VIEW";
+} | {
+    type: "CLOSE";
+} | {
+    type: "ESC";
+} | {
+    type: "CMD_K";
+} | {
+    type: "SELECT";
+    ref: EntityRef | null;
+    entry: ViewStackEntry;
+} | {
+    type: "SET_SELECTION";
+    ref: EntityRef | null;
+} | {
+    type: "HOVER";
+    ref: EntityRef;
+    element: HTMLElement | null;
+    color?: string | null;
+} | {
+    type: "UNHOVER";
+} | {
+    type: "PIN";
+    ref?: EntityRef;
+} | {
+    type: "UNPIN";
+} | {
+    type: "SET_THEME";
+    theme: ThemePreference;
+    resolvedTheme: ResolvedTheme;
+} | {
+    type: "SET_INGEST";
+    active: boolean;
+};
+
+type SessionStore = StoreApi<SessionState> & {
+    send(event: SurfaceEvent): void;
+};
+
+interface OverlayShowOptions {
+    label?: string;
+    color?: string;
+    padding?: number;
+    borderStyle?: string;
+    borderWidth?: number;
+    fillOpacity?: number;
+}
+
+type Corner = "top-left" | "top-right" | "bottom-left" | "bottom-right";
+
+interface CreateHeadlessOptions {
+    theme?: ThemePreference;
+    resolvedTheme?: ResolvedTheme;
+    stylesheets?: string[];
+    initialCorner?: Corner;
+    appTitle?: string;
+}
+interface HeadlessOverlay {
+    show(target: Element, opts?: OverlayShowOptions): void;
+    hide(): void;
+    readonly isVisible: boolean;
+}
+interface HeadlessInspector {
+    start(): void;
+    stop(): void;
+    readonly isActive: boolean;
+}
+interface Headless {
+    mount(target?: Element): void;
+    unmount(): void;
+    readonly registry: Registry;
+    readonly session: SessionStore;
+    readonly overlay: HeadlessOverlay;
+    readonly inspector: HeadlessInspector;
+    readonly shadowRoot: ShadowRoot | null;
+}
+declare function createHeadless(options?: CreateHeadlessOptions): Headless;
+
+export { type CreateHeadlessOptions, type Headless, type HeadlessInspector, type HeadlessOverlay, createHeadless };