@ai-matrx/detail 0.1.0

package/dist/react.d.cts

@@ -0,0 +1,191 @@
+import { D as DetailRef, a as DetailInstanceData, b as DetailPresentation, c as DetailRecordType, d as DetailStatus, e as DetailRow, f as DetailField, g as DetailSourceHealth, h as DetailFrameContext, i as DetailListContext, j as DetailLoadState, k as DetailOpenRequest } from './host-eKqulRpB.cjs';
+export { l as DetailDockedShellProps, m as DetailEffectivePresentation, n as DetailHostPorts, o as DetailHostProvider, p as DetailPageShellProps, q as DetailPresentationSetting, r as DetailShellSlots, s as DetailShells, t as DetailWindowShellProps, u as requireResolveType, v as requireShell, w as useDetailHost } from './host-eKqulRpB.cjs';
+import * as react from 'react';
+import { KeyboardEvent } from 'react';
+
+interface DetailKeyboardHandlers {
+    onClose?: (() => void) | null;
+    onPrev?: (() => void) | null;
+    onNext?: (() => void) | null;
+    /**
+     * 🚨 NEW-22 (VERIFY-U-P1-R4) — CMD+ENTER NEVER VANISHES. The chord is one of
+     * the three bindings the primitive promises, and nothing is registered to save
+     * unless a section with an editor is open, so the keystroke was swallowed in
+     * silence on every read-only record. A deliberate keystroke gets an answer.
+     */
+    onSaveUnavailable?: (() => void) | null;
+}
+interface DetailKeyboard {
+    /** Spread onto the presentation root. */
+    rootProps: {
+        tabIndex: -1;
+        onKeyDownCapture: (event: KeyboardEvent<HTMLElement>) => void;
+    };
+    /** A section with an editor registers its save; returns the unregister. */
+    registerSave: (save: () => void | Promise<void>) => () => void;
+    /** Whether anything is registered — the switcher shows the hint only then. */
+    hasSave: () => boolean;
+}
+declare function useDetailKeyboard(handlers: DetailKeyboardHandlers): DetailKeyboard;
+
+interface DetailCore {
+    ref: DetailRef;
+    data: DetailInstanceData;
+    presentation: DetailPresentation;
+    /** `null` when the host has no registration for this type — the body says so. */
+    recordType: DetailRecordType | null;
+    status: DetailStatus;
+    /** Set when `status === "error"`. */
+    errorMessage: string | null;
+    row: DetailRow | null;
+    title: string;
+    /** The title is a stand-in (loading / not found / failed), not a record's name. */
+    titleIsStandIn: boolean;
+    /**
+     * 🚨 NEW-9 — WHETHER THE RECORD'S OWN DOORS MAY SHOW. A question about the
+     * RECORD, not about its name: a record that exists but stores nothing more
+     * here still opens in its home, and a title that could not be loaded has no
+     * record behind it to open. The header hung the doors off `titleIsStandIn`,
+     * which is why a type with no source became a named dead end.
+     */
+    doorsAvailable: boolean;
+    /**
+     * 🚨 NEW-17 — WHETHER A CONTROL THAT OPENS THIS RECORD SOMEWHERE ELSE IS
+     * ACTUALLY ON THE SCREEN (the token resolves to a route or a peek). The body's
+     * absent-state sentence is derived from this; it used to promise a door for
+     * every type, including the ones whose header shows none.
+     */
+    canOpenElsewhere: boolean;
+    /**
+     * Human label for the record TYPE ("File") — for a statement about the type,
+     * such as the presentation setting's "Every file record now opens as a window".
+     */
+    typeLabel: string;
+    /**
+     * What THIS ROW is ("Company" for a `crm.party` row whose `party_kind` is
+     * `organization`, where `typeLabel` says "Person"). The header's type chip and
+     * the stand-in titles use this; `typeLabel` when the registration cannot tell
+     * the difference. See `DetailRecordType.labelForRow`.
+     */
+    recordLabel: string;
+    about: string | null;
+    fields: DetailField[];
+    /**
+     * The source health strip's content — `null` for a record the platform owns
+     * outright, or while a producer that reads it from the host is still
+     * answering. See `useDetailHealth`.
+     */
+    health: DetailSourceHealth | null;
+    /** The entity token doors / associations / history key off; null = none. */
+    entityToken: string | null;
+    frameCtx: DetailFrameContext | null;
+    keyboard: DetailKeyboard;
+    list: {
+        context: DetailListContext | null;
+        hasPrev: boolean;
+        hasNext: boolean;
+        prev: () => void;
+        next: () => void;
+    };
+    /** Re-open this record in another presentation and leave the current one. */
+    switchTo: (presentation: DetailPresentation) => void;
+    /**
+     * 🚨 D1 — THE ONE EXIT FROM THE PAGE PRESENTATION. Back chevron, Escape and
+     * a switch that leaves the route all come here; no host, route or shell may
+     * call `back()` itself.
+     */
+    leave: () => void;
+    close: () => void;
+}
+declare function useDetailCore(data: DetailInstanceData, presentation: DetailPresentation, 
+/**
+ * `onClose` is how an IN-PLACE presentation is dismissed (the overlay's
+ * close). The page presentation needs none: it is left through `leave`,
+ * which is the guarded exit — see `close` below.
+ */
+options: {
+    onClose?: () => void;
+}): DetailCore;
+
+declare function useDetailRecord(recordType: DetailRecordType | null, id: string | null): DetailLoadState<DetailRow>;
+
+interface UseDetailHealthArgs {
+    recordType: DetailRecordType | null;
+    /** The loaded row — health is only ever produced for a record that loaded. */
+    row: DetailRow | null;
+    ref: DetailRef;
+    /** The host's reconnect action for this record's source, when it has one. */
+    reconnect: ((ref: DetailRef, source: string) => void) | null;
+}
+/**
+ * The strip's Reconnect for a producer's answer: the producer's own action, its
+ * explicit refusal (`null`), or — only when it said nothing — the host's.
+ *
+ * 🚨 AND `grant: "blocked"` NEVER GETS ONE (chair, 2026-09-18). The word means
+ * the source refuses and nothing the person can click repairs it, so the refusal
+ * is structural here rather than a promise each producer must remember to keep:
+ * a host that binds `reconnectSource` cannot put the button back, and neither
+ * can a producer that supplies an action by mistake.
+ */
+declare function reconnectFor(value: DetailSourceHealth, hostReconnect: ((source: string) => void) | null): (() => void) | null;
+declare function useDetailHealth({ recordType, row, ref, reconnect, }: UseDetailHealthArgs): DetailSourceHealth | null;
+
+type OpenDetail = (request: DetailOpenRequest) => Promise<DetailPresentation>;
+/**
+ * @param warmType a record type this surface will open — its setting is
+ * resolved on mount so the click is synchronous.
+ */
+declare function useOpenDetail(warmType?: string | null): OpenDetail;
+
+declare function DetailTitle({ core }: {
+    core: DetailCore;
+}): react.JSX.Element;
+/**
+ * The type, the id and the record's doors, in the BODY — where the header
+ * hands them off below `sm`, and where the id lives at every width now that
+ * the header cluster is icons only.
+ */
+declare function DetailRecordMeta({ core }: {
+    core: DetailCore;
+}): react.JSX.Element;
+declare function DetailActions({ core }: {
+    core: DetailCore;
+}): react.JSX.Element;
+
+declare function DetailBody({ core }: {
+    core: DetailCore;
+}): react.JSX.Element;
+
+declare function DetailPresentationPane({ core }: {
+    core: DetailCore;
+}): react.JSX.Element | null;
+
+interface DetailPresentationProps {
+    data: DetailInstanceData;
+    onClose: () => void;
+}
+declare function DetailWindowPresentation({ data, onClose }: DetailPresentationProps): react.JSX.Element;
+declare function DetailDockedPresentation({ data, onClose }: DetailPresentationProps): react.JSX.Element;
+/**
+ * 🚨 D1 — THE PAGE OWNS ITS OWN EXIT. It accepts no `onBack` FROM ITS CALLER: the
+ * route passes none, and this component is what fills the shell's `onBack` slot,
+ * with `core.leave` — so the back chevron, Escape and a presentation switch all
+ * leave through the one guarded exit (`canGoBack` → `back()`, otherwise the
+ * record's own home). A route that passed its own `router.back()` in here is
+ * exactly how a pasted or bookmarked detail link still landed the tab on
+ * `about:blank` after round 1's fix (VERIFY-U-P1-R2, D1). N9 (VERIFY-U-P1-R5):
+ * this sentence used to read "It takes no `onBack`" directly above the line that
+ * passes one, which is the sentence a future agent trusts.
+ */
+declare function DetailPagePresentation({ data }: {
+    data: DetailInstanceData;
+}): react.JSX.Element;
+
+/** The container the detail header's breakpoint reads — declared by the window chrome. */
+declare const DETAIL_HEADER_CONTAINER = "@container/window-header";
+/** Below this container width the optional actions move into the overflow menu. */
+declare const DETAIL_HEADER_COMPACT_BELOW = "@max-[26rem]/window-header";
+/** The floor under the record's name: ~96px, enough for a readable fragment. */
+declare const DETAIL_TITLE_MIN_WIDTH_CLASS = "min-w-[6rem]";
+
+export { DETAIL_HEADER_COMPACT_BELOW, DETAIL_HEADER_CONTAINER, DETAIL_TITLE_MIN_WIDTH_CLASS, DetailActions, DetailBody, type DetailCore, DetailDockedPresentation, type DetailKeyboard, type DetailKeyboardHandlers, DetailPagePresentation, DetailPresentationPane, type DetailPresentationProps, DetailRecordMeta, DetailTitle, DetailWindowPresentation, type OpenDetail, type UseDetailHealthArgs, reconnectFor, useDetailCore, useDetailHealth, useDetailKeyboard, useDetailRecord, useOpenDetail };

