@cosmicdrift/kumiko-renderer 0.384.0 → 0.386.0

package/dist/web/app/dashboard-shared.js

@@ -0,0 +1,171 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { createContext, useCallback, useContext, useEffect, useRef, useState, } from "react";
+import { currencyDecimals } from "../../headless/index.js";
+import { dispatcherErrorText, useLocale, usePrimitives, useQuery, useTranslation, } from "../../index.js";
+import { resolveSafeLocale } from "../primitives/locale-number.js";
+import { formatMoney } from "../primitives/money-input.js";
+import { Skeleton } from "../ui/skeleton.js";
+import { EmptyState, LoadingState } from "../widgets/states.js";
+import { useRelativeTimeFormatter } from "./relative-time.js";
+const SKELETON_SEGMENT_WIDTHS = ["100%", "72%", "48%"];
+export const WIDE_PANEL = "sm:col-span-2 lg:col-span-4";
+export const HALF_PANEL = "sm:col-span-2 lg:col-span-2";
+const CURRENCY_CODE_PATTERN = /^[A-Za-z]{3}$/;
+export const HOUR_MS = 3_600_000;
+export const DAY_MS = 24 * HOUR_MS;
+const SKELETON_BAR_HEIGHTS = ["40%", "65%", "50%", "85%", "60%", "75%", "45%", "70%"];
+export function panelPayload(panel, screenParams) {
+    return {
+        ...(panel.ignoreScreenFilter === true ? {} : screenParams.filterParams),
+        ...screenParams.rangeParams,
+        ...screenParams.recordParams,
+        ...panel.params,
+    };
+}
+export const DashboardQueryContext = createContext({
+    refreshIntervalMs: undefined,
+    register: () => () => { },
+});
+export function useRefetchRegistry() {
+    const registered = useRef(new Set());
+    const register = useCallback((refetch) => {
+        registered.current.add(refetch);
+        return () => {
+            registered.current.delete(refetch);
+        };
+    }, []);
+    const refetchRegistered = useCallback(async () => {
+        await Promise.all([...registered.current].map((refetch) => refetch()));
+    }, []);
+    return { register, refetchRegistered };
+}
+/** Live query of a panel or gate that takes part in the dashboard's refresh:
+ *  polls at the screen's interval and is refetched by `refetchAll` after an
+ *  action. A disabled query registers nothing. */
+export function useDashboardQuery(type, payload, options = {}) {
+    const { refreshIntervalMs, register } = useContext(DashboardQueryContext);
+    const enabled = options.enabled ?? true;
+    const result = useQuery(type, payload, {
+        live: true,
+        enabled,
+        ...(refreshIntervalMs !== undefined && { refetchIntervalMs: refreshIntervalMs }),
+    });
+    const { refetch } = result;
+    useEffect(() => (enabled ? register(refetch) : undefined), [enabled, register, refetch]);
+    return result;
+}
+export function useDashboardFormats() {
+    const resolver = useLocale();
+    const locale = resolver.locale();
+    const timeZone = resolver.timeZone();
+    const formatRelative = useRelativeTimeFormatter(locale);
+    const number = new Intl.NumberFormat(locale, { maximumFractionDigits: 1 });
+    // Without the significant-digit cap, values below the locale's first
+    // abbreviation step keep a decimal ("298.989,9 €" in de); lessPrecision
+    // picks whichever rule rounds more, so that becomes "299.000 €" while
+    // "1,5 Mio. €" keeps its one decimal.
+    const compactOptions = {
+        notation: "compact",
+        maximumFractionDigits: 1,
+        maximumSignificantDigits: 3,
+        roundingPriority: "lessPrecision",
+    };
+    const compactNumber = new Intl.NumberFormat(locale, compactOptions);
+    const percent = new Intl.NumberFormat(locale, { style: "percent", maximumFractionDigits: 0 });
+    const day = new Intl.DateTimeFormat(locale, { day: "2-digit", month: "2-digit", timeZone });
+    const month = new Intl.DateTimeFormat(locale, { month: "2-digit", year: "numeric", timeZone });
+    const hour = new Intl.DateTimeFormat(locale, { hour: "2-digit", minute: "2-digit", timeZone });
+    const dateTime = new Intl.DateTimeFormat(locale, {
+        dateStyle: "medium",
+        timeStyle: "short",
+        timeZone,
+    });
+    const medium = new Intl.DateTimeFormat(locale, { dateStyle: "medium", timeZone });
+    const formatMinor = (amountMinor, currency, fractionDigits) => formatMoney(amountMinor, currency, locale, fractionDigits);
+    return {
+        timeZone,
+        formatMedium: (atMs) => medium.format(atMs),
+        formatMinor,
+        formatRelative,
+        formatPanelValue: (valueFormat) => valueFormat === undefined
+            ? (value) => number.format(value)
+            : (value) => formatMinor(value, valueFormat.currency, valueFormat.fractionDigits),
+        formatPanelAxisValue: (valueFormat) => {
+            if (valueFormat === undefined || !CURRENCY_CODE_PATTERN.test(valueFormat.currency)) {
+                return (value) => compactNumber.format(value);
+            }
+            const compactMoney = new Intl.NumberFormat(resolveSafeLocale(locale), {
+                ...compactOptions,
+                style: "currency",
+                currency: valueFormat.currency,
+            });
+            const decimals = currencyDecimals(valueFormat.currency);
+            return (value) => compactMoney.format(value / 10 ** decimals);
+        },
+        formatNumber: (value) => number.format(value),
+        formatPercent: (fraction) => percent.format(fraction),
+        formatDay: (atMs) => day.format(atMs),
+        formatMonth: (atMs) => month.format(atMs),
+        formatHour: (atMs) => hour.format(atMs),
+        formatDateTime: (atMs) => dateTime.format(atMs),
+    };
+}
+export function PanelShell({ testId, title, subtitle, action, children, }) {
+    return (_jsxs("section", { "data-testid": testId, className: "flex h-full flex-col rounded-lg border border-border bg-card text-card-foreground", children: [_jsxs("header", { className: "flex min-h-11 shrink-0 flex-wrap items-center justify-between gap-x-3 gap-y-2 border-b border-border-row px-4 py-2", children: [_jsxs("div", { className: "flex min-w-0 flex-col gap-0.5", children: [_jsx("h2", { className: "text-sm font-semibold break-words", children: title }), subtitle !== undefined && _jsx("p", { className: "text-xs text-muted-foreground", children: subtitle })] }), action !== undefined && _jsx("div", { className: "shrink-0", children: action })] }), _jsx("div", { className: "grow p-4", children: children })] }));
+}
+export function PanelError({ label, error, onRetry, testId, }) {
+    const { Button } = usePrimitives();
+    const t = useTranslation();
+    return (_jsxs("div", { role: "alert", "data-testid": testId, className: "flex flex-col items-start gap-2 rounded-lg border border-dashed border-status-bad/40 px-4 py-6 text-sm", children: [_jsx("div", { className: "font-medium text-status-bad", children: t("kumiko.dashboard.panel.error.title", { label }) }), _jsx("div", { className: "text-muted-foreground", children: dispatcherErrorText(error, t) }), _jsx(Button, { variant: "secondary", onClick: onRetry, children: t("kumiko.dashboard.panel.error.retry") }), _jsx("div", { className: "text-xs text-muted-foreground", children: t("kumiko.dashboard.panel.error.isolated") })] }));
+}
+function PanelSkeleton({ shape }) {
+    const t = useTranslation();
+    if (shape === "rows")
+        return _jsx(LoadingState, { rows: 3 });
+    if (shape === "segments") {
+        return (_jsx("output", { "aria-label": t("kumiko.widget.loading"), className: "flex flex-col gap-4", children: SKELETON_SEGMENT_WIDTHS.map((width) => (_jsxs("div", { className: "flex flex-col gap-1.5", children: [_jsx(Skeleton, { className: "h-3 w-24" }), _jsx(Skeleton, { className: "h-2.5 rounded-full", style: { width } })] }, width))) }));
+    }
+    return (_jsx("output", { "aria-label": t("kumiko.widget.loading"), className: "flex h-40 items-end gap-1", children: SKELETON_BAR_HEIGHTS.map((height) => (_jsx(Skeleton, { className: "flex-1", style: { height } }, height))) }));
+}
+export function QueryPanel({ panel, label, subtitle, action, screenParams, translate, skeleton, isEmpty, children, }) {
+    const formats = useDashboardFormats();
+    const { data, error, loading, refetch } = useDashboardQuery(panel.query, panelPayload(panel, screenParams));
+    useReportPanelLoaded(data);
+    let body;
+    if (loading && data === null) {
+        body = _jsx(PanelSkeleton, { shape: skeleton });
+    }
+    else if (error !== null) {
+        body = _jsx(PanelError, { label: label, error: error, onRetry: () => void refetch() });
+    }
+    else if (data === null || isEmpty(data)) {
+        body = (_jsx(EmptyState, { title: translate(panel.emptyLabel ?? "kumiko.list.no-entries"), description: panel.emptyHint !== undefined ? translate(panel.emptyHint) : undefined }));
+    }
+    else {
+        body = children(data, formats);
+    }
+    return (_jsx(PanelShell, { testId: `dashboard-panel-${panel.id}`, title: label, subtitle: subtitle, action: action, children: body }));
+}
+// Starts at render time and restarts whenever the merged query params change;
+// panels additionally report each successful (re)load, so live refetches and
+// retries keep the stamp current.
+export function useLoadedAt(screenParams) {
+    const paramsKey = JSON.stringify([
+        screenParams.filterParams,
+        screenParams.rangeParams,
+        screenParams.recordParams,
+    ]);
+    const [loaded, setLoaded] = useState(() => ({ paramsKey, atMs: Date.now() }));
+    if (loaded.paramsKey !== paramsKey)
+        setLoaded({ paramsKey, atMs: Date.now() });
+    const reportLoaded = useCallback((atMs) => setLoaded((prev) => (prev.atMs >= atMs ? prev : { ...prev, atMs })), []);
+    return { loadedAtMs: loaded.atMs, reportLoaded };
+}
+export const PanelLoadedContext = createContext(() => { });
+export function useReportPanelLoaded(data) {
+    const reportLoaded = useContext(PanelLoadedContext);
+    useEffect(() => {
+        if (data !== null)
+            reportLoaded(Date.now());
+    }, [data, reportLoaded]);
+}

