@ahoo-wang/wow-view-engine 9.2.0-rc.0

package/dist/ui/kit/RenameInput.d.ts

@@ -0,0 +1,63 @@
+import { RefObject } from 'react';
+export interface RenameInputProps {
+    /**
+     * What the name says now; the field opens holding it, selected. Read as
+     * it opens: a name left as it opened is unchanged, even where the words
+     * it was said in changed while the field was open (D2).
+     */
+    initial: string;
+    /** The field's accessible name — best after the thing it renames. */
+    label: string;
+    /** A new name, trimmed; never the one it opened with. */
+    onCommit(name: string): void;
+    /** The edit ended with the name as it was. */
+    onCancel(): void;
+    /**
+     * A blank name is refused: Enter and ✓ do nothing, and leaving the field
+     * puts the old name back. Left out, a blank name is a name like any other
+     * — a panel's, which then goes back to being named after its view.
+     */
+    required?: boolean;
+    /**
+     * The name cannot be taken right now (a write is in flight): Enter and ✓
+     * wait, and leaving the field leaves it open rather than dropping what
+     * was typed.
+     */
+    held?: boolean;
+    /** Where the keyboard goes when Enter or Escape ends the edit. */
+    returnTo?: RefObject<HTMLElement | null>;
+    /**
+     * ✓ and ✕ drawn in the field, named — for a row where the field is the
+     * only thing that says it is being edited.
+     */
+    answers?: {
+        confirm: string;
+        cancel: string;
+    };
+    /** The longest name the field takes: a view's title is held to the store's. */
+    maxLength?: number;
+    className?: string;
+    'data-slot'?: string;
+}
+/**
+ * A name typed in place — a panel's title, a tab's, a view's in the manager
+ * (Q-10): one field, one set of rules.
+ *
+ * It appears focused with the name selected, so typing replaces it. Enter
+ * keeps what was typed and Escape keeps what was there; both stop at the
+ * field, since the field may sit in a dialog or a popover that the same key
+ * would otherwise close. Leaving it — a press elsewhere, Tab — keeps what
+ * was typed too, the way a name edited in place is kept everywhere else;
+ * moving onto its own ✓ or ✕ is not leaving. The name is trimmed, and an
+ * unchanged one is not a rename: nothing is written, and a panel named after
+ * its view does not take that name as a title of its own.
+ *
+ * It takes the keyboard as it mounts, in the same commit as the menu item
+ * that asked for it: a menu closing after that finds the keyboard outside
+ * it and leaves it where it is (unlike a dialog, which takes the keyboard
+ * a moment later — U-01), so the tab bar's plain menu item and the panel
+ * menu's `DialogMenuItem` both hand over (test/dashboardExtensions.test.tsx
+ * and the TabsBuilt story in a browser).
+ */
+export declare function RenameInput({ initial, label, onCommit, onCancel, required, held, returnTo, answers, maxLength, className, 'data-slot': slot, }: RenameInputProps): import('react').JSX.Element;
+//# sourceMappingURL=RenameInput.d.ts.map

package/dist/ui/kit/RenameInput.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"RenameInput.d.ts","sourceRoot":"","sources":["../../../src/ui/kit/RenameInput.tsx"],"names":[],"mappings":"AAaA,OAAO,EAKL,KAAK,SAAS,EACf,MAAM,OAAO,CAAC;AAWf,MAAM,WAAW,gBAAgB;IAC/B;;;;OAIG;IACH,OAAO,EAAE,MAAM,CAAC;IAChB,qEAAqE;IACrE,KAAK,EAAE,MAAM,CAAC;IACd,yDAAyD;IACzD,QAAQ,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IAC7B,8CAA8C;IAC9C,QAAQ,IAAI,IAAI,CAAC;IACjB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB;;;;OAIG;IACH,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,kEAAkE;IAClE,QAAQ,CAAC,EAAE,SAAS,CAAC,WAAW,GAAG,IAAI,CAAC,CAAC;IACzC;;;OAGG;IACH,OAAO,CAAC,EAAE;QAAE,OAAO,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;IAC9C,+EAA+E;IAC/E,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;;;;;;;;;;;;;;GAmBG;AACH,wBAAgB,WAAW,CAAC,EAC1B,OAAO,EACP,KAAK,EACL,QAAQ,EACR,QAAQ,EACR,QAAgB,EAChB,IAAY,EACZ,QAAQ,EACR,OAAO,EACP,SAAS,EACT,SAAS,EACT,WAAW,EAAE,IAAI,GAClB,EAAE,gBAAgB,+BA4FlB"}

package/dist/ui/kit/RenderBoundary.d.ts

