@cosmicdrift/kumiko-renderer 0.328.0 → 0.328.1

package/dist/primitives.js

@@ -0,0 +1,73 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { createContext, useContext, } from "react";
+/** Structural marker a top-level `actions` node can carry so DefaultForm's
+ *  sticky-footer split (fw#1918) treats it as the pinned primary action even
+ *  though it isn't a `Button` with `type="submit"` — e.g. RenderEdit's
+ *  footer-slot mount, whose actual rendered button is opaque app code the
+ *  split can't inspect (see `ScreenSlots.footerPrimary`). */
+export const STICKY_PRIMARY_ACTION_PROP = "kumikoStickyPrimaryAction";
+/** Teil-C action-icon collapse rule: a group of more than two actions where
+ *  every member carries an icon renders icon-only instead of wall-to-wall
+ *  text buttons; any icon-less member keeps the whole group on text so it
+ *  doesn't fall apart visually mid-group. */
+export function shouldRenderActionsIconOnly(actions) {
+    return actions.length > 2 && actions.every((a) => a.icon !== undefined);
+}
+// Status value -> StatusTone heuristic, shared by every surface that shows a
+// raw status value without a tone of its own (projectionDetail header badge,
+// list cells). Covers the common status vocabularies; unknown values stay
+// undefined so the caller keeps its own neutral default.
+const STATUS_TONE_BY_VALUE = {
+    ok: "ok",
+    active: "ok",
+    done: "ok",
+    complete: "ok",
+    completed: "ok",
+    paid: "ok",
+    approved: "ok",
+    published: "ok",
+    success: "ok",
+    pending: "warn",
+    processing: "warn",
+    review: "warn",
+    "in-review": "warn",
+    waiting: "warn",
+    open: "warn",
+    draft: "warn",
+    failed: "bad",
+    error: "bad",
+    overdue: "bad",
+    rejected: "bad",
+    blocked: "bad",
+    critical: "bad",
+};
+const STATUS_TONE_BY_OPTION_TONE = {
+    ok: "ok",
+    warn: "warn",
+    bad: "bad",
+    neutral: "muted",
+};
+export function statusToneForOptionTone(tone) {
+    return STATUS_TONE_BY_OPTION_TONE[tone];
+}
+export function statusToneForValue(value) {
+    const slug = value
+        .trim()
+        .toLowerCase()
+        .replace(/[\s_]+/g, "-");
+    // Own-key check: the value comes from row data, and a plain object lookup
+    // would hand back `Object.prototype.constructor` & friends as a "tone".
+    return Object.hasOwn(STATUS_TONE_BY_VALUE, slug) ? STATUS_TONE_BY_VALUE[slug] : undefined;
+}
+// ---- Context + Provider + Hook ----
+const PrimitivesContext = createContext(undefined);
+export function PrimitivesProvider({ children, value }) {
+    return _jsx(PrimitivesContext.Provider, { value: value, children: children });
+}
+export function usePrimitives() {
+    const registry = useContext(PrimitivesContext);
+    if (registry === undefined) {
+        throw new Error("usePrimitives: no <PrimitivesProvider> mounted. Wrap your app in one (createKumikoApp does this for you with defaultPrimitives from @cosmicdrift/kumiko-renderer-web).");
+    }
+    return registry;
+}

package/dist/screen-fills-height.d.ts

@@ -0,0 +1,3 @@
+export declare function screenFillsHeight(screen: {
+    readonly fillHeight?: boolean;
+}): boolean;

package/dist/screen-fills-height.js

@@ -0,0 +1,3 @@
+export function screenFillsHeight(screen) {
+    return screen.fillHeight !== false;
+}

package/dist/share-links.d.ts

@@ -0,0 +1,4 @@
+/** wa.me link that opens WhatsApp with `text` prefilled — addressed to
+ *  `phone` when given (any formatting; international form required, a
+ *  leading "+" or "00" is accepted), otherwise WhatsApp's contact picker. */
+export declare function buildWhatsAppShareUrl(text: string, phone?: string): string;

package/dist/share-links.js

@@ -0,0 +1,11 @@
+/** wa.me link that opens WhatsApp with `text` prefilled — addressed to
+ *  `phone` when given (any formatting; international form required, a
+ *  leading "+" or "00" is accepted), otherwise WhatsApp's contact picker. */
+export function buildWhatsAppShareUrl(text, phone) {
+    const recipient = phone === undefined ? "" : whatsAppRecipientDigits(phone);
+    return `https://wa.me/${recipient}?text=${encodeURIComponent(text)}`;
+}
+function whatsAppRecipientDigits(phone) {
+    const digits = phone.replace(/\D/g, "");
+    return digits.startsWith("00") ? digits.slice(2) : digits;
+}

