@magicvr/schema-ui-ui 0.1.0

package/components/data-table.d.ts

@@ -0,0 +1,43 @@
+import type { ReactNode } from "react";
+export type SortOrder = "asc" | "desc";
+export interface SortState {
+    field: string;
+    order: SortOrder;
+}
+export interface DataTableColumn<T> {
+    key: string;
+    /** Cell content or header node (checkboxes render in headers for selection). */
+    label: ReactNode;
+    sortable?: boolean;
+    /** W4 · GOAL-005: render the string fallback single-line truncated with a
+     *  native title full-text affordance so long values do not crowd out
+     *  sibling columns. Custom render cells are unaffected. Since the
+     *  table-style refresh every string cell truncates by default; this flag
+     *  is kept for schema declarations that opt into the 16rem cap. */
+    truncate?: boolean;
+    /** Column width hint (px number or CSS length). Content-driven auto layout
+     *  otherwise; a column that declares a width skips the default max-width
+     *  cap so it can exceed it (table-layout auto still grows on content). */
+    width?: number | string;
+    /** Minimum column width (px number or CSS length). */
+    minWidth?: number | string;
+    render?: (row: T) => ReactNode;
+}
+export interface DataTableProps<T> {
+    columns: DataTableColumn<T>[];
+    rows: T[];
+    rowKey: (row: T) => string;
+    sort?: SortState;
+    onSortChange?: (sort: SortState | null) => void;
+    loading?: boolean;
+    error?: string | null;
+    emptyMessage?: string;
+    caption?: string;
+    /** Invoked when a data row is clicked (row selection, S4 · GOAL-007). */
+    onRowClick?: (row: T) => void;
+    /** Row key of the currently selected row (highlight), S4 · GOAL-007. */
+    selectedKey?: string;
+    /** W15-F02: retry control shown in the error state. */
+    onRetry?: () => void;
+}
+export declare function DataTable<T>({ columns, rows, rowKey, sort, onSortChange, loading, error, emptyMessage, caption, onRowClick, selectedKey, onRetry, }: DataTableProps<T>): import("react").JSX.Element;

package/components/ui/async-state.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Shared pure state determination for async display regions (S4 · GOAL-004).
+ *
+ * statCard / chart / list-table each fetch a resource independently and used
+ * to invent their own ad-hoc "Loading…" text placeholder. This module
+ * centralizes the loading / error / empty / ready decision into one pure,
+ * directly-testable function so every consumer renders the same sequence
+ * (Skeleton while loading, a `role="alert"` message on error, a muted empty
+ * message otherwise) instead of drifting independently.
+ */
+export type AsyncDisplayState = "loading" | "error" | "empty" | "ready";
+export interface AsyncDisplayInput {
+    /** True while the underlying fetch/request has not yet settled. */
+    loading: boolean;
+    /** Non-null when the fetch/request failed. */
+    error: string | null;
+    /** True when the fetch succeeded but produced no renderable rows/points. */
+    isEmpty?: boolean;
+}
+/**
+ * Resolves the single display state a region should show.
+ *
+ * Precedence: `error` wins over `loading` (a failed fetch is not "still
+ * loading" even if a stale loading flag lingers), and `loading` wins over
+ * `isEmpty` (emptiness is unknown until the fetch settles).
+ */
+export declare function resolveAsyncDisplayState({ loading, error, isEmpty, }: AsyncDisplayInput): AsyncDisplayState;

package/components/ui/badge.d.ts

@@ -0,0 +1,9 @@
+import * as React from "react";
+import { type VariantProps } from "class-variance-authority";
+declare const badgeVariants: (props?: ({
+    variant?: "default" | "secondary" | "destructive" | "success" | "outline" | null | undefined;
+} & import("class-variance-authority/types").ClassProp) | undefined) => string;
+export interface BadgeProps extends React.HTMLAttributes<HTMLDivElement>, VariantProps<typeof badgeVariants> {
+}
+declare function Badge({ className, variant, ...props }: BadgeProps): React.JSX.Element;
+export { Badge, badgeVariants };

