@declarion/react 0.2.8 → 0.2.10

package/dist-lib/lib/field-classification.d.ts

@@ -0,0 +1,52 @@
+import type { Entity, FieldAccessInfo, ClassificationTierDef, Schema } from "../types/schema";
+/**
+ * isFieldReadable returns true when the caller can see the field's
+ * value. Non-classified fields are always readable (no entry in
+ * field_access). Classified fields are readable when field_access
+ * marks read="granted". Plan §B9.
+ */
+export declare function isFieldReadable(entity: Entity | undefined, fieldName: string): boolean;
+/**
+ * isFieldWritable returns true when the caller can submit a new value
+ * for the field. Form components disable input + show a lock badge
+ * when this returns false. Non-classified fields are always writable
+ * (gating happens via entity-level RBAC at the HTTP layer). Plan §B9.
+ */
+export declare function isFieldWritable(entity: Entity | undefined, fieldName: string): boolean;
+/**
+ * fieldClassification returns the classification tier code gating
+ * the field, or undefined when the field is non-classified. Lets
+ * UI code render a tier badge without re-implementing the field_access
+ * lookup.
+ */
+export declare function fieldClassification(entity: Entity | undefined, fieldName: string): string | undefined;
+/**
+ * fieldRequiredPermission returns the exact grant string an
+ * administrator must add to a role to unlock the field for the
+ * current caller. Returns undefined when the field is readable +
+ * writable (no hint needed). Plan §B9 — operator hand-off surface.
+ */
+export declare function fieldRequiredPermission(entity: Entity | undefined, fieldName: string): string | undefined;
+/**
+ * classificationTier returns the localized tier metadata for a field
+ * (display name, description, audit_on_read flag, icon). Resolves
+ * via the top-level schema.classifications map. Returns undefined when
+ * the field is non-classified or the tier code is unknown in the
+ * catalog (defense — points at a misconfigured registry).
+ */
+export declare function classificationTier(schema: Schema | undefined, entity: Entity | undefined, fieldName: string): ClassificationTierDef | undefined;
+/**
+ * isFieldSoDProtected reports whether the field's tier carries
+ * sod_protected:true in the catalog. Used by UI to surface a stronger
+ * visual treatment (e.g. red lock vs. grey lock) for tiers that
+ * trigger the stricter SoD controls (superadmin-bypass-disabled
+ * tenants, role self-assignment refusal, etc).
+ */
+export declare function isFieldSoDProtected(schema: Schema | undefined, entity: Entity | undefined, fieldName: string): boolean;
+/**
+ * fieldAccessInfo returns the raw FieldAccessInfo entry for a field,
+ * or undefined when the field is non-classified. Convenience for
+ * components that need the full structure (e.g. a tooltip rendering
+ * both classification name + required_permission hint).
+ */
+export declare function fieldAccessInfo(entity: Entity | undefined, fieldName: string): FieldAccessInfo | undefined;

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