@@ -0,0 +1,68 @@
+import { ReactNode } from 'react';
+/**
+ * The parts of a view a render can fail in, each behind a boundary of its
+ * own, so that one of them failing leaves the others standing.
+ *
+ * - `actions`: the host's global action slot in the title bar;
+ * - `editor`: the condition editor, in its band;
+ * - `result`: the result block — rows, cards, charts, and the host's bulk
+ *   and row action slots inside it;
+ * - `panel`: one dashboard panel, by `panelId`;
+ * - `detail`: one of the host's sections in a record's detail
+ *   (`RecordDetailSection`).
+ */
+export type RenderBoundaryName = 'actions' | 'editor' | 'result' | 'panel' | 'detail';
+/**
+ * What a boundary caught, handed to the host as it is caught. This surface's
+ * own callback; the engine's `environment.onError` hears of the same failure
+ * as well, where a workbench or an embed is above the boundary (D40).
+ */
+export interface RenderFailure {
+    boundary: RenderBoundaryName;
+    /** The dashboard panel that failed, for `panel`; absent elsewhere. */
+    panelId?: string;
+    error: unknown;
+    /** React's component stack, where the renderer provides one. */
+    componentStack?: string;
+}
+export type RenderFailureHandler = (failure: RenderFailure) => void;
+export interface RenderBoundaryProps {
+    name: RenderBoundaryName;
+    panelId?: string;
+    /**
+     * Values whose change discards a caught failure and draws the children
+     * again — the open view's runtime id, for instance, so a failure in one
+     * view does not follow the user to the next.
+     */
+    resetKeys?: readonly unknown[];
+    onFailure?: RenderFailureHandler;
+    /**
+     * A one-line fallback for a slot that sits inside a row of controls, where
+     * a block-level alert would break the line it is on.
+     */
+    compact?: boolean;
+    children: ReactNode;
+}
+/**
+ * A boundary around one part of a view.
+ *
+ * What the host renders into a workbench — the action slots (D6) and a
+ * dashboard's markdown — runs inside this package's tree, and React unmounts
+ * the whole tree from the nearest boundary up when any of it throws. Without
+ * one, a row action that throws takes the title bar, the editor and the
+ * unsaved draft with it. With one per part, it takes the rows and nothing
+ * else: the fallback says which part failed and offers to draw it again,
+ * and the failure itself goes to the host, which is the only one who can fix
+ * it. The error is not swallowed — it is reported and made recoverable.
+ */
+export declare function RenderBoundary({ name, panelId, resetKeys, onFailure, compact, children, }: RenderBoundaryProps): import('react').JSX.Element;
+/**
+ * A render function turned into an element, so that it runs *inside* the
+ * boundary around it rather than in whoever built the tree. `actions.global`
+ * is a function the workbench has to call; calling it while assembling the
+ * shell's props would throw above every boundary the shell draws.
+ */
+export declare function RenderSlot({ render }: {
+    render: () => ReactNode;
+}): import('react').JSX.Element;
+//# sourceMappingURL=RenderBoundary.d.ts.map

package/dist/ui/kit/RenderBoundary.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"RenderBoundary.d.ts","sourceRoot":"","sources":["../../../src/ui/kit/RenderBoundary.tsx"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAa,SAAS,EAAE,MAAM,OAAO,CAAC;AAkBlD;;;;;;;;;;;GAWG;AACH,MAAM,MAAM,kBAAkB,GAC5B,SAAS,GAAG,QAAQ,GAAG,QAAQ,GAAG,OAAO,GAAG,QAAQ,CAAC;AAEvD;;;;GAIG;AACH,MAAM,WAAW,aAAa;IAC5B,QAAQ,EAAE,kBAAkB,CAAC;IAC7B,sEAAsE;IACtE,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,KAAK,EAAE,OAAO,CAAC;IACf,gEAAgE;IAChE,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,MAAM,oBAAoB,GAAG,CAAC,OAAO,EAAE,aAAa,KAAK,IAAI,CAAC;AAEpE,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,kBAAkB,CAAC;IACzB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;OAIG;IACH,SAAS,CAAC,EAAE,SAAS,OAAO,EAAE,CAAC;IAC/B,SAAS,CAAC,EAAE,oBAAoB,CAAC;IACjC;;;OAGG;IACH,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,QAAQ,EAAE,SAAS,CAAC;CACrB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,cAAc,CAAC,EAC7B,IAAI,EACJ,OAAO,EACP,SAAS,EACT,SAAS,EACT,OAAe,EACf,QAAQ,GACT,EAAE,mBAAmB,+BAiCrB;AAkFD;;;;;GAKG;AACH,wBAAgB,UAAU,CAAC,EAAE,MAAM,EAAE,EAAE;IAAE,MAAM,EAAE,MAAM,SAAS,CAAA;CAAE,+BAEjE"}

package/dist/ui/kit/RowItem.d.ts

@@ -0,0 +1,31 @@
+import { VariantProps } from 'class-variance-authority';
+import { Item } from '../components/item.js';
+import type * as React from 'react';
+/**
+ * The two marks a row of this package wears, and the colour each is drawn
+ * in.
+ *
+ * The marks stay at the call sites — `data-dragging` and `data-broken` are
+ * what the unit tests and the browser stories read a row's state by — while
+ * the colours live here, so that no call site paints a vendored component
+ * (decisions.md D16 ruling 8).
+ */
+declare const rowItemVariants: (props?: ({
+    density?: "dense" | "roomy" | null | undefined;
+    pressable?: boolean | null | undefined;
+    description?: "label" | "prose" | null | undefined;
+} & import('class-variance-authority/types').ClassProp) | undefined) => string;
+export type RowItemProps = React.ComponentProps<typeof Item> & VariantProps<typeof rowItemVariants>;
+/**
+ * One row of a list, over the registry's `Item` (decisions.md D16 ruling 3).
+ *
+ * Five lists in this package used to be five hand-laid-out flex rows, each
+ * with its own gaps, its own truncation and — in the manager's case — a
+ * hand-measured width to keep the action icons in a column. They are one
+ * recipe now: `ItemMedia` leads, `ItemContent` takes the room, `ItemActions`
+ * closes, and `ItemFooter` is the line that wraps underneath. What is left
+ * at a call site is the content and the layout it asks for, never a colour.
+ */
+export declare function RowItem({ className, density, description, pressable, ...props }: RowItemProps): React.JSX.Element;
+export {};
+//# sourceMappingURL=RowItem.d.ts.map

package/dist/ui/kit/RowItem.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"RowItem.d.ts","sourceRoot":"","sources":["../../../src/ui/kit/RowItem.tsx"],"names":[],"mappings":"AAaA,OAAO,KAAK,KAAK,KAAK,MAAM,OAAO,CAAC;AACpC,OAAO,EAAO,KAAK,YAAY,EAAE,MAAM,0BAA0B,CAAC;AAElE,OAAO,EAAE,IAAI,EAAE,MAAM,uBAAuB,CAAC;AAE7C;;;;;;;;GAQG;AACH,QAAA,MAAM,eAAe;;;;8EA0DpB,CAAC;AAEF,MAAM,MAAM,YAAY,GAAG,KAAK,CAAC,cAAc,CAAC,OAAO,IAAI,CAAC,GAC1D,YAAY,CAAC,OAAO,eAAe,CAAC,CAAC;AAEvC;;;;;;;;;GASG;AACH,wBAAgB,OAAO,CAAC,EACtB,SAAS,EACT,OAAiB,EACjB,WAAW,EACX,SAAS,EACT,GAAG,KAAK,EACT,EAAE,YAAY,qBAWd"}