package/components/ui/breadcrumbs.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Breadcrumb navigation for nested admin pages (GOAL-015).
+ *
+ * Semantic hierarchy, not visit history (user ruling 2026-08-14):
+ * the trail is the page's place in the manifest navigation tree
+ * (slot → group labels → page) plus consumer-declared parents for
+ * inner pages reached by row navigation (e.g. dictionary-entries →
+ * data-dictionary, task-runs → scheduled-tasks). No protocol change:
+ * the parent map is a web-shell declaration (BREADCRUMB_PAGE_PARENTS).
+ *
+ * Trail shape: 首页 => 一级页 => ... => n级内页 — the home page
+ * (manifest homePageRef, the domain-root default) always leads, then nav
+ * group labels and declared parents, then the current page. Visual: compact
+ * 12px trail — muted clickable ancestors (hover brighten + underline), thin
+ * "/" separators, brighter non-clickable current item, and an optional
+ * small circular ghost back button (semantic parent) at the far left.
+ */
+import { type MessageParams } from "@/i18n/catalog";
+export interface BreadcrumbEntry {
+    /** Page id (manifest pageId); group labels use the label text as key. */
+    pageId: string;
+    label: string;
+    /** Application route of this ancestor; empty for group labels. */
+    route: string;
+    /** True for the current (deepest) page. */
+    current: boolean;
+}
+export interface BreadcrumbPage {
+    pageId: string;
+    title?: string;
+    titleKey?: string;
+    route: string;
+}
+interface BreadcrumbNavItem {
+    pageRef?: string;
+    label?: string;
+    labelKey?: string;
+    items?: BreadcrumbNavItem[];
+}
+export declare function Breadcrumbs({ entries, onNavigate, onBack, showBack, }: {
+    entries: BreadcrumbEntry[];
+    onNavigate: (route: string) => void;
+    onBack: () => void;
+    /** Compact circular ghost back button (semantic parent), far left. */
+    showBack?: boolean;
+}): import("react").JSX.Element | null;
+/**
+ * Resolves the SEMANTIC breadcrumb trail for a matched page.
+ *
+ * Sources, in order:
+ *   1. manifest navigation tree — a page rendered under a group shows the
+ *      group labels as non-clickable ancestors (outermost first);
+ *   2. declared parents (options.parents) — inner pages reached by row
+ *      navigation declare their parent pageId; the chain walks up until a
+ *      page with no declared parent (its nav group chain, if any, is
+ *      included). Unknown declared parents fail safe (skipped).
+ *   3. pages not in the tree and without a declared parent are
+ *      single-level (no trail UI).
+ *
+ * This is NOT the visit history: the same page always shows the same
+ * trail regardless of how the user got there (user ruling 2026-08-14).
+ */
+export declare function resolveBreadcrumbTrail(pages: BreadcrumbPage[], currentPage: BreadcrumbPage | undefined, t: (key: string, params?: MessageParams, literalFallback?: string) => string, options?: {
+    navigation?: {
+        top?: BreadcrumbNavItem[];
+        sidebar?: BreadcrumbNavItem[];
+        user?: BreadcrumbNavItem[];
+    };
+    /** Consumer-declared parent pageId per inner page (web-shell level). */
+    parents?: Record<string, string>;
+    /**
+     * Home pageId (manifest app.homePageRef — the domain-root default page,
+     * not necessarily the dashboard). The trail ALWAYS starts with it:
+     * 首页 => 一级页 => ... => n级内页 (user spec 2026-08-14).
+     */
+    homePageId?: string;
+}): BreadcrumbEntry[];
+export {};

package/components/ui/button.d.ts

@@ -0,0 +1,11 @@
+import * as React from "react";
+import { type VariantProps } from "class-variance-authority";
+declare const buttonVariants: (props?: ({
+    variant?: "default" | "secondary" | "outline" | "ghost" | null | undefined;
+    size?: "default" | "sm" | "lg" | null | undefined;
+} & import("class-variance-authority/types").ClassProp) | undefined) => string;
+export interface ButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElement>, VariantProps<typeof buttonVariants> {
+    asChild?: boolean;
+}
+declare const Button: React.ForwardRefExoticComponent<ButtonProps & React.RefAttributes<HTMLButtonElement>>;
+export { Button, buttonVariants };

