@declarion/react 0.2.7 → 0.2.9

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/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-CXFBdyeL.js}

@@ -219,32 +219,32 @@ var O = (e) => JSON.stringify(e ?? {}), k = null, A = class extends Error {
 	constructor(e) {
 		super(`refresh failed terminally (${e})`), this.status = e, this.name = "RefreshDeadError";
 	}
-}, j = null, M = null, pe = 3e4, me = 5e3;
-function he() {
+}, j = null, M = null, N = 3e4, pe = 5e3;
+function me() {
 	F().catch((e) => {
 		e instanceof A && I();
 	});
 }
-function N(e) {
+function he(e) {
 	if (j &&= (clearTimeout(j), null), M = null, !e || typeof window > "u") return;
 	let t = Date.parse(e);
 	if (Number.isNaN(t)) return;
 	M = t;
-	let n = Math.max(t - Date.now() - pe, me);
+	let n = Math.max(t - Date.now() - N, pe);
 	j = setTimeout(() => {
-		j = null, he();
+		j = null, me();
 	}, n);
 }
 function ge() {
 	j &&= (clearTimeout(j), null), M = null;
 }
 typeof document < "u" && document.addEventListener("visibilitychange", () => {
-	document.visibilityState === "visible" && M !== null && Date.now() >= M - pe && he();
+	document.visibilityState === "visible" && M !== null && Date.now() >= M - N && me();
 });
 async function P(e) {
 	try {
 		let t = await e.json();
-		N(t?.result?.expires_at ?? t?.expires_at);
+		he(t?.result?.expires_at ?? t?.expires_at);
 	} catch {}
 }
 async function _e() {
@@ -410,6 +410,7 @@ async function K(e, t, n) {
 		url: i.url,
 		kind: "direct"
 	};
+	if (!i.url.startsWith(H + "/")) 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();
@@ -763,6 +764,6 @@ function it(e) {
 	return e ? Array.isArray(e) ? e.filter($) : $(e) ? [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 };
+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, he 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-CXFBdyeL.js.map