@@ -0,0 +1,72 @@
+export type SortDir = "asc" | "desc";
+export type SortNulls = "first" | "last";
+export interface SortCol {
+    field: string;
+    dir: SortDir;
+    nulls?: SortNulls;
+}
+/**
+ * Parse a sort expression string into a list of SortCol entries.
+ *
+ * Tolerant per plan §5.2:
+ *   - empty/null/undefined → []
+ *   - missing direction defaults to "asc"
+ *   - missing nulls segment is left undefined (system default applies server-side)
+ *   - unknown nulls literal is dropped (server is the strict authority)
+ *   - empty fields between commas are skipped
+ */
+export declare function parseSort(s: string | null | undefined): SortCol[];
+/**
+ * Filter a raw sort URL string so $property.* segments (deferred per plan §2)
+ * don't reach the backend's strict parser. EVERY OTHER token passes through
+ * unchanged - including malformed grammar like `:nulls_middle` or extra
+ * colons - so the backend can return a typed ValidationError and the SDK
+ * surfaces the error to the user. Plan §14 strict-parse contract requires
+ * that grammar violations are NOT silently rewritten on the client.
+ */
+export declare function stripUnsupportedSortSegments(s: string | null | undefined): string | undefined;
+/**
+ * Serialize a list of SortCol entries back to the canonical string form.
+ * Round-trips losslessly with parseSort for any valid input.
+ */
+export declare function serializeSort(cols: SortCol[]): string;
+/**
+ * Server-enforced cap (plan §3 Decision 4, §4.2). Mirrored on the client so
+ * we never POST a sort the server will reject with HTTP 400.
+ */
+export declare const MAX_SORT_COLS = 5;
+/**
+ * Shift-click on a column header (plan §7.1).
+ *
+ *   - field already in `prev`  → remove it (toggle off).
+ *   - field not in `prev`      → append { field, dir: "asc" } to the tail.
+ *
+ * When the list is already at the {@link MAX_SORT_COLS} cap AND `field` is
+ * not already in it, the helper refuses and returns `prev` unchanged. The
+ * UI surfaces this implicitly: the "Add to multi-sort" menu item is hidden
+ * once the cap is reached, and a shift-click on a brand-new column at the
+ * cap is a no-op (consistent UX, matches the brief's "refuse" call).
+ *
+ * Nulls placement of every retained column is preserved verbatim - shift-
+ * click never silently rewrites another column's NULL setting.
+ *
+ * Returned arrays are always new references; never mutates `prev`.
+ */
+export declare function applyShiftClickSort(prev: SortCol[], field: string): SortCol[];
+/**
+ * "Add to multi-sort" menu action (plan §7.2). Adds `col` to the sort tail
+ * with the caller-chosen `dir` + `nulls`. Dedupes: if `col.field` is already
+ * present in `prev`, the earlier occurrence is removed and the new one
+ * appended at the tail (server rejects duplicate fields, plan §4.2).
+ *
+ * Refuses to grow past {@link MAX_SORT_COLS}: when appending would exceed
+ * the cap AND the field is not already present, returns `prev` unchanged.
+ * The menu item that drives this is hidden at the cap, so this guard exists
+ * to keep the helper safe under any caller.
+ */
+export declare function applyAppendSort(prev: SortCol[], col: SortCol): SortCol[];
+/**
+ * "Clear sort on this column" menu action (plan §7.2). Removes the one
+ * entry matching `field` from `prev`; returns `prev` unchanged if absent.
+ */
+export declare function removeSortField(prev: SortCol[], field: string): SortCol[];

package/dist-lib/{rich-text-CaQ6-8Gx.js → rich-text-CJpzFOG5.js}