package/components/ui/card.d.ts

@@ -0,0 +1,8 @@
+import * as React from "react";
+declare const Card: React.ForwardRefExoticComponent<React.HTMLAttributes<HTMLDivElement> & React.RefAttributes<HTMLDivElement>>;
+declare const CardHeader: React.ForwardRefExoticComponent<React.HTMLAttributes<HTMLDivElement> & React.RefAttributes<HTMLDivElement>>;
+declare const CardTitle: React.ForwardRefExoticComponent<React.HTMLAttributes<HTMLHeadingElement> & React.RefAttributes<HTMLParagraphElement>>;
+declare const CardDescription: React.ForwardRefExoticComponent<React.HTMLAttributes<HTMLParagraphElement> & React.RefAttributes<HTMLParagraphElement>>;
+declare const CardContent: React.ForwardRefExoticComponent<React.HTMLAttributes<HTMLDivElement> & React.RefAttributes<HTMLDivElement>>;
+declare const CardFooter: React.ForwardRefExoticComponent<React.HTMLAttributes<HTMLDivElement> & React.RefAttributes<HTMLDivElement>>;
+export { Card, CardHeader, CardFooter, CardTitle, CardDescription, CardContent };

package/components/ui/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * @schema-ui/ui 聚合导出：设计系统原子 + DataTable 核心（R3 六包化）。
+ */
+export * from "./async-state";
+export * from "./badge";
+export * from "./breadcrumbs";
+export * from "./button";
+export * from "./card";
+export * from "./input";
+export * from "./label";
+export * from "./skeleton";
+export * from "./textarea";
+export * from "../data-table";

package/components/ui/input.d.ts

@@ -0,0 +1,5 @@
+import * as React from "react";
+export interface InputProps extends React.InputHTMLAttributes<HTMLInputElement> {
+}
+declare const Input: React.ForwardRefExoticComponent<InputProps & React.RefAttributes<HTMLInputElement>>;
+export { Input };

package/components/ui/label.d.ts

@@ -0,0 +1,3 @@
+import * as React from "react";
+declare const Label: React.ForwardRefExoticComponent<React.LabelHTMLAttributes<HTMLLabelElement> & React.RefAttributes<HTMLLabelElement>>;
+export { Label };

package/components/ui/skeleton.d.ts

@@ -0,0 +1,2 @@
+declare function Skeleton({ className, ...props }: React.HTMLAttributes<HTMLDivElement>): import("react").JSX.Element;
+export { Skeleton };

package/components/ui/textarea.d.ts

@@ -0,0 +1,5 @@
+import * as React from "react";
+export interface TextareaProps extends React.TextareaHTMLAttributes<HTMLTextAreaElement> {
+}
+declare const Textarea: React.ForwardRefExoticComponent<TextareaProps & React.RefAttributes<HTMLTextAreaElement>>;
+export { Textarea };

