@xemahq/ui-kernel 0.7.0 → 0.8.0

package/src/offline/storage.ts

@@ -0,0 +1,107 @@
+import type { OutboxEntry, OutboxStorage } from './types';
+
+/** In-memory outbox storage — the SSR / test fallback (no persistence). */
+export class InMemoryOutboxStorage implements OutboxStorage {
+  private readonly map = new Map<string, OutboxEntry>();
+
+  async getAll(): Promise<OutboxEntry[]> {
+    return [...this.map.values()].sort((a, b) => a.createdAt - b.createdAt);
+  }
+
+  async put(entry: OutboxEntry): Promise<void> {
+    this.map.set(entry.id, { ...entry });
+  }
+
+  async delete(id: string): Promise<void> {
+    this.map.delete(id);
+  }
+
+  async clear(): Promise<void> {
+    this.map.clear();
+  }
+}
+
+const DB_VERSION = 1;
+
+/** IndexedDB-backed outbox storage — durable across reloads and app restarts,
+ *  so a mutation captured offline survives the tab being closed. */
+export class IndexedDbOutboxStorage implements OutboxStorage {
+  private dbPromise: Promise<IDBDatabase> | null = null;
+
+  constructor(
+    private readonly dbName = 'xema-offline-outbox',
+    private readonly storeName = 'entries',
+  ) {}
+
+  private open(): Promise<IDBDatabase> {
+    if (this.dbPromise) {
+      return this.dbPromise;
+    }
+    this.dbPromise = new Promise<IDBDatabase>((resolve, reject) => {
+      const req = indexedDB.open(this.dbName, DB_VERSION);
+      req.onupgradeneeded = () => {
+        const db = req.result;
+        if (!db.objectStoreNames.contains(this.storeName)) {
+          db.createObjectStore(this.storeName, { keyPath: 'id' });
+        }
+      };
+      req.onsuccess = () => resolve(req.result);
+      req.onerror = () => reject(req.error ?? new Error('indexedDB open failed'));
+    });
+    return this.dbPromise;
+  }
+
+  private async tx<T>(
+    mode: IDBTransactionMode,
+    run: (store: IDBObjectStore) => IDBRequest<T> | void,
+  ): Promise<T | undefined> {
+    const db = await this.open();
+    return new Promise<T | undefined>((resolve, reject) => {
+      const transaction = db.transaction(this.storeName, mode);
+      const store = transaction.objectStore(this.storeName);
+      let request: IDBRequest<T> | void;
+      try {
+        request = run(store);
+      } catch (err) {
+        reject(err);
+        return;
+      }
+      transaction.onabort = () =>
+        reject(transaction.error ?? new Error('indexedDB tx aborted'));
+      transaction.oncomplete = () =>
+        resolve(request ? (request as IDBRequest<T>).result : undefined);
+      transaction.onerror = () =>
+        reject(transaction.error ?? new Error('indexedDB tx error'));
+    });
+  }
+
+  async getAll(): Promise<OutboxEntry[]> {
+    const all = (await this.tx<OutboxEntry[]>('readonly', (s) => s.getAll())) ?? [];
+    return all.sort((a, b) => a.createdAt - b.createdAt);
+  }
+
+  async put(entry: OutboxEntry): Promise<void> {
+    await this.tx('readwrite', (s) => s.put(entry));
+  }
+
+  async delete(id: string): Promise<void> {
+    await this.tx('readwrite', (s) => s.delete(id));
+  }
+
+  async clear(): Promise<void> {
+    await this.tx('readwrite', (s) => s.clear());
+  }
+}
+
+/** Pick the best available storage: IndexedDB in a browser, else in-memory
+ *  (SSR / tests / private-mode fallbacks). */
+export function createDefaultOutboxStorage(): OutboxStorage {
+  if (typeof indexedDB !== 'undefined') {
+    try {
+      return new IndexedDbOutboxStorage();
+    } catch {
+      // Some privacy modes throw on open — fall back to in-memory.
+    }
+  }
+  return new InMemoryOutboxStorage();
+}

package/src/offline/types.ts