@@ -45,4 +45,4 @@ function l(e) {
 //#endregion
 export { c as a, t as i, s as n, r as o, o as r, i as s, n as t };
 
-//# sourceMappingURL=rich-text-CaQ6-8Gx.js.map
+//# sourceMappingURL=rich-text-CJpzFOG5.js.map

package/dist-lib/{rich-text-CaQ6-8Gx.js.map → rich-text-CJpzFOG5.js.map}

@@ -1 +1 @@
-{"version":3,"file":"rich-text-CaQ6-8Gx.js","names":[],"sources":["../src/lib/rich-text.ts"],"sourcesContent":["import type { HydratedFile } from \"@/types/files\";\n\nexport interface RichTextValue {\n  markdown: string;\n  files: Record<string, HydratedFile>;\n}\n\nconst declarionFilePattern = /declarion:\\/\\/file\\/([0-9a-fA-F-]{36})/g;\n\nexport function richTextMarkdown(value: unknown): string {\n  if (typeof value === \"string\") return value;\n  if (isRecord(value) && typeof value.markdown === \"string\") return value.markdown;\n  return \"\";\n}\n\nexport function richTextFiles(value: unknown): Record<string, HydratedFile> {\n  if (!isRecord(value) || !isRecord(value.files)) return {};\n    const files: Record<string, HydratedFile> = {};\n    for (const [fileId, file] of Object.entries(value.files)) {\n      if (isRecord(file) && typeof file.id === \"string\") {\n        files[fileId] = file as unknown as HydratedFile;\n      }\n    }\n  return files;\n}\n\nexport function createRichTextValue(markdownValue: unknown, inlineFilesValue: unknown): RichTextValue {\n  return {\n    markdown: richTextMarkdown(markdownValue),\n    files: inlineFilesById(inlineFilesValue),\n  };\n}\n\nexport function withRichTextFile(value: unknown, file: HydratedFile): RichTextValue {\n  const next = createRichTextValue(value, null);\n  next.files[file.id] = file;\n  return next;\n}\n\nexport function withoutRichTextFiles(value: unknown, removedIds: Iterable<string>): RichTextValue {\n  const next = createRichTextValue(value, null);\n  for (const fileId of removedIds) delete next.files[fileId];\n  return next;\n}\n\nexport function inlineFilesById(value: unknown): Record<string, HydratedFile> {\n  if (!Array.isArray(value)) return {};\n  const files: Record<string, HydratedFile> = {};\n  for (const item of value) {\n    if (isRecord(item) && typeof item.id === \"string\") {\n      files[item.id] = item as unknown as HydratedFile;\n    }\n  }\n  return files;\n}\n\nexport function extractDeclarionFileIds(markdown: string): string[] {\n  const seen = new Set<string>();\n  const ids: string[] = [];\n  let match: RegExpExecArray | null;\n  declarionFilePattern.lastIndex = 0;\n  while ((match = declarionFilePattern.exec(markdown)) !== null) {\n    const fileId = match[1];\n    if (seen.has(fileId)) continue;\n    seen.add(fileId);\n    ids.push(fileId);\n  }\n  return ids;\n}\n\nexport function extractDeclarionFileId(url: string | undefined): string | null {\n  if (!url) return null;\n  const match = /^declarion:\\/\\/file\\/([0-9a-fA-F-]{36})$/.exec(url);\n  return match?.[1] ?? null;\n}\n\nexport function richTextTokenForFile(file: Pick<HydratedFile, \"id\" | \"content_type\" | \"filename\">): string {\n  const ref = `declarion://file/${file.id}`;\n  if (file.content_type.startsWith(\"image/\")) return `![](${ref})`;\n  const label = file.filename || file.id;\n  return `[${label}](${ref})`;\n}\n\nfunction isRecord(value: unknown): value is Record<string, unknown> {\n  return typeof value === \"object\" && value !== null;\n}\n"],"mappings":";AAOA,IAAM,IAAuB;AAE7B,SAAgB,EAAiB,GAAwB;CAGvD,OAFI,OAAO,KAAU,WAAiB,IAClC,EAAS,CAAK,KAAK,OAAO,EAAM,YAAa,WAAiB,EAAM,WACjE;AACT;AAaA,SAAgB,EAAoB,GAAwB,GAA0C;CACpG,OAAO;EACL,UAAU,EAAiB,CAAa;EACxC,OAAO,EAAgB,CAAgB;CACzC;AACF;AAEA,SAAgB,EAAiB,GAAgB,GAAmC;CAClF,IAAM,IAAO,EAAoB,GAAO,IAAI;CAE5C,OADA,EAAK,MAAM,EAAK,MAAM,GACf;AACT;AAEA,SAAgB,EAAqB,GAAgB,GAA6C;CAChG,IAAM,IAAO,EAAoB,GAAO,IAAI;CAC5C,KAAK,IAAM,KAAU,GAAY,OAAO,EAAK,MAAM;CACnD,OAAO;AACT;AAEA,SAAgB,EAAgB,GAA8C;CAC5E,IAAI,CAAC,MAAM,QAAQ,CAAK,GAAG,OAAO,CAAC;CACnC,IAAM,IAAsC,CAAC;CAC7C,KAAK,IAAM,KAAQ,GACjB,AAAI,EAAS,CAAI,KAAK,OAAO,EAAK,MAAO,aACvC,EAAM,EAAK,MAAM;CAGrB,OAAO;AACT;AAEA,SAAgB,EAAwB,GAA4B;CAClE,IAAM,oBAAO,IAAI,IAAY,GACvB,IAAgB,CAAC,GACnB;CAEJ,KADA,EAAqB,YAAY,IACzB,IAAQ,EAAqB,KAAK,CAAQ,OAAO,OAAM;EAC7D,IAAM,IAAS,EAAM;EACjB,EAAK,IAAI,CAAM,MACnB,EAAK,IAAI,CAAM,GACf,EAAI,KAAK,CAAM;CACjB;CACA,OAAO;AACT;AAEA,SAAgB,EAAuB,GAAwC;CAG7E,OAFK,IACS,2CAA2C,KAAK,CACvD,IAAQ,MAAM,OAFJ;AAGnB;AAEA,SAAgB,EAAqB,GAAsE;CACzG,IAAM,IAAM,oBAAoB,EAAK;CAGrC,OAFI,EAAK,aAAa,WAAW,QAAQ,IAAU,OAAO,EAAI,KAEvD,IADO,EAAK,YAAY,EAAK,GACnB,IAAI,EAAI;AAC3B;AAEA,SAAS,EAAS,GAAkD;CAClE,OAAO,OAAO,KAAU,cAAY;AACtC"}
+{"version":3,"file":"rich-text-CJpzFOG5.js","names":[],"sources":["../src/lib/rich-text.ts"],"sourcesContent":["import type { HydratedFile } from \"@/types/files\";\n\nexport interface RichTextValue {\n  markdown: string;\n  files: Record<string, HydratedFile>;\n}\n\nconst declarionFilePattern = /declarion:\\/\\/file\\/([0-9a-fA-F-]{36})/g;\n\nexport function richTextMarkdown(value: unknown): string {\n  if (typeof value === \"string\") return value;\n  if (isRecord(value) && typeof value.markdown === \"string\") return value.markdown;\n  return \"\";\n}\n\nexport function richTextFiles(value: unknown): Record<string, HydratedFile> {\n  if (!isRecord(value) || !isRecord(value.files)) return {};\n    const files: Record<string, HydratedFile> = {};\n    for (const [fileId, file] of Object.entries(value.files)) {\n      if (isRecord(file) && typeof file.id === \"string\") {\n        files[fileId] = file as unknown as HydratedFile;\n      }\n    }\n  return files;\n}\n\nexport function createRichTextValue(markdownValue: unknown, inlineFilesValue: unknown): RichTextValue {\n  return {\n    markdown: richTextMarkdown(markdownValue),\n    files: inlineFilesById(inlineFilesValue),\n  };\n}\n\nexport function withRichTextFile(value: unknown, file: HydratedFile): RichTextValue {\n  const next = createRichTextValue(value, null);\n  next.files[file.id] = file;\n  return next;\n}\n\nexport function withoutRichTextFiles(value: unknown, removedIds: Iterable<string>): RichTextValue {\n  const next = createRichTextValue(value, null);\n  for (const fileId of removedIds) delete next.files[fileId];\n  return next;\n}\n\nexport function inlineFilesById(value: unknown): Record<string, HydratedFile> {\n  if (!Array.isArray(value)) return {};\n  const files: Record<string, HydratedFile> = {};\n  for (const item of value) {\n    if (isRecord(item) && typeof item.id === \"string\") {\n      files[item.id] = item as unknown as HydratedFile;\n    }\n  }\n  return files;\n}\n\nexport function extractDeclarionFileIds(markdown: string): string[] {\n  const seen = new Set<string>();\n  const ids: string[] = [];\n  let match: RegExpExecArray | null;\n  declarionFilePattern.lastIndex = 0;\n  while ((match = declarionFilePattern.exec(markdown)) !== null) {\n    const fileId = match[1];\n    if (seen.has(fileId)) continue;\n    seen.add(fileId);\n    ids.push(fileId);\n  }\n  return ids;\n}\n\nexport function extractDeclarionFileId(url: string | undefined): string | null {\n  if (!url) return null;\n  const match = /^declarion:\\/\\/file\\/([0-9a-fA-F-]{36})$/.exec(url);\n  return match?.[1] ?? null;\n}\n\nexport function richTextTokenForFile(file: Pick<HydratedFile, \"id\" | \"content_type\" | \"filename\">): string {\n  const ref = `declarion://file/${file.id}`;\n  if (file.content_type.startsWith(\"image/\")) return `![](${ref})`;\n  const label = file.filename || file.id;\n  return `[${label}](${ref})`;\n}\n\nfunction isRecord(value: unknown): value is Record<string, unknown> {\n  return typeof value === \"object\" && value !== null;\n}\n"],"mappings":";AAOA,IAAM,IAAuB;AAE7B,SAAgB,EAAiB,GAAwB;CAGvD,OAFI,OAAO,KAAU,WAAiB,IAClC,EAAS,CAAK,KAAK,OAAO,EAAM,YAAa,WAAiB,EAAM,WACjE;AACT;AAaA,SAAgB,EAAoB,GAAwB,GAA0C;CACpG,OAAO;EACL,UAAU,EAAiB,CAAa;EACxC,OAAO,EAAgB,CAAgB;CACzC;AACF;AAEA,SAAgB,EAAiB,GAAgB,GAAmC;CAClF,IAAM,IAAO,EAAoB,GAAO,IAAI;CAE5C,OADA,EAAK,MAAM,EAAK,MAAM,GACf;AACT;AAEA,SAAgB,EAAqB,GAAgB,GAA6C;CAChG,IAAM,IAAO,EAAoB,GAAO,IAAI;CAC5C,KAAK,IAAM,KAAU,GAAY,OAAO,EAAK,MAAM;CACnD,OAAO;AACT;AAEA,SAAgB,EAAgB,GAA8C;CAC5E,IAAI,CAAC,MAAM,QAAQ,CAAK,GAAG,OAAO,CAAC;CACnC,IAAM,IAAsC,CAAC;CAC7C,KAAK,IAAM,KAAQ,GACjB,AAAI,EAAS,CAAI,KAAK,OAAO,EAAK,MAAO,aACvC,EAAM,EAAK,MAAM;CAGrB,OAAO;AACT;AAEA,SAAgB,EAAwB,GAA4B;CAClE,IAAM,oBAAO,IAAI,IAAY,GACvB,IAAgB,CAAC,GACnB;CAEJ,KADA,EAAqB,YAAY,IACzB,IAAQ,EAAqB,KAAK,CAAQ,OAAO,OAAM;EAC7D,IAAM,IAAS,EAAM;EACjB,EAAK,IAAI,CAAM,MACnB,EAAK,IAAI,CAAM,GACf,EAAI,KAAK,CAAM;CACjB;CACA,OAAO;AACT;AAEA,SAAgB,EAAuB,GAAwC;CAG7E,OAFK,IACS,2CAA2C,KAAK,CACvD,IAAQ,MAAM,OAFJ;AAGnB;AAEA,SAAgB,EAAqB,GAAsE;CACzG,IAAM,IAAM,oBAAoB,EAAK;CAGrC,OAFI,EAAK,aAAa,WAAW,QAAQ,IAAU,OAAO,EAAI,KAEvD,IADO,EAAK,YAAY,EAAK,GACnB,IAAI,EAAI;AAC3B;AAEA,SAAS,EAAS,GAAkD;CAClE,OAAO,OAAO,KAAU,cAAY;AACtC"}

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

@@ -98,6 +98,34 @@ export interface EntityField {
     structure?: string;
     array?: boolean;
     copyable?: boolean;
+    /**
+     * Plan 2026-05-26 §4 / B13. Names the data_classifications tier
+     * gating reads + writes on this field. Read-side: stripped from the
+     * row when the caller lacks `classification:<tier>:read`. Write-side:
+     * 422 FIELDS_FORBIDDEN when the caller writes the key without
+     * `classification:<tier>:write`. Frontend reads the tier's localized
+     * display name from the top-level `classifications:` map and
+     * cross-references `schema.entities.<code>.field_access.<field>` for
+     * the per-caller decision.
+     */
+    classification?: string;
+}
+/**
+ * Per-caller classification decision for one classified field on one
+ * entity. Plan 2026-05-26 §8 / B9. Populated by the schema endpoint
+ * from the caller's grants + authority tier; the frontend reads this
+ * to render the locked-widget badge ("🔒 Compensation"), disable write
+ * inputs, and surface the operator-facing `required_permission` hint
+ * to the user (e.g. "Ask your admin to grant you
+ * classification:compensation:read").
+ */
+export interface FieldAccessInfo {
+    read: "granted" | "denied";
+    write: "granted" | "denied";
+    classification: string;
+    /** Only set when read OR write is denied — the exact grant string an
+     *  administrator needs to add to a role to unlock this field. */
+    required_permission?: string;
 }
 export interface StructureDef {
     name: LocalizedString;
@@ -283,6 +311,16 @@ export interface Entity {
      * Server delivers RBAC-pruned nodes in tagged-union wire format (plan §8).
      */
     action_layout?: ActionLayoutNode[];
+    /**
+     * Plan 2026-05-26 §B9 / §B13. Per-caller classification access
+     * decision keyed by field name. Only present for entities that
+     * declare at least one classified field; absent on non-classification
+     * entities so the wire stays byte-equivalent for non-classification
+     * deployments. Frontend reads this map to render the locked-widget
+     * badge, disable write inputs, and surface the required_permission
+     * hint to the user.
+     */
+    field_access?: Record<string, FieldAccessInfo>;
     /**
      * Per-entity realtime opt-in. When true the entity is in the CDC
      * publication, its list views auto-update from the SSE stream, and the
@@ -763,4 +801,31 @@ export interface Schema {
     branding?: Branding;
     areas?: AreaDef[];
     accents?: Record<string, AccentDef>;
+    /**
+     * Plan 2026-05-26 §B9 / §B13. data_classifications catalog keyed by
+     * tier code — display name + description + audit_on_read flag + icon
+     * + sod_protected flag. Absent when the consumer declares no tiers
+     * (preserves byte-equivalent wire shape for non-classification
+     * deployments). Frontend resolves the localized tier name from this
+     * map when rendering locked-widget badges.
+     */
+    classifications?: Record<string, ClassificationTierDef>;
+}
+/**
+ * Plan 2026-05-26 §B9. One entry in the top-level classifications map.
+ * Mirrors engine.DataClassification.
+ */
+export interface ClassificationTierDef {
+    name: LocalizedString;
+    description?: LocalizedString;
+    audit_on_read?: boolean;
+    icon?: string;
+    /**
+     * When true, the tier triggers stricter SoD controls: superadmin
+     * reveals emit a distinct audit code, tenant param
+     * `auth.superadmin_classification_bypass=false` disables the
+     * implicit bypass, role self-assignment is refused, transitive role
+     * inheritance is hard-errored at load. Plan §11 Decisions Log #20-22.
+     */
+    sod_protected?: boolean;
 }

package/dist-lib/{value-qao1rdkR.js → value-DaEUgsnK.js}

@@ -410,6 +410,7 @@ async function K(e, t, n) {
 		url: i.url,
 		kind: "direct"
 	};
+	if (!i.url.startsWith("/api/files/")) throw Error(`embed file proxy: refusing non-files-route URL ${JSON.stringify(i.url)}`);
 	let a = await G(t === "download" ? Ee(i.url) : i.url, n);
 	if (!a.ok) throw Error(`embed file proxy fetch failed: ${a.status} ${a.statusText}`);
 	let o = await a.blob();
@@ -765,4 +766,4 @@ function it(e) {
 //#endregion
 export { ve as A, g as B, B as C, F as D, ge as E, x as F, m as H, re as I, b as L, fe as M, C as N, L as O, S as P, oe as R, A as S, V as T, p as U, _ as V, c as W, q as _, Xe as a, De as b, Be as c, Ue as d, We as f, Je as g, Re as h, tt as i, E as j, N as k, He as l, Ke as m, rt as n, Qe as o, Ve as p, nt as r, Ze as s, it as t, qe as u, Me as v, Se as w, Ne as x, Q as y, h as z };
 
-//# sourceMappingURL=value-qao1rdkR.js.map
+//# sourceMappingURL=value-DaEUgsnK.js.map