package/dist/web/app/dashboard-text.d.ts

@@ -0,0 +1,6 @@
+import type { Translate } from "../../headless/index.ts";
+import type { DashboardFormats } from "./dashboard-shared.tsx";
+export declare function isRecord(value: unknown): value is Readonly<Record<string, unknown>>;
+/** Plain strings pass through; DashboardI18nText is translated (nested params first).
+ *  Anything else yields undefined so callers fall back to their own placeholder. */
+export declare function resolveDashboardText(value: unknown, translate: Translate, formats: DashboardFormats): string | undefined;

package/dist/web/app/dashboard-text.js

@@ -0,0 +1,65 @@
+const MAX_TEXT_PARAM_DEPTH = 4;
+export function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isDashboardI18nText(value) {
+    return isRecord(value) && typeof value["i18nKey"] === "string";
+}
+function isMoneyParam(value) {
+    return (isRecord(value) &&
+        value["kind"] === "money" &&
+        typeof value["amountMinor"] === "number" &&
+        typeof value["currency"] === "string");
+}
+function isDateParam(value) {
+    return isRecord(value) && value["kind"] === "date" && typeof value["atMs"] === "number";
+}
+function isRelativeTimeParam(value) {
+    return isRecord(value) && value["kind"] === "relativeTime" && typeof value["atMs"] === "number";
+}
+function isTextParam(value) {
+    return (typeof value === "string" ||
+        typeof value === "number" ||
+        isDashboardI18nText(value) ||
+        isMoneyParam(value) ||
+        isDateParam(value) ||
+        isRelativeTimeParam(value));
+}
+function resolveTextParam(param, translate, formats, depth) {
+    if (typeof param === "string" || typeof param === "number")
+        return param;
+    if (isMoneyParam(param))
+        return formats.formatMinor(param.amountMinor, param.currency);
+    if (isDateParam(param))
+        return formats.formatMedium(param.atMs);
+    if (isRelativeTimeParam(param))
+        return formats.formatRelative(param.atMs);
+    if (isDashboardI18nText(param)) {
+        // Too deep: show the key instead of recursing further.
+        return depth >= MAX_TEXT_PARAM_DEPTH
+            ? param.i18nKey
+            : resolveI18nText(param, translate, formats, depth + 1);
+    }
+    return "";
+}
+function resolveI18nText(text, translate, formats, depth) {
+    if (text.i18nParams === undefined)
+        return translate(text.i18nKey);
+    const params = {};
+    for (const [name, param] of Object.entries(text.i18nParams)) {
+        if (isTextParam(param))
+            params[name] = resolveTextParam(param, translate, formats, depth);
+    }
+    return translate(text.i18nKey, params);
+}
+/** Plain strings pass through; DashboardI18nText is translated (nested params first).
+ *  Anything else yields undefined so callers fall back to their own placeholder. */
+export function resolveDashboardText(value, translate, formats) {
+    if (typeof value === "string")
+        return value;
+    if (typeof value === "number")
+        return String(value);
+    if (isDashboardI18nText(value))
+        return resolveI18nText(value, translate, formats, 1);
+    return undefined;
+}

