@ai-matrx/alchemy 0.6.2 → 0.8.2

package/dist/react-bar.d.ts

@@ -0,0 +1,379 @@
+import { TransferOutcome } from '@ai-matrx/kit/content-transfer';
+import * as React from 'react';
+
+/**
+ * Matrx Alchemy — Declare types (CONTRACT §2.1).
+ *
+ * A declaration is plain JSON data (chair ruling N2): no functions, no classes,
+ * no React. Runtime behaviour lives in `MountedSurface` (`/declare/host`) and in
+ * handler registrations, never here. Zero React, zero `@ai-matrx/agents`.
+ */
+type Json = null | boolean | number | string | Json[] | {
+    [key: string]: Json;
+};
+/** Unchanged from `ui_surface_value_type_chk`. */
+type ValueType = "string" | "number" | "boolean" | "object" | "array" | "document";
+type Classification = "ordinary" | "secret" | "credential";
+/** Persisted (CONTRACT §2.7). Projection enforces it before any value leaves. */
+interface Sensitivity {
+    /** false = never leaves through Operate. Default true. */
+    exportable: boolean;
+    /** secret/credential are always excluded; no caller can relax this. Default "ordinary". */
+    classification: Classification;
+    /** Pre-checked in the preparation workspace. Default true. */
+    includedByDefault: boolean;
+}
+interface ValueGroup {
+    key: string;
+    label: string;
+    sortOrder: number;
+    description?: string;
+}
+/** The four runtime slots a capture fills (absorbs page-capture). */
+type LiveSlot = "selection" | "on-demand" | "errors" | "requests";
+interface DeclaredValue {
+    name: string;
+    label: string;
+    description: string;
+    valueType: ValueType;
+    /** Registered content-ir kind key (DB: kind_key). */
+    valueKind?: string;
+    alwaysAvailable: boolean;
+    typicalCharCount: number;
+    autoContext?: boolean;
+    group?: string;
+    sortOrder?: number;
+    sensitivity?: Partial<Sensitivity>;
+    /** Filled at capture time from a live slot instead of the scope. */
+    liveSlot?: LiveSlot;
+    /** "request" values drop out of "Only the data". Default "data". */
+    role?: "data" | "request";
+}
+/** Where a write lands. "stream" = applied live, op by op, into an editable text. */
+type WriteMode = "draft" | "entity" | "ui" | "stream";
+/** Who may apply WITHOUT a click. "queued" = filed for an organization's review. */
+type ApplyPolicy = "manual" | "ask" | "auto" | "queued";
+/** The WidgetHandle text op set, unchanged in meaning. */
+type StreamOp = "replace" | "insert_before" | "insert_after" | "prepend" | "append" | "patch";
+interface WriteTarget {
+    name: string;
+    label: string;
+    description: string;
+    valueType: ValueType;
+    valueKind?: string;
+    /** Read twin (evidence loop). Required when patchable or mode === "stream". */
+    updatesValue?: string;
+    patchable?: boolean;
+    approvalComparison?: "text-replacement";
+    mode: WriteMode;
+    /** Required iff mode === "stream". */
+    streamOps?: readonly StreamOp[];
+    /** Default "manual". Binding overrides may only tighten. */
+    applyPolicy?: ApplyPolicy;
+    destination?: boolean;
+    /** Present when the target writes into an item rather than the screen. */
+    itemType?: string;
+    group?: string;
+    sortOrder?: number;
+}
+/** One kind of thing inside a screen (a row, a message, a code block, a card). */
+interface ItemType {
+    name: string;
+    label: string;
+    description: string;
+    /** Value names that together identify one item. */
+    identity: readonly string[];
+    levels?: readonly string[];
+    entityType?: string;
+    values: readonly DeclaredValue[];
+    writeTargets?: readonly WriteTarget[];
+}
+type Readiness = "verified" | "partial" | "stub";
+/** `ui_surface_execution_mode_check`, unchanged. */
+type ExecutionMode = "python-stream" | "nextjs-stream" | "browser-realtime" | "local-runtime";
+interface ConfigNamespaceDeclaration {
+    namespace: string;
+    label: string;
+    description: string;
+}
+interface EvidenceSourceDeclaration {
+    kind: "processed_document";
+    idValue: string;
+    fileIdValue?: string;
+    labelValue?: string;
+    representation?: "clean" | "raw";
+}
+/**
+ * One screen's declaration. Owning packages add fields (agent roles, client
+ * tools) as EXTENSION SLOTS — by interface extension or declaration merging —
+ * and register a `DeclarationExtension` so validation and the sync cover them.
+ */
+interface SurfaceDeclaration {
+    surfaceName: string;
+    /** REQUIRED. `ui_surface.client_name`; must equal the surfaceName prefix. */
+    client: string;
+    /** REQUIRED. `ui_surface.execution_mode`. */
+    executionMode: ExecutionMode;
+    /** REQUIRED. `ui_surface.description` ("" only where the live row is empty). */
+    description: string;
+    label: string;
+    readiness: Readiness;
+    readinessNote?: string;
+    urlPattern?: string;
+    inheritsFrom?: string;
+    intro?: string;
+    overlayId?: string;
+    values: readonly DeclaredValue[];
+    groups?: readonly ValueGroup[];
+    writeTargets?: readonly WriteTarget[];
+    itemTypes?: readonly ItemType[];
+    liveSlots?: readonly LiveSlot[];
+    configNamespaces?: readonly ConfigNamespaceDeclaration[];
+    evidenceSources?: readonly EvidenceSourceDeclaration[];
+    skipBaselineValues?: boolean;
+}
+type ValueProvenance = {
+    kind: "own";
+} | {
+    kind: "inherited";
+    from: string;
+} | {
+    kind: "baseline";
+};
+type ResolvedValue = DeclaredValue & {
+    provenance: ValueProvenance;
+    groupKey: string;
+    /** Defaults filled. */
+    resolvedSensitivity: Sensitivity;
+};
+interface ResolvedSurfaceDeclaration extends SurfaceDeclaration {
+    contentHash: string;
+    values: readonly ResolvedValue[];
+    groups: readonly ValueGroup[];
+}
+/**
+ * ITEM KEYS. A value or write target is identified by (surfaceName, itemType ?? "", name).
+ * The qualified key "<itemType>.<name>" names an item value; a bare name is a screen value.
+ */
+type QualifiedValueKey = string;
+/** Live slot payloads (page-capture's shapes, kept). */
+interface LiveValues {
+    selection?: {
+        choices: Record<string, Json>;
+        text: string | null;
+    };
+    "on-demand"?: readonly OnDemandSection[];
+    errors?: readonly string[];
+    requests?: readonly RecentRequest[];
+}
+interface OnDemandSection {
+    id: string;
+    title: string;
+    description?: string;
+    role: "data" | "request";
+    brief?: Json;
+    load(signal: AbortSignal): Promise<Json>;
+}
+interface RecentRequest {
+    method: string;
+    path: string;
+    status: string;
+    httpStatus?: number;
+    durationMs?: number;
+    requestId?: string;
+    client?: string;
+    requestBody?: Json;
+    requestBodyNote?: string;
+    errorSentence?: string;
+    timestamp: number;
+}
+/** RAW-FREE. What leaves the package about a clicked item. */
+interface ResolvedItem {
+    itemType: string;
+    identity: Record<string, string>;
+    level?: string;
+    readOnly: boolean;
+}
+
+/**
+ * The click target (CONTRACT §2.4) in its own module: `/ports` references it,
+ * and `/ports` must stay free of every other package (types only).
+ */
+
+/** The transfer Payload's kinds (`actions/types.ts` asserts equality at compile time). */
+type PayloadKind = "text" | "markdown" | "json" | "rows" | "registered";
+/** What eligibility is computed from: everything declared at the click target. */
+interface ClickTarget {
+    surface: {
+        instanceId: string;
+        surfaceName: string;
+    } | null;
+    /** The resolved declaration (inheritance applied). Eligibility decides by KEY existence over it. */
+    declaration: ResolvedSurfaceDeclaration | null;
+    /** Declared value keys with a read path here (screen names + qualified item keys). Key existence, not population. */
+    valueKeys: ReadonlySet<QualifiedValueKey>;
+    /** Scope chain, most general first: ["global", "<domain>", "<surfaceName>"]. */
+    scopeChain: readonly string[];
+    /** The surface's explicit exclusions (the one override). */
+    excludedActionIds: ReadonlySet<string>;
+    item: ResolvedItem | null;
+    level: string | null;
+    /** Offsets + the live range handle, editable or not. */
+    selection: {
+        text: string;
+        type: "editable" | "non-editable";
+        start: number;
+        end: number;
+        /** Opaque host handle (DOM Range / element) used to restore or stream into the selection. */
+        handle?: unknown;
+    } | null;
+    /** Payload kinds a capture of this target would produce (from declared value types/kinds). */
+    payloadKinds: readonly PayloadKind[];
+    /** Declared targets writable on this target right now. */
+    writable: readonly WriteTarget[];
+    readOnly: boolean;
+    /** True when any declared value here is secret/credential or non-exportable. */
+    restricted: boolean;
+    organizationId: string | null;
+    auth: {
+        authenticated: boolean;
+        admin: boolean;
+        creator: boolean;
+    };
+    /**
+     * Host-owned context a provider reads to act (the rich-document source, the
+     * editable field's callbacks). Opaque to the package; never crosses into the
+     * model. Providers that need it narrow it themselves.
+     */
+    host?: unknown;
+}
+
+/**
+ * Matrx Alchemy — Actions types (CONTRACT §2.4).
+ *
+ * One registry of everything a person can do to a thing. Providers plug in;
+ * eligibility is computed from what is declared at the click target; duplicate
+ * ids are refused; an action that does not apply is ABSENT (chair ruling R1).
+ *
+ * Framework-neutral: zero React, zero `@ai-matrx/agents`. Icons are string KEYS
+ * resolved by the host's `IconResolverPort`; labels go through `I18nPort`.
+ */
+
+/** rich-document's ActionCategory, unchanged, plus the three the context menu groups by. */
+type ActionCategory = "feedback" | "copy" | "export" | "save" | "edit" | "share" | "creator" | "app" | "listen" | "study" | "ask" | "ai" | "admin" | "clipboard" | "history" | "surface-info";
+interface ResolveRestriction {
+    exclude?: readonly string[];
+    categories?: readonly ActionCategory[];
+}
+
+/**
+ * `@ai-matrx/alchemy/declare/host` — HOST-BINDING types only (CONTRACT §2.1, §2.6).
+ * Never imported by providers (`/declare`, `/actions`, `/menu`, `/operate` see only
+ * the raw-free `ResolvedItem`). Types only: no runtime code.
+ */
+
+interface ItemAnchor {
+    /** The host element the person clicked. */
+    element: unknown;
+    level?: string;
+}
+/** Raw item reads: consumed only by projection and the write handler that owns the target. */
+interface InternalResolvedItem extends ResolvedItem {
+    readValues(signal: AbortSignal): Promise<Record<string, unknown>>;
+}
+/** A mounted instance of a declared surface. Structural handle, never a global name lookup. */
+interface MountedSurface {
+    instanceId: string;
+    surfaceName: string;
+    isMounted(): boolean;
+    /** Same revision before and after a read, or capture refuses with "surface-changed". */
+    getRevision?(): string;
+    unsavedChanges?(): boolean;
+    readValues(signal: AbortSignal): Promise<Record<string, unknown>>;
+    readLive?(signal: AbortSignal): Promise<LiveValues>;
+    resolveItem?(anchor: ItemAnchor): InternalResolvedItem | null;
+}
+
+interface ProjectionSource {
+    surface: MountedSurface | null;
+    declaration: ResolvedSurfaceDeclaration | null;
+    item: InternalResolvedItem | null;
+}
+
+/**
+ * The one run path (T1e). Every layout runs an action through here, so the
+ * sign-in-then-resume rule, projection and failure capture live once.
+ */
+
+type RunResult = {
+    status: "ran";
+    outcome: TransferOutcome | void;
+} | {
+    status: "auth-pending";
+} | {
+    status: "failed";
+    error: unknown;
+};
+
+/**
+ * The React half of T1e: one hook every renderer uses to resolve the registry
+ * at a target, build the model and run a node. Handlers never live in a
+ * renderer — they live in providers and run through `runAction`.
+ *
+ * The context object is shared through globalThis so every per-layout entry
+ * (each bundled separately) reads the same provider (module state is banned
+ * across dual-loader graphs).
+ */
+
+interface MenuEngineOptions {
+    restrict?: ResolveRestriction;
+    /** Raw sources for projection (the host's mounted surface / clicked item). */
+    source?: ProjectionSource;
+    /** Content the menu acts on when nothing is selected (header text). */
+    content?: string | null;
+    contentFingerprint?: string;
+    /** Called after a node ran (close the menu, announce). */
+    onRan?: (nodeId: string, result: RunResult) => void;
+    /** Resolve only while true (renderers resolve on open). Default true. */
+    active?: boolean;
+    /**
+     * Re-resolve when this changes even if the target object is the same (a
+     * host that keeps one target per mount and reads live state through it).
+     */
+    revision?: string | number;
+}
+
+/**
+ * `@ai-matrx/alchemy/react/sheet` — the mobile bottom-sheet layout, T1m.
+ * T1's twin over the SAME model (`sheet(model)`), so mobile can never drift
+ * from desktop. Path-based drill-down: a list of submenu ids re-resolved
+ * against the live model every render, so loading agents update in place.
+ */
+
+interface ActionSheetProps extends MenuEngineOptions {
+    target: ClickTarget;
+    open: boolean;
+    onOpenChange(open: boolean): void;
+    title?: string;
+}
+
+interface ActionBarProps extends MenuEngineOptions {
+    target: ClickTarget;
+    /** Compact presentation (smaller gaps); membership is identical. */
+    mini?: boolean;
+    className?: string;
+    /** Hide the ⋯ (the host turned the options off); the primaries still render. */
+    hideOverflow?: boolean;
+    /**
+     * Below this viewport width the ⋯ opens the mobile bottom sheet
+     * (`/react/sheet`, loaded on first tap) instead of a dropdown. Default 768.
+     */
+    sheetBelow?: number;
+    /** Override the sheet loader (tests, custom bundlers). */
+    loadSheet?: () => Promise<{
+        ActionSheet: React.ComponentType<ActionSheetProps>;
+    }>;
+}
+declare function ActionBar({ target, mini, className, hideOverflow, sheetBelow, loadSheet, ...options }: ActionBarProps): React.ReactElement | null;
+
+export { ActionBar, type ActionBarProps };