@@ -0,0 +1,77 @@
+// ═══════════════════════════════════════════════════════════════════════════
+// @xemahq/ui-kernel/offline — types
+//
+// A generic offline field-capture kit: an IndexedDB-backed outbox that queues
+// mutations while disconnected and drains them (with retry + idempotency) on
+// reconnect. Provider-agnostic — any mutation (an app-forge record submit, a
+// status change, …) is enqueued by a stable `kind` whose executor is registered
+// once. The motivating case is field/trade-fair capture with no signal.
+// ═══════════════════════════════════════════════════════════════════════════
+
+/** Lifecycle of a queued mutation. */
+export enum OutboxEntryStatus {
+  /** Waiting to be sent (offline, or not yet attempted). */
+  Pending = 'pending',
+  /** Currently being sent. */
+  Inflight = 'inflight',
+  /** Failed transiently; will be retried (attempts < maxAttempts). */
+  Retrying = 'retrying',
+  /** Exhausted retries — needs manual retry or discard (dead-letter). */
+  Failed = 'failed',
+}
+
+/** One queued mutation. `payload` is opaque to the outbox; the executor for
+ *  `kind` interprets it. */
+export interface OutboxEntry<TPayload = unknown> {
+  /** Stable entry id (also the default idempotency key). */
+  id: string;
+  /** Registered executor key (e.g. "app-forge:create-record"). */
+  kind: string;
+  payload: TPayload;
+  /** Sent to the backend so a redelivered mutation is not double-applied. */
+  idempotencyKey: string;
+  status: OutboxEntryStatus;
+  attempts: number;
+  createdAt: number;
+  updatedAt: number;
+  /** Last error message (for the dead-letter UI). */
+  lastError?: string;
+  /** Optional human label for the pending-items UI. */
+  label?: string;
+}
+
+/** Persistence backend for the outbox. IndexedDB in the browser; in-memory for
+ *  SSR / tests. */
+export interface OutboxStorage {
+  getAll(): Promise<OutboxEntry[]>;
+  put(entry: OutboxEntry): Promise<void>;
+  delete(id: string): Promise<void>;
+  clear(): Promise<void>;
+}
+
+/** Context passed to an executor when a queued mutation is sent. */
+export interface OutboxExecuteContext {
+  /** Pass to the backend (e.g. as an `Idempotency-Key` header). */
+  idempotencyKey: string;
+  /** How many times this entry has now been attempted (1-based). */
+  attempt: number;
+  entryId: string;
+}
+
+/** Sends one queued mutation. Throwing schedules a retry (see
+ *  {@link OutboxOptions.isRetriable}). */
+export type OutboxExecutor<TPayload = unknown> = (
+  payload: TPayload,
+  ctx: OutboxExecuteContext,
+) => Promise<void>;
+
+/** Snapshot of outbox state for UI (offline badge, pending count, dead-letter). */
+export interface OutboxSnapshot {
+  entries: OutboxEntry[];
+  pendingCount: number;
+  failedCount: number;
+  /** True while a drain is in progress. */
+  draining: boolean;
+  /** Current connectivity (from the outbox's online controller). */
+  online: boolean;
+}

package/src/ui/branding/app-branding-provider.tsx

@@ -20,7 +20,7 @@
 // ═══════════════════════════════════════════════════════════════════════════
 import * as React from 'react';
 
-import type { BrandingConfig } from '@xemahq/kernel-contracts/app-runtime';
+import type { BrandingConfig } from '@xemahq/kernel-contracts/app-platform';
 
 import { cn } from '../cn';
 

package/src/ui/capture/field-spec-to-zod.test.ts

@@ -57,3 +57,25 @@ describe('fieldSpecToZod', () => {
     expect(fieldSpecToZod(fields).safeParse({ title: 'Hi', status: 'open', tags: [{ name: '' }] }).success).toBe(false);
   });
 });
+
+describe('media fields (image/file/audio)', () => {
+  const media: CaptureFieldSpec[] = [
+    { key: 'photo', label: 'Photo', type: CaptureFieldType.Image, required: true },
+    { key: 'attachment', label: 'Attachment', type: CaptureFieldType.File },
+    { key: 'memo', label: 'Voice memo', type: CaptureFieldType.Audio },
+  ];
+  const dataUrl = 'data:image/png;base64,AAAA';
+
+  it('accepts a captured data-URL for a required media field', () => {
+    expect(fieldSpecToZod(media).safeParse({ photo: dataUrl }).success).toBe(true);
+  });
+
+  it('rejects an empty required media field', () => {
+    expect(fieldSpecToZod(media).safeParse({ photo: '' }).success).toBe(false);
+    expect(fieldSpecToZod(media).safeParse({}).success).toBe(false);
+  });
+
+  it('allows omitted optional media fields', () => {
+    expect(fieldSpecToZod(media).safeParse({ photo: dataUrl }).success).toBe(true);
+  });
+})

