@cosmicdrift/kumiko-renderer 0.373.0 → 0.377.0

package/dist/headless/apex/lightbox.js

@@ -0,0 +1,81 @@
+// Vanilla lightbox for Apex marketing pages — click .shot-frame img to enlarge,
+// prev/next (buttons or arrow keys) walks all .shot-frame images on the page.
+// Injected by renderApexPage; no React, no per-app wiring.
+export const APEX_LIGHTBOX_HTML = `<dialog id="apex-lightbox" class="apex-lightbox" aria-label="Screenshot preview">
+  <button type="button" class="apex-lightbox__close" aria-label="Close">&times;</button>
+  <button type="button" class="apex-lightbox__prev" aria-label="Previous screenshot">&lsaquo;</button>
+  <button type="button" class="apex-lightbox__next" aria-label="Next screenshot">&rsaquo;</button>
+  <img class="apex-lightbox__img" alt="" />
+</dialog>`;
+// Split from APEX_LIGHTBOX_SCRIPT so APEX_LIGHTBOX_SCRIPT_CSP_HASH hashes
+// exactly the bytes the browser executes — CSP's script-src hash-source
+// covers the content between <script> and </script>, nothing more/less.
+const APEX_LIGHTBOX_SCRIPT_BODY = `
+(function () {
+  var dlg = document.getElementById("apex-lightbox");
+  if (!dlg) return;
+  var img = dlg.querySelector(".apex-lightbox__img");
+  var closeBtn = dlg.querySelector(".apex-lightbox__close");
+  var prevBtn = dlg.querySelector(".apex-lightbox__prev");
+  var nextBtn = dlg.querySelector(".apex-lightbox__next");
+  if (!img || !closeBtn || !prevBtn || !nextBtn) return;
+  var shots = [];
+  var current = 0;
+  function show(i) {
+    var shot = shots[i];
+    current = i;
+    img.src = shot.currentSrc || shot.src;
+    img.alt = shot.alt || "";
+  }
+  function step(delta) {
+    if (shots.length < 2) return;
+    show((current + delta + shots.length) % shots.length);
+  }
+  function open(target) {
+    shots = Array.prototype.slice.call(document.querySelectorAll(".shot-frame img"));
+    var start = shots.indexOf(target);
+    if (start < 0) {
+      shots = [target];
+      start = 0;
+    }
+    show(start);
+    prevBtn.hidden = nextBtn.hidden = shots.length < 2;
+    if (typeof dlg.showModal === "function") dlg.showModal();
+  }
+  function close() {
+    if (dlg.open) dlg.close();
+  }
+  document.addEventListener("click", function (e) {
+    var t = e.target;
+    if (!(t instanceof HTMLImageElement)) return;
+    if (!t.closest(".shot-frame")) return;
+    e.preventDefault();
+    open(t);
+  });
+  closeBtn.addEventListener("click", close);
+  prevBtn.addEventListener("click", function () { step(-1); });
+  nextBtn.addEventListener("click", function () { step(1); });
+  document.addEventListener("keydown", function (e) {
+    if (!dlg.open) return;
+    if (e.key === "ArrowLeft") {
+      e.preventDefault();
+      step(-1);
+    } else if (e.key === "ArrowRight") {
+      e.preventDefault();
+      step(1);
+    }
+  });
+  dlg.addEventListener("click", function (e) {
+    if (e.target === dlg) close();
+  });
+  dlg.addEventListener("cancel", function (e) {
+    e.preventDefault();
+    close();
+  });
+})();
+`;
+/** ponytail: one delegated listener; no-op when no .shot-frame on the page. */
+export const APEX_LIGHTBOX_SCRIPT = `<script>${APEX_LIGHTBOX_SCRIPT_BODY}</script>`;
+// CSP hash-source for the inline script above; apex output is often
+// pre-rendered, so a per-request nonce can't work. Guarded by lightbox.test.ts.
+export const APEX_LIGHTBOX_SCRIPT_CSP_HASH = "sha256-CLZlqZx0zShYKXq1Qg6+VYMTEC6tqiIlNf6JPA1nLck=";

package/dist/headless/contracts/asset.d.ts