package/dist/web/layout/nav-tree.js

@@ -1,6 +1,7 @@
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { ChevronDown, ChevronRight, Plus, Search } from "lucide-react";
 import { createContext, useCallback, useContext, useEffect, useMemo, useRef, useState, } from "react";
+import { rendererWarn } from "../../dev-console.js";
 import { resolveNavigation } from "../../headless/index.js";
 import { createLiveRefetchScheduler } from "../../hooks/live-refetch-scheduler.js";
 import { lastSegment, toAppSchema, useLiveEvents, useNav, useTranslation } from "../../index.js";
@@ -140,8 +141,7 @@ function NavLeadingIcon({ node, active, expanded = false, label, }) {
     const NavIcon = iconKey !== undefined && isKnownIcon ? NAV_ICON_LOOKUP[iconKey] : undefined;
     useEffect(() => {
         if (iconKey !== undefined && !isKnownIcon) {
-            // biome-ignore lint/suspicious/noConsole: diagnostic for unregistered nav icon keys
-            console.warn(`[kumiko] Nav entry "${node.qualifiedName}" references icon "${iconKey}", which is not ` +
+            rendererWarn(`[kumiko] Nav entry "${node.qualifiedName}" references icon "${iconKey}", which is not ` +
                 `registered in NAV_ICONS — falling back to the dot indicator. Check the icon key spelling.`);
         }
     }, [iconKey, isKnownIcon, node.qualifiedName]);
@@ -316,8 +316,7 @@ function warnTreeActionMisconfigured(label, problem) {
     if (warnedTreeActionLabels.has(key))
         return;
     warnedTreeActionLabels.add(key);
-    // biome-ignore lint/suspicious/noConsole: dev-warning for a setup error
-    console.warn(`[kumiko] Nav action "${label}" ${problem}`);
+    rendererWarn(`[kumiko] Nav action "${label}" ${problem}`);
 }
 // An action button carries screen XOR target (see TreeAction) — `screen`
 // renders a KumikoLink to the route, `target` a dispatch button. Same

package/dist/web/layout/target-resolver-stub.js

@@ -16,6 +16,7 @@
 // die URL via nav.setSearchParams UND ruft den globalen dispatchTarget für
 // Test-Listener-Kompatibilität.
 import { useCallback } from "react";
+import { rendererDebug } from "../../dev-console.js";
 import { requestLeave, useNav } from "../../index.js";
 import { serializeTarget } from "./target-url.js";
 let testListener;
@@ -31,8 +32,7 @@ export function dispatchTarget(target) {
         }
         return;
     }
-    // biome-ignore lint/suspicious/noConsole: fallback wenn kein Subscriber registered
-    console.debug("[NavTree] target dispatched (unhandled)", target);
+    rendererDebug("[NavTree] target dispatched (unhandled)", target);
 }
 /** Test-Hook: Exklusiver Spy. Returnt cleanup. */
 export function setDispatchListener(fn) {

package/dist/web/primitives/banner.d.ts

@@ -0,0 +1,4 @@
+import type { ReactNode } from "react";
+import type { BannerProps } from "../../index.ts";
+import "../react-css-custom-properties.ts";
+export declare function DefaultBanner({ variant, title, titleTestId, children, actions, padded, testId, id, }: BannerProps): ReactNode;

package/dist/web/primitives/banner.js

@@ -0,0 +1,28 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { cn } from "../lib/cn.js";
+import "../react-css-custom-properties.js";
+import { fieldLabelId } from "./field.js";
+// ---- Banner (shadcn: Alert) ----
+export function DefaultBanner({ variant = "info", title, titleTestId, children, actions, padded, testId, id, }) {
+    const isError = variant === "error";
+    const isWarning = variant === "warning";
+    const isPrimary = variant === "primary";
+    // `id` is set when a <Field> wraps this Banner as its control (see
+    // BannerProps.id). A <div> isn't labelable, so a <label htmlFor> pointing
+    // at it is inert for screen readers — role="group" + aria-labelledby is
+    // the actual mechanism, pointed at the label id Field emits (fieldLabelId).
+    const bannerRole = id !== undefined ? "group" : isError ? "alert" : undefined;
+    const banner = (_jsxs("div", { role: bannerRole, ...(id !== undefined && { "aria-labelledby": fieldLabelId(id) }), "data-testid": testId, "data-variant": variant, className: cn("relative w-full rounded-lg border px-4 py-3 text-sm flex items-center gap-3", 
+        // Viewport breakpoint like the form footer bar; actions drop below the text on phones.
+        isPrimary && "flex-col items-start sm:flex-row sm:items-center", isError
+            ? "border-destructive/50 text-destructive bg-destructive/10 dark:border-destructive"
+            : isWarning
+                ? "border-status-warn/30 bg-status-warn/10 text-status-warn"
+                : isPrimary
+                    ? "border-l-4 border-l-primary bg-card text-card-foreground"
+                    : "bg-card text-card-foreground"), children: [_jsxs("div", { className: "flex-1", children: [title !== undefined && (_jsx("div", { "data-testid": titleTestId, className: "font-semibold", children: title })), children] }), actions !== undefined && _jsx("div", { "data-slot": "actions", children: actions })] }));
+    // Page state: the banner sits alone in main (which no longer has padding).
+    // The wrapper adds 24px outer spacing so the banner does not stick
+    // edge-to-edge to the sidebar/browser.
+    return padded === true ? _jsx("div", { className: "p-6", children: banner }) : banner;
+}

package/dist/web/primitives/button.d.ts

@@ -0,0 +1,7 @@
+import type { IconKey } from "@cosmicdrift/kumiko-framework/ui-types";
+import type { ReactNode } from "react";
+import type { ButtonProps } from "../../index.ts";
+import "../react-css-custom-properties.ts";
+export declare function actionIconFor(icon: IconKey | undefined): IconKey | undefined;
+export declare const SECONDARY_BUTTON_EXTRA_CLASSES = "border-input hover:bg-muted";
+export declare function DefaultButton({ type, onClick, disabled, loading, variant, size, ariaLabel, title, pressed, expanded, width, children, testId, className, ref, icon, iconEnd, dataAttributes, }: ButtonProps): ReactNode;

package/dist/web/primitives/button.js

@@ -0,0 +1,48 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Loader2 } from "lucide-react";
+import { NAV_ICONS } from "../icons.js";
+import { cn } from "../lib/cn.js";
+import { Button as UiButton } from "../ui/button.js";
+import "../react-css-custom-properties.js";
+// ---- Button (vendored shadcn ui/button) ----
+// Contract variant -> shadcn variant: secondary has always been the
+// bordered bg-background look = shadcn's `outline`. primary->default,
+// danger->destructive, link->link (no bg, underline on hover).
+const BUTTON_VARIANT = {
+    primary: "default",
+    secondary: "outline",
+    danger: "destructive",
+    link: "link",
+    "danger-ghost": "ghost",
+    ghost: "ghost",
+};
+const BUTTON_SIZE = {
+    sm: "sm",
+    md: "default",
+    icon: "icon",
+};
+// Closed IconKey vocabulary, checked against the shared NAV_ICONS registry
+// (icons.tsx) — an unknown key (schema data isn't statically typed against
+// IconKey the way this prop is) renders no icon instead of crashing, same
+// fallback shape as fieldIconFor above.
+export function actionIconFor(icon) {
+    return icon !== undefined && Object.hasOwn(NAV_ICONS, icon) ? icon : undefined;
+}
+// Shared by DefaultButton's `secondary` variant and triggers that need Radix `asChild`
+// prop forwarding (which DefaultButton does not support), so both stay visually identical.
+export const SECONDARY_BUTTON_EXTRA_CLASSES = "border-input hover:bg-muted";
+export function DefaultButton({ type = "button", onClick, disabled, loading, variant = "primary", size = "md", ariaLabel, title, pressed, expanded, width = "auto", children, testId, className, ref, icon, iconEnd, dataAttributes, }) {
+    // The link variant renders text-like (inline link in running text/banner),
+    // not as a padded surface; width="full" stretches CTA buttons in cards/panels.
+    const resolvedClassName = cn(variant === "link" ? "h-auto px-0 py-0" : "", variant === "danger-ghost"
+        ? "text-destructive hover:text-destructive hover:bg-destructive/10"
+        : "", variant === "ghost" ? "text-primary hover:text-primary hover:bg-primary/10" : "", variant === "secondary" ? SECONDARY_BUTTON_EXTRA_CLASSES : "", pressed === true
+        ? "border-primary/40 bg-accent text-accent-foreground ring-1 ring-primary/30"
+        : "", width === "full" ? "w-full" : "", className);
+    const IconStart = icon !== undefined ? NAV_ICONS[icon] : undefined;
+    const IconEnd = iconEnd !== undefined ? NAV_ICONS[iconEnd] : undefined;
+    // Loading swaps the leading icon slot for a spinner and keeps `children` —
+    // replacing the label would shift the button's width mid-submit.
+    const leading = loading === true ? (_jsx(Loader2, { className: "size-4 animate-spin", "aria-hidden": "true" })) : IconStart !== undefined ? (_jsx(IconStart, { className: "size-4", "aria-hidden": "true" })) : null;
+    return (_jsxs(UiButton, { ref: ref, type: type, onClick: onClick, disabled: disabled === true || loading === true, ...dataAttributes, "data-testid": testId, "data-loading": loading === true ? "true" : undefined, variant: BUTTON_VARIANT[variant], size: BUTTON_SIZE[size], "aria-label": ariaLabel, "aria-pressed": pressed, "aria-expanded": expanded, title: title ?? (size === "icon" ? ariaLabel : undefined), className: resolvedClassName, children: [leading, children, IconEnd !== undefined && _jsx(IconEnd, { className: "size-4", "aria-hidden": "true" })] }));
+}

