@magicvr/schema-ui-shell 0.1.0

package/renderer/schema-table.d.ts

@@ -0,0 +1,90 @@
+import { type ResourceItem } from "@/renderer/resource";
+import type { RenderTableNode } from "@/renderer/render.types";
+/**
+ * Default schema-driven table surface (R1 · GOAL-004 / D-004) + S4 CRUD wiring
+ * + A-002 generic adapter (GOAL-010 S3).
+ *
+ * Renders a whitelisted table node's `props.columns` over its `props.dataSource`.
+ * Fails closed when the node declares no columns, no (valid) data source, or a
+ * response that violates the frozen rowKey invariant (F-001 / F-002).
+ *
+ * F-001 (I-010-001 v0.2.0 §2): `dataSource` must be a single-slash same-origin
+ * path; invalid/absent sources render an observable fail-closed state and never
+ * reach the (auth) fetcher.
+ *
+ * F-002 (I-010-001 v0.2.0 §3): `props.rowKey` (default `"id"`) is the direct
+ * field name of each row's unique, non-empty scalar key (string / finite
+ * number). A missing / empty / non-scalar / duplicate key stops rendering the
+ * table data and forbids row actions and selection.
+ *
+ * S4 (GOAL-007 · I-007-003 v0.2.2 §9): when rendered inside a `RenderPage`
+ * (which always wraps content in the SchemaCrudProvider), the table surfaces
+ * `props.toolbar` (create trigger) and `props.actions` (row edit/delete),
+ * participates in row selection for the page's recordView / edit-form prefill,
+ * reads its query from the shared per-table query state (so the search-form
+ * binding and the post-write reload both reach it), and registers its injected
+ * fetcher so modal form submits / row actions use the same transport. All of
+ * this is fixture-driven: no record-specific logic lives here.
+ */
+export interface SchemaTableProps {
+    node: RenderTableNode;
+    /** Injectable fetch (defaults to `globalThis.fetch`). */
+    fetcher?: typeof fetch;
+}
+export interface SchemaTableColumnSpec {
+    field: string;
+    label?: string;
+    sortable?: boolean;
+    /** W4 · GOAL-005: single-line truncate + title affordance for long values. */
+    truncate?: boolean;
+    /** Column width hint (px number or CSS length). */
+    width?: number | string;
+    /** Minimum column width (px number or CSS length). */
+    minWidth?: number | string;
+    /** W16-F04: render a cent-valued number as a localized currency string. */
+    format?: "currency";
+    /** W16-F09: render this cell as a colored badge using the row field value. */
+    badgeStyleField?: string;
+}
+/** Structured row predicate used by Schema actions; malformed predicates fail closed. */
+export declare function rowActionDisabled(action: unknown, row: ResourceItem): boolean;
+/** Extracts the table node's column specs, fail-closed on malformed entries. */
+export declare function schemaTableColumns(node: RenderTableNode): SchemaTableColumnSpec[];
+/**
+ * Resolves the table node's list endpoint (F-001). v2.9 prefers the node-level
+ * DataRef (ADR-0039, source:api url); the legacy props.dataSource string stays
+ * supported. Returns null when absent or not a single-slash same-origin path;
+ * the table then fails closed and never fetches (the fixture fallback was
+ * removed in GOAL-010 S3).
+ */
+export declare function schemaTableDataSource(node: RenderTableNode): string | null;
+/** v2.9 node-level DataRef params (ADR-0039 route bindings), else empty. */
+export declare function schemaTableDataParams(node: RenderTableNode): Record<string, unknown> | undefined;
+/** F-002: the direct field name used as each row's unique key (default "id"). */
+export declare function schemaTableRowKey(node: RenderTableNode): string;
+/** One select option of a schema-driven table filter. */
+export interface SchemaTableFilterOptionSpec {
+    value: string;
+    label?: string;
+    labelKey?: string;
+}
+/** A schema-driven table filter (table node `props.filters`; select-only). */
+export interface SchemaTableFilterSpec {
+    field: string;
+    type: "select";
+    label?: string;
+    labelKey?: string;
+    options: SchemaTableFilterOptionSpec[];
+}
+/**
+ * Extracts the table node's filter specs (fail-closed on malformed entries).
+ * Only `select` filters are supported; other/unknown types are dropped so a
+ * schema typo never renders a broken control.
+ */
+export declare function schemaTableFilters(node: RenderTableNode): SchemaTableFilterSpec[];
+/**
+ * Windowed pager page list: 1 … current±1 … total, with gap markers for
+ * long page runs (stable shape for tests and a11y).
+ */
+export declare function pagerPages(current: number, total: number): Array<number | "gap">;
+export declare function SchemaTable({ node, fetcher }: SchemaTableProps): import("react").JSX.Element;