package/dist/ui/kit/StatusStrip.d.ts

@@ -0,0 +1,114 @@
+import { ReactNode } from 'react';
+import { Issue } from '../../model/index.js';
+import { AlertTone } from './alerts.js';
+export interface StatusStripProps {
+    /** How loud it is: the colour, the icon and the role come with it. */
+    tone: AlertTone;
+    /** The whole of it in one sentence; the strip is one line tall. */
+    title: string;
+    /**
+     * The findings behind the sentence. They fold away behind a count, because
+     * the result below is what the user came for and a stack of sentences
+     * pushes it off the screen.
+     */
+    details?: readonly string[];
+    /** What to do about it — a retry, usually — at the end of the line. */
+    action?: ReactNode;
+    className?: string;
+}
+/**
+ * Anything the view has to say that is not a row: a warning, a query that
+ * failed, a config that needs fixing before it runs.
+ *
+ * It is one line by design. A block-sized alert pushes the result down the
+ * page — and the result is still there, since a failed query never clears the
+ * table — so a finding that blocks nothing must not hide what does not need
+ * hiding. That is a decision about height, not about the component: this is
+ * the registry's `Alert` in the line-high variant (`ui/kit/alerts.tsx`), which is
+ * where the tone's colour, its icon and its role are decided for every
+ * callout at once — an error is announced as an alert, everything else as a
+ * status, so a screen reader interrupts only for what stopped the view.
+ */
+export declare function StatusStrip({ tone, title, details, action, className, }: StatusStripProps): import('react').JSX.Element;
+/**
+ * One of each sentence.
+ *
+ * A dashboard validates a global condition once as its own and once more per
+ * panel it maps onto, and two leaves can trip the same rule; the code and the
+ * params are the sentence, and the same sentence twice tells nobody anything
+ * more. A strip counts what it shows, so the count has to be of sentences.
+ */
+export declare function dedupeIssues(issues: readonly Issue[]): Issue[];
+export interface IssueStripProps {
+    /** Every finding of the view; this picks the ones it is about. */
+    issues: readonly Issue[];
+    className?: string;
+}
+/**
+ * The findings that do not block, said once and in one line.
+ *
+ * A warning stops nothing — the query ran, save is allowed — but the view is
+ * not quite what its author saved, and a finding nobody can see was never
+ * reported. One warning is its own sentence; several collapse behind a count,
+ * because the result underneath is what the user came for.
+ */
+export declare function WarningStrip({ issues, className }: IssueStripProps): import('react').JSX.Element | null;
+/**
+ * What is true about the answer and not wrong with it, as a quiet line: the
+ * groups a view's own limit left out, when every row shown is whole
+ * (`note`, `IssueSeverity`). The info tone rather than a warning's — a
+ * screen that warns about what it was asked to do teaches its reader to
+ * stop reading warnings.
+ */
+export declare function NoteStrip({ issues, className }: IssueStripProps): import('react').JSX.Element | null;
+export interface QueryStripProps {
+    /** The query's own failure; nothing is said while there is none. */
+    error: Issue | null | undefined;
+    /**
+     * Whether a result from before the failure is still on screen. It changes
+     * what the line means — an empty frame that failed says one thing, rows
+     * that are one refresh out of date another — and only the caller knows.
+     */
+    stale: boolean;
+    /**
+     * Whether that result was asked under other conditions than the query
+     * that failed (`ViewQueryState.conditionsChanged`): the line then says
+     * the rows are from before the change, not only from before now.
+     */
+    conditionsChanged?: boolean;
+    /** Given, the line ends in a retry; an embed that offers none leaves it out. */
+    onRetry?(): void;
+    className?: string;
+}
+/**
+ * A query that did not come back.
+ *
+ * The rows below it are the last ones that did: a failure never clears the
+ * result, because a view that empties itself on a dropped connection has lost
+ * what the user was reading for no reason the user caused.
+ */
+export declare function QueryStrip({ error, stale, conditionsChanged, onRetry, className, }: QueryStripProps): import('react').JSX.Element | null;
+export interface ErrorStripProps extends IssueStripProps {
+    /** What the line says; a dashboard names itself rather than "this view". */
+    title?: string;
+    /**
+     * The way out of it, at the end of the line. A finding that stops the
+     * view is worth nothing to a reader who cannot see where to go and fix
+     * it, and the surface is the only one that knows where that is — a record
+     * view's is the column settings, which the toolbar would have opened if
+     * there were a result for a toolbar to sit over.
+     */
+    action?: ReactNode;
+}
+/**
+ * What stops the view from running.
+ *
+ * It is a line rather than a banner because the last successful result is
+ * still on screen underneath — a config that stopped running did not stop
+ * being worth reading — and a banner would push it away. It shows the issues
+ * it is handed: a surface with a condition editor hands over `filter.unmarked`,
+ * the ones no pill carries; an embed, which has no editor and so marks nothing
+ * anywhere, hands over all of them.
+ */
+export declare function ErrorStrip({ issues, title, action, className, }: ErrorStripProps): import('react').JSX.Element | null;
+//# sourceMappingURL=StatusStrip.d.ts.map