@@ -0,0 +1,15 @@
+export type AssetResolveContext = {
+    readonly tenantId?: string;
+    readonly theme?: "light" | "dark";
+    readonly platform?: "web" | "ios" | "android";
+    readonly locale?: string;
+};
+export type AssetResolution = {
+    readonly uri: string;
+    readonly width?: number;
+    readonly height?: number;
+    readonly alt?: string;
+};
+export type AssetResolver = {
+    resolve(qn: string, ctx?: AssetResolveContext): AssetResolution | null;
+};

package/dist/headless/contracts/asset.js

@@ -0,0 +1,17 @@
+// Asset-Resolver — the layer between "qualified asset name" and "URL the
+// renderer can point an <img>/<Image> at". An asset (logo, illustration,
+// icon bundle) is declared by a feature with a qualified name
+// ("admin:asset:hero-logo") and resolved at render-time against the
+// current tenant / theme / platform.
+//
+// Why a resolver indirection:
+//   - Tenant-theming (different logo per tenant) without the feature
+//     knowing what tenant it's rendering for.
+//   - Dark-mode / light-mode variants picked up from the current theme
+//     context.
+//   - Web vs mobile different asset bundles (e.g. PNG vs SVG).
+//
+// The app registers a concrete resolver on startup and hands it to the
+// renderer via context. Feature code calls `useAsset("admin:asset:logo")`
+// (renderer-side hook) → internally `AssetResolver.resolve(qn)`.
+export {};

package/dist/headless/contracts/index.d.ts

@@ -0,0 +1,3 @@
+export type { AssetResolution, AssetResolveContext, AssetResolver, } from "./asset.ts";
+export type { LocaleResolver } from "./locale.ts";
+export type { BadgeProps, ButtonProps, CardProps, DatePickerProps, IconProps, ModalProps, NumberInputProps, PrimitiveCommonProps, PrimitivesContract, SelectOption, SelectProps, TextInputProps, ToastIntent, ToastProps, ToggleProps, } from "./primitives.ts";

package/dist/headless/contracts/index.js

@@ -0,0 +1 @@
+export {};

package/dist/headless/contracts/locale.d.ts

@@ -0,0 +1,7 @@
+export type LocaleResolver = {
+    translate(key: string, params?: Readonly<Record<string, unknown>>): string;
+    locale(): string;
+    timeZone(): string;
+    subscribe(listener: () => void): () => void;
+    setLocale?(locale: string): void;
+};

package/dist/headless/contracts/locale.js

@@ -0,0 +1,11 @@
+// Locale-Resolver — translation lookup + language/region info the
+// renderer needs. Sits in front of i18next (or whatever i18n library
+// the app wires up). ui-core calls it generically so form-controller,
+// view-model, and nav-resolver all produce already-translated strings
+// to hand to the renderer.
+//
+// The framework already has an i18n layer (@cosmicdrift/kumiko-framework/i18n) that
+// features register translations against. This contract is what ui-core
+// consumes — the app's entrypoint instantiates the resolver from a
+// framework i18next instance and passes it to the renderer via context.
+export {};

package/dist/headless/contracts/primitives.d.ts