package/i18n/catalog.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Translation catalog (S1 · C2/C3).
+ *
+ * Catalogs are pure data files under `messages/`; `en-US` is the canonical
+ * baseline. Resolution order for a key in locale L:
+ *
+ *   catalog[L] → catalog[en-US] → observable missing-key event → key itself
+ *
+ * A key is "missing" only when neither the current catalog nor the en-US
+ * catalog has it; the en-US fallback is silent (designed behavior). Missing
+ * keys never render empty, never throw, and never block the flow; they are
+ * observable via the `schema-ui:missing-translation` window event (deduped
+ * per locale+key, so the first occurrence always reports).
+ */
+import { type Locale } from "./locale";
+export type MessageParams = Record<string, string | number>;
+export interface MissingTranslationDetail {
+    locale: Locale;
+    key: string;
+    /** Optional rendering context (e.g. "nav.sidebar", "page.users.form"). */
+    path?: string;
+}
+export declare const MISSING_TRANSLATION_EVENT = "schema-ui:missing-translation";
+/** True when the key exists in the given locale catalog. */
+export declare function hasTranslation(key: string, locale: Locale): boolean;
+/** Raw catalog text for a key, or null when the locale catalog lacks it. */
+export declare function lookupTranslation(key: string, locale: Locale): string | null;
+/** Replaces `{name}` placeholders with params; unknown placeholders stay. */
+export declare function interpolate(template: string, params?: MessageParams): string;
+/** Publishes a deduped missing-key report to the window event bus. */
+export declare function reportMissingTranslation(detail: MissingTranslationDetail): void;
+/** Resets the missing-key dedupe set (test seam). */
+export declare function resetMissingTranslationReports(): void;
+/**
+ * Resolves a message key for a locale with the frozen fallback chain.
+ * Never throws, never returns an empty string for a missing key.
+ *
+ * Fallback order: catalog[locale] → catalog[en-US] → `literalFallback`
+ * (protocol literal text, when supplied) → key itself.
+ */
+export declare function translate(key: string, params?: MessageParams, locale?: Locale, path?: string, literalFallback?: string): string;
+/** Binds a locale (+ optional context path) to a translate function. */
+export declare function createTranslator(locale: Locale, options?: {
+    path?: string;
+}): (key: string, params?: MessageParams, literalFallback?: string) => string;
+/**
+ * Resolves a schema/manifest text prop pair — the `*Key` field wins over the
+ * literal protocol text, and the literal text is the last fallback before the
+ * key itself (frozen chain: 当前语种 → en-US → 字面文本 → key).
+ */
+export declare function resolveTextProp(props: Record<string, unknown> | undefined, keyProp: string, literalProp: string, t: (key: string, params?: MessageParams, literalFallback?: string) => string, fallback?: string): string;

package/i18n/format.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Locale-aware date/number formatting (S1 · C5).
+ *
+ * Formatting follows the effective locale through Intl.* — no custom format
+ * templates (VP-007: "首版不暴露任意日期/数字格式模板，随有效 locale").
+ * Formatting is fail-safe: invalid inputs render empty, invalid timezones
+ * degrade to the locale's default zone instead of throwing.
+ */
+import { type Locale } from "./locale";
+export interface FormatOptions {
+    /** IANA timezone name; omitted = the environment's default zone. */
+    timeZone?: string;
+}
+/** Formats a date value in the given locale. Returns "" for invalid input. */
+export declare function formatDate(value: Date | string | number, locale?: Locale, options?: FormatOptions): string;
+/** Formats a finite number in the given locale. Returns "" for invalid input. */
+export declare function formatNumber(value: number, locale?: Locale, options?: Intl.NumberFormatOptions): string;

package/i18n/locale.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Locale pure-logic unit (S1 · C1).
+ *
+ * `resolveLocale` is a side-effect-free function that computes the effective
+ * locale from the user's explicit choice, the system default, and the browser
+ * language preferences. Keeping the decision logic in a plain function lets
+ * vitest exercise every branch without a browser.
+ *
+ * Frozen priority (VP-007 / D-002 §I-L10N-002, user-confirmed 2026-08-09):
+ *
+ *   user explicit choice → system default (non-auto) → browser preference
+ *   (auto) → en-US safe fallback
+ */
+export declare const SUPPORTED_LOCALES: readonly ["zh-CN", "en-US"];
+export type Locale = (typeof SUPPORTED_LOCALES)[number];
+/** The user-facing choice; "auto" defers to system/browser preference. */
+export type LocalePreference = Locale | "auto";
+export declare const DEFAULT_LOCALE: Locale;
+export interface LocaleResolutionInput {
+    /**
+     * localStorage["schema-ui:locale"] — the user's explicit choice.
+     * null / undefined / invalid → no explicit choice.
+     */
+    stored: string | null;
+    /**
+     * System default from the public bootstrap (/api/branding defaultLocale).
+     * "auto" or null → no system default.
+     */
+    systemDefault: string | null;
+    /** Browser language preferences in order (navigator.languages). */
+    browserLanguages: readonly string[];
+}
+export declare function isSupportedLocale(raw: string | null | undefined): raw is Locale;
+/**
+ * Normalizes a BCP 47-ish candidate to a supported locale.
+ * Accepts exact tags, case variants, underscore separators, and language-only
+ * prefixes ("zh", "zh-cn", "zh_CN", "en-US", "en", "en-us", "en-GB" → en-US).
+ * Returns null for anything else (including "auto").
+ */
+export declare function normalizeLocaleCandidate(raw: string | null | undefined): Locale | null;
+/**
+ * Resolves the effective locale using the frozen priority. Pure — no I/O.
+ */
+export declare function resolveLocale(input: LocaleResolutionInput): Locale;
+/**
+ * Normalizes a raw stored value into a LocalePreference.
+ * Any value that is not a supported locale resolves to "auto".
+ */
+export declare function normalizePreference(raw: string | null | undefined): LocalePreference;
+/** Real browser inputs for the boot path (provider default). */
+export declare function defaultBrowserLanguages(): readonly string[];