package/dist/ui/kit/StatusStrip.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"StatusStrip.d.ts","sourceRoot":"","sources":["../../../src/ui/kit/StatusStrip.tsx"],"names":[],"mappings":"AAaA,OAAO,EAAY,KAAK,SAAS,EAAE,MAAM,OAAO,CAAC;AAEjD,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,sBAAsB,CAAC;AAElD,OAAO,EAAa,KAAK,SAAS,EAAE,MAAM,aAAa,CAAC;AAYxD,MAAM,WAAW,gBAAgB;IAC/B,sEAAsE;IACtE,IAAI,EAAE,SAAS,CAAC;IAChB,mEAAmE;IACnE,KAAK,EAAE,MAAM,CAAC;IACd;;;;OAIG;IACH,OAAO,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;IAC5B,uEAAuE;IACvE,MAAM,CAAC,EAAE,SAAS,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,WAAW,CAAC,EAC1B,IAAI,EACJ,KAAK,EACL,OAAO,EACP,MAAM,EACN,SAAS,GACV,EAAE,gBAAgB,+BA8ClB;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,MAAM,EAAE,SAAS,KAAK,EAAE,GAAG,KAAK,EAAE,CAK9D;AAaD,MAAM,WAAW,eAAe;IAC9B,kEAAkE;IAClE,MAAM,EAAE,SAAS,KAAK,EAAE,CAAC;IACzB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,EAAE,MAAM,EAAE,SAAS,EAAE,EAAE,eAAe,sCAsBlE;AAED;;;;;;GAMG;AACH,wBAAgB,SAAS,CAAC,EAAE,MAAM,EAAE,SAAS,EAAE,EAAE,eAAe,sCAmB/D;AAED,MAAM,WAAW,eAAe;IAC9B,oEAAoE;IACpE,KAAK,EAAE,KAAK,GAAG,IAAI,GAAG,SAAS,CAAC;IAChC;;;;OAIG;IACH,KAAK,EAAE,OAAO,CAAC;IACf;;;;OAIG;IACH,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B,gFAAgF;IAChF,OAAO,CAAC,IAAI,IAAI,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,EACzB,KAAK,EACL,KAAK,EACL,iBAAyB,EACzB,OAAO,EACP,SAAS,GACV,EAAE,eAAe,sCAuCjB;AAED,MAAM,WAAW,eAAgB,SAAQ,eAAe;IACtD,4EAA4E;IAC5E,KAAK,CAAC,EAAE,MAAM,CAAC;IACf;;;;;;OAMG;IACH,MAAM,CAAC,EAAE,SAAS,CAAC;CACpB;AAED;;;;;;;;;GASG;AACH,wBAAgB,UAAU,CAAC,EACzB,MAAM,EACN,KAAK,EACL,MAAM,EACN,SAAS,GACV,EAAE,eAAe,sCA2BjB"}

package/dist/ui/kit/SystemMark.d.ts

@@ -0,0 +1,32 @@
+/**
+ * The mark a view that came with the definition wears in a list of views: a
+ * lock at the row's end, a word for a screen reader, and on pointing, the
+ * sentence that says why it is locked.
+ *
+ * A glyph and not the word "system" after the name: every row of the shared
+ * group then said the same two syllables, and the fact a reader needs from
+ * it — this one cannot be renamed or deleted — is the lock's to say. The
+ * sidebar and the switcher draw the same view, so they draw it with this
+ * one mark; the title bar, which has room, keeps the word beside the lock.
+ *
+ * A system view the store keeps and this user may edit (D81) keeps the
+ * lock — it is still everyone's view, not this user's — and only the
+ * sentence on pointing changes (`editable`): it can be changed, by whoever
+ * the host lets, and the change reaches everyone.
+ *
+ * The glyph hangs off a span rather than being the tooltip's trigger itself,
+ * for the reason `ViewList` gives for the kind icon: a row that is a
+ * `Button` or a menu item draws `pointer-events: none` over every `<svg>`
+ * inside it.
+ */
+export declare function SystemMark({ className, editable, stored, }: {
+    className?: string;
+    /** True when this user may change the view (D81); the sentence says so. */
+    editable?: boolean;
+    /**
+     * True for a view the store keeps (D81): it did not come with the
+     * definition, so a reader who may not change it is told only that.
+     */
+    stored?: boolean;
+}): import('react').JSX.Element;
+//# sourceMappingURL=SystemMark.d.ts.map

package/dist/ui/kit/SystemMark.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"SystemMark.d.ts","sourceRoot":"","sources":["../../../src/ui/kit/SystemMark.tsx"],"names":[],"mappings":"AAkBA;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,UAAU,CAAC,EACzB,SAAS,EACT,QAAgB,EAChB,MAAc,GACf,EAAE;IACD,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,2EAA2E;IAC3E,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB;;;OAGG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;CAClB,+BA8BA"}

package/dist/ui/kit/Truncated.d.ts