package/dist/web/primitives/card-styles.d.ts

@@ -0,0 +1,8 @@
+import "../react-css-custom-properties.ts";
+export declare const cardSurface: (props?: ({
+    radius?: "lg" | "xl" | null | undefined;
+} & import("class-variance-authority/types").ClassProp) | undefined) => string;
+export declare const cardFooter = "flex flex-wrap items-center justify-end gap-2 py-4";
+export declare const cardFooterInset = "px-[var(--card-padding)]";
+export declare const cardFooterBorder = "border-t bg-muted/50";
+export declare const cardHeaderBorder = "border-b bg-muted/50";

package/dist/web/primitives/card-styles.js

@@ -0,0 +1,18 @@
+import { cva } from "class-variance-authority";
+import "../react-css-custom-properties.js";
+// ---- Card chrome (one definition for form/section/card) ----
+// The one card surface. Dimensions (padding/radius/shadow) come from --card-*
+// CSS tokens (defaults in styles.css) so an app can override them once,
+// centrally, in its styles.css, like the colors. Radius variant:
+// xl = card/screen surface (default, token-driven), lg = "inner" surface.
+export const cardSurface = cva("flex flex-col border bg-card text-card-foreground shadow-[var(--card-shadow)]", {
+    variants: { radius: { xl: "rounded-[var(--card-radius)]", lg: "rounded-lg" } },
+    defaultVariants: { radius: "xl" },
+});
+// Wraps instead of running off-screen when the row outgrows its container (fw#2528).
+export const cardFooter = "flex flex-wrap items-center justify-end gap-2 py-4";
+export const cardFooterInset = "px-[var(--card-padding)]";
+// /30 read as nearly invisible against the light-theme card (white card,
+// muted at 94% lightness) — /50 keeps the same token, just a stronger step.
+export const cardFooterBorder = "border-t bg-muted/50";
+export const cardHeaderBorder = "border-b bg-muted/50";