package/dist/sort-by-accessor.d.ts

@@ -0,0 +1,5 @@
+import type { DataTableSort } from "./primitives.js";
+/** Sorts `rows` by a `DataTableSort` against a field->accessor map. Unknown
+ *  field or `sort === null` returns `rows` unchanged (no-op, not an error —
+ *  callers pass whatever the DataTable reports). */
+export declare function sortByAccessor<TRow>(rows: readonly TRow[], sort: DataTableSort | null, accessors: Readonly<Record<string, (row: TRow) => string | number>>): readonly TRow[];

package/dist/sort-by-accessor.js

@@ -0,0 +1,16 @@
+/** Sorts `rows` by a `DataTableSort` against a field->accessor map. Unknown
+ *  field or `sort === null` returns `rows` unchanged (no-op, not an error —
+ *  callers pass whatever the DataTable reports). */
+export function sortByAccessor(rows, sort, accessors) {
+    if (sort === null)
+        return rows;
+    const accessor = accessors[sort.field];
+    if (accessor === undefined)
+        return rows;
+    const factor = sort.dir === "asc" ? 1 : -1;
+    return [...rows].sort((a, b) => {
+        const av = accessor(a);
+        const bv = accessor(b);
+        return av < bv ? -factor : av > bv ? factor : 0;
+    });
+}

package/dist/sse/live-events.d.ts

@@ -0,0 +1,23 @@
+import { type ReactNode } from "react";
+export type LiveEvent = {
+    readonly type: string;
+    readonly data: {
+        readonly id: string;
+        readonly aggregateType: string;
+        readonly version: number;
+        readonly payload: unknown;
+        readonly createdAt: string;
+    };
+};
+/** Abonniert Live-Events für eine Entity (aggregateType). Returnt die
+ *  Unsubscribe-Funktion. Mehrere Subscriptions parallel auf dieselbe
+ *  Entity sind erlaubt — jede bekommt ihr eigenes Event. */
+export type LiveEventSubscriber = (entityName: string, listener: (event: LiveEvent) => void) => () => void;
+export type LiveEventsProviderProps = {
+    readonly children: ReactNode;
+    readonly value: LiveEventSubscriber;
+};
+export declare function LiveEventsProvider({ children, value }: LiveEventsProviderProps): ReactNode;
+/** Hook für useQuery-like Consumer. Liefert die Subscribe-Function
+ *  aus dem Context. Wenn kein Provider da ist, ist's ein No-op. */
+export declare function useLiveEvents(): LiveEventSubscriber;

package/dist/sse/live-events.js

@@ -0,0 +1,28 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+// Live-Events-Contract, plattform-neutral. Die Plattform (Web mit
+// EventSource, Native mit polyfill) liefert einen `LiveEventSubscriber`
+// via `<LiveEventsProvider value={...}>`; der shared-Layer konsumiert
+// nur das Interface.
+//
+// Warum ein Context statt Module-Singleton wie vor dem Split: ein
+// Module-Singleton koppelt an eine globale Verbindung. Mit Context
+// kann der Caller pro Tree eine andere Subscribe-Quelle durchreichen
+// — nützlich in Tests (Fake-Feed), bei Multi-Tenant-Bridges, und
+// beim Native-Renderer wo die Verbindungs-Lifecycle oft nicht dem
+// App-Lifecycle entspricht.
+import { createContext, useContext } from "react";
+// Wenn kein Provider da ist, liefern wir einen No-op-Subscriber statt
+// zu crashen. Grund: useQuery({ live: true }) kann optimistisch
+// ausgehakt werden ohne den ganzen Baum abzureißen, wenn die Plattform
+// z.B. SSE temporär deaktiviert hat. Fehler-Signale würden stumm
+// geschluckt — das ist explizit dokumentiert.
+const noopSubscriber = () => () => { };
+const LiveEventsContext = createContext(noopSubscriber);
+export function LiveEventsProvider({ children, value }) {
+    return _jsx(LiveEventsContext.Provider, { value: value, children: children });
+}
+/** Hook für useQuery-like Consumer. Liefert die Subscribe-Function
+ *  aus dem Context. Wenn kein Provider da ist, ist's ein No-op. */
+export function useLiveEvents() {
+    return useContext(LiveEventsContext);
+}