@@ -0,0 +1,93 @@
+export type PrimitiveCommonProps = {
+    readonly id?: string;
+    readonly name?: string;
+    readonly disabled?: boolean;
+    readonly readOnly?: boolean;
+    readonly required?: boolean;
+    readonly label?: string;
+    readonly placeholder?: string;
+    readonly helperText?: string;
+    readonly errors?: readonly string[];
+};
+export type TextInputProps = PrimitiveCommonProps & {
+    readonly value: string;
+    readonly onChange: (next: string) => void;
+    readonly onBlur?: () => void;
+    readonly type?: "text" | "email" | "url" | "tel" | "password";
+    readonly maxLength?: number;
+    readonly autoComplete?: string;
+};
+export type NumberInputProps = PrimitiveCommonProps & {
+    readonly value: number | null;
+    readonly onChange: (next: number | null) => void;
+    readonly onBlur?: () => void;
+    readonly min?: number;
+    readonly max?: number;
+    readonly step?: number;
+};
+export type SelectOption<TValue extends string = string> = {
+    readonly value: TValue;
+    readonly label: string;
+};
+export type SelectProps<TValue extends string = string> = PrimitiveCommonProps & {
+    readonly value: TValue | null;
+    readonly onChange: (next: TValue | null) => void;
+    readonly options: readonly SelectOption<TValue>[];
+};
+export type ToggleProps = PrimitiveCommonProps & {
+    readonly value: boolean;
+    readonly onChange: (next: boolean) => void;
+};
+export type DatePickerProps = PrimitiveCommonProps & {
+    readonly value: string | null;
+    readonly onChange: (next: string | null) => void;
+    readonly minDate?: string;
+    readonly maxDate?: string;
+};
+export type ButtonProps = {
+    readonly onPress: () => void;
+    readonly label: string;
+    readonly variant?: "primary" | "secondary" | "destructive" | "ghost";
+    readonly disabled?: boolean;
+    readonly loading?: boolean;
+    readonly leftIcon?: string;
+    readonly rightIcon?: string;
+};
+export type ModalProps = {
+    readonly open: boolean;
+    readonly onClose: () => void;
+    readonly title?: string;
+    readonly description?: string;
+};
+export type ToastIntent = "info" | "success" | "warning" | "error";
+export type ToastProps = {
+    readonly intent: ToastIntent;
+    readonly title: string;
+    readonly description?: string;
+    readonly onDismiss?: () => void;
+};
+export type BadgeProps = {
+    readonly label: string;
+    readonly intent?: ToastIntent;
+};
+export type CardProps = {
+    readonly title?: string;
+    readonly description?: string;
+};
+export type IconProps = {
+    readonly name: string;
+    readonly size?: number;
+};
+export type PrimitivesContract<TPrimitive = unknown> = {
+    readonly TextInput: TPrimitive;
+    readonly NumberInput: TPrimitive;
+    readonly Select: TPrimitive;
+    readonly Toggle: TPrimitive;
+    readonly DatePicker: TPrimitive;
+    readonly Button: TPrimitive;
+    readonly Modal: TPrimitive;
+    readonly Toast: TPrimitive;
+    readonly Badge: TPrimitive;
+    readonly Card: TPrimitive;
+    readonly Icon: TPrimitive;
+};

package/dist/headless/contracts/primitives.js

@@ -0,0 +1,21 @@
+// Primitives-Contract — the minimal set of UI building blocks every
+// renderer must provide. A "primitive" is a unit the standard-renderers
+// (entityList, entityEdit, etc.) call into without knowing which library
+// implements it. On web that's shadcn; on mobile it's react-native-paper;
+// both packages (primitives-shadcn, primitives-paper) implement this
+// contract and the app wires one of them into the renderer via context.
+//
+// Why a contract here (in ui-core) instead of in each renderer:
+// ui-core's view-model builder and form-controller produce metadata
+// (field-type, validation-state, label, placeholder) that the renderer
+// translates into primitive invocations. Having the contract shape in
+// ui-core means the metadata can carry references to primitives by name
+// ("text-input", "select") and the translation is a pure map-lookup on
+// the renderer side, not a switch statement that re-derives UI intent
+// from entity-schema.
+//
+// Runtime-free: every primitive is expressed as its input contract only
+// (what props it takes). Concrete components live in each primitives-*
+// package and depend on React / React Native / etc.; ui-core never
+// imports them.
+export {};

package/dist/headless/dispatcher/index.d.ts

@@ -0,0 +1,2 @@
+export type { BatchResult, Command, Dispatcher, DispatcherError, DispatcherStatus, FieldIssue, PendingFile, PendingWrite, QueryOpts, QueryResult, StreamOpts, WriteOpts, WriteResult, } from "./types.ts";
+export { StreamFrame, type StreamFrameEvent } from "./types.ts";

package/dist/headless/dispatcher/index.js

@@ -0,0 +1 @@
+export { StreamFrame } from "./types.js";

package/dist/headless/dispatcher/types.d.ts