package/dist/web/primitives/card.d.ts

@@ -0,0 +1,4 @@
+import type { ReactNode } from "react";
+import type { CardProps } from "../../index.ts";
+import "../react-css-custom-properties.ts";
+export declare function DefaultCard({ slots, options, className, testId, dataAttributes, children, }: CardProps): ReactNode;

package/dist/web/primitives/card.js

@@ -0,0 +1,41 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { cn } from "../lib/cn.js";
+import { InsideScreenFormColumnContext } from "./metric.js";
+import "../react-css-custom-properties.js";
+import { cardFooter, cardFooterBorder, cardFooterInset, cardSurface } from "./card-styles.js";
+import { FormScreenShell } from "./form.js";
+// Generic card chrome (rounded-xl like the entity card), slot- and
+// options-based so the contract grows additively and consumers never have
+// to migrate.
+export function DefaultCard({ slots, options, className, testId, dataAttributes, children, }) {
+    const screenBody = options?.screenBody ?? false;
+    const padded = screenBody ? false : (options?.padded ?? true);
+    const radius = options?.radius ?? "xl";
+    const footerBordered = options?.footerBordered ?? true;
+    const footerInset = options?.footerInset ?? true;
+    const fillHeight = options?.fillHeight ?? false;
+    const framed = screenBody ? false : (options?.framed ?? true);
+    const s = slots ?? {};
+    const defaultHeader = s.title !== undefined ||
+        s.subtitle !== undefined ||
+        s.headerContent !== undefined ||
+        s.headerActions !== undefined ? (_jsxs("div", { className: cn("flex flex-col gap-3 px-[var(--card-padding)] pt-6 pb-4", fillHeight && "shrink-0"), children: [(s.title !== undefined || s.subtitle !== undefined || s.headerActions !== undefined) && (_jsxs("div", { className: "flex flex-wrap items-start justify-between gap-3", children: [_jsxs("div", { className: "flex flex-col gap-1", children: [s.title !== undefined && (_jsx("h3", { className: "text-base font-semibold leading-none tracking-tight", children: s.title })), s.subtitle !== undefined && (_jsx("p", { className: "text-sm text-muted-foreground", children: s.subtitle }))] }), s.headerActions] })), s.headerContent] })) : null;
+    const header = s.header ?? defaultHeader;
+    const hasHeader = header !== null && header !== undefined;
+    const card = (_jsxs("div", { ...dataAttributes, "data-slot": "card", "data-testid": testId, className: cn(framed ? cardSurface({ radius }) : "flex flex-col", 
+        // An unframed card has no radius to clip; overflow-hidden would also
+        // zero its flex-item min-height and cut off content inside a scroller.
+        (framed || fillHeight) && "overflow-hidden", 
+        // Same "no flex-1" reasoning as DefaultForm's own fillHeight card
+        // (fw#2722/#2778): sizes to content and only shrinks (min-h-0) once
+        // an ancestor is itself height-constrained.
+        fillHeight && "min-h-0 flex flex-col", className), children: [header, children != null && (_jsx("div", { className: cn("grow", screenBody && "flex flex-col gap-6", padded &&
+                    (hasHeader
+                        ? "px-[var(--card-padding)] pb-[var(--card-padding)]"
+                        : "p-[var(--card-padding)]"), 
+                // The one region allowed to shrink and scroll internally — mirrors
+                // FormSections' fillHeight === true && "min-h-0" treatment of the
+                // section it wraps.
+                fillHeight && "min-h-0 flex flex-col"), children: children })), s.footer !== undefined && s.footer !== null && s.footer !== false && (_jsx("div", { className: cn(cardFooter, footerInset && cardFooterInset, footerBordered && cardFooterBorder, fillHeight && "shrink-0"), children: s.footer }))] }));
+    return (_jsx(InsideScreenFormColumnContext.Provider, { value: false, children: screenBody ? _jsx(FormScreenShell, { children: card }) : card }));
+}