package/dist/tokens.d.ts

@@ -0,0 +1,83 @@
+import { type ReactNode } from "react";
+export type ColorTokens = {
+    readonly background: string;
+    readonly foreground: string;
+    readonly card: string;
+    readonly cardForeground: string;
+    readonly popover: string;
+    readonly popoverForeground: string;
+    readonly primary: string;
+    readonly primaryForeground: string;
+    readonly secondary: string;
+    readonly secondaryForeground: string;
+    readonly muted: string;
+    readonly mutedForeground: string;
+    readonly accent: string;
+    readonly accentForeground: string;
+    readonly destructive: string;
+    readonly destructiveForeground: string;
+    readonly border: string;
+    readonly input: string;
+    readonly ring: string;
+};
+export type RadiusTokens = {
+    readonly sm: string;
+    readonly md: string;
+    readonly lg: string;
+    readonly xl: string;
+};
+export type FontTokens = {
+    readonly sans: string;
+    readonly heading: string;
+    readonly mono: string;
+};
+export type ShadowTokens = {
+    readonly card: string;
+};
+export type SpacingTokens = {
+    readonly card: string;
+};
+export type CoreTokens = {
+    readonly color: ColorTokens;
+    readonly radius: RadiusTokens;
+    readonly font: FontTokens;
+    readonly shadow: ShadowTokens;
+    readonly spacing: SpacingTokens;
+};
+/** Erweiterung für App-eigene Token-Kategorien. Devs augmentieren:
+ *
+ *    declare module "@cosmicdrift/kumiko-renderer" {
+ *      interface AppTokens {
+ *        chart: { gridline: string; line: string };
+ *      }
+ *    }
+ *
+ *  Und reichen im App-CSS die passenden `--chart-*` Variablen rein.
+ *  Kumikos Default-Primitives nutzen nur CoreTokens. */
+export interface AppTokens {
+}
+export type Tokens = CoreTokens & AppTokens;
+export type ThemeMode = "light" | "dark";
+export type TokensApi = {
+    readonly tokens: Tokens;
+    readonly mode: ThemeMode;
+    readonly setMode: (mode: ThemeMode) => void;
+    readonly toggleMode: () => void;
+};
+export type TokensProviderProps = {
+    readonly children: ReactNode;
+    readonly value: TokensApi;
+};
+export declare function TokensProvider({ children, value }: TokensProviderProps): ReactNode;
+/** Read-only Tokens-Hook. Liefert CSS-var-Strings — nutzbar in
+ *  style-Props oder Tailwind-arbitrary-values wie
+ *  `bg-[var(--color-primary)]` (selten, die shadcn-Tailwind-Klassen
+ *  `bg-primary` sind idiomatischer). */
+export declare function useTokens(): Tokens;
+/** Volle API inkl. Theme-Toggle. Für den Dark/Light-Switch-Button. */
+export declare function useTokenController(): TokensApi;
+/** Tokens mit var-string-Werten. Konstant — die "Werte" sind
+ *  Referenzen, die echten Farben ändern sich per CSS ohne dass das
+ *  Objekt mutiert werden muss. Plattform-Packages (renderer-web,
+ *  -native) importieren das in ihre TokensApi-Impl. */
+export declare const cssVarTokens: Tokens;

package/dist/tokens.js