package/i18n/runtime.d.ts

@@ -0,0 +1,90 @@
+/**
+ * I18n React runtime (S1 · C4/C5).
+ *
+ * - Resolves the effective locale via `resolveLocale` (frozen priority).
+ * - Persists the user's explicit choice in localStorage["schema-ui:locale"]
+ *   (single channel, same pattern as the theme mechanism; login/logout never
+ *   clears it — D-002 §I-L10N-002).
+ * - Applies `document.documentElement.lang` on locale change.
+ * - Exposes `t` / `formatDate` / `formatNumber` to components.
+ */
+import { type ReactNode } from "react";
+import { type MessageParams } from "./catalog";
+import { type Locale, type LocalePreference } from "./locale";
+import { type TimezonePreference } from "./timezone";
+export declare const LOCALE_STORAGE_KEY = "schema-ui:locale";
+export declare function readStoredLocale(): string | null;
+export declare function writeStoredLocale(preference: LocalePreference): void;
+/** Applies the effective locale to <html lang>. No-op outside a browser. */
+export declare function applyLocaleToDocument(locale: Locale): void;
+/** Returns the provider's currently effective locale (defaults en-US). */
+export declare function getActiveLocale(): Locale;
+/** Internal: keeps the registry in sync with the provider's effective locale. */
+export declare function setActiveLocale(locale: Locale): void;
+export interface I18nState {
+    /** Effective (resolved) locale — always a supported locale. */
+    locale: Locale;
+    /** User preference; "auto" defers to system/browser defaults. */
+    preference: LocalePreference;
+    /** Sets the user preference and persists it (localStorage single channel). */
+    setPreference: (preference: LocalePreference) => void;
+    /** Effective timezone (IANA name or "auto" per contract §2 / L1–L4). */
+    timezone: string;
+    /** User timezone preference; "auto" defers to session/site defaults. */
+    timezonePreference: TimezonePreference;
+    /** Sets the user timezone preference and persists it (single channel). */
+    setTimezonePreference: (preference: TimezonePreference) => void;
+    /**
+     * Site-wide default currency (ISO 4217 from /api/branding; "" = unset).
+     * Money consumers use this as the explicit currency before falling back
+     * to the embedded per-locale map (contract §4.1 / §4.3).
+     */
+    defaultCurrency: string;
+    /** Translate a catalog key with the effective locale. */
+    t: (key: string, params?: MessageParams) => string;
+    /** Locale-aware date formatting (defaults to the effective timezone). */
+    formatDate: (value: Date | string | number, options?: {
+        timeZone?: string;
+    }) => string;
+    /** Locale-aware number formatting. */
+    formatNumber: (value: number, options?: Intl.NumberFormatOptions) => string;
+}
+export interface I18nProviderProps {
+    children: ReactNode;
+    /** System default locale from the public bootstrap; null/"auto" = none. */
+    systemDefault?: string | null;
+    /** Test seam: explicit stored preference (defaults to localStorage). */
+    stored?: string | null;
+    /** Test seam: browser language list (defaults to navigator.languages). */
+    browserLanguages?: readonly string[];
+    /**
+     * Site default timezone from /api/branding (contract §2 · L3). The provider
+     * also captures it from `systemDefaultUrl` when present; this prop wins.
+     */
+    siteTimezone?: string | null;
+    /** Test seam: explicit stored timezone preference (defaults to localStorage). */
+    storedTimezone?: string | null;
+    /** Test seam: session timezone probe (defaults to detectBrowserTimezone). */
+    detectTimezone?: () => string;
+    /** Site default currency (ISO 4217); test seam for /api/branding. */
+    siteDefaultCurrency?: string | null;
+    /**
+     * When set, the provider fetches this public startup endpoint once and
+     * re-resolves the system default locale from `defaultLocale` (VP-007 S3:
+     * the shell/login apply the site-wide default when the user has no
+     * explicit choice) and the site default timezone from `siteTimezone`
+     * (workspace-020 · contract §2 · L3). Applies after the initial resolve.
+     */
+    systemDefaultUrl?: string;
+}
+export declare function I18nProvider({ children, systemDefault, stored, browserLanguages, siteTimezone, storedTimezone, detectTimezone, siteDefaultCurrency, systemDefaultUrl, }: I18nProviderProps): import("react").JSX.Element;
+export declare function useI18n(): I18nState;
+/**
+ * Tolerant translator hook for deep renderer internals.
+ *
+ * Returns the provider's translator, or a safe default (en-US resolution +
+ * missing-key observable fallback) when no provider is mounted. Production
+ * always mounts I18nProvider; bare component tests and pre-provider surfaces
+ * degrade to the documented safe fallback instead of throwing.
+ */
+export declare function useTranslate(): (key: string, params?: MessageParams) => string;

