@declarion/react 0.1.65 → 0.1.67

package/dist-lib/lib/rich-text.d.ts

@@ -0,0 +1,14 @@
+import type { HydratedFile } from "../types/files";
+export interface RichTextValue {
+    markdown: string;
+    files: Record<string, HydratedFile>;
+}
+export declare function richTextMarkdown(value: unknown): string;
+export declare function richTextFiles(value: unknown): Record<string, HydratedFile>;
+export declare function createRichTextValue(markdownValue: unknown, inlineFilesValue: unknown): RichTextValue;
+export declare function withRichTextFile(value: unknown, file: HydratedFile): RichTextValue;
+export declare function withoutRichTextFiles(value: unknown, removedIds: Iterable<string>): RichTextValue;
+export declare function inlineFilesById(value: unknown): Record<string, HydratedFile>;
+export declare function extractDeclarionFileIds(markdown: string): string[];
+export declare function extractDeclarionFileId(url: string | undefined): string | null;
+export declare function richTextTokenForFile(file: Pick<HydratedFile, "id" | "content_type" | "filename">): string;

package/dist-lib/lib/versionTracker.d.ts

@@ -0,0 +1,66 @@
+/**
+ * versionTracker — central staleness-detection state for the SPA.
+ *
+ * Every API response carries `X-Declarion-Version: <combined-fingerprint>`
+ * (set by the server's version_header middleware). The FIRST arrival
+ * in a bundle's lifetime is captured as the baseline; any later
+ * response with a different value triggers drift detection — the SPA
+ * either silently invalidates the schema query (if only schema differs)
+ * or prompts the user to reload (if assets/binary changed).
+ *
+ * **State is in-memory only — no sessionStorage / localStorage.** Each
+ * bundle load captures its own baseline from its first response. The
+ * bundle IS its own version contract; the live server's first answer
+ * defines what version the bundle should consider itself. Persisting
+ * across reloads is actively harmful: a stale baseline from a previous
+ * bundle could override the live answer, producing a "click Reload →
+ * page reloads → toast pops again" infinite loop. This is the same
+ * lesson behind why `index.html` is `Cache-Control: no-cache` — the
+ * bootstrap manifest must always be live, never replayed.
+ *
+ * Defense in depth runs three sources into the same comparator:
+ *   1. observe() — header read on every API response (apiFetch hook).
+ *   2. fetchProbe() — explicit GET /api/version (focus / online / 60s).
+ *   3. (optional) SSE `version-changed` event from useSSE.
+ *
+ * Cross-tab coordination via BroadcastChannel('declarion-version') —
+ * runtime IPC only, not persistence. When one tab detects drift it
+ * fans the decision out so all tabs reload together (avoids the
+ * half-old / half-new tab anti-pattern). Each tab still bootstraps
+ * its own baseline independently.
+ */
+export interface VersionDelta {
+    /** Reason the delta was emitted. Lets subscribers decide UX. */
+    kind: "schema-only" | "asset-or-binary" | "unknown";
+    /** Latest combined fingerprint observed. Drives the next baseline. */
+    observed: string;
+    /** Per-component breakdown when /api/version was reached. */
+    components?: VersionComponents;
+}
+export interface VersionComponents {
+    schema: string;
+    asset: string;
+    binary: string;
+}
+export type VersionDeltaListener = (delta: VersionDelta) => void;
+/**
+ * Observe an API response. Captures the first-seen fingerprint and
+ * compares subsequent ones. Idempotent — safe to call from every
+ * apiFetch round-trip; backward-compatible — no-op when the header
+ * is absent (older server).
+ */
+export declare function observe(headers: Headers | undefined | null): void;
+/**
+ * Hit /api/version with If-None-Match (cheap when nothing changed —
+ * 304 with no body). On any change, emit a typed delta.
+ */
+export declare function fetchProbe(): Promise<void>;
+/**
+ * Subscribe to drift events. Called once from useVersionWatcher; the
+ * subscriber renders the UpdatePrompt (toast or silent invalidation).
+ */
+export declare function subscribe(cb: VersionDeltaListener): () => void;
+/**
+ * Test-only: reset internal state. Not exposed via package exports.
+ */
+export declare function __resetForTests(): void;

package/dist-lib/types/api.d.ts