@@ -0,0 +1,80 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+// Design-Tokens im shadcn-Namensschema. Werte sind CSS-Variable-
+// Referenzen (`var(--color-primary)`) — die echten Zahlen leben in
+// styles.css (Web) bzw. in einer StyleSheet.create-Config (Native,
+// später). Der Hook ist vor allem für Custom-Components die mal
+// einen Token-Wert in eine JS-style-prop schieben müssen; die
+// Default-Primitives nutzen direkt Tailwind-Klassen und brauchen
+// ihn nicht.
+//
+// Theme-Toggle läuft über `.dark`-Class auf `<html>` — kein JS-State
+// nötig, CSS rendert sofort neu. `useTokenController().toggleTheme()`
+// ist nur ein DOM-Wrapper, kein eigener React-State.
+//
+// Erweiterbar: AppTokens-Interface wie bei Primitives. Dev kann
+// eigene Token-Kategorien deklarieren und mit var-Strings befüllen.
+import { createContext, useContext } from "react";
+// ---- Context + Provider + Hooks ----
+const TokensContext = createContext(undefined);
+export function TokensProvider({ children, value }) {
+    return _jsx(TokensContext.Provider, { value: value, children: children });
+}
+/** Read-only Tokens-Hook. Liefert CSS-var-Strings — nutzbar in
+ *  style-Props oder Tailwind-arbitrary-values wie
+ *  `bg-[var(--color-primary)]` (selten, die shadcn-Tailwind-Klassen
+ *  `bg-primary` sind idiomatischer). */
+export function useTokens() {
+    return useTokenController().tokens;
+}
+/** Volle API inkl. Theme-Toggle. Für den Dark/Light-Switch-Button. */
+export function useTokenController() {
+    const api = useContext(TokensContext);
+    if (api === undefined) {
+        throw new Error("useTokens/useTokenController: no <TokensProvider> mounted. createKumikoApp verdrahtet den Provider automatisch mit @cosmicdrift/kumiko-renderer-web defaults.");
+    }
+    return api;
+}
+/** Tokens mit var-string-Werten. Konstant — die "Werte" sind
+ *  Referenzen, die echten Farben ändern sich per CSS ohne dass das
+ *  Objekt mutiert werden muss. Plattform-Packages (renderer-web,
+ *  -native) importieren das in ihre TokensApi-Impl. */
+export const cssVarTokens = {
+    color: {
+        background: "var(--color-background)",
+        foreground: "var(--color-foreground)",
+        card: "var(--color-card)",
+        cardForeground: "var(--color-card-foreground)",
+        popover: "var(--color-popover)",
+        popoverForeground: "var(--color-popover-foreground)",
+        primary: "var(--color-primary)",
+        primaryForeground: "var(--color-primary-foreground)",
+        secondary: "var(--color-secondary)",
+        secondaryForeground: "var(--color-secondary-foreground)",
+        muted: "var(--color-muted)",
+        mutedForeground: "var(--color-muted-foreground)",
+        accent: "var(--color-accent)",
+        accentForeground: "var(--color-accent-foreground)",
+        destructive: "var(--color-destructive)",
+        destructiveForeground: "var(--color-destructive-foreground)",
+        border: "var(--color-border)",
+        input: "var(--color-input)",
+        ring: "var(--color-ring)",
+    },
+    radius: {
+        sm: "var(--radius-sm)",
+        md: "var(--radius-md)",
+        lg: "var(--radius-lg)",
+        xl: "var(--radius-xl)",
+    },
+    font: {
+        sans: "var(--font-sans)",
+        heading: "var(--font-heading)",
+        mono: "var(--font-mono)",
+    },
+    shadow: {
+        card: "var(--card-shadow)",
+    },
+    spacing: {
+        card: "var(--card-padding)",
+    },
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-renderer",
-  "version": "0.328.0",
+  "version": "0.328.1",
   "description": "Platform-agnostic React renderer for Kumiko screens. Contains the shared logic — primitives-contract, hooks, KumikoScreen, navigation & SSE abstractions — that any platform-specific renderer (web, native) composes. No DOM, no EventSource, no react-dom.",
   "license": "BUSL-1.1",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -10,14 +10,14 @@
   },
   "exports": {
     ".": {
-      "types": "./src/index.ts",
-      "default": "./src/index.ts"
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
     }
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-framework": "0.328.0",
-    "@cosmicdrift/kumiko-headless": "0.328.0",
-    "@cosmicdrift/kumiko-types": "0.328.0",
+    "@cosmicdrift/kumiko-framework": "0.328.1",
+    "@cosmicdrift/kumiko-headless": "0.328.1",
+    "@cosmicdrift/kumiko-types": "0.328.1",
     "react": "^19.2.6",
     "temporal-polyfill": "^0.3.2",
     "zod": "^4.4.3"
@@ -28,7 +28,7 @@
     "@types/react-dom": "^19.2.3",
     "jsdom": "^29.1.1",
     "react-dom": "^19.2.6",
-    "@cosmicdrift/kumiko-locale-de": "0.328.0"
+    "@cosmicdrift/kumiko-locale-de": "0.328.1"
   },
   "repository": {
     "type": "git",
@@ -41,10 +41,17 @@
   },
   "publishConfig": {
     "registry": "https://registry.npmjs.org",
-    "access": "public"
+    "access": "public",
+    "exports": {
+      ".": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      }
+    }
   },
   "files": [
-    "src",
+    "dist",
+    "src/changes.json",
     "README.md",
     "LICENSE"
   ]