@@ -0,0 +1,86 @@
+import type { FieldIssue } from "@cosmicdrift/kumiko-framework/errors";
+import type { Store } from "../store/index.ts";
+export type { FieldIssue };
+export type DispatcherError = {
+    readonly code: string;
+    readonly httpStatus: number;
+    readonly i18nKey: string;
+    readonly i18nParams?: Readonly<Record<string, unknown>>;
+    readonly message: string;
+    readonly details?: {
+        readonly fields?: readonly FieldIssue[];
+    } & Record<string, unknown>;
+    readonly docsUrl?: string;
+    readonly requestId?: string;
+};
+export type WriteResult<TData = unknown> = {
+    readonly isSuccess: true;
+    readonly data: TData;
+} | {
+    readonly isSuccess: false;
+    readonly error: DispatcherError;
+};
+export type QueryResult<TData = unknown> = {
+    readonly isSuccess: true;
+    readonly data: TData;
+} | {
+    readonly isSuccess: false;
+    readonly error: DispatcherError;
+};
+export type BatchResult = {
+    readonly isSuccess: true;
+    readonly results: readonly WriteResult[];
+} | {
+    readonly isSuccess: false;
+    readonly error: DispatcherError;
+    readonly failedIndex: number;
+    readonly results: readonly WriteResult[];
+};
+export type Command = {
+    readonly type: string;
+    readonly payload: unknown;
+};
+export type DispatcherStatus = "online" | "offline" | "syncing";
+export type PendingWrite = {
+    readonly id: string;
+    readonly type: string;
+    readonly payload: unknown;
+    readonly queuedAt: string;
+    readonly attempts: number;
+    readonly lastError?: DispatcherError;
+};
+export type PendingFile = {
+    readonly id: string;
+    readonly fileName: string;
+    readonly sizeBytes: number;
+    readonly queuedAt: string;
+    readonly attempts: number;
+    readonly progress?: number;
+    readonly lastError?: DispatcherError;
+};
+export type WriteOpts = {
+    readonly requestId?: string;
+    readonly signal?: AbortSignal;
+};
+export type QueryOpts = {
+    readonly signal?: AbortSignal;
+};
+export type StreamOpts = {
+    readonly signal?: AbortSignal;
+};
+export declare const StreamFrame: {
+    readonly chunk: "chunk";
+    readonly ping: "ping";
+    readonly done: "done";
+    readonly error: "error";
+};
+export type StreamFrameEvent = (typeof StreamFrame)[keyof typeof StreamFrame];
+export type Dispatcher = {
+    write<TData = unknown>(type: string, payload: unknown, opts?: WriteOpts): Promise<WriteResult<TData>>;
+    query<TData = unknown>(type: string, payload: unknown, opts?: QueryOpts): Promise<QueryResult<TData>>;
+    batch(commands: readonly Command[], opts?: WriteOpts): Promise<BatchResult>;
+    stream<TChunk = unknown>(type: string, payload: unknown, opts?: StreamOpts): AsyncGenerator<TChunk, void, undefined>;
+    readonly statusStore: Store<DispatcherStatus>;
+    pendingWrites(): readonly PendingWrite[];
+    pendingFiles(): readonly PendingFile[];
+};

package/dist/headless/dispatcher/types.js

@@ -0,0 +1,34 @@
+// Dispatcher Contract — the interface every client-side Dispatcher implements.
+// Two implementations ship with Kumiko:
+//
+//   - dispatcher-live: HTTP-only, always online. Writes go straight to
+//     /api/write or /api/batch; a failed network call is a failed write.
+//     Used on the web by default and on mobile when the app is "cockpit"-
+//     style (admin dashboards, back-office UIs).
+//
+//   - dispatcher-savable: Local-first with an outbound queue. Writes land
+//     in a local store, the queue syncs when the network is back. Used on
+//     mobile and for PWA-style web apps.
+//
+// The UI code never reaches for either implementation directly — it takes
+// a `Dispatcher` through a provider/context and calls `write` / `query` /
+// `batch`. A feature-module can therefore be rendered identically on a
+// live-online admin screen and on a mobile app that edits offline; the
+// dispatcher choice is an app-level concern, not a feature-level one.
+//
+// Result shape: `{ isSuccess: true, data } | { isSuccess: false, error }`.
+// Pattern matches the server's WriteResult but does not import it — this
+// package stays free of @cosmicdrift/kumiko-framework so it runs in any JS runtime
+// (browser, Expo/React Native, Web Worker). The HTTP dispatcher adapts
+// the server response to this shape; the savable dispatcher synthesizes
+// it from its own state machine. The shape is the boundary, not the
+// internal detail.
+// SSE frame event names for POST /api/stream — shared across the server route,
+// the live-dispatcher wire parser, and their tests so a typo on one side
+// fails the type-checker instead of the integration test.
+export const StreamFrame = {
+    chunk: "chunk",
+    ping: "ping",
+    done: "done",
+    error: "error",
+};

package/dist/headless/form/form-controller.d.ts

@@ -0,0 +1,2 @@
+import type { FormController, FormControllerOptions, FormValues } from "./types.ts";
+export declare function createFormController<TValues extends FormValues, TCtx = unknown>(options: FormControllerOptions<TValues, TCtx>): FormController<TValues>;