@@ -0,0 +1,25 @@
+import { HTMLAttributes } from 'react';
+/** The elements a one-line text of user content is drawn as. */
+type TruncatedTag = 'span' | 'p' | 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6';
+export type TruncatedProps = Omit<HTMLAttributes<HTMLElement>, 'children' | 'title'> & {
+    /** The text, whole: drawn on one line, cut with an ellipsis. */
+    text: string;
+    /** The element it is drawn as: a span, or a heading. */
+    as?: TruncatedTag;
+    [data: `data-${string}`]: string | number | boolean | undefined;
+};
+/**
+ * One line of user content that may not fit — a view's name, a panel's
+ * title, a legend entry — cut with an ellipsis, and read whole one hover
+ * away where it is cut (second review R2-75: 9 of 13 view names cut in the
+ * 1280 sidebar, 「品类 → 子类的实付构成（近 12…」 and 「…分解（近 12…」 told
+ * apart only by opening each). A `Tooltip` and not the native `title`
+ * (D16-6), as the record table's column names do (`SortableHeader`); it
+ * opens only where the text is cut, so nothing repeats what is already on
+ * screen. A screen reader is read the text itself, which the ellipsis never
+ * cuts. The trigger is the element itself: nothing is wrapped around it, so
+ * the layout it stood in is untouched.
+ */
+export declare function Truncated({ text, as: Tag, className, ...props }: TruncatedProps): import('react').JSX.Element;
+export {};
+//# sourceMappingURL=Truncated.d.ts.map

package/dist/ui/kit/Truncated.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Truncated.d.ts","sourceRoot":"","sources":["../../../src/ui/kit/Truncated.tsx"],"names":[],"mappings":"AAYA,OAAO,EAAoB,KAAK,cAAc,EAAE,MAAM,OAAO,CAAC;AAK9D,gEAAgE;AAChE,KAAK,YAAY,GAAG,MAAM,GAAG,GAAG,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,IAAI,CAAC;AAE3E,MAAM,MAAM,cAAc,GAAG,IAAI,CAC/B,cAAc,CAAC,WAAW,CAAC,EAC3B,UAAU,GAAG,OAAO,CACrB,GAAG;IACF,gEAAgE;IAChE,IAAI,EAAE,MAAM,CAAC;IACb,wDAAwD;IACxD,EAAE,CAAC,EAAE,YAAY,CAAC;IAClB,CAAC,IAAI,EAAE,QAAQ,MAAM,EAAE,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,SAAS,CAAC;CACjE,CAAC;AAMF;;;;;;;;;;;GAWG;AACH,wBAAgB,SAAS,CAAC,EACxB,IAAI,EACJ,EAAE,EAAE,GAAY,EAChB,SAAS,EACT,GAAG,KAAK,EACT,EAAE,cAAc,+BAwBhB"}

package/dist/ui/kit/ViewExpansion.d.ts

@@ -0,0 +1,89 @@
+import { RefObject } from 'react';
+/** Whether a surface fills the screen, and the one way to change it. */
+export interface ViewExpansion {
+    expanded: boolean;
+    toggle(): void;
+}
+/**
+ * Let a surface fill the screen **where it stands**.
+ *
+ * Expanding in place rather than portalling is the whole decision. A portal
+ * re-parents the subtree, React recreates every node under it, and focus, the
+ * scroll position and a half-finished IME composition go with them — and the
+ * surface loses the host ancestor whose `.dark` class it was following.
+ * Nothing moves instead: the `.fve-root` at or above the element the ref
+ * points at is marked `data-view-expanded`, and one unlayered rule in
+ * `styles.css` pins it to the viewport.
+ *
+ * The top layer — `requestFullscreen()`, or `popover="manual"` — would solve
+ * the containing-block problem outright and was rejected for one reason:
+ * every popup this package opens is portalled to `document.body`, so the
+ * field picker, the filter menus, the save split button and the view switcher
+ * would all render *behind* the expanded view, or under fullscreen not render
+ * at all. A view you cannot open a menu in is not an expanded view. In the
+ * normal layer the promise is kept by the popups themselves: `popups.tsx`
+ * puts a layer of their own on every one, above the level this surface takes
+ * — see the `z-index` note in `styles.css`.
+ *
+ * It is **not a modal**, and says so by omission: no `aria-modal`, no focus
+ * trap, no `inert` anywhere. Nothing is being asked and there is nothing to
+ * answer — this is the same content it was a moment ago, in the same place,
+ * with the same focus. Claiming modality would tell a screen reader that the
+ * host's page is unavailable, which is a promise about content we are in no
+ * position to make: the expanded element is still a descendant of the host's
+ * own DOM, and making "everything else" inert would mean walking up and
+ * inerting a sibling at every level — which is a portal's job, and a portal
+ * is what costs the draft.
+ *
+ * What it does borrow from a modal is the one thing a full-viewport surface
+ * genuinely needs: the background does not scroll underneath it, because a
+ * scroll whose effect nobody can see is a scroll position silently lost. And
+ * Escape closes it, unless the key belongs to something in front.
+ *
+ * @param target the surface to expand, or anything inside one
+ * @param toggleRef the control that opened it, which focus goes back to
+ * @param enabled false while there is nothing to expand, which also ends an
+ *   expansion already in force rather than holding it for later
+ */
+export declare function useViewExpansion(target: RefObject<HTMLElement | null>, toggleRef: RefObject<HTMLElement | null>, enabled?: boolean): ViewExpansion;
+export interface ViewExpandToggleProps {
+    expansion: ViewExpansion;
+    ref?: RefObject<HTMLButtonElement | null>;
+}
+/**
+ * The control that fills the screen with this view, in the title bar's
+ * right-hand group: it is one of the answers to *how am I looking at this*,
+ * beside the editor's fold and before whatever the host adds.
+ *
+ * `aria-expanded` rather than `aria-pressed`, which is what the legacy
+ * button wore: the surface it governs is a region that grows and shrinks,
+ * the same relationship the sidebar's and the editor's toggles already
+ * describe, and one page should not name that relationship two ways.
+ * `aria-keyshortcuts` is how the Escape route is discoverable without
+ * spending a tooltip on it — and it is announced only while there is
+ * something for the key to do.
+ *
+ * The name is the one the state asks for, and the tooltip is the same
+ * string: a pointer hovering this while the view fills the screen reads
+ * "Exit full screen", which is what pressing it does now — not what it did
+ * before it was pressed.
+ */
+export declare function ViewExpandToggle({ expansion, ref }: ViewExpandToggleProps): import('react').JSX.Element;
+/**
+ * The way back out of a surface whose control is not inside it.
+ *
+ * `ViewSurface` renders one on every surface and it is `hidden` until
+ * `useViewExpansion` finds that the control governing this expansion is
+ * *outside* the element — which is the only shape an `EmbeddedView` has,
+ * since it grows no control of its own and a host puts one in its own chrome.
+ * The moment the surface fills the screen, that host control is underneath
+ * it: a desktop user might guess Escape, and a touch device has no Escape at
+ * all, so without this there is no way out.
+ *
+ * It carries no handler. The surface that owns the expansion is the one that
+ * knows how to collapse, and it answers the click — which keeps `ViewSurface`
+ * free of any expansion state, and keeps this out of the page while the
+ * control that governs the view is on screen with the rest of the chrome.
+ */
+export declare function ViewExpandExit(): import('react').JSX.Element;
+//# sourceMappingURL=ViewExpansion.d.ts.map

