@ai-matrx/detail 0.1.0

package/dist/host-eKqulRpB.d.cts

@@ -0,0 +1,524 @@
+import * as react from 'react';
+import { ComponentType, ReactNode } from 'react';
+
+/** The three ways a record detail can show. `window` is the platform default. */
+declare const DETAIL_PRESENTATIONS: readonly ["window", "docked", "page"];
+type DetailPresentation = (typeof DETAIL_PRESENTATIONS)[number];
+/** A record, named the way the platform names records: type token + id. */
+interface DetailRef {
+    type: string;
+    id: string;
+}
+/** What the opener already knows, shown instantly until the row loads. */
+interface DetailSeed {
+    name?: string | null;
+    about?: string | null;
+}
+/**
+ * The list the record was opened FROM, so `[` / `]` move to the previous /
+ * next record without going back to the list. Plain data — it travels through
+ * the host's state store and the URL.
+ */
+interface DetailListContext {
+    items: DetailRef[];
+    index: number;
+    /**
+     * Set when this list is a WINDOW cut out of a longer one (the page
+     * presentation carries the list in the URL and it is capped —
+     * `ui.detail.list_context_max_ids`): the length of the list it was cut from,
+     * so the detail can say the neighbours beyond it are not reachable from here
+     * instead of presenting the window as the whole list (NEW-7).
+     */
+    trimmedFrom?: number;
+}
+/** What `useOpenDetail` accepts. */
+interface DetailOpenRequest extends DetailRef {
+    /** Skip the setting and open this way. Omit to honour the user's setting. */
+    presentation?: DetailPresentation;
+    seed?: DetailSeed | null;
+    list?: DetailListContext | null;
+}
+/** The payload a presentation receives — everything an open request carried. */
+interface DetailInstanceData extends DetailRef {
+    seed: DetailSeed | null;
+    list: DetailListContext | null;
+}
+type DetailRow = Record<string, unknown>;
+type DetailLoadResult<Row extends DetailRow = DetailRow> = {
+    row: Row;
+} | {
+    notFound: true;
+};
+/** One rendered field. `ref` makes the value a door instead of text. */
+interface DetailField {
+    key: string;
+    label: string;
+    text: string;
+    /** Render in a monospace block (JSON, long identifiers). */
+    mono?: boolean;
+    /**
+     * This value names another record — render it as a door.
+     *
+     * 🚨 AND THE DOOR SAYS WHAT IT OPENS (chair, 2026-09-18). The body used to
+     * render the door from `ref.id` alone, so a field whose `text` was
+     * "Acme Robotics" printed a truncated uuid instead: a door nobody can read is
+     * half a dead end. `name` is the record's own name for the host's `RefCell` to
+     * render; when it is omitted the body falls back to `text` (unless `text` is
+     * the id itself, in which case there is nothing better to say).
+     */
+    ref?: {
+        token: string;
+        id: string;
+        name?: string | null;
+    } | null;
+}
+/**
+ * The "source health strip" for a synced record — where it came from, when it
+ * was last refreshed, whether the grant behind it still works, and how to open
+ * it at the source. Absent for records the platform owns outright.
+ */
+interface DetailSourceHealth {
+    /** Human name of the source ("Google Drive", "Search Console"). */
+    source: string;
+    lastRefreshedAt?: string | null;
+    /**
+     * 🚨 THE GRANT-STATE VOCABULARY. Five of the six say what is wrong with the
+     * CONNECTION; `blocked` says the record cannot be refreshed and NOTHING the
+     * person can click repairs it (chair, 2026-09-18).
+     *
+     *   - `ok`       → the grant behind this record works;
+     *   - `expired`  → it lapsed and a reconnect renews it;
+     *   - `revoked`  → someone withdrew it and a reconnect re-grants it;
+     *   - `missing`  → we never had it, or the record is not shared with us;
+     *   - `unknown`  → we could not check (a read failed) — reconnecting is safe;
+     *   - `blocked`  → the source itself refuses, and no control repairs it: a
+     *                  provider outage, a quota, a platform-configuration fault,
+     *                  a connection the server reports as unavailable. The strip
+     *                  says BLOCKED, states the reason, and offers NO Reconnect —
+     *                  which `reconnectFor` enforces for this word whatever the
+     *                  producer or the host supplies, because a button that
+     *                  cannot work is a control that does nothing (law 4).
+     *
+     * `unknown` used to carry both meanings, so a blocked record was offered the
+     * consent window it could not be repaired by (VERIFY-U-P1-R5, N1's class).
+     */
+    grant: "ok" | "expired" | "revoked" | "missing" | "unknown" | "blocked";
+    /** One sentence for the grant state, in the person's language. */
+    grantDetail?: string | null;
+    openAtSourceHref?: string | null;
+    /**
+     * The per-record label for the "open at source" control, when the
+     * registration knows it precisely (chair, 2026-09-18). `DetailBody` derives
+     * a label from `source` on its own (see `deriveOpenAtSourceLabel`) for a
+     * producer that has no opinion, but that derivation guesses from a family
+     * name ("Google Docs, Sheets & Drive files" → "Open in Google") — a
+     * registration that knows the row's exact kind (a Doc vs. a Sheet vs. a
+     * plain Drive file; a Calendar event) sets this instead and it wins.
+     */
+    openAtSourceLabel?: string;
+    /**
+     * The repair offered when the grant is not `ok`. 🚨 THREE-VALUED, AND THE
+     * THREE MEAN DIFFERENT THINGS (Bugbot round 18 on frontend PR 228):
+     *
+     *   - a function  → offer THIS action;
+     *   - `null`      → offer NOTHING: the producer has decided a reconnect
+     *                   would not repair this refusal (a share the owner must
+     *                   grant, a record we own, an unclassified failure) and a
+     *                   Reconnect button would be a control that does nothing;
+     *   - omitted     → the producer has no opinion; the host's `reconnectSource`
+     *                   port supplies the action when it has one.
+     *
+     * `useDetailHealth` honours `null` explicitly — it used to fill the host
+     * action back in with `??`, which reads `null` as "unset", so a synced record
+     * whose refusal a reconnect cannot fix still showed Reconnect.
+     */
+    onReconnect?: (() => void) | null;
+    /** Offered when the record can be refreshed on demand. */
+    onRefresh?: (() => void | Promise<void>) | null;
+}
+/** What a `health` producer is told about the record it is answering for. */
+interface DetailHealthContext {
+    ref: DetailRef;
+    /** Aborted when the record changes or the detail closes. */
+    signal: AbortSignal;
+}
+/**
+ * The health producer: sync or async, and free to answer `null` for a record
+ * that is not synced. A throw or a rejection is rendered as an honest "we could
+ * not check the connection" strip, never as silence (`useDetailHealth`).
+ */
+type DetailHealthProducer<Row extends DetailRow = DetailRow> = (row: Row, ctx: DetailHealthContext) => DetailSourceHealth | null | Promise<DetailSourceHealth | null>;
+/** An extra section a record type adds under the fixed ones. */
+interface DetailSection {
+    id: string;
+    label: string;
+    content: ReactNode;
+}
+/** What a registration's optional `Frame` and sections receive. */
+interface DetailFrameContext {
+    ref: DetailRef;
+    recordType: DetailRecordType;
+    title: string;
+    about: string | null;
+    status: DetailStatus;
+    fields: DetailField[];
+    presentation: DetailPresentation;
+}
+/**
+ * ONE registration per record type. The core component (header + fixed
+ * sections) is derived from this; a record type never writes presentation
+ * code. Everything optional degrades to "section absent", never to a dead
+ * or disabled-looking control.
+ */
+interface DetailRecordType<Row extends DetailRow = DetailRow> {
+    /** The type token this registration answers for (as opened). */
+    type: string;
+    /** Human label ("Task", "File"). */
+    label: string;
+    icon: ComponentType<{
+        className?: string;
+    }>;
+    /** Accent classes for the icon and type chip; semantic tokens only. */
+    accent?: {
+        text: string;
+        bg: string;
+        ring: string;
+    } | null;
+    /**
+     * The canonical entity-registry token for doors, associations and history.
+     * `null` when the type is not a registry entity — the header then offers
+     * copy-id only, and the associations / history sections are absent.
+     */
+    entityToken: string | null;
+    /**
+     * Load the full row. `null` when the type has no single canonical source
+     * (the detail then renders from the seed alone and says so).
+     */
+    load: ((id: string, signal: AbortSignal) => Promise<DetailLoadResult<Row>>) | null;
+    /** The title to show; receives the loaded row (or null) and the seed. */
+    title: (row: Row | null, seed: DetailSeed | null) => string;
+    /**
+     * 🚨 WHAT THIS ROW IS, WHEN THE TYPE CANNOT SAY (chair, 2026-09-18). `label` is
+     * per TYPE, and a registered type is regularly a family: `crm.party` holds
+     * 1,432 companies and 460 persons, so a type labelled "Person" told a person
+     * that a company is a person — twice on screen, above a field reading
+     * `organization` (VERIFY-U-P1-R5, N6). A registration that can tell the
+     * difference from the row answers here.
+     *
+     * It names the RECORD, so it is used for the header's type chip and for the
+     * stand-in titles ("Company 3f2a1b9c") only. The presentation pane keeps the
+     * type-level `label`, because "Every contact record now opens as a window" is a
+     * statement about the TYPE's setting, not about the row on screen.
+     *
+     * `null` (or omitted) falls back to `label`, then to the raw type token.
+     */
+    labelForRow?: (row: Row | null) => string | null;
+    /** The field list for the fields section. */
+    fields: (row: Row) => DetailField[];
+    /**
+     * 🚨 THE SOURCE HEALTH STRIP'S PRODUCER. Source health for a SYNCED record;
+     * omit it, or answer `null`, for a record the platform owns outright.
+     *
+     * It may be ASYNC, because whether the grant behind a synced record still works
+     * is not in the row — it is the connector's recorded per-capability health, read
+     * from the server. The host wires this field when it registers the record type
+     * (never a second reader of the connector's health), and `useDetailHealth`
+     * resolves it. Until 2026-09-17 nothing set it, so the strip could not render on
+     * any record and the promise that a refusal anywhere shows on every dependent
+     * record with the same Reconnect had no witness (VERIFY-U-P1-R4).
+     */
+    health?: DetailHealthProducer<Row> | null;
+    /**
+     * Tokens the associations section shows. `null` hides the section.
+     * Omitted → the host's default set minus this record's own token.
+     */
+    associationTokens?: string[] | null;
+    /** Show the history section (row versions). Default: when `entityToken` is set. */
+    history?: boolean;
+    /** Extra sections under the fixed ones. */
+    extraSections?: ((row: Row | null, ctx: DetailFrameContext) => DetailSection[]) | null;
+    /**
+     * Wraps the whole body (surface runtime, right-click menu, …). Receives the
+     * live context so a host can expose the dossier to its agents. Optional.
+     */
+    Frame?: ComponentType<{
+        ctx: DetailFrameContext;
+        children: ReactNode;
+    }> | null;
+}
+type DetailStatus = "loading" | "ready" | "not-found" | "error"
+/** The type has no `load` — rendered from the seed alone. */
+ | "none";
+type DetailLoadState<Row extends DetailRow = DetailRow> = {
+    status: "loading";
+} | {
+    status: "ready";
+    row: Row;
+} | {
+    status: "not-found";
+} | {
+    status: "error";
+    message: string;
+} | {
+    status: "none";
+};
+/** One row of the history section. */
+interface DetailHistoryEntry {
+    version: number;
+    operation: string;
+    actorId: string | null;
+    occurredAt: string;
+    isCurrent: boolean;
+}
+
+/** Props every shell receives; the package fills the slots, the host owns the chrome. */
+interface DetailShellSlots {
+    /** Accessible plain-text title (window chrome, drawer title, document title). */
+    title: string;
+    /** Rich title: icon · name · type chip · the record's doors. */
+    titleNode: ReactNode;
+    /** Presentation switcher · previous / next · copy id. Compact. */
+    actions: ReactNode;
+    children: ReactNode;
+    onClose: () => void;
+}
+interface DetailWindowShellProps extends DetailShellSlots {
+    /** `type.id` — the deep-link instance and the window manager's key. */
+    instanceKey: string;
+    target: DetailRef;
+    /**
+     * 🚨 NEW-15 — THE LIST TRAVELS INTO THE DEEP LINK. The window's `?panels=`
+     * token used to carry the record and the presentation only, so a REFRESH lost
+     * the previous / next controls and the counter without a word. The shell puts
+     * this into the token the way the page presentation puts it into the query.
+     */
+    list: DetailListContext | null;
+}
+interface DetailDockedShellProps extends DetailShellSlots {
+    instanceKey: string;
+    target: DetailRef;
+}
+interface DetailPageShellProps extends DetailShellSlots {
+    target: DetailRef;
+    /** Back affordance — the page is the one presentation that left the URL. */
+    onBack: () => void;
+}
+interface DetailEffectivePresentation {
+    /** The effective presentation for this type, `undefined` when unresolved. */
+    value: DetailPresentation | undefined;
+    /** The per-record-type exception still in effect, from ANY rung. */
+    forType: DetailPresentation | undefined;
+}
+interface DetailPresentationSetting {
+    /** `undefined` while unresolved; `error` names the failure — never both silent. */
+    value: DetailPresentation | undefined;
+    error: string | null;
+    /**
+     * The PER-RECORD-TYPE exception in effect for this type, when there is one
+     * (`undefined` = this type opens the way the default says). The pane offers
+     * "use the default for this type" only then — an offer to remove something
+     * that does not exist is a control that does nothing (NEW-2).
+     */
+    forType?: DetailPresentation | undefined;
+}
+interface DetailShells {
+    Window?: ComponentType<DetailWindowShellProps>;
+    Docked?: ComponentType<DetailDockedShellProps>;
+    Page?: ComponentType<DetailPageShellProps>;
+}
+interface DetailHostPorts {
+    /**
+     * The ONE record-type map. `null` = the host has no registration for the
+     * type. Bound by each presentation's entry (with its shell), not at boot —
+     * the map pulls the registry and the frame into whatever imports it.
+     */
+    resolveType?: (type: string) => DetailRecordType | null;
+    /** React face — the effective `ui.detail.default_presentation` for a type. A hook. */
+    usePresentationSetting: (type: string) => DetailPresentationSetting;
+    /** Awaited face for click handlers. Rejects with the resolver's error. */
+    resolvePresentation: (type: string) => Promise<DetailPresentation>;
+    /** Warm the cache so the click path is synchronous. */
+    warmPresentation: (type: string) => void;
+    /**
+     * 🚨 NEW-10 (VERIFY-U-P1-R3) — RE-READ THE LADDER AFTER A WRITE, AND SAY WHAT
+     * ANSWERS NOW. Removing your own per-type exception while your ORGANIZATION
+     * holds one for the same type succeeded and the pane promised the records
+     * "now open the way you normally open records" — they did not; the
+     * organization's entry still won on the next open and nothing re-read the
+     * ladder. A host binds this to a FRESH ladder read (cache invalidated), never
+     * to the cached value the write just made stale. Optional: a host that cannot
+     * re-read says so and the pane promises nothing.
+     */
+    reReadPresentation?: (type: string) => Promise<DetailEffectivePresentation>;
+    /**
+     * Write the person's presentation setting from inside a detail (the ONE
+     * screen that writes `ui.detail.default_presentation`). `forType` non-null
+     * writes the PER-RECORD-TYPE override instead of the default.
+     *
+     * `clear` with a `forType` REMOVES that record type's exception instead of
+     * setting one, so an exception set from a record can be taken back from the
+     * same place (NEW-2). It is the same map-entry write with the key absent — a
+     * host never grows a second writer for it.
+     *
+     * Optional: a host that can only READ the setting binds nothing and the pane
+     * is absent — never a disabled-looking control. A refusal comes back as
+     * `{ ok: false, reason }` (the settings ladder's reasons are sentences and
+     * the surface renders them), never as a thrown error.
+     */
+    savePresentation?: (args: {
+        presentation: DetailPresentation;
+        forType: string | null;
+        clear?: boolean;
+    }) => Promise<{
+        ok: true;
+    } | {
+        ok: false;
+        reason: string;
+    }>;
+    /** Open an in-place presentation (window / docked). Page goes through `navigate`. */
+    open: (args: {
+        presentation: Exclude<DetailPresentation, "page">;
+        data: DetailInstanceData;
+    }) => void;
+    close: (presentation: Exclude<DetailPresentation, "page">) => void;
+    navigate: {
+        pageHref: (ref: DetailRef, extra?: {
+            list?: DetailListContext | null;
+        }) => string;
+        toPage: (ref: DetailRef, extra?: {
+            seed?: DetailSeed | null;
+            list?: DetailListContext | null;
+            /**
+             * 🚨 NEW-14 (VERIFY-U-P1-R3) — MOVING INSIDE A LIST REPLACES, NEVER
+             * PUSHES. Arrowing to a neighbour on the page pushed a history entry,
+             * so twenty records meant twenty Backs and the chevron labelled "Back"
+             * returned to the previous RECORD instead of the list. The record whose
+             * history entry is being replaced, so the host can carry its "this tab
+             * pushed a detail page" answer (`canGoBack`) forward to the record now
+             * showing. Absent ⇒ a push, which is what opening a page IS.
+             */
+            replacing?: DetailRef | null;
+        }) => void;
+        back: () => void;
+        /**
+         * 🚨 D1. Whether THIS tab reached the detail page from inside the app, so
+         * `back()` lands on a screen the person was actually on. A deep link
+         * opened in a fresh tab has NOTHING behind it: `back()` there leaves the
+         * tab on `about:blank` with the whole app gone (measured 2026-09-17).
+         * A host answers `false` whenever it is not certain.
+         */
+        canGoBack: (ref: DetailRef) => boolean;
+        /**
+         * Where the page goes when there is nothing behind it: the record's own
+         * home (its canonical route), or the host's home when the type has none.
+         * REPLACES the detail page — it is being left, not stacked on.
+         */
+        toRecordHome: (ref: DetailRef, entityToken: string | null) => void;
+    };
+    shells: DetailShells;
+    doors: {
+        /** The record's own doors (open / new tab / peek) — sibling of the title. */
+        RecordDoors: ComponentType<{
+            token: string;
+            id: string;
+            name?: string | null;
+        }>;
+        /** A reference inside the record — never a bare uuid. */
+        /**
+         * One id rendered as a door. `name` is the record's own name when the caller
+         * has it — a door showing a truncated uuid is half a dead end (chair,
+         * 2026-09-18), so a host that can name the record renders the name and keeps
+         * the id for the copy control.
+         */
+        RefCell: ComponentType<{
+            value: string;
+            label: string;
+            token: string;
+            name?: string | null;
+        }>;
+        tokenFromColumnName: (column: string) => string | null;
+        isUuidValue: (value: unknown) => value is string;
+        /**
+         * 🚨 NEW-17 (VERIFY-U-P1-R4) — WHETHER THIS RECORD REALLY OPENS ANYWHERE.
+         * `RecordDoors` renders nothing when the token has no route and no peek, so
+         * the honest absent state promised "the controls above still open it where it
+         * lives" beside a header that carried no such control — for `session`, and for
+         * every unregistered type. The body's sentence is derived from this answer,
+         * never fixed.
+         */
+        hasDoor: (token: string, id: string) => boolean;
+    };
+    associations: {
+        /** Tokens shown when a registration does not name its own. */
+        defaultTokens: readonly string[];
+        /** Whether a token may anchor an associations section at all. */
+        canAnchor: (token: string) => boolean;
+    };
+    history: {
+        list: (token: string, id: string, signal: AbortSignal) => Promise<DetailHistoryEntry[]>;
+        /**
+         * 🚨 NEW-23 (VERIFY-U-P1-R5) — WHO MADE THE CHANGE IS A PERSON, NOT AN ID.
+         * Every history row printed a bare 36-character uuid under "Changed by",
+         * because no `actor` or `user` token has a door in a host's registry: an
+         * identity the UI names that opens nothing and says nothing (the
+         * no-dead-ends class). A host binds its ONE existing identity resolver here
+         * — never a second one — and the row shows the person's name. Optional: a
+         * host that has no directory binds nothing and the row keeps the id under a
+         * title that says what it is, which is honest rather than silent.
+         *
+         * It is given the record's own row too, because the directory a host may
+         * legitimately read is usually the owning organization's members and the
+         * row is where that organization is named.
+         */
+        ActorName?: ComponentType<{
+            actorId: string;
+            row: DetailRow | null;
+        }>;
+    };
+    notify: {
+        error: (message: string) => void;
+        success: (message: string) => void;
+    };
+    copyText: (text: string) => Promise<boolean>;
+    /**
+     * 🚨 THE SAME RECONNECT THE CONNECTOR ROWS SHOW. A synced record whose grant
+     * has expired, been revoked or lost a scope offers exactly the repair the
+     * connector surface offers, from the record's own health strip, so a person
+     * never has to go and find the connections screen. Optional: a host that
+     * cannot open a consent flow binds nothing and the strip states the problem
+     * without offering a control that would not help (law 4). A producer that
+     * answers `onReconnect: null` overrides this for its record — see
+     * `DetailSourceHealth.onReconnect`.
+     */
+    reconnectSource?: (ref: DetailRef, source: string) => void;
+    /**
+     * Where the developer goes to fix an unregistered or sourceless type — a
+     * phrase for the console remedy the core prints once per type per tab (the
+     * PERSON sees a plain sentence; the developer sees this). Optional: the
+     * default names the `resolveType` port. A host names its own registry, e.g.
+     * "the item registry (features/item-presentation/registry.tsx)".
+     */
+    remedy?: {
+        typeMap: string;
+    };
+}
+/**
+ * Binds ports. Nested providers merge over their parent, shells included, so
+ * a presentation entry can add only its own shell.
+ */
+declare function DetailHostProvider({ ports, children, }: {
+    ports: Partial<DetailHostPorts>;
+    children: ReactNode;
+}): react.JSX.Element;
+/**
+ * The bound ports. Throws with the remedy when a port is missing — a detail
+ * that opened with no host would otherwise render every section empty and
+ * look finished.
+ */
+declare function useDetailHost(): DetailHostPorts;
+/** The record-type map, or an error naming which entry forgot to bind it. */
+declare function requireResolveType(host: DetailHostPorts): NonNullable<DetailHostPorts["resolveType"]>;
+/** A presentation's shell, or an error naming which entry forgot to bind it. */
+declare function requireShell<K extends keyof DetailShells>(shells: DetailShells, which: K): NonNullable<DetailShells[K]>;
+
+export { type DetailRef as D, type DetailInstanceData as a, type DetailPresentation as b, type DetailRecordType as c, type DetailStatus as d, type DetailRow as e, type DetailField as f, type DetailSourceHealth as g, type DetailFrameContext as h, type DetailListContext as i, type DetailLoadState as j, type DetailOpenRequest as k, type DetailDockedShellProps as l, type DetailEffectivePresentation as m, type DetailHostPorts as n, DetailHostProvider as o, type DetailPageShellProps as p, type DetailPresentationSetting as q, type DetailShellSlots as r, type DetailShells as s, type DetailWindowShellProps as t, requireResolveType as u, requireShell as v, useDetailHost as w };