package/dist/react.d.ts

@@ -0,0 +1,191 @@
+import { D as DetailRef, a as DetailInstanceData, b as DetailPresentation, c as DetailRecordType, d as DetailStatus, e as DetailRow, f as DetailField, g as DetailSourceHealth, h as DetailFrameContext, i as DetailListContext, j as DetailLoadState, k as DetailOpenRequest } from './host-eKqulRpB.js';
+export { l as DetailDockedShellProps, m as DetailEffectivePresentation, n as DetailHostPorts, o as DetailHostProvider, p as DetailPageShellProps, q as DetailPresentationSetting, r as DetailShellSlots, s as DetailShells, t as DetailWindowShellProps, u as requireResolveType, v as requireShell, w as useDetailHost } from './host-eKqulRpB.js';
+import * as react from 'react';
+import { KeyboardEvent } from 'react';
+
+interface DetailKeyboardHandlers {
+    onClose?: (() => void) | null;
+    onPrev?: (() => void) | null;
+    onNext?: (() => void) | null;
+    /**
+     * 🚨 NEW-22 (VERIFY-U-P1-R4) — CMD+ENTER NEVER VANISHES. The chord is one of
+     * the three bindings the primitive promises, and nothing is registered to save
+     * unless a section with an editor is open, so the keystroke was swallowed in
+     * silence on every read-only record. A deliberate keystroke gets an answer.
+     */
+    onSaveUnavailable?: (() => void) | null;
+}
+interface DetailKeyboard {
+    /** Spread onto the presentation root. */
+    rootProps: {
+        tabIndex: -1;
+        onKeyDownCapture: (event: KeyboardEvent<HTMLElement>) => void;
+    };
+    /** A section with an editor registers its save; returns the unregister. */
+    registerSave: (save: () => void | Promise<void>) => () => void;
+    /** Whether anything is registered — the switcher shows the hint only then. */
+    hasSave: () => boolean;
+}
+declare function useDetailKeyboard(handlers: DetailKeyboardHandlers): DetailKeyboard;
+
+interface DetailCore {
+    ref: DetailRef;
+    data: DetailInstanceData;
+    presentation: DetailPresentation;
+    /** `null` when the host has no registration for this type — the body says so. */
+    recordType: DetailRecordType | null;
+    status: DetailStatus;
+    /** Set when `status === "error"`. */
+    errorMessage: string | null;
+    row: DetailRow | null;
+    title: string;
+    /** The title is a stand-in (loading / not found / failed), not a record's name. */
+    titleIsStandIn: boolean;
+    /**
+     * 🚨 NEW-9 — WHETHER THE RECORD'S OWN DOORS MAY SHOW. A question about the
+     * RECORD, not about its name: a record that exists but stores nothing more
+     * here still opens in its home, and a title that could not be loaded has no
+     * record behind it to open. The header hung the doors off `titleIsStandIn`,
+     * which is why a type with no source became a named dead end.
+     */
+    doorsAvailable: boolean;
+    /**
+     * 🚨 NEW-17 — WHETHER A CONTROL THAT OPENS THIS RECORD SOMEWHERE ELSE IS
+     * ACTUALLY ON THE SCREEN (the token resolves to a route or a peek). The body's
+     * absent-state sentence is derived from this; it used to promise a door for
+     * every type, including the ones whose header shows none.
+     */
+    canOpenElsewhere: boolean;
+    /**
+     * Human label for the record TYPE ("File") — for a statement about the type,
+     * such as the presentation setting's "Every file record now opens as a window".
+     */
+    typeLabel: string;
+    /**
+     * What THIS ROW is ("Company" for a `crm.party` row whose `party_kind` is
+     * `organization`, where `typeLabel` says "Person"). The header's type chip and
+     * the stand-in titles use this; `typeLabel` when the registration cannot tell
+     * the difference. See `DetailRecordType.labelForRow`.
+     */
+    recordLabel: string;
+    about: string | null;
+    fields: DetailField[];
+    /**
+     * The source health strip's content — `null` for a record the platform owns
+     * outright, or while a producer that reads it from the host is still
+     * answering. See `useDetailHealth`.
+     */
+    health: DetailSourceHealth | null;
+    /** The entity token doors / associations / history key off; null = none. */
+    entityToken: string | null;
+    frameCtx: DetailFrameContext | null;
+    keyboard: DetailKeyboard;
+    list: {
+        context: DetailListContext | null;
+        hasPrev: boolean;
+        hasNext: boolean;
+        prev: () => void;
+        next: () => void;
+    };
+    /** Re-open this record in another presentation and leave the current one. */
+    switchTo: (presentation: DetailPresentation) => void;
+    /**
+     * 🚨 D1 — THE ONE EXIT FROM THE PAGE PRESENTATION. Back chevron, Escape and
+     * a switch that leaves the route all come here; no host, route or shell may
+     * call `back()` itself.
+     */
+    leave: () => void;
+    close: () => void;
+}
+declare function useDetailCore(data: DetailInstanceData, presentation: DetailPresentation, 
+/**
+ * `onClose` is how an IN-PLACE presentation is dismissed (the overlay's
+ * close). The page presentation needs none: it is left through `leave`,
+ * which is the guarded exit — see `close` below.
+ */
+options: {
+    onClose?: () => void;
+}): DetailCore;
+
+declare function useDetailRecord(recordType: DetailRecordType | null, id: string | null): DetailLoadState<DetailRow>;
+
+interface UseDetailHealthArgs {
+    recordType: DetailRecordType | null;
+    /** The loaded row — health is only ever produced for a record that loaded. */
+    row: DetailRow | null;
+    ref: DetailRef;
+    /** The host's reconnect action for this record's source, when it has one. */
+    reconnect: ((ref: DetailRef, source: string) => void) | null;
+}
+/**
+ * The strip's Reconnect for a producer's answer: the producer's own action, its
+ * explicit refusal (`null`), or — only when it said nothing — the host's.
+ *
+ * 🚨 AND `grant: "blocked"` NEVER GETS ONE (chair, 2026-09-18). The word means
+ * the source refuses and nothing the person can click repairs it, so the refusal
+ * is structural here rather than a promise each producer must remember to keep:
+ * a host that binds `reconnectSource` cannot put the button back, and neither
+ * can a producer that supplies an action by mistake.
+ */
+declare function reconnectFor(value: DetailSourceHealth, hostReconnect: ((source: string) => void) | null): (() => void) | null;
+declare function useDetailHealth({ recordType, row, ref, reconnect, }: UseDetailHealthArgs): DetailSourceHealth | null;
+
+type OpenDetail = (request: DetailOpenRequest) => Promise<DetailPresentation>;
+/**
+ * @param warmType a record type this surface will open — its setting is
+ * resolved on mount so the click is synchronous.
+ */
+declare function useOpenDetail(warmType?: string | null): OpenDetail;
+
+declare function DetailTitle({ core }: {
+    core: DetailCore;
+}): react.JSX.Element;
+/**
+ * The type, the id and the record's doors, in the BODY — where the header
+ * hands them off below `sm`, and where the id lives at every width now that
+ * the header cluster is icons only.
+ */
+declare function DetailRecordMeta({ core }: {
+    core: DetailCore;
+}): react.JSX.Element;
+declare function DetailActions({ core }: {
+    core: DetailCore;
+}): react.JSX.Element;
+
+declare function DetailBody({ core }: {
+    core: DetailCore;
+}): react.JSX.Element;
+
+declare function DetailPresentationPane({ core }: {
+    core: DetailCore;
+}): react.JSX.Element | null;
+
+interface DetailPresentationProps {
+    data: DetailInstanceData;
+    onClose: () => void;
+}
+declare function DetailWindowPresentation({ data, onClose }: DetailPresentationProps): react.JSX.Element;
+declare function DetailDockedPresentation({ data, onClose }: DetailPresentationProps): react.JSX.Element;
+/**
+ * 🚨 D1 — THE PAGE OWNS ITS OWN EXIT. It accepts no `onBack` FROM ITS CALLER: the
+ * route passes none, and this component is what fills the shell's `onBack` slot,
+ * with `core.leave` — so the back chevron, Escape and a presentation switch all
+ * leave through the one guarded exit (`canGoBack` → `back()`, otherwise the
+ * record's own home). A route that passed its own `router.back()` in here is
+ * exactly how a pasted or bookmarked detail link still landed the tab on
+ * `about:blank` after round 1's fix (VERIFY-U-P1-R2, D1). N9 (VERIFY-U-P1-R5):
+ * this sentence used to read "It takes no `onBack`" directly above the line that
+ * passes one, which is the sentence a future agent trusts.
+ */
+declare function DetailPagePresentation({ data }: {
+    data: DetailInstanceData;
+}): react.JSX.Element;
+
+/** The container the detail header's breakpoint reads — declared by the window chrome. */
+declare const DETAIL_HEADER_CONTAINER = "@container/window-header";
+/** Below this container width the optional actions move into the overflow menu. */
+declare const DETAIL_HEADER_COMPACT_BELOW = "@max-[26rem]/window-header";
+/** The floor under the record's name: ~96px, enough for a readable fragment. */
+declare const DETAIL_TITLE_MIN_WIDTH_CLASS = "min-w-[6rem]";
+
+export { DETAIL_HEADER_COMPACT_BELOW, DETAIL_HEADER_CONTAINER, DETAIL_TITLE_MIN_WIDTH_CLASS, DetailActions, DetailBody, type DetailCore, DetailDockedPresentation, type DetailKeyboard, type DetailKeyboardHandlers, DetailPagePresentation, DetailPresentationPane, type DetailPresentationProps, DetailRecordMeta, DetailTitle, DetailWindowPresentation, type OpenDetail, type UseDetailHealthArgs, reconnectFor, useDetailCore, useDetailHealth, useDetailKeyboard, useDetailRecord, useOpenDetail };