package/dist/web/primitives/contexts.d.ts

@@ -0,0 +1,22 @@
+import { type ReactNode } from "react";
+import type { FormWidth } from "../../index.ts";
+import "../react-css-custom-properties.ts";
+export declare const FieldLayoutContext: import("react").Context<"inline" | "row" | "stacked" | undefined>;
+export declare const ScreenFormContext: import("react").Context<boolean>;
+export declare const DrawerBodyContext: import("react").Context<boolean>;
+export declare const FieldLabelledContext: import("react").Context<boolean>;
+export declare const FieldDescriptionContext: import("react").Context<string | undefined>;
+export declare const InsideFormContext: import("react").Context<boolean>;
+export declare const BareFormContext: import("react").Context<boolean>;
+export declare const EmbeddedFormContext: import("react").Context<boolean>;
+export declare function EmbeddedFormProvider({ children }: {
+    children: ReactNode;
+}): ReactNode;
+export declare function BareFormProvider({ children }: {
+    children: ReactNode;
+}): ReactNode;
+export declare const ScreenWidthContext: import("react").Context<FormWidth | undefined>;
+export declare function ScreenWidthProvider({ width, children, }: {
+    readonly width: FormWidth | undefined;
+    readonly children: ReactNode;
+}): ReactNode;

package/dist/web/primitives/contexts.js