package/i18n/timezone.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Timezone pure-logic unit (workspace-020 · R2 · C1).
+ *
+ * `resolveEffectiveTimezone` computes the effective timezone from the user's
+ * explicit override, the session probe, and the site default, per contract
+ * GOAL-002 D-001 §2 (user-confirmed I-001, 2026-08-26):
+ *
+ *   L1 user override (localStorage "schema-ui:timezone") → L2 session probe
+ *   (Intl) → L3 site default (siteTimezone) → L4 "auto" fallback
+ *
+ * Keeping the decision logic in plain functions lets vitest exercise every
+ * branch; the probe is injectable so tests do not depend on the host zone.
+ */
+export declare const TIMEZONE_STORAGE_KEY = "schema-ui:timezone";
+export declare const AUTO_TIMEZONE = "auto";
+/** The user-facing choice; a timezone IANA name or "auto". */
+export type TimezonePreference = string | "auto";
+export interface TimezoneResolutionInput {
+    /**
+     * localStorage["schema-ui:timezone"] — the user's explicit override.
+     * null / undefined / invalid / "auto" → no override (skip to L2).
+     */
+    stored: string | null;
+    /**
+     * Site default from the public bootstrap (/api/branding siteTimezone).
+     * "auto" / "" / null → unset (skip to L4 when L2 is empty).
+     */
+    siteDefault: string | null;
+    /**
+     * Session probe of the host zone (injectable; real default is
+     * `detectBrowserTimezone`). Invalid or empty results are skipped.
+     */
+    detect: () => string;
+}
+/**
+ * Validates an IANA timezone name via Intl (RangeError on invalid names).
+ * Side-effect-free apart from the noexcept Intl probe; returns false for
+ * empty / non-string / unknown zones instead of throwing.
+ */
+export declare function isValidIanaTimeZone(raw: string | null | undefined): raw is string;
+/**
+ * Normalizes a raw stored/site value into a TimezonePreference.
+ * Any value that is not a valid IANA name resolves to "auto".
+ */
+export declare function normalizeTimezonePreference(raw: string | null | undefined): TimezonePreference;
+/** Reads the stored user override; best-effort (privacy mode → null). */
+export declare function readStoredTimezone(): string | null;
+/** Persists the user override; "auto" removes the key (single channel). */
+export declare function writeStoredTimezone(preference: TimezonePreference): void;
+/** Real session probe: the host zone from Intl.resolvedOptions(). */
+export declare function detectBrowserTimezone(): string;
+/**
+ * Resolves the effective timezone per contract §2 (L1 → L2 → L3 → L4).
+ * Returns an IANA name, or "auto" when nothing is configured/detectable —
+ * consumers then fall back to the locale's default zone.
+ */
+export declare function resolveEffectiveTimezone(input: TimezoneResolutionInput): string;