@zephytiju/prism-quick-files 0.1.0

package/README.md

@@ -0,0 +1,192 @@
+# PrismQuickFilesMicroUI
+
+Platform Prism quick-files micro-UI. Component id: `quick-files`.
+Published to npm as [`@zephytiju/prism-quick-files`](https://www.npmjs.com/package/@zephytiju/prism-quick-files).
+
+The Dossier **Quick File Insert** side panel — an axiom component, sibling of the editor viewport
+(not a sub-component of it): the `QUICK FILE INSERT` title header (title, subtitle, trailing meta
+are component configuration keys — Prism has no composed title node), the bordered search box, the
+`FILES ARE THE SHORTCUT` / `RECENT / COMMON FILES` section labels, per-prototype file rows (world
+view / dossier doc / board / folder icons on semantic kind tokens, name + mono meta line, `+`
+insert action) and the `DROP-IN FILE MODEL` info card. Rows are indexed through the `IFileEntry`
+list query via the generated interface client over the host Lattice transport. Composed
+applications (for example Guanlan) consume it as-is; the component is platform-owned.
+
+## D6 — the drag/insert state contract (the heart of this component)
+
+The panel **never references any receiving component**. On insert (`+`) or drag-start of a file
+row it publishes ONLY a bounded drag/insert state object carrying file metadata — never a
+component reference — on the `quick-files.drag-state` Prism channel; **ESC and drag-end clear it**
+(drop or cancel alike). Receivers interpret the payload themselves:
+
+| Receiver | Interpretation |
+| --- | --- |
+| world view | Geovision Embed block restoring the `IGeoView` snapshot addressed by `snapshotRef` (the drop-in file model) |
+| evidence pack | Evidence Table block |
+| dossier | new paragraph carrying an inline reference link (per D10, links are inline in paragraph text — never standalone blocks) |
+| unknown kind | paragraph with a generic inline file link |
+
+Because only state flows between them, the panel and the editor can be composed into different
+side-panel/viewport layouts without either knowing about the other (design decision D6 — this
+component is the reference case).
+
+## Configuration keys
+
+| Prop | Meaning |
+| --- | --- |
+| `locale` | UI locale for the component-fixed strings: `"en" \| "zh-CN"` (default `"en"`) — see [i18n](#internationalization-i18n) |
+| `title` | Panel title header (defaults to the locale's `panelTitle`, `"QUICK FILE INSERT"`) |
+| `subtitle` | Mono subtitle under the title (defaults to the locale's `panelSubtitle`) |
+| `trailingMeta` | Trailing header meta (defaults to the locale's `{count} FILES` pattern with the live row count) |
+| `variant` | `"rail"` (default full side panel) or `"popover"` (compact, anchored to a block's `+` control; no info card) |
+| `categoryFilters` | Restrict rendered rows to these `IFileEntry` kinds (world views, dossiers, boards, evidence, folders) |
+| `recencyWindowMs` | Keep rows whose `lastOpenedAt` lies within this window; entries without a timestamp are kept |
+| `kindTokens` | File kind → semantic color token overrides (defaults: world view → `signal`, doc/evidence → `ok`, board → `warn`, folder → `accent`) |
+
+## Channel contract
+
+| Direction | Kind | Id | Payload |
+| --- | --- | --- | --- |
+| publishes | state | `quick-files.drag-state` | `{ entryId, kind, name, mime, snapshotRef, sourcePanel: "quick-files" } \| null` — published on `+` insert and on drag-start, cleared (`null`) on drag-end and ESC |
+
+Channel ids are string literals at every call-site so the build-time channel-graph scanner can
+derive the graph. The publication is setter-only (`usePrismStateSetter`): the panel never
+re-renders from its own or anyone's publications. The panel also mirrors the payload into the
+HTML5 data transfer (`application/x-prism-quick-file`) on real drags so non-Prism drop targets
+work too. The panel consumes no channels.
+
+## Lattice binding
+
+Rows come from the interface-declared `interfaces/IFileEntry/list` query, invoked through the
+generated `createFileEntryClient` from `@zephytiju/lattice-common-interfaces` over
+`useLatticeTransport` — no URLs, clients, or credentials in component code. The generated bundle's
+bounded summary (`id`/`name`/`kind`/`sizeBytes`) is a structural subset of the panel's row
+projection (`mime`, `snapshotRef`, mono meta line, pin, recency); richer hosts return the superset
+on the same route. Missing `mime`/`snapshotRef` fields fall back to bounded defaults (kind mime
+map; the entry id as the snapshot address). The fetch lifecycle (busy skeletons, error alert with
+Retry, guided empty state) is local state only — the panel publishes nothing about its own
+loading.
+
+## Audit rule
+
+File browsing and insertion are routine actions and are NOT audit-worthy. This component emits NO
+audit event and NO Prism event of any kind — the single outbound signal is the bounded drag/insert
+state above.
+
+## Internationalization (i18n)
+
+The component ships `en` and `zh-CN` locale bundles — `src/locales/en.json` / `src/locales/zh-CN.json` —
+and every component-fixed UI string is resolved from them (the panel title default, subtitle
+default, `{count} FILES` pattern, search placeholder and label, section labels, the DROP-IN FILE
+MODEL card, empty/no-match copy, error title, Retry). The component renders no hardcoded copy.
+
+```json
+{
+  "quick-files": {
+    "panelTitle": "QUICK FILE INSERT",
+    "panelSubtitle": "WORLD VIEWS, DOSSIERS, BOARDS, EVIDENCE",
+    "trailingMetaCount": "{count} FILES",
+    "searchPlaceholder": "Search recent files and world views",
+    "sectionHint": "FILES ARE THE SHORTCUT",
+    "sectionRecent": "RECENT / COMMON FILES",
+    "infoCardTitle": "DROP-IN FILE MODEL",
+    "infoCardBody": "World views are versioned spatial metadata files. …",
+    "emptyTitle": "No files yet",
+    "retry": "Retry"
+  }
+}
+```
+
+- `locale?: "en" | "zh-CN"` prop (default `"en"`) selects the string table per instance.
+- `trailingMetaCount` uses a simple `{count}` placeholder interpolated with the visible row count
+  (plain substitution, no regexes — `formatMessage` is exported from the package entry).
+- **Composition-authored strings are localized by the composer; component-fixed strings live in the
+  locale JSONs.** An explicit `title` / `subtitle` / `trailingMeta` override is
+  configuration-authored: a host with a localized title passes its own string per locale.
+- Locale bundles are namespaced under the component id (`"quick-files"`) so a composer can
+  deep-merge every component's bundle into ONE UI language bundle without collisions:
+
+```ts
+import { locales as quickFilesLocales } from "@zephytiju/prism-quick-files";
+// quickFilesLocales["zh-CN"] -> { "quick-files": { … } }
+const uiBundle = deepMerge(hostStrings, quickFilesLocales["zh-CN"]);
+```
+
+The parsed bundles are exported from the package entry (`locales`, `en`, `zhCN`,
+`stringsForLocale`), and the raw JSONs are also served by the `./locales/*` exports subpath
+(e.g. `@zephytiju/prism-quick-files/locales/zh-CN.json`); `files` ships both `dist` and `locales`.
+
+## Theme
+
+No palette is hardcoded. Every color resolves to SEMANTIC theme tokens (`ok`, `accent`,
+`threat`, `warn`, `signal`, `card`, `card-dark`, `border`, `line`, `text`, `muted`, `input`,
+`deep`, `panel`) consumed as CSS variables, plus `--mantine-font-family-monospace` for the mono
+typography — the palette is supplied entirely by the host's `MantineProvider`. The prototype's
+kind hues map onto tokens: purple world views → `signal`, mint docs → `ok`, amber boards → `warn`,
+blue folders (and the `+` insert action, search border, subtitle) → `accent`. The local demo ships
+TWO themes, both defined in `src/demo.tsx`: `geovisionTheme` (dark), mapping each semantic token
+onto the exact `:root` variables of the authoritative v9 prototype, and the contrasting
+`latticeLightTheme` (light) mapping the SAME semantic token keys onto a different palette — the
+component is skinned purely through the surrounding `MantineProvider`.
+
+## Source layout
+
+`src/` is strictly two parts:
+
+- Component source (what the package compiles): `QuickFiles.tsx` (the panel),
+  `FileRow.tsx` (item-level row owning the `quick-files.drag-state` publication),
+  `icons.tsx` (the prototype's `.fic` glyph set + kind token defaults), `types.ts` (bounded
+  channel/route types), `index.ts` (public entry), and `src/locales/` (`en.json`, `zh-CN.json`,
+  `index.ts` — the i18n string bundles, their resolver, and the `{count}` interpolation helper).
+- Demo: exactly ONE file, `src/demo.tsx` — the two host themes (GeoVision v9 + Lattice Light),
+  the mock host executor answering `interfaces/IFileEntry/list` with the nine prototype rows,
+  the demo page rendering THREE `QuickFiles` hosts (dark rail + light rail + light popover with
+  category filters) behind a global EN | 中文 switcher (plus per-instance switches), and the D6
+  demonstration: a channel monitor reading the published drag state plus a mock receiver (drop
+  target) that consumes the SAME channel and interprets each kind its own way.
+
+The npm package ships `dist` (compiled component + type declarations + locale JSONs) and the
+top-level `locales/` directory (the raw JSON bundles, served by the `./locales/*` exports
+subpath); no demo code is published. `scripts/copy-locales.mjs` copies the JSON bundles into
+both locations during `npm run build`.
+
+## Local development
+
+```sh
+npm install
+npm run typecheck
+npm test
+npm run dev
+npm run shot-demo
+```
+
+`npm install` pulls the platform peers (`@zephytiju/prism-react`,
+`@zephytiju/lattice-common-interfaces`) from the npm registry, along with the host-side peer
+dependencies (`react`, `react-dom`, `@mantine/core`). When consuming the published package,
+install it directly (`npm install @zephytiju/prism-quick-files`) and provide those peer
+dependencies in the host application.
+
+The demo (`npm run dev`, entry `src/demo.tsx`) plays the host: it installs a mock action executor
+answering the interface-declared `IFileEntry` list route with the nine sample rows of the v9
+prototype, then renders three themed `QuickFiles` hosts — GeoVision v9 dark (rail), Lattice
+Light (rail), and a Lattice Light popover host restricted to world views + dossiers. A global
+EN | 中文 segmented control switches the `locale` prop of every instance at once, and each
+instance carries its own per-instance control so the hosts can render DIFFERING locales
+simultaneously. Below the hosts, the D6 demonstration: the `quick-files.drag-state` monitor
+shows the last published `{entryId, kind, name, mime, snapshotRef, sourcePanel}` payload, and the
+mock receiver materializes typed blocks from each payload (world view → Geovision Embed restoring
+the IGeoView snapshot; evidence pack → Evidence Table; dossier → paragraph with an inline link;
+unknown → generic inline file link per D10). Host affordances demonstrate clearing the state
+(same as ESC) and the error + Retry branch. `npm run shot-demo` boots the vite dev server, drives
+the demo in headless Chrome (dark host `en`, light host `zh-CN`), inserts a world view and a
+dossier row, and captures both states to `/tmp/guanlan-review/demo-quick-files-themes.png` and
+`/tmp/guanlan-review/demo-quick-files-insert.png`.
+
+## Design record
+
+https://qcnwge0wy4s0.feishu.cn/wiki/B87YwS2PriaGvlkAcOtctKm8nsd — decisions D4 (interface
+binding), D5 (component tiers — this is an axiom component), D6 (cross-component state passing —
+this component is the reference case) and D10 (inline links, embedded block chrome).
+Component doc: https://qcnwge0wy4s0.feishu.cn/wiki/KhFPwrEOIiALwpkvofrcc9KYnEe. Visual reference:
+the authoritative v9 HTML prototype (`dossier-editor-standalone-v9.html`, `.qins` / `.qrow` /
+`.fic`), attached to the design record.

package/dist/DropInModelCard.d.ts

@@ -0,0 +1,9 @@
+export interface QuickFilesDropInModelCardProps {
+    /** Locale-resolved card title (DROP-IN FILE MODEL). */
+    readonly title: string;
+    /** Locale-resolved card body copy. */
+    readonly body: string;
+}
+/** The DROP-IN FILE MODEL info card of the rail variant (v9 bottom card). */
+export declare function QuickFilesDropInModelCard({ title, body }: QuickFilesDropInModelCardProps): import("react").JSX.Element;
+//# sourceMappingURL=DropInModelCard.d.ts.map

package/dist/DropInModelCard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"DropInModelCard.d.ts","sourceRoot":"","sources":["../src/DropInModelCard.tsx"],"names":[],"mappings":"AAGA,MAAM,WAAW,8BAA8B;IAC7C,uDAAuD;IACvD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,sCAAsC;IACtC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAED,6EAA6E;AAC7E,wBAAgB,yBAAyB,CAAC,EAAE,KAAK,EAAE,IAAI,EAAE,EAAE,8BAA8B,+BAyBxF"}

package/dist/DropInModelCard.js

@@ -0,0 +1,7 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Box, Text } from "@mantine/core";
+import { ACCENT, BORDER, CARD_DARK_BG, MONO, MUTED } from "./tokens.js";
+/** The DROP-IN FILE MODEL info card of the rail variant (v9 bottom card). */
+export function QuickFilesDropInModelCard({ title, body }) {
+    return (_jsxs(Box, { p: 10, style: { background: CARD_DARK_BG, border: `1px solid ${BORDER}`, borderRadius: 5 }, "data-testid": "quick-files-info-card", children: [_jsx(Text, { ff: MONO, fz: 9, fw: 500, style: { color: ACCENT, letterSpacing: "0.04em", marginBottom: 6 }, children: title }), _jsx(Text, { ff: MONO, fz: 9, style: { color: MUTED, lineHeight: 1.6 }, "data-testid": "quick-files-info-body", children: body })] }));
+}

package/dist/FileList.d.ts

@@ -0,0 +1,25 @@
+import type { QuickFilesStrings } from "./locales/index.js";
+import type { QuickFileEntry, QuickFilesStatus } from "./types.js";
+export interface QuickFilesFileListProps {
+    /** Lifecycle of the most recent list fetch (busy / error / ready). */
+    readonly status: QuickFilesStatus;
+    /** The raw fetched entries (null while the first query is in flight). */
+    readonly entries: readonly QuickFileEntry[] | null;
+    /** Filtered + ordered rows to render (see selectVisibleRows). */
+    readonly rows: readonly QuickFileEntry[];
+    /** Locale string table for the region's fixed copy. */
+    readonly strings: QuickFilesStrings;
+    /** File kind → semantic color token overrides (defaults are curated). */
+    readonly kindTokens: Readonly<Record<string, string>>;
+    /** Re-runs the list query (the error state's Retry action). */
+    readonly onRetry: () => void;
+}
+/**
+ * The panel's rows region: busy skeletons while the first list query is in
+ * flight, an error alert with Retry, a guided empty state, the no-matches
+ * notice, and the file rows themselves (kind glyph + semantic token, name,
+ * mono meta line, + insert action — each row publishing the bounded drag
+ * state itself, per FileRow).
+ */
+export declare function QuickFilesFileList({ status, entries, rows, strings, kindTokens, onRetry }: QuickFilesFileListProps): import("react").JSX.Element;
+//# sourceMappingURL=FileList.d.ts.map

package/dist/FileList.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"FileList.d.ts","sourceRoot":"","sources":["../src/FileList.tsx"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AAC5D,OAAO,KAAK,EAAE,cAAc,EAAkB,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAInF,MAAM,WAAW,uBAAuB;IACtC,sEAAsE;IACtE,QAAQ,CAAC,MAAM,EAAE,gBAAgB,CAAC;IAClC,yEAAyE;IACzE,QAAQ,CAAC,OAAO,EAAE,SAAS,cAAc,EAAE,GAAG,IAAI,CAAC;IACnD,iEAAiE;IACjE,QAAQ,CAAC,IAAI,EAAE,SAAS,cAAc,EAAE,CAAC;IACzC,uDAAuD;IACvD,QAAQ,CAAC,OAAO,EAAE,iBAAiB,CAAC;IACpC,yEAAyE;IACzE,QAAQ,CAAC,UAAU,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IACtD,+DAA+D;IAC/D,QAAQ,CAAC,OAAO,EAAE,MAAM,IAAI,CAAC;CAC9B;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,EAAE,MAAM,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,UAAU,EAAE,OAAO,EAAE,EAAE,uBAAuB,+BA+DlH"}

package/dist/FileList.js

@@ -0,0 +1,23 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+import { Alert, Button, Card, Group, Skeleton, Stack, Text } from "@mantine/core";
+import { FileRow } from "./FileRow.js";
+import { DEFAULT_KIND_GLYPHS, DEFAULT_KIND_TOKENS } from "./icons.js";
+import { buildQuickFileDragState } from "./dragState.js";
+import { formatMessage } from "./locales/index.js";
+import { formatBytes } from "./visibleRows.js";
+import { MUTED } from "./tokens.js";
+/**
+ * The panel's rows region: busy skeletons while the first list query is in
+ * flight, an error alert with Retry, a guided empty state, the no-matches
+ * notice, and the file rows themselves (kind glyph + semantic token, name,
+ * mono meta line, + insert action — each row publishing the bounded drag
+ * state itself, per FileRow).
+ */
+export function QuickFilesFileList({ status, entries, rows, strings, kindTokens, onRetry }) {
+    return (_jsx(_Fragment, { children: status.phase === "error" ? (_jsx(Alert, { variant: "light", color: "threat", title: strings.errorTitle, "data-testid": "quick-files-error", children: _jsxs(Stack, { gap: "xs", children: [_jsx(Text, { size: "sm", "data-testid": "quick-files-error-message", children: status.message }), _jsx(Group, { children: _jsx(Button, { variant: "default", "data-testid": "quick-files-retry", onClick: onRetry, children: strings.retry }) })] }) })) : entries === null ? (_jsx(Stack, { gap: 8, "data-testid": "quick-files-loading", "aria-busy": "true", children: [0, 1, 2, 3].map((row) => (_jsx(Skeleton, { height: 58, radius: 5 }, row))) })) : entries.length === 0 ? (_jsx(Card, { withBorder: true, "data-testid": "quick-files-empty", children: _jsxs(Stack, { gap: "xs", children: [_jsx(Text, { fw: 500, children: strings.emptyTitle }), _jsx(Text, { size: "sm", children: strings.emptyHint })] }) })) : rows.length === 0 ? (_jsx(Text, { size: "sm", c: MUTED, "data-testid": "quick-files-no-matches", children: strings.noMatches })) : (_jsx(Stack, { gap: 8, "data-testid": "quick-files-rows", children: rows.map((entry) => {
+                const glyph = entry.glyph ?? DEFAULT_KIND_GLYPHS[entry.kind] ?? "doc";
+                const token = kindTokens[entry.kind] ?? DEFAULT_KIND_TOKENS[entry.kind] ?? "accent";
+                const meta = entry.meta ?? `${entry.kind.toUpperCase()} • ${formatBytes(entry.sizeBytes)}`;
+                return (_jsx(FileRow, { entry: entry, dragState: buildQuickFileDragState(entry), glyph: glyph, kindToken: token, insertLabel: formatMessage(strings.insertLabel, { name: entry.name }), dragLabel: formatMessage(strings.dragLabel, { name: entry.name }), meta: meta }, entry.id));
+            }) })) }));
+}

package/dist/FileRow.d.ts

@@ -0,0 +1,31 @@
+import type { QuickFileDragState, QuickFileEntry, QuickFileGlyph } from "./types.js";
+export interface FileRowProps {
+    /** The IFileEntry projection the row renders. */
+    readonly entry: QuickFileEntry;
+    /** Bounded drag/insert payload builder output for this row. */
+    readonly dragState: QuickFileDragState;
+    /** Icon glyph for the row's kind (boards pick workflow vs audit). */
+    readonly glyph: QuickFileGlyph;
+    /** Semantic color token driving the icon hue (host theme resolves it). */
+    readonly kindToken: string;
+    /** Accessible label for the + insert action (locale-resolved). */
+    readonly insertLabel: string;
+    /** Accessible label for the drag handle (locale-resolved). */
+    readonly dragLabel: string;
+    /** Mono meta line rendered under the name (defaults to kind + size). */
+    readonly meta: string;
+}
+/**
+ * Per-prototype Quick File Insert row (v9): kind icon, name, mono meta line
+ * and the + insert action.
+ *
+ * The row OWNS the "quick-files.drag-state" channel binding (D6 reference
+ * case): the + insert action and a drag-start each publish ONLY the bounded
+ * file-metadata state {entryId, kind, name, mime, snapshotRef, sourcePanel}
+ * — never a component reference — and drag-end (drop OR cancel) clears it.
+ * Any receiver (editor viewport body, block insertion point, another panel)
+ * interprets the payload in its own way; the row knows none of them. The
+ * setter-only binding means publications never re-render the panel.
+ */
+export declare function FileRow({ entry, dragState, glyph, kindToken, insertLabel, dragLabel, meta }: FileRowProps): import("react").JSX.Element;
+//# sourceMappingURL=FileRow.d.ts.map

package/dist/FileRow.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"FileRow.d.ts","sourceRoot":"","sources":["../src/FileRow.tsx"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,kBAAkB,EAAE,cAAc,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AAErF,MAAM,WAAW,YAAY;IAC3B,iDAAiD;IACjD,QAAQ,CAAC,KAAK,EAAE,cAAc,CAAC;IAC/B,+DAA+D;IAC/D,QAAQ,CAAC,SAAS,EAAE,kBAAkB,CAAC;IACvC,qEAAqE;IACrE,QAAQ,CAAC,KAAK,EAAE,cAAc,CAAC;IAC/B,0EAA0E;IAC1E,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,kEAAkE;IAClE,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,8DAA8D;IAC9D,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,wEAAwE;IACxE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAKD;;;;;;;;;;;GAWG;AACH,wBAAgB,OAAO,CAAC,EAAE,KAAK,EAAE,SAAS,EAAE,KAAK,EAAE,SAAS,EAAE,WAAW,EAAE,SAAS,EAAE,IAAI,EAAE,EAAE,YAAY,+BAkFzG"}

package/dist/FileRow.js

@@ -0,0 +1,54 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useCallback } from "react";
+import { Box, Group, Text, UnstyledButton } from "@mantine/core";
+import { usePrismStateSetter } from "@zephytiju/prism-react";
+import { FileKindIcon } from "./icons.js";
+import { DRAG_STATE_CHANNEL } from "./dragState.js";
+import { ACCENT, BORDER, CARD_BG, MONO, MUTED, TEXT } from "./tokens.js";
+/** MIME type carried in the HTML5 drag data so non-Prism drop targets work too. */
+const DRAG_MIME = "application/x-prism-quick-file";
+/**
+ * Per-prototype Quick File Insert row (v9): kind icon, name, mono meta line
+ * and the + insert action.
+ *
+ * The row OWNS the "quick-files.drag-state" channel binding (D6 reference
+ * case): the + insert action and a drag-start each publish ONLY the bounded
+ * file-metadata state {entryId, kind, name, mime, snapshotRef, sourcePanel}
+ * — never a component reference — and drag-end (drop OR cancel) clears it.
+ * Any receiver (editor viewport body, block insertion point, another panel)
+ * interprets the payload in its own way; the row knows none of them. The
+ * setter-only binding means publications never re-render the panel.
+ */
+export function FileRow({ entry, dragState, glyph, kindToken, insertLabel, dragLabel, meta }) {
+    const publishDragState = usePrismStateSetter(DRAG_STATE_CHANNEL);
+    const insert = useCallback(() => {
+        publishDragState(dragState);
+    }, [dragState, publishDragState]);
+    const iconColor = `var(--mantine-color-${kindToken}-filled)`;
+    return (_jsxs(Group, { gap: 10, wrap: "nowrap", align: "center", px: 12, style: {
+            minHeight: 58,
+            background: CARD_BG,
+            border: `1px solid ${BORDER}`,
+            borderRadius: 5,
+            cursor: "grab",
+        }, "data-testid": `quick-files-row-${entry.id}`, draggable: true, "aria-label": dragLabel, onDragStart: (event) => {
+            publishDragState(dragState);
+            // jsdom dispatches synthetic drags without a dataTransfer; real
+            // browsers always provide one.
+            if (event.dataTransfer) {
+                event.dataTransfer.effectAllowed = "copy";
+                event.dataTransfer.setData(DRAG_MIME, JSON.stringify(dragState));
+            }
+        }, onDragEnd: () => {
+            // Drop or cancel — the drag session is over either way: clear.
+            publishDragState(null);
+        }, children: [_jsx(Box, { style: { color: iconColor, flexShrink: 0 }, "data-testid": `quick-files-icon-${entry.id}`, children: _jsx(FileKindIcon, { glyph: glyph }) }), _jsxs(Box, { style: { flex: 1, minWidth: 0 }, children: [_jsx(Text, { fz: 12, fw: 500, style: {
+                            color: TEXT,
+                            whiteSpace: "nowrap",
+                            overflow: "hidden",
+                            textOverflow: "ellipsis",
+                        }, "data-testid": `quick-files-name-${entry.id}`, children: entry.name }), _jsx(Text, { ff: MONO, fz: 9, style: { color: MUTED, letterSpacing: "0.03em" }, "data-testid": `quick-files-meta-${entry.id}`, children: meta })] }), _jsx(UnstyledButton, { type: "button", fz: 18, fw: 500, lh: 1, style: { color: ACCENT, flexShrink: 0 }, "aria-label": insertLabel, "data-testid": `quick-files-insert-${entry.id}`, onClick: (event) => {
+                    event.stopPropagation();
+                    insert();
+                }, children: "+" })] }));
+}

package/dist/PanelHeader.d.ts

@@ -0,0 +1,17 @@
+export interface QuickFilesPanelHeaderProps {
+    /** Rail variant pads the header taller than the popover variant. */
+    readonly rail: boolean;
+    /** Resolved title — component configuration key with locale default applied. */
+    readonly title: string;
+    /** Resolved mono subtitle under the title. */
+    readonly subtitle: string;
+    /** Resolved trailing header meta (e.g. "{count} FILES"). */
+    readonly trailingMeta: string;
+}
+/**
+ * The panel's title header (v9 QUICK FILE INSERT block): title, mono subtitle
+ * and trailing meta — all component configuration keys (Prism has no composed
+ * title node), rendered with locale defaults by the composition root.
+ */
+export declare function QuickFilesPanelHeader({ rail, title, subtitle, trailingMeta }: QuickFilesPanelHeaderProps): import("react").JSX.Element;
+//# sourceMappingURL=PanelHeader.d.ts.map

package/dist/PanelHeader.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"PanelHeader.d.ts","sourceRoot":"","sources":["../src/PanelHeader.tsx"],"names":[],"mappings":"AAGA,MAAM,WAAW,0BAA0B;IACzC,oEAAoE;IACpE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IACvB,gFAAgF;IAChF,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,8CAA8C;IAC9C,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,4DAA4D;IAC5D,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;CAC/B;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,QAAQ,EAAE,YAAY,EAAE,EAAE,0BAA0B,+BAyCxG"}

package/dist/PanelHeader.js

@@ -0,0 +1,11 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Group, Stack, Text } from "@mantine/core";
+import { ACCENT, CARD_DARK_BG, MONO, MUTED, TEXT } from "./tokens.js";
+/**
+ * The panel's title header (v9 QUICK FILE INSERT block): title, mono subtitle
+ * and trailing meta — all component configuration keys (Prism has no composed
+ * title node), rendered with locale defaults by the composition root.
+ */
+export function QuickFilesPanelHeader({ rail, title, subtitle, trailingMeta }) {
+    return (_jsxs(Group, { justify: "space-between", align: "flex-start", wrap: "nowrap", gap: 8, px: 16, pt: rail ? 14 : 10, pb: 10, style: { background: CARD_DARK_BG }, "data-testid": "quick-files-header", children: [_jsxs(Stack, { gap: 4, miw: 0, children: [_jsx(Text, { fz: 13, fw: 600, style: { color: TEXT, letterSpacing: "0.01em" }, "data-testid": "quick-files-title", children: title }), _jsx(Text, { ff: MONO, fz: 9, style: { color: ACCENT, letterSpacing: "0.04em" }, "data-testid": "quick-files-subtitle", children: subtitle })] }), _jsx(Text, { ff: MONO, fz: 9, style: { color: MUTED, letterSpacing: "0.03em", flexShrink: 0, paddingTop: 2 }, "data-testid": "quick-files-trailing-meta", children: trailingMeta })] }));
+}

package/dist/QuickFiles.d.ts

@@ -0,0 +1,57 @@
+import type { QuickFilesLocale } from "./locales/index.js";
+export interface QuickFilesProps {
+    /** Panel title header (component configuration key; defaults to the locale's `panelTitle`). */
+    readonly title?: string;
+    /** Mono subtitle under the title (defaults to the locale's `panelSubtitle`). */
+    readonly subtitle?: string;
+    /** Trailing header meta (defaults to the locale's `{count} FILES` pattern). */
+    readonly trailingMeta?: string;
+    /** Layout variant: "rail" (default full side panel) or "popover" (compact, no info card). */
+    readonly variant?: "rail" | "popover";
+    /** Category filters — restrict rendered rows to these IFileEntry kinds (config key). */
+    readonly categoryFilters?: readonly string[];
+    /**
+     * Recency window in milliseconds — keep rows whose `lastOpenedAt` lies within
+     * the window (entries without a timestamp are kept; config key).
+     */
+    readonly recencyWindowMs?: number;
+    /** File kind → semantic color token overrides (defaults are curated). */
+    readonly kindTokens?: Readonly<Record<string, string>>;
+    /** UI locale for the component-fixed strings (default "en"). */
+    readonly locale?: QuickFilesLocale;
+}
+/**
+ * Platform Prism quick-files micro-UI (component id "quick-files"): the
+ * Dossier Quick File Insert side panel — an axiom component, sibling of the
+ * editor viewport (NOT a sub-component of it).
+ *
+ * Renders the per-prototype panel of the authoritative v9 HTML prototype: the
+ * QUICK FILE INSERT title header (title, subtitle and trailing meta are
+ * component configuration keys — Prism has no composed title node), the
+ * bordered search box, the FILES ARE THE SHORTCUT / RECENT-COMMON FILES
+ * section labels, file rows (world view / dossier doc / board / folder icons
+ * with semantic kind tokens, name + mono meta line, + insert action) and the
+ * DROP-IN FILE MODEL info card. Rows are indexed through the IFileEntry list
+ * query.
+ *
+ * D6 REFERENCE CASE — the panel NEVER references any receiving component. On
+ * insert (+) or drag-start of a file row it publishes ONLY a bounded drag /
+ * insert state {entryId, kind, name, mime, snapshotRef, sourcePanel} on the
+ * "quick-files.drag-state" Prism channel; receivers interpret it themselves
+ * (world view → geovision embed restoring an IGeoView snapshot; evidence pack
+ * → evidence table; dossier → paragraph with inline link; unknown → generic
+ * inline file link, per D10). ESC and drag-end clear the state. No audit
+ * events: file browsing/insertion is routine, not audit-worthy.
+ *
+ * No palette is hardcoded: every color resolves to semantic theme tokens
+ * (ok / accent / warn / signal / card / card-dark / border / line / muted /
+ * text …) supplied by the host's MantineProvider.
+ *
+ * COMPOSITION ROOT of the focused sub-component files: PanelHeader (title
+ * header), SearchBox, SectionLabels, FileList (+ FileRow, icons),
+ * DropInModelCard, and the hooks/modules clients.ts (Lattice clients),
+ * dragState.ts (bounded drag-state publication), useQuickFilesEntries.ts
+ * (list lifecycle) and visibleRows.ts (row visibility/ordering rules).
+ */
+export declare function QuickFiles({ title, subtitle, trailingMeta, variant, categoryFilters, recencyWindowMs, kindTokens, locale, }: QuickFilesProps): import("react").JSX.Element;
+//# sourceMappingURL=QuickFiles.d.ts.map

package/dist/QuickFiles.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"QuickFiles.d.ts","sourceRoot":"","sources":["../src/QuickFiles.tsx"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,oBAAoB,CAAC;AAG3D,MAAM,WAAW,eAAe;IAC9B,+FAA+F;IAC/F,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,gFAAgF;IAChF,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,+EAA+E;IAC/E,QAAQ,CAAC,YAAY,CAAC,EAAE,MAAM,CAAC;IAC/B,6FAA6F;IAC7F,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CAAC;IACtC,wFAAwF;IACxF,QAAQ,CAAC,eAAe,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC7C;;;OAGG;IACH,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;IAClC,yEAAyE;IACzE,QAAQ,CAAC,UAAU,CAAC,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAC;IACvD,gEAAgE;IAChE,QAAQ,CAAC,MAAM,CAAC,EAAE,gBAAgB,CAAC;CACpC;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,wBAAgB,UAAU,CAAC,EACzB,KAAK,EACL,QAAQ,EACR,YAAY,EACZ,OAAgB,EAChB,eAAe,EACf,eAAe,EACf,UAAe,EACf,MAAa,GACd,EAAE,eAAe,+BA0EjB"}

package/dist/QuickFiles.js

@@ -0,0 +1,75 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { useMemo, useState } from "react";
+import { Stack } from "@mantine/core";
+import { useLatticeTransport } from "@zephytiju/prism-react";
+import { createQuickFilesClients } from "./clients.js";
+import { useQuickFileDragStatePublish } from "./dragState.js";
+import { QuickFilesDropInModelCard } from "./DropInModelCard.js";
+import { QuickFilesFileList } from "./FileList.js";
+import { QuickFilesPanelHeader } from "./PanelHeader.js";
+import { QuickFilesSearchBox } from "./SearchBox.js";
+import { QuickFilesSectionLabels } from "./SectionLabels.js";
+import { CARD_BG, LINE } from "./tokens.js";
+import { useQuickFilesEntries } from "./useQuickFilesEntries.js";
+import { formatMessage, stringsForLocale } from "./locales/index.js";
+import { selectVisibleRows } from "./visibleRows.js";
+/**
+ * Platform Prism quick-files micro-UI (component id "quick-files"): the
+ * Dossier Quick File Insert side panel — an axiom component, sibling of the
+ * editor viewport (NOT a sub-component of it).
+ *
+ * Renders the per-prototype panel of the authoritative v9 HTML prototype: the
+ * QUICK FILE INSERT title header (title, subtitle and trailing meta are
+ * component configuration keys — Prism has no composed title node), the
+ * bordered search box, the FILES ARE THE SHORTCUT / RECENT-COMMON FILES
+ * section labels, file rows (world view / dossier doc / board / folder icons
+ * with semantic kind tokens, name + mono meta line, + insert action) and the
+ * DROP-IN FILE MODEL info card. Rows are indexed through the IFileEntry list
+ * query.
+ *
+ * D6 REFERENCE CASE — the panel NEVER references any receiving component. On
+ * insert (+) or drag-start of a file row it publishes ONLY a bounded drag /
+ * insert state {entryId, kind, name, mime, snapshotRef, sourcePanel} on the
+ * "quick-files.drag-state" Prism channel; receivers interpret it themselves
+ * (world view → geovision embed restoring an IGeoView snapshot; evidence pack
+ * → evidence table; dossier → paragraph with inline link; unknown → generic
+ * inline file link, per D10). ESC and drag-end clear the state. No audit
+ * events: file browsing/insertion is routine, not audit-worthy.
+ *
+ * No palette is hardcoded: every color resolves to semantic theme tokens
+ * (ok / accent / warn / signal / card / card-dark / border / line / muted /
+ * text …) supplied by the host's MantineProvider.
+ *
+ * COMPOSITION ROOT of the focused sub-component files: PanelHeader (title
+ * header), SearchBox, SectionLabels, FileList (+ FileRow, icons),
+ * DropInModelCard, and the hooks/modules clients.ts (Lattice clients),
+ * dragState.ts (bounded drag-state publication), useQuickFilesEntries.ts
+ * (list lifecycle) and visibleRows.ts (row visibility/ordering rules).
+ */
+export function QuickFiles({ title, subtitle, trailingMeta, variant = "rail", categoryFilters, recencyWindowMs, kindTokens = {}, locale = "en", }) {
+    // Every component-fixed UI string comes from the bundled locale JSONs;
+    // the title header renders from component configuration keys with locale
+    // defaults (composition-authored overrides stay localized by the composer).
+    const strings = stringsForLocale(locale);
+    const [search, setSearch] = useState("");
+    // Setter-only drag-state publication + the ESC cancel listener (D6).
+    useQuickFileDragStatePublish();
+    const transport = useLatticeTransport();
+    const clients = useMemo(() => createQuickFilesClients(transport), [transport]);
+    const { entries, status, reload } = useQuickFilesEntries(clients);
+    const rows = useMemo(() => (entries === null ? [] : selectVisibleRows(entries, search, categoryFilters, recencyWindowMs)), [entries, search, categoryFilters, recencyWindowMs]);
+    const rail = variant === "rail";
+    const resolvedTitle = title ?? strings.panelTitle;
+    const resolvedSubtitle = subtitle ?? strings.panelSubtitle;
+    const resolvedTrailingMeta = trailingMeta ?? formatMessage(strings.trailingMetaCount, { count: rows.length });
+    return (_jsxs(Stack, { gap: 8, miw: 0, style: {
+            width: rail ? 340 : 300,
+            background: CARD_BG,
+            borderLeft: `1px solid ${LINE}`,
+            borderTopRightRadius: 6,
+            borderBottomRightRadius: 6,
+            overflow: "hidden",
+        }, "data-testid": "quick-files-panel", children: [_jsx(QuickFilesPanelHeader, { rail: rail, title: resolvedTitle, subtitle: resolvedSubtitle, trailingMeta: resolvedTrailingMeta }), _jsxs(Stack, { gap: 12, px: 16, pb: 14, miw: 0, children: [_jsx(QuickFilesSearchBox, { value: search, onChange: setSearch, placeholder: strings.searchPlaceholder, label: strings.searchLabel }), _jsx(QuickFilesSectionLabels, { hint: strings.sectionHint, recent: strings.sectionRecent }), _jsx(QuickFilesFileList, { status: status, entries: entries, rows: rows, strings: strings, kindTokens: kindTokens, onRetry: () => {
+                            void reload();
+                        } }), rail && entries !== null && entries.length > 0 ? (_jsx(QuickFilesDropInModelCard, { title: strings.infoCardTitle, body: strings.infoCardBody })) : null] })] }));
+}

package/dist/SearchBox.d.ts

@@ -0,0 +1,13 @@
+export interface QuickFilesSearchBoxProps {
+    /** Current search text (controlled). */
+    readonly value: string;
+    /** Reports the raw input value on every keystroke. */
+    readonly onChange: (value: string) => void;
+    /** Locale-resolved placeholder. */
+    readonly placeholder: string;
+    /** Locale-resolved accessible label. */
+    readonly label: string;
+}
+/** The panel's bordered accent search box on the card-dark surface (v9 ⌕). */
+export declare function QuickFilesSearchBox({ value, onChange, placeholder, label }: QuickFilesSearchBoxProps): import("react").JSX.Element;
+//# sourceMappingURL=SearchBox.d.ts.map

package/dist/SearchBox.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SearchBox.d.ts","sourceRoot":"","sources":["../src/SearchBox.tsx"],"names":[],"mappings":"AAIA,MAAM,WAAW,wBAAwB;IACvC,wCAAwC;IACxC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,sDAAsD;IACtD,QAAQ,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,IAAI,CAAC;IAC3C,mCAAmC;IACnC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,wCAAwC;IACxC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;CACxB;AAED,8EAA8E;AAC9E,wBAAgB,mBAAmB,CAAC,EAAE,KAAK,EAAE,QAAQ,EAAE,WAAW,EAAE,KAAK,EAAE,EAAE,wBAAwB,+BAsCpG"}

package/dist/SearchBox.js

@@ -0,0 +1,23 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Group, TextInput } from "@mantine/core";
+import { SearchGlyph } from "./icons.js";
+import { ACCENT, INPUT_BG, MONO, MUTED, TEXT } from "./tokens.js";
+/** The panel's bordered accent search box on the card-dark surface (v9 ⌕). */
+export function QuickFilesSearchBox({ value, onChange, placeholder, label }) {
+    return (_jsxs(Group, { gap: 10, wrap: "nowrap", align: "center", px: 10, style: {
+            height: 40,
+            background: INPUT_BG,
+            border: `1px solid ${ACCENT}`,
+            borderRadius: 5,
+        }, "data-testid": "quick-files-search", c: ACCENT, children: [_jsx(SearchGlyph, {}), _jsx(TextInput, { variant: "unstyled", value: value, onChange: (event) => {
+                    onChange(event.currentTarget.value);
+                }, placeholder: placeholder, "aria-label": label, "data-testid": "quick-files-search-input", styles: {
+                    input: {
+                        fontFamily: MONO,
+                        fontSize: 10,
+                        color: TEXT,
+                        minHeight: 36,
+                        "::placeholder": { color: MUTED },
+                    },
+                } })] }));
+}

package/dist/SectionLabels.d.ts

@@ -0,0 +1,9 @@
+export interface QuickFilesSectionLabelsProps {
+    /** Locale-resolved upper section label (FILES ARE THE SHORTCUT). */
+    readonly hint: string;
+    /** Locale-resolved lower section label (RECENT / COMMON FILES). */
+    readonly recent: string;
+}
+/** The panel's two mono section labels (prototype: FILES ARE THE SHORTCUT / RECENT-COMMON). */
+export declare function QuickFilesSectionLabels({ hint, recent }: QuickFilesSectionLabelsProps): import("react").JSX.Element;
+//# sourceMappingURL=SectionLabels.d.ts.map

package/dist/SectionLabels.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SectionLabels.d.ts","sourceRoot":"","sources":["../src/SectionLabels.tsx"],"names":[],"mappings":"AAGA,MAAM,WAAW,4BAA4B;IAC3C,oEAAoE;IACpE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,mEAAmE;IACnE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED,+FAA+F;AAC/F,wBAAgB,uBAAuB,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,4BAA4B,+BAWrF"}

package/dist/SectionLabels.js

@@ -0,0 +1,7 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Stack, Text } from "@mantine/core";
+import { MONO, MUTED } from "./tokens.js";
+/** The panel's two mono section labels (prototype: FILES ARE THE SHORTCUT / RECENT-COMMON). */
+export function QuickFilesSectionLabels({ hint, recent }) {
+    return (_jsxs(Stack, { gap: 5, "data-testid": "quick-files-sections", children: [_jsx(Text, { ff: MONO, fz: 9, fw: 500, style: { color: MUTED, letterSpacing: "0.04em" }, children: hint }), _jsx(Text, { ff: MONO, fz: 9, fw: 500, style: { color: MUTED, letterSpacing: "0.04em" }, children: recent })] }));
+}

package/dist/clients.d.ts

@@ -0,0 +1,22 @@
+import type { LatticeTransport } from "@zephytiju/prism-react";
+import type { QuickFileEntryListResult, QuickFileListRequest } from "./types.js";
+/**
+ * Lattice clients for the quick-files panel (design record D4).
+ *
+ * The list query goes through the GENERATED `createFileEntryClient` from
+ * @zephytiju/lattice-common-interfaces over the host Lattice transport — no
+ * URLs, clients, or credentials in component code. The generated bundle's
+ * bounded summary (id/name/kind/sizeBytes) is a structural subset of the
+ * panel's row projection; richer hosts return the superset on the same route,
+ * which survives the erased generic and is picked up by the widening cast
+ * below (bounded fields only — mime, snapshotRef, meta line, pin, recency).
+ */
+export interface QuickFilesClients {
+    /** `interfaces/IFileEntry/list` — the panel's file index. */
+    readonly files: {
+        readonly list: (request?: QuickFileListRequest) => Promise<QuickFileEntryListResult>;
+    };
+}
+/** Builds the interface clients bound to the host Lattice transport. */
+export declare function createQuickFilesClients(transport: LatticeTransport): QuickFilesClients;
+//# sourceMappingURL=clients.d.ts.map