@@ -0,0 +1,50 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { createContext } from "react";
+import "../react-css-custom-properties.js";
+// Boolean optics depend on the surrounding Field layout: layout="inline"
+// (checkbox lists like MultiSelectCheckboxes, the BooleanField widget) keeps
+// the checkbox, the standard form field (layout="stacked"/default) gets the
+// new switch. Pure web-renderer rendering decision, no contract field needed
+// — Field hands its resolved layout down to the nested Input via context.
+export const FieldLayoutContext = createContext("stacked");
+// True inside the sections of a card-less screen form: sections then drop their
+// own horizontal padding, the screen form's scroll surface provides it.
+export const ScreenFormContext = createContext(false);
+export const DrawerBodyContext = createContext(false);
+// aria-labelledby into a Field label that doesn't exist leaves a radiogroup
+// without any accessible name — fall back to the control's name instead.
+export const FieldLabelledContext = createContext(false);
+// The Field description is the control's accessible description; the control
+// is a descendant (not a prop of Field), so the id travels via context. Always
+// provided (undefined without a description) so a nested Field never inherits
+// its parent's description id.
+export const FieldDescriptionContext = createContext(undefined);
+// ---- Form + Section + Grid + Text ----
+// Puts DefaultSection into inner-region mode: the whole form is ONE card,
+// sections are divider-separated parts inside it (shadcn pattern like
+// Shipping/Invoice/Profile). Standalone (outside a form) a section stays its
+// own card.
+export const InsideFormContext = createContext(false);
+// Embedded forms (e.g. in AuthCard) already get their card surface from the
+// container; the self-carding DefaultForm would otherwise produce a
+// card-in-card. BareFormProvider switches DefaultForm to a bare <form>
+// (stacked fields, no frame of its own/max-width).
+export const BareFormContext = createContext(false);
+// Dashboard panels with an embedded settings form (`DashboardScreenPanel.chromeless`):
+// the form renders in the page grid like a standalone screen form, without the
+// card frame, but keeps its own (non-pinned) save bar.
+export const EmbeddedFormContext = createContext(false);
+export function EmbeddedFormProvider({ children }) {
+    return _jsx(EmbeddedFormContext.Provider, { value: true, children: children });
+}
+export function BareFormProvider({ children }) {
+    return _jsx(BareFormContext.Provider, { value: true, children: children });
+}
+// App-wide default for FormScreenShell's width when a screen doesn't set its
+// own `layout.width`. Undefined (no `createKumikoApp({ screenWidth })`) lets each
+// shell keep its own default: "4xl" for FormScreenShell, 640px for the
+// screen-form column.
+export const ScreenWidthContext = createContext(undefined);
+export function ScreenWidthProvider({ width, children, }) {
+    return _jsx(ScreenWidthContext.Provider, { value: width, children: children });
+}