package/src/ui/capture/field-spec-to-zod.ts

@@ -54,7 +54,18 @@ function fieldSchema(field: CaptureFieldSpec): z.ZodTypeAny {
     base = arr;
   } else {
     base = scalarSchema(field);
-    if (field.required && (field.type === CaptureFieldType.String || field.type === CaptureFieldType.Text || field.type === CaptureFieldType.User || field.type === CaptureFieldType.Reference || field.type === CaptureFieldType.Datetime)) {
+    if (
+      field.required &&
+      (field.type === CaptureFieldType.String ||
+        field.type === CaptureFieldType.Text ||
+        field.type === CaptureFieldType.User ||
+        field.type === CaptureFieldType.Reference ||
+        field.type === CaptureFieldType.Datetime ||
+        // Media fields carry a data-URL string; required = a capture was made.
+        field.type === CaptureFieldType.Image ||
+        field.type === CaptureFieldType.File ||
+        field.type === CaptureFieldType.Audio)
+    ) {
       base = (base as z.ZodString).min(1, { message: `${field.label} is required` });
     }
   }

package/src/ui/capture/field-spec.ts

@@ -22,9 +22,12 @@
  * App Platform pass straight through. `object`/`list` are the structural
  * composites this kit adds for nested + repeatable capture.
  *
- * The string VALUES are the contract — keep them identical to app-forge's enum
- * (parity is checked there by `check-app-enum-parity.mjs`). Adding a value here
- * that app-forge lacks is fine (superset); changing an existing value is not.
+ * The string VALUES are the contract — keep the first ten identical to
+ * `AppFieldType` in `@xemahq/kernel-contracts/app-definition` (the single
+ * source of truth for App Platform field types). Adding a value here that
+ * `AppFieldType` lacks is fine (superset); changing an existing shared value is
+ * not. This kit can't import the enum (it adds members), so the shared values
+ * are mirrored deliberately.
  */
 export enum CaptureFieldType {
   String = 'string',
@@ -39,6 +42,14 @@ export enum CaptureFieldType {
   User = 'user',
   Object = 'object',
   List = 'list',
+  // ── Media capture (field-capture kit) ──
+  // Value is a data-URL string (base64), so it stays JSON-serializable and
+  // flows unchanged through the record model + the offline outbox. `Image`
+  // opens the device camera on mobile (`capture`), `File` attaches any file,
+  // `Audio` records a voice memo via MediaRecorder.
+  Image = 'image',
+  File = 'file',
+  Audio = 'audio',
 }
 
 /**
@@ -69,6 +80,16 @@ export interface CaptureFieldSpec {
   /** `number`/`decimal`: numeric bounds. `list`: min/max item count. */
   readonly min?: number;
   readonly max?: number;
+  /**
+   * `image`/`file`/`audio`: the `accept` filter for the file picker (e.g.
+   * `image/*`, `application/pdf`). Defaults per type when omitted.
+   */
+  readonly accept?: string;
+  /**
+   * `image`/`file`: the HTML `capture` hint — `environment` opens the rear
+   * camera, `user` the front camera. Omitted = a normal file picker.
+   */
+  readonly capture?: 'user' | 'environment';
   /**
    * Optional section grouping key for FLAT `CaptureFieldSpec[]` schemas. When a
    * schema is expressed as {@link CaptureSection}[] this is ignored (grouping is

package/src/ui/capture/schema-field-input.tsx

@@ -8,7 +8,7 @@
 // seam app-forge uses to plug its record-backed `ReferenceSelect`).
 // ═══════════════════════════════════════════════════════════════════════════
 import { Plus, Trash2 } from 'lucide-react';
-import { type ReactNode } from 'react';
+import { useCallback, useRef, useState, type ReactNode } from 'react';
 
 import { cn } from '../cn';
 import { Button } from '../primitives/button';
@@ -98,12 +98,140 @@ export function SchemaFieldInput(props: SchemaFieldInputProps) {
       return <ObjectInput {...props} />;
     case CaptureFieldType.List:
       return <ListInput {...props} />;
+    case CaptureFieldType.Image:
+    case CaptureFieldType.File:
+      return <MediaFieldInput {...props} />;
+    case CaptureFieldType.Audio:
+      return <AudioFieldInput {...props} />;
     // string (and any unknown) — plain single-line input.
     default:
       return <Input id={inputId} value={asString(value)} onChange={(e) => onChange(e.target.value)} disabled={disabled} placeholder={field.placeholder} />;
   }
 }
 
+const FILE_INPUT_CLASS =
+  'block w-full text-body-2 text-foreground file:mr-3 file:rounded-md file:border-0 file:bg-secondary file:px-3 file:py-1.5 file:text-body-2 file:text-secondary-foreground hover:file:bg-secondary/80 disabled:cursor-not-allowed disabled:opacity-50';
+
+/** Read a File/Blob as a base64 data-URL (JSON-serializable, offline-safe). */
+function readAsDataUrl(file: Blob, onDone: (dataUrl: string) => void): void {
+  const reader = new FileReader();
+  reader.onload = () =>
+    onDone(typeof reader.result === 'string' ? reader.result : '');
+  reader.readAsDataURL(file);
+}
+
+/**
+ * `image`/`file` capture. On mobile, `field.capture` makes an image field open
+ * the camera directly. The value is a data-URL so it stays JSON-serializable and
+ * flows unchanged through the record model + offline outbox.
+ */
+function MediaFieldInput({ field, value, onChange, disabled, path }: SchemaFieldInputProps) {
+  const inputId = `field-${path}`;
+  const current = asString(value);
+  const isImage = field.type === CaptureFieldType.Image;
+  const accept = field.accept ?? (isImage ? 'image/*' : undefined);
+  return (
+    <div className="mt-1 space-y-2">
+      <input
+        id={inputId}
+        type="file"
+        className={FILE_INPUT_CLASS}
+        disabled={disabled}
+        {...(accept ? { accept } : {})}
+        {...(field.capture ? { capture: field.capture } : {})}
+        onChange={(e) => {
+          const file = e.target.files?.[0];
+          if (file) {
+            readAsDataUrl(file, onChange);
+          }
+        }}
+      />
+      {current ? (
+        <div className="flex items-center gap-2">
+          {isImage && current.startsWith('data:image') ? (
+            <img src={current} alt={field.label} className="max-h-32 rounded-md border border-input" />
+          ) : (
+            <span className="truncate text-body-2 text-muted-foreground">Attached</span>
+          )}
+          <Button type="button" variant="ghost" size="sm" onClick={() => onChange('')} disabled={disabled}>
+            Clear
+          </Button>
+        </div>
+      ) : null}
+    </div>
+  );
+}
+
+/**
+ * `audio` capture — records a voice memo via MediaRecorder and stores it as a
+ * data-URL. Browser APIs are touched only inside the record handler (SSR-safe).
+ */
+function AudioFieldInput({ value, onChange, disabled, path }: SchemaFieldInputProps) {
+  const inputId = `field-${path}`;
+  const current = asString(value);
+  const [recording, setRecording] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+  const recorderRef = useRef<MediaRecorder | null>(null);
+  const chunksRef = useRef<Blob[]>([]);
+
+  const start = useCallback(async () => {
+    setError(null);
+    try {
+      const stream = await navigator.mediaDevices.getUserMedia({ audio: true });
+      const recorder = new MediaRecorder(stream);
+      chunksRef.current = [];
+      recorder.ondataavailable = (e) => {
+        if (e.data.size > 0) {
+          chunksRef.current.push(e.data);
+        }
+      };
+      recorder.onstop = () => {
+        for (const track of stream.getTracks()) {
+          track.stop();
+        }
+        readAsDataUrl(
+          new Blob(chunksRef.current, { type: recorder.mimeType || 'audio/webm' }),
+          onChange,
+        );
+      };
+      recorderRef.current = recorder;
+      recorder.start();
+      setRecording(true);
+    } catch {
+      setError('Microphone unavailable or permission denied.');
+    }
+  }, [onChange]);
+
+  const stop = useCallback(() => {
+    recorderRef.current?.stop();
+    recorderRef.current = null;
+    setRecording(false);
+  }, []);
+
+  return (
+    <div className="mt-1 space-y-2">
+      <div className="flex items-center gap-2">
+        {recording ? (
+          <Button type="button" variant="secondary" size="sm" onClick={stop} disabled={disabled}>
+            Stop
+          </Button>
+        ) : (
+          <Button type="button" variant="secondary" size="sm" onClick={() => void start()} disabled={disabled}>
+            {current ? 'Re-record' : 'Record'}
+          </Button>
+        )}
+        {current ? (
+          <Button type="button" variant="ghost" size="sm" onClick={() => onChange('')} disabled={disabled}>
+            Clear
+          </Button>
+        ) : null}
+      </div>
+      {error ? <p className="text-body-2 text-destructive">{error}</p> : null}
+      {current && !recording ? <audio id={inputId} controls src={current} className="w-full" /> : null}
+    </div>
+  );
+}
+
 /** Renders one label + input + error block for a nested field. */
 function NestedField(props: SchemaFieldInputProps) {
   const { field, path, errors } = props;

package/src/lib/biome-host/define-web-biome.test.js

@@ -1,93 +0,0 @@
-// Test suite for defineWebBiome's define-time scope/access validation and the
-// chrome default. Runs on Node's native test runner against the COMPILED dist
-// (CommonJS), so the package needs no jest/vitest/ts-jest toolchain — the
-// `test` script builds first, then runs this file with `node --test`.
-//
-// Covered:
-//   1. A `public` page with access `'member'` (or omitted) throws at define time.
-//   2. A `public` + access `'public'` page is accepted; its route carries no
-//      nav item and mounts with access `'public'`.
-//   3. A non-public page declaring access `'public'` throws at define time.
-//   4. `chrome` defaults to `'host'` when a page omits it; `'none'` passes through.
-
-'use strict';
-
-const test = require('node:test');
-const assert = require('node:assert/strict');
-
-const { defineWebBiome } = require('../../../dist/lib/biome-host/define-web-biome.js');
-
-const load = () => Promise.resolve({ default: () => null });
-const bridge = /** @type {any} */ ({});
-
-test('rejects a public page whose access is not public (member default)', () => {
-  assert.throws(
-    () =>
-      defineWebBiome({
-        id: 'test-biome',
-        displayName: 'Test',
-        pages: [{ slug: 'ext/:id', label: 'Ext', scope: 'public', load }],
-      }),
-    /a 'public' scope page MUST declare access: 'public'/,
-  );
-});
-
-test('rejects a public page with an explicit non-public access tier', () => {
-  assert.throws(
-    () =>
-      defineWebBiome({
-        id: 'test-biome',
-        displayName: 'Test',
-        pages: [
-          { slug: 'ext/:id', label: 'Ext', scope: 'public', access: 'org-admin', load },
-        ],
-      }),
-    /a 'public' scope page MUST declare access: 'public'/,
-  );
-});
-
-test('rejects a non-public page that declares access public', () => {
-  assert.throws(
-    () =>
-      defineWebBiome({
-        id: 'test-biome',
-        displayName: 'Test',
-        pages: [{ slug: 'system/x', label: 'X', access: 'public', load }],
-      }),
-    /access: 'public' is only valid on a 'public' scope page/,
-  );
-});
-
-test('accepts a public + access:public page and emits no nav item', () => {
-  const factory = defineWebBiome({
-    id: 'test-biome',
-    displayName: 'Test',
-    pages: [
-      { slug: 'ext/:id', label: 'Ext', scope: 'public', access: 'public', load },
-    ],
-  });
-  const biome = factory(bridge);
-  assert.equal(biome.routes.length, 1);
-  const route = biome.routes[0];
-  assert.equal(route.path, 'ext/:id');
-  assert.equal(route.access, 'public');
-  assert.equal(route.projectScoped, false);
-  // Public routes never enter the authenticated app rail.
-  assert.equal(biome.navItems.length, 0);
-});
-
-test('chrome defaults to host and none passes through', () => {
-  const factory = defineWebBiome({
-    id: 'test-biome',
-    displayName: 'Test',
-    pages: [
-      { slug: 'system/a', label: 'A', load },
-      { slug: 'system/b', label: 'B', chrome: 'none', load },
-    ],
-  });
-  const biome = factory(bridge);
-  const a = biome.routes.find((r) => r.path === 'system/a');
-  const b = biome.routes.find((r) => r.path === 'system/b');
-  assert.equal(a.chrome, 'host');
-  assert.equal(b.chrome, 'none');
-});