@aiaiai-pt/design-system 0.44.1 → 0.45.0

package/components/ActionFormRenderer.svelte

@@ -24,7 +24,11 @@
   // `target_config.layout_key` and validated through `resolveLayout`,
   // so an operator-supplied string never reaches the DOM verbatim
   // (RH#11 / R-SEC-07 / TH-08).
-  import { resolveLayout } from "./action-form-renderer-layouts";
+  import { resolveLayout, type LayoutSection } from "./action-form-renderer-layouts";
+  // #634 S4 — live section show/hide from the contract's `visible_when`
+  // predicate (pure client evaluation over the value bag; the server owns
+  // enforcement).
+  import { sectionVisible } from "./action-form-visibility";
 
   /**
    * The renderer treats every parameter/action/placement as a loose record
@@ -42,7 +46,15 @@
     placement?: Entity | null;
     target?: Record<string, unknown> | null;
     source?: Record<string, unknown> | null;
-    sections?: Array<{ key?: string; label?: string; parameters?: Entity[] }>;
+    sections?: Array<{
+      key?: string;
+      label?: string;
+      order?: number | null;
+      columns?: number | null;
+      /** Read defensively (hosts carry concrete precondition types). */
+      visible_when?: unknown;
+      parameters?: Entity[];
+    }>;
     parameters?: Entity[];
     criteria?: Entity[];
   };
@@ -193,12 +205,21 @@
   );
   const schemaSections = $derived(schemaSectionsFromContract());
   const sections = $derived(schemaSections ?? groupIntoSections(visibleParameters));
+  // #634 S4 — LIVE conditional sections: a section whose `visible_when`
+  // predicate fails against the current value bag is hidden (and re-appears
+  // the moment the driving value changes). Sections without a predicate —
+  // including every legacy fold section — always pass, so this is inert
+  // until a sheet declares `visible_when`. The value bag still spans ALL
+  // parameters (hidden sections keep their answers).
+  const liveSections = $derived(
+    sections.filter((section) => sectionVisible(section, values)),
+  );
   // Wizard pagination (#105 P6): when a section is active, render only it. The
   // value bag is unaffected — every parameter is still seeded and submitted.
   const displaySections = $derived(
     activeSectionKey == null
-      ? sections
-      : sections.filter((section) => section.name === activeSectionKey),
+      ? liveSections
+      : liveSections.filter((section) => section.name === activeSectionKey),
   );
   const payload = $derived(buildPayload());
   const payloadJson = $derived(JSON.stringify(payload, null, 2));
@@ -216,8 +237,13 @@
   function isEmpty(value: unknown): boolean {
     return value === undefined || value === null || value === "";
   }