package/theme/theme.d.ts

@@ -0,0 +1,64 @@
+/**
+ * Theme pure-logic unit (S1 · C3 + VP-007 S3 system default).
+ *
+ * `applyTheme` is a side-effect-free function that computes the desired theme
+ * and then applies it to the provided document root.  Keeping the decision
+ * logic in a plain function lets vitest exercise it without a browser.
+ *
+ * `initTheme` is the top-level boot call used by the synchronous external
+ * `/theme-init.js` script in index.html and by main.tsx (the module call is
+ * kept as a safety net for test/storybook entry points).
+ *
+ * VP-007 S3 priority (D-002, user-confirmed): user explicit choice →
+ * system default theme (from the public startup configuration, non-auto) →
+ * OS preference. The user's explicit choice always wins.
+ */
+export type Theme = "light" | "dark";
+export interface ThemeInput {
+    /** Value of `localStorage.getItem("theme")` — null when absent. */
+    stored: string | null;
+    /** `window.matchMedia("(prefers-color-scheme: dark)").matches` */
+    prefersDark: boolean;
+    /** System default theme from /api/branding (auto/light/dark); null = auto. */
+    systemDefault?: string | null;
+}
+export interface ThemeOutput {
+    theme: Theme;
+    /** CSS `color-scheme` value for the root element. */
+    colorScheme: "light" | "dark";
+}
+/**
+ * Pure function: decides the effective theme from storage + system default +
+ * OS preference. No DOM side-effects — safe to call in vitest.
+ */
+export declare function resolveTheme(input: ThemeInput): ThemeOutput;
+/**
+ * Applies the resolved theme to a DOM element (typically
+ * `document.documentElement`).  Adds or removes the `dark` class and sets
+ * the `color-scheme` style so native browser controls match.
+ */
+export declare function applyThemeToElement(el: HTMLElement, output: ThemeOutput): void;
+/**
+ * End-to-end theme boot: reads real browser APIs and mutates the DOM.
+ * Called from the synchronous external /theme-init.js script in index.html and from main.tsx.
+ *
+ * W4 P2-1: localStorage may throw when site storage is disabled (privacy
+ * mode). main.tsx calls initTheme at module top level — an uncaught throw
+ * would abort module evaluation and the app would never mount (white screen,
+ * not even the failure surface). Guard reads/writes exactly like tokens.ts.
+ */
+export declare function initTheme(): void;
+/**
+ * Applies the system default theme (from the public startup configuration)
+ * when the user has no explicit choice. VP-007 S3: the explicit user theme
+ * always wins; otherwise the system default (non-auto) beats the OS
+ * preference. Called after branding loads on the login page and the shell.
+ */
+export declare function applySystemDefaultTheme(systemDefault: string | null | undefined): void;
+/**
+ * Sets the user's preferred theme, persists it to localStorage, and applies
+ * it immediately.  Pass `null` to revert to OS preference. W4 P2-1: storage
+ * writes are best-effort — a disabled-storage environment still applies the
+ * theme for the current page.
+ */
+export declare function setTheme(theme: Theme | null): void;