package/dist/ui/kit/ViewExpansion.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ViewExpansion.d.ts","sourceRoot":"","sources":["../../../src/ui/kit/ViewExpansion.tsx"],"names":[],"mappings":"AAaA,OAAO,EAAqC,KAAK,SAAS,EAAE,MAAM,OAAO,CAAC;AAM1E,wEAAwE;AACxE,MAAM,WAAW,aAAa;IAC5B,QAAQ,EAAE,OAAO,CAAC;IAClB,MAAM,IAAI,IAAI,CAAC;CAChB;AA4MD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AACH,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,SAAS,CAAC,WAAW,GAAG,IAAI,CAAC,EACrC,SAAS,EAAE,SAAS,CAAC,WAAW,GAAG,IAAI,CAAC,EACxC,OAAO,UAAO,GACb,aAAa,CAkMf;AAED,MAAM,WAAW,qBAAqB;IACpC,SAAS,EAAE,aAAa,CAAC;IACzB,GAAG,CAAC,EAAE,SAAS,CAAC,iBAAiB,GAAG,IAAI,CAAC,CAAC;CAC3C;AAED;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,gBAAgB,CAAC,EAAE,SAAS,EAAE,GAAG,EAAE,EAAE,qBAAqB,+BAoBzE;AAED;;;;;;;;;;;;;;;GAeG;AACH,wBAAgB,cAAc,gCAQ7B"}

package/dist/ui/kit/ViewSurface.d.ts