package/src/__tests__/error-i18n-defaults.test.ts

@@ -1,82 +0,0 @@
-import { describe, expect, test } from "bun:test";
-import {
-  AccessDeniedError,
-  ConflictError,
-  FeatureDisabledError,
-  InternalError,
-  NotFoundError,
-  RateLimitError,
-  UnconfiguredError,
-  UniqueViolationError,
-  UnprocessableError,
-  ValidationError,
-  VersionConflictError,
-} from "@cosmicdrift/kumiko-framework/errors";
-import { localeDeBundle } from "@cosmicdrift/kumiko-locale-de";
-import { REQUIRED_FIELD_I18N_KEY } from "../app/form-schema";
-import { kumikoDefaultTranslations } from "../i18n-defaults";
-
-// Keys are read off LIVE error instances, not a hardcoded list — a copied list
-// would mirror the bundle and never catch a renamed i18nKey or a new error
-// class shipped without a default translation. Ship an 11th error class (or
-// rename a key) without adding the default → this fails.
-const errorInstances = [
-  new InternalError(),
-  new AccessDeniedError(),
-  new NotFoundError("Thing"),
-  new ConflictError(),
-  new VersionConflictError({ entityId: 1, expectedVersion: 1, currentVersion: 2 }),
-  new UniqueViolationError({ entityName: "Thing" }),
-  new UnprocessableError("reason"),
-  new UnconfiguredError({ feature: "f", key: "k" }),
-  new FeatureDisabledError("f", "h"),
-  new RateLimitError({
-    bucket: "b",
-    limit: 1,
-    windowSeconds: 1,
-    remaining: 0,
-    retryAfterSeconds: 1,
-    resetAt: "1970-01-01T00:00:00Z",
-  }),
-  new ValidationError({ fields: [] }),
-];
-
-const de = localeDeBundle;
-const en = kumikoDefaultTranslations["en"];
-
-describe("kumikoDefaultTranslations covers every error i18nKey", () => {
-  for (const e of errorInstances) {
-    test(`${e.code} → ${e.i18nKey} has en default and de locale-package copy`, () => {
-      expect(de[e.i18nKey]).toBeTruthy();
-      expect(en?.[e.i18nKey]).toBeTruthy();
-    });
-  }
-
-  // Client-emitted (renderer-web download helper) — not thrown by a class, but
-  // rendered through the same last-resort bundle. Gap #5 named it explicitly.
-  test("errors.download.urlMissing has de+en default", () => {
-    expect(de?.["errors.download.urlMissing"]).toBeTruthy();
-    expect(en?.["errors.download.urlMissing"]).toBeTruthy();
-  });
-
-  // Client-emitted (dispatcher-live error-mapping) — network/abort never
-  // reach the server, so no error class mints these; still rendered through
-  // this last-resort bundle whenever a feature reads res.error.i18nKey raw.
-  test("dispatcher.errors.network has de+en default", () => {
-    expect(de?.["dispatcher.errors.network"]).toBeTruthy();
-    expect(en?.["dispatcher.errors.network"]).toBeTruthy();
-  });
-
-  test("dispatcher.errors.aborted has de+en default", () => {
-    expect(de?.["dispatcher.errors.aborted"]).toBeTruthy();
-    expect(en?.["dispatcher.errors.aborted"]).toBeTruthy();
-  });
-
-  // Client-emitted (form-schema.ts required-field presence check) — not
-  // thrown by an error class, applied as a params.i18nKey override on a zod
-  // issue instead; still rendered through this last-resort bundle.
-  test("form-schema's required-field i18nKey has de+en default", () => {
-    expect(de[REQUIRED_FIELD_I18N_KEY]).toBeTruthy();
-    expect(en?.[REQUIRED_FIELD_I18N_KEY]).toBeTruthy();
-  });
-});

package/src/__tests__/format-when.test.ts

@@ -1,12 +0,0 @@
-import { describe, expect, test } from "bun:test";
-import { formatWhen } from "../format-when";
-
-describe("formatWhen", () => {
-  test("formats a parseable ISO timestamp", () => {
-    expect(formatWhen("2024-01-01T00:00:00.000Z")).not.toBe("2024-01-01T00:00:00.000Z");
-  });
-
-  test("falls back to the raw value on an unparseable input", () => {
-    expect(formatWhen("garbage")).toBe("garbage");
-  });
-});