+  // #634 S4 — the gate counts only parameters whose section is LIVE-visible:
+  // a required field inside a `visible_when`-hidden section must not block
+  // submit (it is unreachable). In the legacy fold path this flattens back
+  // to exactly `visibleParameters`.
+  const gateParameters = $derived(liveSections.flatMap((section) => section.items));
   const canSubmit = $derived(
-    visibleParameters
+    gateParameters
       .filter((parameter) => parameter.required)
       .every((parameter) =>
         String(parameter.type ?? "") === "file"
@@ -306,18 +332,34 @@
     return [...byName.entries()].map(([name, sectionItems]) => ({ name, items: sectionItems }));
   }
 
-  function schemaSectionsFromContract(): Array<{ name: string; items: Entity[] }> | null {
+  function schemaSectionsFromContract(): LayoutSection[] | null {
     if (!Array.isArray(schema?.sections)) return null;
     const next = schema.sections
-      .map((section) => {
+      .map((section, index) => {
         const items = Array.isArray(section.parameters)
           ? section.parameters
               .filter((parameter) => parameter.is_active !== false && isVisible(parameter))
               .sort((a, b) => Number(a.order ?? 0) - Number(b.order ?? 0))
           : [];
-        return { name: String(section.label ?? section.key ?? "Details"), items };
+        // #634 S3/S4 — carry the contract's presentation keys through to the
+        // layouts: stable `key`, declared `columns`, the `visible_when`
+        // predicate, and `order` (the server emits sections pre-sorted; the
+        // sort below is a defensive mirror, stable via declaration index).
+        return {
+          name: String(section.label ?? section.key ?? "Details"),
+          key: section.key ? String(section.key) : undefined,
+          columns: Number(section.columns ?? 1),
+          visibleWhen:
+            section.visible_when && typeof section.visible_when === "object"
+              ? (section.visible_when as Record<string, unknown>)
+              : null,
+          order: Number(section.order ?? 0),
+          index,
+          items,
+        };
       })
-      .filter((section) => section.items.length);
+      .filter((section) => section.items.length)
+      .sort((a, b) => a.order - b.order || a.index - b.index);
     return next.length ? next : null;
   }
 

package/components/ActionFormRenderer.svelte.d.ts

@@ -22,6 +22,10 @@ type ActionSchema = {
     sections?: Array<{
         key?: string;
         label?: string;
+        order?: number | null;
+        columns?: number | null;
+        /** Read defensively (hosts carry concrete precondition types). */
+        visible_when?: unknown;
         parameters?: Entity[];
     }>;
     parameters?: Entity[];

package/components/LayoutStackedDefault.svelte

@@ -5,9 +5,15 @@
    * Each section is a labelled <fieldset>, parameters laid out as a
    * single-column flex column. This is the safe fallback for unknown
    * layout keys — see `resolve.ts`.
+   *
+   * #634 S3 — a section declaring `columns: 2` lays its cells on a
+   * two-column grid; `span: full` params (and wide types — geo/file)
+   * break out to the full row (the EntityFormSurface two-col precedent).
+   * Default (columns 1 / absent) keeps the single-column stack
+   * byte-identical.
    */
   import Card from "./Card.svelte";
-  import type { LayoutSection } from "./action-form-renderer-layouts";
+  import { fieldSpansFull, type LayoutSection } from "./action-form-renderer-layouts";
   import type { Snippet } from "svelte";
 
   let {
@@ -23,9 +29,16 @@
   {#each sections as section (section.name)}
     <Card variant="flat" class="section" role="group" aria-label={section.name}>
       <h4>{section.name}</h4>
-      <div class="rows">
+      <div
+        class="rows"
+        class:two-col={(section.columns ?? 1) === 2}
+        data-columns={section.columns ?? 1}
+      >
         {#each section.items as parameter}
-          <div class="field-row">
+          <div
+            class="field-row"
+            class:span-full={fieldSpansFull(parameter, section.columns)}
+          >
             {@render field(parameter)}
           </div>
         {/each}
@@ -53,6 +66,26 @@
     gap: var(--space-md);
   }
 
+  /* #634 S3 — two-column density: half-width cells flow the grid,
+     span-full cells break out to the whole row. Collapses back to one
+     column on narrow viewports (the EntityFormSurface breakpoint). */
+  .rows.two-col {
+    display: grid;
+    grid-template-columns: repeat(2, minmax(0, 1fr));
+    column-gap: var(--space-md);
+    row-gap: var(--space-md);
+  }
+
+  .rows.two-col .field-row.span-full {
+    grid-column: 1 / -1;
+  }
+
+  @media (max-width: 48rem) {
+    .rows.two-col {
+      grid-template-columns: 1fr;
+    }
+  }
+
   .field-row {
     display: flex;
     flex-direction: column;

package/components/LayoutStackedDefault.svelte.d.ts

@@ -1,4 +1,4 @@
-import type { LayoutSection } from "./action-form-renderer-layouts";
+import { type LayoutSection } from "./action-form-renderer-layouts";
 import type { Snippet } from "svelte";
 type $$ComponentProps = {
     sections: LayoutSection[];

package/components/action-form-renderer-layouts.d.ts

@@ -34,7 +34,24 @@ export interface LayoutEntry {
 export interface LayoutSection {
     name: string;
     items: Array<Record<string, unknown>>;
+    /** #634 S3 — stable contract key (schema.sections[].key), when present. */
+    key?: string;
+    /** #634 S3 — declared section density (1|2). Layouts that arrange rows
+     *  vertically render a two-column grid when 2; other layouts may ignore
+     *  it (their arrangement is their own contract). Default 1. */
+    columns?: number;
+    /** #634 S4 — the section's optional `visible_when` predicate, carried
+     *  from the contract for live show/hide (see action-form-visibility). */
+    visibleWhen?: Record<string, unknown> | null;
 }
+/**
+ * #634 S3 — whether a parameter's cell spans the full row inside a
+ * `columns: 2` section. An explicit `span: "full"` on the parameter wins;
+ * wide types clamp to full regardless; everything else flows half-width
+ * (so a bare `columns: 2` declaration visibly two-columns its fields).
+ * In a single-column section every cell is trivially full.
+ */
+export declare function fieldSpansFull(parameter: Record<string, unknown>, columns: number | undefined): boolean;
 import type { Snippet } from "svelte";
 export interface LayoutComponentProps {
     sections: LayoutSection[];

package/components/action-form-renderer-layouts.ts

@@ -41,6 +41,36 @@ export interface LayoutEntry {
 export interface LayoutSection {
   name: string;
   items: Array<Record<string, unknown>>;
+  /** #634 S3 — stable contract key (schema.sections[].key), when present. */
+  key?: string;
+  /** #634 S3 — declared section density (1|2). Layouts that arrange rows
+   *  vertically render a two-column grid when 2; other layouts may ignore
+   *  it (their arrangement is their own contract). Default 1. */
+  columns?: number;
+  /** #634 S4 — the section's optional `visible_when` predicate, carried
+   *  from the contract for live show/hide (see action-form-visibility). */
+  visibleWhen?: Record<string, unknown> | null;
+}
+
+/** Parameter types that can never sit half-width in a two-column section —
+ *  they carry their own wide UI (map canvas, upload list). Mirrors the CRUD
+ *  form-surface compiler's full-width clamp (form-surface.ts). */
+const FULL_WIDTH_PARAM_TYPES = new Set(["geo", "file", "json"]);
+
+/**
+ * #634 S3 — whether a parameter's cell spans the full row inside a
+ * `columns: 2` section. An explicit `span: "full"` on the parameter wins;
+ * wide types clamp to full regardless; everything else flows half-width
+ * (so a bare `columns: 2` declaration visibly two-columns its fields).
+ * In a single-column section every cell is trivially full.
+ */
+export function fieldSpansFull(
+  parameter: Record<string, unknown>,
+  columns: number | undefined,
+): boolean {
+  if ((columns ?? 1) < 2) return true;
+  if (parameter.span === "full") return true;
+  return FULL_WIDTH_PARAM_TYPES.has(String(parameter.type ?? ""));
 }
 
 import type { Snippet } from "svelte";
@@ -56,9 +86,11 @@ export interface LayoutComponentProps {
 /** The registry. Order is the order shown to operators in the
  *  AddPlacementPanel select; the first entry is the default. */
 const REGISTRY: Record<LayoutKey, Component<LayoutComponentProps>> = {
-  "stacked-default": LayoutStackedDefault as unknown as Component<LayoutComponentProps>,
+  "stacked-default":
+    LayoutStackedDefault as unknown as Component<LayoutComponentProps>,
   "inline-row": LayoutInlineRow as unknown as Component<LayoutComponentProps>,
-  "compact-mobile": LayoutCompactMobile as unknown as Component<LayoutComponentProps>,
+  "compact-mobile":
+    LayoutCompactMobile as unknown as Component<LayoutComponentProps>,
 };
 
 const DEFAULT_KEY: LayoutKey = "stacked-default";
@@ -79,4 +111,6 @@ export function resolveLayout(key: unknown): LayoutEntry {
 }
 
 /** All known keys, in registry order. Useful for picker UIs. */
-export const LAYOUT_KEYS: readonly LayoutKey[] = Object.keys(REGISTRY) as LayoutKey[];
+export const LAYOUT_KEYS: readonly LayoutKey[] = Object.keys(
+  REGISTRY,
+) as LayoutKey[];

package/components/action-form-visibility.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Client-side `visible_when` evaluation for action-form sections (#634 S4).
+ *
+ * The action's server-compiled contract round-trips an OPTIONAL
+ * `visible_when` predicate per section (the platform's Foundry-framed
+ * ActionPrecondition shape — conditions are data, one vocabulary). The
+ * server owns ENFORCEMENT (submission gates); this module owns the pure
+ * PRESENTATION concern: live show/hide of a section as the operator types.
+ *
+ * The operator set is a deliberate SUBSET of the server evaluator
+ * (`validation.py::_evaluate_operator`) — the comparisons a form value bag
+ * can answer locally. Two deliberate divergences, both UI-safe:
+ *
+ * - Blank form values (`""`, null, undefined) are treated as ABSENT for
+ *   `is_null` / `not_null` — an untouched text input means "no value yet",
+ *   so `{field: X, operator: not_null}` reads "shown once X has a value"
+ *   (the spec's canonical example).
+ * - An operator this subset doesn't know evaluates to VISIBLE (fail-open).
+ *   Hiding inputs on an unknown operator would make fields unreachable;
+ *   the server's gates still enforce whatever the condition meant.
+ */
+export interface VisibleWhenCondition {
+    field?: string;
+    operator?: string;
+    value?: unknown;
+    [key: string]: unknown;
+}
+/** Blank = the form has no value for the field yet. `false` and `0` are
+ *  real values; only null / undefined / empty-string count as blank. */
+export declare function isBlankFormValue(value: unknown): boolean;
+/**
+ * Evaluate one `visible_when` condition against the live form value bag.
+ * Returns whether the section should be VISIBLE.
+ */
+export declare function evaluateVisibleWhen(condition: VisibleWhenCondition | null | undefined, values: Record<string, unknown>): boolean;
+/** A section shape carrying an optional predicate. Reads BOTH spellings so
+ *  hosts can pass either the renderer's mapped sections (`visibleWhen`) or
+ *  raw contract sections (`visible_when`) without an adapter. `unknown` on
+ *  purpose: hosts carry their own concrete precondition types; the evaluator
+ *  reads the predicate defensively. */
+export interface ConditionalSection {
+    visibleWhen?: unknown;
+    visible_when?: unknown;
+}
+/** Whether a section is visible given the live value bag. Sections with no
+ *  predicate are always visible. Accepts any object shape (fold sections
+ *  carry no predicate at all) — the predicate is read defensively. */
+export declare function sectionVisible(section: object | null | undefined, values: Record<string, unknown>): boolean;

package/components/action-form-visibility.ts

@@ -0,0 +1,171 @@
+/**
+ * Client-side `visible_when` evaluation for action-form sections (#634 S4).
+ *
+ * The action's server-compiled contract round-trips an OPTIONAL
+ * `visible_when` predicate per section (the platform's Foundry-framed
+ * ActionPrecondition shape — conditions are data, one vocabulary). The
+ * server owns ENFORCEMENT (submission gates); this module owns the pure
+ * PRESENTATION concern: live show/hide of a section as the operator types.
+ *
+ * The operator set is a deliberate SUBSET of the server evaluator
+ * (`validation.py::_evaluate_operator`) — the comparisons a form value bag
+ * can answer locally. Two deliberate divergences, both UI-safe:
+ *
+ * - Blank form values (`""`, null, undefined) are treated as ABSENT for
+ *   `is_null` / `not_null` — an untouched text input means "no value yet",
+ *   so `{field: X, operator: not_null}` reads "shown once X has a value"
+ *   (the spec's canonical example).
+ * - An operator this subset doesn't know evaluates to VISIBLE (fail-open).
+ *   Hiding inputs on an unknown operator would make fields unreachable;
+ *   the server's gates still enforce whatever the condition meant.
+ */
+
+export interface VisibleWhenCondition {
+  field?: string;
+  operator?: string;
+  value?: unknown;
+  [key: string]: unknown;
+}
+
+/** Blank = the form has no value for the field yet. `false` and `0` are
+ *  real values; only null / undefined / empty-string count as blank. */
+export function isBlankFormValue(value: unknown): boolean {
+  return value === undefined || value === null || value === "";
+}
+
+function asComparableNumber(value: unknown): number | null {
+  if (typeof value === "number") return Number.isFinite(value) ? value : null;
+  if (typeof value === "string" && value.trim() !== "") {
+    const parsed = Number(value);
+    return Number.isFinite(parsed) ? parsed : null;
+  }
+  return null;
+}
+
+function numericCompare(
+  operator: "gt" | "lt" | "gte" | "lte",
+  actual: unknown,
+  expected: unknown,
+): boolean {
+  // Mirrors the server: a missing actual is VACUOUSLY satisfied for the
+  // ordering operators (the gate that owns refusal runs server-side).
+  if (isBlankFormValue(actual)) return true;
+  const left = asComparableNumber(actual);
+  const right = asComparableNumber(expected);
+  if (left === null || right === null) {
+    // Fall back to string comparison only when both sides are strings
+    // (e.g. ISO dates order lexicographically); otherwise fail open.
+    if (typeof actual === "string" && typeof expected === "string") {
+      if (operator === "gt") return actual > expected;
+      if (operator === "lt") return actual < expected;
+      if (operator === "gte") return actual >= expected;
+      return actual <= expected;
+    }
+    return true;
+  }
+  if (operator === "gt") return left > right;
+  if (operator === "lt") return left < right;
+  if (operator === "gte") return left >= right;
+  return left <= right;
+}
+
+function looseEquals(actual: unknown, expected: unknown): boolean {
+  if (actual === expected) return true;
+  // Form controls carry strings; sheets author typed literals. "3" == 3 and
+  // "true" == true are the same answer from the operator's point of view.
+  if (typeof expected === "boolean") return String(actual) === String(expected);
+  const leftNumber = asComparableNumber(actual);
+  const rightNumber = asComparableNumber(expected);
+  if (leftNumber !== null && rightNumber !== null)
+    return leftNumber === rightNumber;
+  return String(actual ?? "") === String(expected ?? "");
+}
+
+function stringMatch(
+  mode: "contains" | "starts" | "ends",
+  actual: unknown,
+  expected: unknown,
+): boolean {
+  if (isBlankFormValue(actual) || isBlankFormValue(expected)) return false;
+  const haystack = String(actual).toLowerCase();
+  const needle = String(expected).toLowerCase();
+  if (mode === "contains") return haystack.includes(needle);
+  if (mode === "starts") return haystack.startsWith(needle);
+  return haystack.endsWith(needle);
+}
+
+/**
+ * Evaluate one `visible_when` condition against the live form value bag.
+ * Returns whether the section should be VISIBLE.
+ */
+export function evaluateVisibleWhen(
+  condition: VisibleWhenCondition | null | undefined,
+  values: Record<string, unknown>,
+): boolean {
+  if (!condition || typeof condition !== "object") return true;
+  const field = typeof condition.field === "string" ? condition.field : "";
+  const operator =
+    typeof condition.operator === "string" ? condition.operator : "";
+  if (!field || !operator) return true;
+  const actual = values[field];
+  const expected = condition.value;
+
+  switch (operator) {
+    case "eq":
+      return looseEquals(actual, expected);
+    case "ne":
+      return !looseEquals(actual, expected);
+    case "gt":
+    case "lt":
+    case "gte":
+    case "lte":
+      return numericCompare(operator, actual, expected);
+    case "in":
+      return Array.isArray(expected)
+        ? expected.some((entry) => looseEquals(actual, entry))
+        : false;
+    case "not_in":
+      return Array.isArray(expected)
+        ? !expected.some((entry) => looseEquals(actual, entry))
+        : true;
+    case "is_null":
+      return isBlankFormValue(actual);
+    case "not_null":
+      return !isBlankFormValue(actual);
+    case "contains":
+      return stringMatch("contains", actual, expected);
+    case "starts_with":
+      return stringMatch("starts", actual, expected);
+    case "ends_with":
+      return stringMatch("ends", actual, expected);
+    default:
+      // Unknown operator → fail-open VISIBLE (see module doc).
+      return true;
+  }
+}
+
+/** A section shape carrying an optional predicate. Reads BOTH spellings so
+ *  hosts can pass either the renderer's mapped sections (`visibleWhen`) or
+ *  raw contract sections (`visible_when`) without an adapter. `unknown` on
+ *  purpose: hosts carry their own concrete precondition types; the evaluator
+ *  reads the predicate defensively. */
+export interface ConditionalSection {
+  visibleWhen?: unknown;
+  visible_when?: unknown;
+}
+
+/** Whether a section is visible given the live value bag. Sections with no
+ *  predicate are always visible. Accepts any object shape (fold sections
+ *  carry no predicate at all) — the predicate is read defensively. */
+export function sectionVisible(
+  section: object | null | undefined,
+  values: Record<string, unknown>,
+): boolean {
+  if (!section) return true;
+  const bag = section as ConditionalSection;
+  const predicate =
+    (bag.visibleWhen as VisibleWhenCondition | null | undefined) ??
+    (bag.visible_when as VisibleWhenCondition | null | undefined) ??
+    null;
+  return evaluateVisibleWhen(predicate, values);
+}

package/components/index.d.ts

@@ -106,3 +106,4 @@ export { default as GeoSearch } from "./GeoSearch.svelte";
 export { default as Calendar } from "./Calendar.svelte";
 export { default as ActionFormRenderer } from "./ActionFormRenderer.svelte";
 export { serializeValueSource, parseValueSource } from "./ValueSourcePicker.helpers.js";
+export { evaluateVisibleWhen, isBlankFormValue, sectionVisible } from "./action-form-visibility";

package/components/index.js

@@ -173,3 +173,11 @@ export { default as Calendar } from "./Calendar.svelte";
 
 // Action form renderer (placement-aware; admin preview + portal runtime, #73)
 export { default as ActionFormRenderer } from "./ActionFormRenderer.svelte";
+// #634 S4 — pure client-side `visible_when` evaluation (section show/hide).
+// Exported at the root so host step-models (wizard rails) share the exact
+// evaluator the renderer applies internally.
+export {
+  evaluateVisibleWhen,
+  isBlankFormValue,
+  sectionVisible,
+} from "./action-form-visibility";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aiaiai-pt/design-system",
-  "version": "0.44.1",
+  "version": "0.45.0",
   "description": "Design system tokens and Svelte components for aiaiai products",
   "license": "MIT",
   "type": "module",
@@ -31,6 +31,10 @@
       "svelte": "./components/index.js",
       "default": "./components/index.js"
     },
+    "./components/action-form-visibility": {
+      "types": "./components/action-form-visibility.d.ts",
+      "default": "./components/action-form-visibility.ts"
+    },
     "./components/*.svelte": {
       "types": "./components/*.svelte.d.ts",
       "svelte": "./components/*.svelte",