@@ -0,0 +1,100 @@
+import { DisplayContext } from './display.js';
+import { ViewMessages } from './messages.js';
+import { ViewDensity, ViewPreset } from './presets.js';
+import { FveToken } from '../theme/tokens.js';
+import * as React from 'react';
+/**
+ * The mode a surface is asked for: `light` or `dark` pins it, `system`
+ * follows the reader's `prefers-color-scheme`, live. Left out, it follows a
+ * `.dark` class on an ancestor — the host's own switch.
+ */
+export type ViewTheme = 'light' | 'dark' | 'system';
+export interface ViewSurfaceProps extends React.ComponentProps<'div'> {
+    /**
+     * Follows the host when left out; set it to pin an embedded view, or to
+     * `system` to follow the reader's system on a page with no switch of its
+     * own.
+     */
+    theme?: ViewTheme;
+    /**
+     * A preset from `@ahoo-wang/wow-view-engine/themes.css` (or one of the
+     * host's own, written the same way), pinned on this surface and on every
+     * popup it opens. Left out, the surface takes the preset of its nearest
+     * ancestor carrying `data-fve-preset` — `<html>`, as a rule — and its
+     * popups do too, so a preset set on a part of the page reaches the popups
+     * portalled out of it.
+     */
+    preset?: ViewPreset;
+    /**
+     * How dense this surface sits, pinned on it and on every popup it opens
+     * (themes.md 2.4). Left out, the surface takes the `data-fve-density` of
+     * its nearest ancestor with one — `<html>`, as a rule — or else the
+     * density its preset recommends.
+     */
+    density?: ViewDensity;
+    /**
+     * The host's own values for this surface alone — any `--fve-*` of the
+     * theme's contract (`FveToken`), as a host would set it on `:root` — written
+     * on the surface's root and on every popup it opens (theme-architecture.md
+     * 7, S2). A popup is portalled to `<body>`, out from under any wrapper the
+     * host sets variables on, so a part of the page that should look different
+     * says it here rather than on a wrapper. Like the host's `:root`, it beats
+     * any preset, the one pinned here included.
+     */
+    tokens?: Partial<Record<FveToken, string>>;
+    /**
+     * Wording, merged over what is already in force — the defaults, or an outer
+     * `MessagesProvider`; this is also where translation goes.
+     */
+    messages?: ViewMessages;
+    /** The language dates and times show in; the runtime's when left out. */
+    locale?: string;
+    /**
+     * The engine the views inside were opened from, whose starting words
+     * (`ViewEngineOptions.text`) say a definition's key where `messages` —
+     * and every provider's above — lack it. A `ViewHost`, a
+     * workbench and an embed hand them down already; a host that draws
+     * parts inside a surface of its own, with no Provider around it, passes
+     * its engine here, or those keys show as keys (D2).
+     */
+    engine?: {
+        startingWord(key: string): string | undefined;
+    };
+    /**
+     * The zone times show in. A workbench passes its engine's, the zone a
+     * relative filter is evaluated in, so a row's time reads on the same clock
+     * it was filtered by.
+     */
+    timeZone?: string;
+    /**
+     * The clock "now" is read from — the engine's `environment`, which a
+     * workbench and an embed pass. A table cell leaves out the year of a time
+     * in the current one, so a page whose clock is pinned reads the same every
+     * day; the runtime's own clock when left out.
+     */
+    clock?: {
+        now(): Date;
+    };
+}
+export declare function useSurfaceTheme(): 'light' | 'dark' | undefined;
+export declare function useSurfaceTokens(): string | undefined;
+export declare function useSurfaceFont(): string | undefined;
+export declare function useSurfaceHostTokens(): Partial<Record<FveToken, string>> | undefined;
+/**
+ * The attributes a popup takes from the surface it opened from, so the
+ * stylesheet resolves it as it does the surface: the mode, the preset, the
+ * change convention, the density and whether the first chart slot follows
+ * the brand. Spread onto every element a popup portals out.
+ */
+export declare function useSurfaceAttributes(): {
+    lang: string | undefined;
+    'data-theme': 'light' | 'dark' | undefined;
+    'data-fve-preset': string | undefined;
+    'data-fve-change-colors': string | undefined;
+    'data-fve-density': string | undefined;
+    'data-fve-brand-chart': string | undefined;
+};
+/** The language and zone the nearest surface shows values in. */
+export declare function useSurfaceDisplay(): DisplayContext;
+export declare function ViewSurface({ engine, ...props }: ViewSurfaceProps): React.JSX.Element;
+//# sourceMappingURL=ViewSurface.d.ts.map

package/dist/ui/kit/ViewSurface.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ViewSurface.d.ts","sourceRoot":"","sources":["../../../src/ui/kit/ViewSurface.tsx"],"names":[],"mappings":"AAaA,OAAO,KAAK,KAAK,MAAM,OAAO,CAAC;AAG/B,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAQnD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAElD,OAAO,KAAK,EAAE,WAAW,EAAE,UAAU,EAAE,MAAM,cAAc,CAAC;AAC5D,OAAO,EAGL,KAAK,QAAQ,EACd,MAAM,oBAAoB,CAAC;AAE5B;;;;GAIG;AACH,MAAM,MAAM,SAAS,GAAG,OAAO,GAAG,MAAM,GAAG,QAAQ,CAAC;AAEpD,MAAM,WAAW,gBAAiB,SAAQ,KAAK,CAAC,cAAc,CAAC,KAAK,CAAC;IACnE;;;;OAIG;IACH,KAAK,CAAC,EAAE,SAAS,CAAC;IAClB;;;;;;;OAOG;IACH,MAAM,CAAC,EAAE,UAAU,CAAC;IACpB;;;;;OAKG;IACH,OAAO,CAAC,EAAE,WAAW,CAAC;IACtB;;;;;;;;OAQG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC,CAAC;IAC3C;;;OAGG;IACH,QAAQ,CAAC,EAAE,YAAY,CAAC;IACxB,yEAAyE;IACzE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;;;;;OAOG;IACH,MAAM,CAAC,EAAE;QAAE,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAA;KAAE,CAAC;IAC3D;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB;;;;;OAKG;IACH,KAAK,CAAC,EAAE;QAAE,GAAG,IAAI,IAAI,CAAA;KAAE,CAAC;CACzB;AAsCD,wBAAgB,eAAe,IAAI,OAAO,GAAG,MAAM,GAAG,SAAS,CAE9D;AA2BD,wBAAgB,gBAAgB,IAAI,MAAM,GAAG,SAAS,CAErD;AAuDD,wBAAgB,cAAc,IAAI,MAAM,GAAG,SAAS,CAEnD;AAsBD,wBAAgB,oBAAoB,IAClC,OAAO,CAAC,MAAM,CAAC,QAAQ,EAAE,MAAM,CAAC,CAAC,GAAG,SAAS,CAE9C;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,IAAI;IACtC,IAAI,EAAE,MAAM,GAAG,SAAS,CAAC;IACzB,YAAY,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAAC;IAC3C,iBAAiB,EAAE,MAAM,GAAG,SAAS,CAAC;IACtC,wBAAwB,EAAE,MAAM,GAAG,SAAS,CAAC;IAC7C,kBAAkB,EAAE,MAAM,GAAG,SAAS,CAAC;IACvC,sBAAsB,EAAE,MAAM,GAAG,SAAS,CAAC;CAC5C,CASA;AAoID,iEAAiE;AACjE,wBAAgB,iBAAiB,IAAI,cAAc,CAElD;AAED,wBAAgB,WAAW,CAAC,EAAE,MAAM,EAAE,GAAG,KAAK,EAAE,EAAE,gBAAgB,qBAMjE"}