package/dist/web/primitives/data-table-cell.d.ts

@@ -0,0 +1,76 @@
+import type { SelectOptionTone } from "@cosmicdrift/kumiko-framework/ui-types";
+import { type ReactNode } from "react";
+import type { CellLink, CellLinkItem, ListColumnFileDisplay, ListRowViewModel, RuntimeCellLink, RuntimeCellLinkItems } from "../../headless/index.ts";
+import type { DataTableSort } from "../../index.ts";
+import { type DataTableRowGrouping } from "../../index.ts";
+import "../react-css-custom-properties.ts";
+export declare function isEmptyCellValue(value: unknown): boolean;
+export declare function isUnlabeledFalse(type: string, value: unknown, renderer: unknown): boolean;
+export declare function showsBareCheckMark(type: string, value: unknown, renderer: unknown): boolean;
+export declare function isBadgeColumn(col: {
+    readonly type: string;
+    readonly renderer?: unknown;
+}): boolean;
+export declare function FirstCellLink({ enabled, empty, emptyLabel, onOpen, children, }: {
+    readonly enabled: boolean;
+    readonly empty: boolean;
+    readonly emptyLabel?: string | undefined;
+    readonly onOpen: () => void;
+    readonly children: ReactNode;
+}): ReactNode;
+export declare const FIT_CONTENT_CELL_CLASS = "w-px";
+export declare function SortableHeader({ field, label, sortable, highlighted, numeric, fitContent, sort, onSortChange, }: {
+    readonly field: string;
+    readonly label: string;
+    readonly sortable: boolean;
+    readonly highlighted?: boolean;
+    readonly numeric?: boolean;
+    readonly fitContent?: boolean;
+    readonly sort?: DataTableSort;
+    readonly onSortChange?: (next: DataTableSort | null) => void;
+}): ReactNode;
+export declare function isComponentRendererRef(renderer: unknown): {
+    readonly name: string;
+} | undefined;
+export declare function defaultCellRender(value: unknown, type: string, optionLabels?: Readonly<Record<string, string>>, locale?: string, columnKey?: string, grouping?: boolean): string;
+export declare function cellTitle(value: unknown): string | undefined;
+type DataTableCellProps = {
+    readonly value: unknown;
+    readonly row: Readonly<Record<string, unknown>>;
+    readonly field: string;
+    readonly type: string;
+    readonly renderer?: unknown;
+    readonly optionLabels?: Readonly<Record<string, string>>;
+    readonly optionTones?: Readonly<Partial<Record<string, SelectOptionTone>>>;
+    readonly onChange?: (value: unknown) => void;
+    readonly translate?: (key: string, params?: Readonly<Record<string, unknown>>) => string;
+    readonly locale?: string;
+    readonly grouping?: boolean;
+    readonly fileDisplay?: ListColumnFileDisplay;
+    readonly compactFile?: boolean;
+    readonly link?: CellLink;
+    readonly linkItems?: readonly CellLinkItem[];
+};
+export declare function cellLinkProp(col: {
+    readonly field: string;
+    readonly linkFor?: RuntimeCellLink | undefined;
+    readonly linkItemsFor?: RuntimeCellLinkItems | undefined;
+}, row: ListRowViewModel, allowed: boolean): {
+    readonly link?: CellLink;
+    readonly linkItems?: readonly CellLinkItem[];
+};
+export type TableItem = {
+    readonly kind: "group";
+    readonly key: string;
+    readonly label: string;
+    readonly collapsed: boolean;
+} | {
+    readonly kind: "row";
+    readonly row: ListRowViewModel;
+};
+export declare function buildTableItems(rows: readonly ListRowViewModel[], grouping: DataTableRowGrouping | undefined, toggledGroups: ReadonlySet<string>): readonly TableItem[];
+export declare function rowToneClass(tone: SelectOptionTone | undefined): string;
+export declare const NUMERIC_COLUMN_TYPES: ReadonlySet<string>;
+export declare const TABULAR_COLUMN_TYPES: ReadonlySet<string>;
+export declare function DataTableCell({ value, row, field, type, renderer, optionLabels, optionTones, onChange, translate, locale, grouping, fileDisplay, compactFile, link, linkItems, }: DataTableCellProps): ReactNode;
+export {};