@@ -1,4 +1,5 @@
 import type { AccentDef, LocalizedString } from "./schema";
+import type { HydratedFile } from "./files";
 export interface ListMeta {
     total: number;
     page: number;
@@ -47,9 +48,26 @@ export interface AuthUser {
     roles: string[];
     permissions?: string[];
     tenant?: Tenant;
+    /** Populated only when the request is acting under an impersonation session. */
+    impersonation?: ImpersonationInfo;
     created_at: string;
     updated_at: string;
 }
+/**
+ * ImpersonationInfo is the read-side projection of the active session
+ * surfaced by auth.me. Drives the banner, topbar chip, viewport frame,
+ * and the "Exit impersonation" menu item.
+ */
+export interface ImpersonationInfo {
+    session_id: string;
+    real_user_id: string;
+    real_user_email?: string;
+    target_user_id: string;
+    target_user_email?: string;
+    reason: string;
+    started_at: string;
+    expires_at: string;
+}
 export interface LoginResponse {
     expires_at: string;
     user: AuthUser;
@@ -87,6 +105,7 @@ export interface PublicBranding {
     app_logo?: string;
     app_initial?: string;
     accent_color?: string;
+    ai_name?: string;
     wordmark?: string;
     version_label?: string;
     auth_tagline?: LocalizedString;
@@ -199,6 +218,7 @@ export type Units = Record<string, string>;
 /** A row enriched with $-prefixed sub-resources (as returned by Get or write responses). */
 export interface EnrichedRow extends Record<string, unknown> {
     $refs?: Refs;
+    $files?: Record<string, HydratedFile | HydratedFile[] | null>;
     $statuses?: V2StatusInstance[];
     $properties?: V2PropertyInstance[];
     $params?: V2ParamInstance[];

package/dist-lib/types/files.d.ts

@@ -0,0 +1,76 @@
+export type FileFieldMode = "single" | "array" | "named_map" | "rich_text_inline";
+export interface FileFieldDisplay {
+    widget: string;
+    placeholder?: string;
+    crop_on_upload?: boolean;
+    aspect_ratio?: string;
+    focal_point?: boolean;
+    is_listable?: boolean;
+    listable_thumbnail?: string;
+    reorderable?: boolean;
+    bulk_upload?: boolean;
+    bulk_download?: boolean;
+    lazy_load?: boolean;
+}
+export interface FileNamedSlotDef {
+    accepts?: string[];
+    max_size_bytes?: number;
+    svg_sanitize?: boolean;
+    pdf_strip_js?: boolean;
+    exif_strip?: boolean;
+    aspect_ratio?: string;
+    storage_backend?: string;
+}
+export interface FileFieldDef {
+    name: string;
+    mode: FileFieldMode;
+    accepts?: string[];
+    max_size_bytes?: number;
+    max_count?: number;
+    max_total_size_bytes?: number;
+    required?: boolean;
+    slots?: Record<string, FileNamedSlotDef>;
+    display?: FileFieldDisplay;
+}
+export interface HydratedFile {
+    id: string;
+    filename: string;
+    content_type: string;
+    size_bytes: number;
+    sha256?: string;
+    width?: number;
+    height?: number;
+    page_count?: number;
+    uploaded_at?: string;
+    uploaded_by?: string;
+    url?: string;
+    presigned_url?: string;
+    derivations?: Record<string, string>;
+    metadata?: Record<string, unknown>;
+    position?: number;
+    slot?: string;
+    version?: {
+        number?: number;
+        is_current?: boolean;
+        supersedes_file_id?: string;
+    };
+}
+export type NamedFileFieldValue = Record<string, HydratedFile | null>;
+export type FileFieldValue = HydratedFile | HydratedFile[] | NamedFileFieldValue | null;
+export interface UploadProgress {
+    loaded: number;
+    total: number;
+    pct: number;
+}
+export interface UploadedFile {
+    id: string;
+    filename: string;
+    content_type: string;
+    size_bytes: number;
+    sha256: string;
+    dedup?: boolean;
+    width?: number;
+    height?: number;
+    url?: string;
+    metadata?: Record<string, unknown>;
+}

package/dist-lib/types/schema.d.ts

@@ -1,4 +1,5 @@
 import { OrderedMap } from "./ordmap";
+import type { FileFieldDef } from "./files";
 export { OrderedMap };
 export type LocalizedString = Record<string, string>;
 /**
@@ -8,6 +9,12 @@ export type LocalizedString = Record<string, string>;
  */
 export declare const DETAIL_SCREEN_NONE = "none";
 export declare function loc(ls: LocalizedString | undefined, lang?: string): string;
+export declare const DISPLAY_KEY = "$display";
+export declare function getDisplayValue(row: Record<string, unknown> | null | undefined, entity: {
+    display?: {
+        display_field?: string;
+    };
+} | null | undefined): string | undefined;
 export declare function fieldDisplayName(field: EntityField, fieldName: string, entities?: Record<string, Entity>): string;
 export interface RefDisplay {
     field: string;
@@ -53,6 +60,7 @@ export interface EntityField {
         color?: string;
     }>;
     enum?: string;
+    files?: FileFieldDef;
     ref?: RefConfig;
     structure?: string;
     array?: boolean;
@@ -183,6 +191,7 @@ export interface Entity {
         description?: LocalizedString;
         icon: string;
         display_field?: string;
+        display_template?: string;
     };
     fields: OrderedMap<EntityField>;
     soft_delete?: string;
@@ -194,6 +203,7 @@ export interface Entity {
     actions?: Record<string, Action>;
     handlers?: Record<string, HandlerDef>;
     associations?: Record<string, AssociationDef>;
+    files?: OrderedMap<FileFieldDef>;
     detail_screen?: string;
 }
 export declare function getPrimaryKeyFields(entity: Entity): string[];
@@ -469,6 +479,7 @@ export interface Branding {
     app_logo?: string;
     app_initial?: string;
     accent_color?: string;
+    ai_name?: string;
     wordmark?: string;
     version_label?: string;
     status_url?: string;

package/dist-lib/vite/fingerprint-plugin.d.ts

@@ -0,0 +1,45 @@
+import type { Plugin } from "vite";
+export interface DeclarionFingerprintPluginOptions {
+    /**
+     * Subdirectory of `outDir` to walk. Defaults to "assets" — Vite's
+     * standard hashed-output location. Override only if a consumer has
+     * customized `build.assetsDir`.
+     */
+    assetsDir?: string;
+    /**
+     * Filename of the emitted fingerprint, written next to `index.html`.
+     * Defaults to "bundle-fingerprint.txt". Match this on the server
+     * side (`apps/server/fingerprint.go:readBundleFingerprint`) if you
+     * customize.
+     */
+    filename?: string;
+}
+/**
+ * Vite plugin that emits a single-line `bundle-fingerprint.txt` next
+ * to `index.html` after every production build. The fingerprint is a
+ * SHA-256 over every file in `assetsDir/` — sorted by name, length-
+ * prefixed (`name\x00sha256\x00`) so concatenation is collision-safe.
+ *
+ * The Declarion server reads this file at boot and folds it into the
+ * combined build identity exposed via `X-Declarion-Version` and
+ * `/api/version`. When a consumer redeploys the UI bundle (changed
+ * JS/CSS/assets) the file changes → server fingerprint changes → SDK
+ * detects asset drift → user is prompted to reload to pick up the
+ * new code.
+ *
+ * Why a separate file rather than walking `assetsDir/` from Go at
+ * boot:
+ *   - Eliminates a per-process I/O dependency on bundle layout
+ *     conventions (Vite could change `assetsDir` defaults; the
+ *     plugin is the canonical contract).
+ *   - Computed once at build time, read once at boot — never on the
+ *     hot path.
+ *   - Lets the consumer image ship the fingerprint as an immutable
+ *     artifact rather than re-deriving it at every server start.
+ *
+ * Backward compatible: if a consumer hasn't adopted the plugin yet,
+ * `bundle-fingerprint.txt` is absent at boot, the server logs once
+ * and degrades to binary-only drift detection (still correct — the
+ * binary fingerprint differs across builds anyway). No errors.
+ */
+export declare function declarionFingerprintPlugin(options?: DeclarionFingerprintPluginOptions): Plugin;

package/dist-lib/vite/index.d.ts

@@ -0,0 +1,21 @@
+/**
+ * @declarion/react/vite — Vite plugin entry point.
+ *
+ * Separate from the SDK's main React entry (`@declarion/react`) so this
+ * Node-only code never accidentally pulls into a browser bundle.
+ *
+ * Usage in a consumer's `vite.config.ts`:
+ *
+ *     import { declarionFingerprintPlugin } from "@declarion/react/vite";
+ *
+ *     export default defineConfig({
+ *       plugins: [react(), declarionFingerprintPlugin()],
+ *     });
+ *
+ * One line, one plugin — works in every Declarion deployment mode
+ * (local-up, prebuilt-declarion, fully-prebuilt prod) because the
+ * plugin runs at consumer-build time regardless of where the SDK
+ * itself comes from (npm pin / vite alias / link).
+ */
+export { declarionFingerprintPlugin } from "./fingerprint-plugin";
+export type { DeclarionFingerprintPluginOptions } from "./fingerprint-plugin";

package/dist-lib/vite/index.js

@@ -0,0 +1,52 @@
+import { createHash as e } from "node:crypto";
+import { readFileSync as t, readdirSync as n, statSync as r, writeFileSync as i } from "node:fs";
+import { join as a } from "node:path";
+//#region src/vite/fingerprint-plugin.ts
+function o(n = {}) {
+	let r = n.filename ?? "bundle-fingerprint.txt";
+	return {
+		name: "declarion-fingerprint",
+		apply: "build",
+		closeBundle: {
+			sequential: !0,
+			handler() {
+				let o = this.environment.config, c = o.build.outDir, l = a(c, n.assetsDir ?? o.build.assetsDir ?? "assets"), u = s(l);
+				u.sort();
+				let d = e("sha256");
+				for (let n of u) {
+					let r = a(l, n), i = e("sha256").update(t(r)).digest("hex");
+					d.update(`${n.length}:${n}\n`), d.update(`${i.length}:${i}\n`);
+				}
+				let f = d.digest("hex");
+				i(a(c, r), f + "\n", "utf8");
+			}
+		}
+	};
+}
+function s(e) {
+	let t = [], i = [{
+		abs: e,
+		rel: ""
+	}];
+	for (; i.length > 0;) {
+		let { abs: e, rel: o } = i.pop(), s;
+		try {
+			s = n(e);
+		} catch (e) {
+			if (e && typeof e == "object" && "code" in e && e.code === "ENOENT") return [];
+			throw e;
+		}
+		for (let n of s) {
+			let s = a(e, n), c = o ? `${o}/${n}` : n;
+			r(s).isDirectory() ? i.push({
+				abs: s,
+				rel: c
+			}) : t.push(c);
+		}
+	}
+	return t;
+}
+//#endregion
+export { o as declarionFingerprintPlugin };
+
+//# sourceMappingURL=index.js.map

package/dist-lib/vite/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","names":[],"sources":["../../src/vite/fingerprint-plugin.ts"],"sourcesContent":["import type { Plugin } from \"vite\";\nimport { createHash } from \"node:crypto\";\nimport {\n  readdirSync,\n  readFileSync,\n  statSync,\n  writeFileSync,\n} from \"node:fs\";\nimport { join } from \"node:path\";\n\nexport interface DeclarionFingerprintPluginOptions {\n  /**\n   * Subdirectory of `outDir` to walk. Defaults to \"assets\" — Vite's\n   * standard hashed-output location. Override only if a consumer has\n   * customized `build.assetsDir`.\n   */\n  assetsDir?: string;\n\n  /**\n   * Filename of the emitted fingerprint, written next to `index.html`.\n   * Defaults to \"bundle-fingerprint.txt\". Match this on the server\n   * side (`apps/server/fingerprint.go:readBundleFingerprint`) if you\n   * customize.\n   */\n  filename?: string;\n}\n\n/**\n * Vite plugin that emits a single-line `bundle-fingerprint.txt` next\n * to `index.html` after every production build. The fingerprint is a\n * SHA-256 over every file in `assetsDir/` — sorted by name, length-\n * prefixed (`name\\x00sha256\\x00`) so concatenation is collision-safe.\n *\n * The Declarion server reads this file at boot and folds it into the\n * combined build identity exposed via `X-Declarion-Version` and\n * `/api/version`. When a consumer redeploys the UI bundle (changed\n * JS/CSS/assets) the file changes → server fingerprint changes → SDK\n * detects asset drift → user is prompted to reload to pick up the\n * new code.\n *\n * Why a separate file rather than walking `assetsDir/` from Go at\n * boot:\n *   - Eliminates a per-process I/O dependency on bundle layout\n *     conventions (Vite could change `assetsDir` defaults; the\n *     plugin is the canonical contract).\n *   - Computed once at build time, read once at boot — never on the\n *     hot path.\n *   - Lets the consumer image ship the fingerprint as an immutable\n *     artifact rather than re-deriving it at every server start.\n *\n * Backward compatible: if a consumer hasn't adopted the plugin yet,\n * `bundle-fingerprint.txt` is absent at boot, the server logs once\n * and degrades to binary-only drift detection (still correct — the\n * binary fingerprint differs across builds anyway). No errors.\n */\nexport function declarionFingerprintPlugin(\n  options: DeclarionFingerprintPluginOptions = {},\n): Plugin {\n  const filename = options.filename ?? \"bundle-fingerprint.txt\";\n\n  return {\n    name: \"declarion-fingerprint\",\n    apply: \"build\",\n    closeBundle: {\n      // `sequential: true` is the safe default — run after rollup has\n      // finished writing the bundle, before any other closeBundle\n      // hooks observe the output dir.\n      sequential: true,\n      handler() {\n        // Read outDir + assetsDir from the resolved Vite config. We\n        // don't capture them in a `configResolved` hook because\n        // `closeBundle` already runs after config resolution.\n        const cfg = this.environment.config;\n        const outDir = cfg.build.outDir;\n        const assetsDir = options.assetsDir ?? cfg.build.assetsDir ?? \"assets\";\n        const assetsRoot = join(outDir, assetsDir);\n\n        const files = collectFiles(assetsRoot);\n        files.sort(); // deterministic order\n\n        const h = createHash(\"sha256\");\n        for (const relPath of files) {\n          const abs = join(assetsRoot, relPath);\n          const fileHash = createHash(\"sha256\")\n            .update(readFileSync(abs))\n            .digest(\"hex\");\n          // Length-prefix discipline — same as the Go side\n          // (store/migrations.go:215-282 + apps/server/fingerprint.go).\n          // `a`+`bc` and `ab`+`c` must produce different hashes.\n          h.update(`${relPath.length}:${relPath}\\n`);\n          h.update(`${fileHash.length}:${fileHash}\\n`);\n        }\n        const combined = h.digest(\"hex\");\n\n        writeFileSync(join(outDir, filename), combined + \"\\n\", \"utf8\");\n      },\n    },\n  };\n}\n\n/**\n * Walks `root` recursively and returns POSIX-style relative paths of\n * every regular file. Sorted by the caller. Symlinks are followed\n * since Vite output dirs don't contain them in practice.\n */\nfunction collectFiles(root: string): string[] {\n  const out: string[] = [];\n  const stack: { abs: string; rel: string }[] = [{ abs: root, rel: \"\" }];\n  while (stack.length > 0) {\n    const { abs, rel } = stack.pop()!;\n    let entries: string[];\n    try {\n      entries = readdirSync(abs);\n    } catch (err) {\n      // Missing assetsDir: nothing to fingerprint. Return empty;\n      // the plugin still emits the file so the server boot path\n      // doesn't have to special-case missing-yet-defined assets.\n      if (\n        err &&\n        typeof err === \"object\" &&\n        \"code\" in err &&\n        (err as { code: string }).code === \"ENOENT\"\n      ) {\n        return [];\n      }\n      throw err;\n    }\n    for (const name of entries) {\n      const childAbs = join(abs, name);\n      const childRel = rel ? `${rel}/${name}` : name;\n      if (statSync(childAbs).isDirectory()) {\n        stack.push({ abs: childAbs, rel: childRel });\n      } else {\n        out.push(childRel);\n      }\n    }\n  }\n  return out;\n}\n"],"mappings":";;;;AAuDA,SAAgB,EACd,IAA6C,EAAE,EACvC;CACR,IAAM,IAAW,EAAQ,YAAY;AAErC,QAAO;EACL,MAAM;EACN,OAAO;EACP,aAAa;GAIX,YAAY;GACZ,UAAU;IAIR,IAAM,IAAM,KAAK,YAAY,QACvB,IAAS,EAAI,MAAM,QAEnB,IAAa,EAAK,GADN,EAAQ,aAAa,EAAI,MAAM,aAAa,SACpB,EAEpC,IAAQ,EAAa,EAAW;AACtC,MAAM,MAAM;IAEZ,IAAM,IAAI,EAAW,SAAS;AAC9B,SAAK,IAAM,KAAW,GAAO;KAC3B,IAAM,IAAM,EAAK,GAAY,EAAQ,EAC/B,IAAW,EAAW,SAAS,CAClC,OAAO,EAAa,EAAI,CAAC,CACzB,OAAO,MAAM;AAKhB,KADA,EAAE,OAAO,GAAG,EAAQ,OAAO,GAAG,EAAQ,IAAI,EAC1C,EAAE,OAAO,GAAG,EAAS,OAAO,GAAG,EAAS,IAAI;;IAE9C,IAAM,IAAW,EAAE,OAAO,MAAM;AAEhC,MAAc,EAAK,GAAQ,EAAS,EAAE,IAAW,MAAM,OAAO;;GAEjE;EACF;;AAQH,SAAS,EAAa,GAAwB;CAC5C,IAAM,IAAgB,EAAE,EAClB,IAAwC,CAAC;EAAE,KAAK;EAAM,KAAK;EAAI,CAAC;AACtE,QAAO,EAAM,SAAS,IAAG;EACvB,IAAM,EAAE,QAAK,WAAQ,EAAM,KAAK,EAC5B;AACJ,MAAI;AACF,OAAU,EAAY,EAAI;WACnB,GAAK;AAIZ,OACE,KACA,OAAO,KAAQ,YACf,UAAU,KACT,EAAyB,SAAS,SAEnC,QAAO,EAAE;AAEX,SAAM;;AAER,OAAK,IAAM,KAAQ,GAAS;GAC1B,IAAM,IAAW,EAAK,GAAK,EAAK,EAC1B,IAAW,IAAM,GAAG,EAAI,GAAG,MAAS;AAC1C,GAAI,EAAS,EAAS,CAAC,aAAa,GAClC,EAAM,KAAK;IAAE,KAAK;IAAU,KAAK;IAAU,CAAC,GAE5C,EAAI,KAAK,EAAS;;;AAIxB,QAAO"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@declarion/react",
-  "version": "0.1.65",
+  "version": "0.1.67",
   "private": false,
   "license": "MIT",
   "description": "React SDK for Declarion, the schema-driven business apps platform.",
@@ -15,6 +15,11 @@
       "import": "./dist-lib/index.js",
       "default": "./dist-lib/index.js"
     },
+    "./vite": {
+      "types": "./dist-lib/vite/index.d.ts",
+      "import": "./dist-lib/vite/index.js",
+      "default": "./dist-lib/vite/index.js"
+    },
     "./styles.css": "./dist-lib/declarion-react.css"
   },
   "files": [
@@ -67,6 +72,8 @@
     "@types/react": "^19.0.0",
     "@types/react-dom": "^19.0.0",
     "@vitejs/plugin-react": "^6.0.1",
+    "eslint": "^10.2.1",
+    "eslint-plugin-react-hooks": "^7.1.1",
     "jsdom": "^29.0.1",
     "msw": "^2.13.4",
     "react": "^19.0.0",
@@ -74,14 +81,15 @@
     "tailwindcss": "^4.2.4",
     "tsc-alias": "^1.8.16",
     "typescript": "^6.0.3",
+    "typescript-eslint": "^8.59.0",
     "vite": "^8.0.9",
     "vitest": "^4.1.5"
   },
   "scripts": {
     "dev": "vite",
     "build": "tsc --noEmit && vite build",
-    "build:lib": "vite build --config vite.lib.config.ts && tsc -p tsconfig.lib.json && tsc-alias -p tsconfig.lib.json",
-    "lint": "tsc --noEmit",
+    "build:lib": "vite build --config vite.lib.config.ts && vite build --config vite.plugin.config.ts && tsc -p tsconfig.lib.json && tsc-alias -p tsconfig.lib.json",
+    "lint": "tsc --noEmit && eslint src",
     "test": "vitest run",
     "preview": "vite preview"
   }