package/dist/ui/kit/alerts.d.ts

@@ -0,0 +1,60 @@
+import { InfoIcon } from 'lucide-react';
+import type * as React from 'react';
+/** How loud a callout is; it decides the colour, the icon and the role. */
+export type AlertTone = 'error' | 'warning' | 'info';
+/**
+ * The icon each tone wears, written once.
+ *
+ * Lucide's own distinction: the circle is the error — something stopped —
+ * and the triangle is the warning — something is off but the view ran. Two
+ * callouts that pick their own glyph teach the reader two vocabularies, so
+ * every one of them takes the icon from here.
+ */
+export declare const TONE_ICON: Record<AlertTone, typeof InfoIcon>;
+/**
+ * The registry's `Alert`, laid out as one line.
+ *
+ * `Alert` is a block: a grid of title over description, padded for a banner
+ * and with its action pinned to the top-right corner over a reserved column.
+ * Everything this package has to say about a view — a warning, a failed
+ * query, a write that did not land, a ceiling about to be hit — is a
+ * sentence and at most a row of buttons, said above a result that is still
+ * the real one (D1). So the grid becomes a wrapping row and the action slot
+ * joins the end of it; nothing else about the component is touched.
+ *
+ * It is a cva extension in a wrapper rather than a copy of these classes at
+ * each call site (D16 ruling 8): there is one callout recipe, and a second
+ * one is how two callouts start disagreeing about what a warning looks like.
+ */
+export declare const lineAlertVariants: (props?: ({
+    tone?: "warning" | "error" | "info" | null | undefined;
+    frame?: "box" | "bare" | null | undefined;
+} & import('class-variance-authority/types').ClassProp) | undefined) => string;
+/**
+ * What a `LineAlert` takes: a `div`'s props, its tone and its frame. Written
+ * out rather than read off the vendored `Alert` and the class recipe, so a
+ * registry update (`shadcn add --diff`) never changes this public type
+ * (R2-85); `test/variants.test.tsx` holds the two in step.
+ */
+export interface LineAlertProps extends React.ComponentProps<'div'> {
+    tone: AlertTone;
+    /** `box`, the default: a band of its own. `bare`: no frame, smaller type. */
+    frame?: LineAlertFrame | null;
+}
+/** How a `LineAlert` is framed; see `LineAlertProps.frame`. */
+export type LineAlertFrame = 'box' | 'bare';
+/**
+ * One callout, one line high.
+ *
+ * The tone decides three things together, which is the point of having one
+ * of these: the colour, the icon, and how it is announced — an error
+ * interrupts a screen reader (`role="alert"`), a warning or a note waits its
+ * turn (`role="status"`), because only what stopped the view is worth
+ * cutting across whatever its reader was doing.
+ *
+ * The sentence goes in an `AlertTitle` and the buttons in an `AlertAction`.
+ * There is no description: the sentence *is* the message (D1), and a title
+ * with nothing under it is a heading for an empty section.
+ */
+export declare function LineAlert({ tone, frame, className, children, ...props }: LineAlertProps): React.JSX.Element;
+//# sourceMappingURL=alerts.d.ts.map

package/dist/ui/kit/alerts.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"alerts.d.ts","sourceRoot":"","sources":["../../../src/ui/kit/alerts.tsx"],"names":[],"mappings":"AAaA,OAAO,KAAK,KAAK,KAAK,MAAM,OAAO,CAAC;AAGpC,OAAO,EAAmB,QAAQ,EAAqB,MAAM,cAAc,CAAC;AAI5E,2EAA2E;AAC3E,MAAM,MAAM,SAAS,GAAG,OAAO,GAAG,SAAS,GAAG,MAAM,CAAC;AAErD;;;;;;;GAOG;AACH,eAAO,MAAM,SAAS,EAAE,MAAM,CAAC,SAAS,EAAE,OAAO,QAAQ,CAIxD,CAAC;AAEF;;;;;;;;;;;;;;GAcG;AACH,eAAO,MAAM,iBAAiB;;;8EA6D7B,CAAC;AAEF;;;;;GAKG;AACH,MAAM,WAAW,cAAe,SAAQ,KAAK,CAAC,cAAc,CAAC,KAAK,CAAC;IACjE,IAAI,EAAE,SAAS,CAAC;IAChB,6EAA6E;IAC7E,KAAK,CAAC,EAAE,cAAc,GAAG,IAAI,CAAC;CAC/B;AAED,+DAA+D;AAC/D,MAAM,MAAM,cAAc,GAAG,KAAK,GAAG,MAAM,CAAC;AAE5C;;;;;;;;;;;;GAYG;AACH,wBAAgB,SAAS,CAAC,EACxB,IAAI,EACJ,KAAK,EACL,SAAS,EACT,QAAQ,EACR,GAAG,KAAK,EACT,EAAE,cAAc,qBAahB"}

package/dist/ui/kit/anchor.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Where a menu is placed: the mark or row pressed, or the point it was
+ * pressed at. The charts hand one over with every press and the follow-up
+ * menu hangs from it, so it lives beside neither (2026-09-27 quality
+ * review: the charts reached into `analysis/DrillMenu.tsx` for it while
+ * the analysis folder drew the charts, a cycle between the two folders).
+ */
+export type PickAnchor = Element | {
+    getBoundingClientRect(): DOMRect;
+};
+/** The point a pointer event happened at, as something a menu can anchor to. */
+export declare function pointAnchor(event: {
+    clientX: number;
+    clientY: number;
+}): PickAnchor;
+//# sourceMappingURL=anchor.d.ts.map