@aiaiai-pt/design-system 0.45.0 → 0.46.0

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

@@ -52,17 +52,20 @@ export interface LayoutSection {
   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"]);
+import {
+  FULL_WIDTH_WIDGET_KINDS,
+  widgetKind,
+} from "./action-form-renderer-widgets";
 
 /**
  * #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.
+ * wide WIDGET KINDS (map canvas, upload list, textarea, json editor —
+ * resolved widget-first per #36, so both the field summary's `widget` and
+ * a bare legacy `type` clamp) go 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.
+ * Mirrors the CRUD form-surface compilers' FULL_WIDTH_WIDGETS clamp.
  */
 export function fieldSpansFull(
   parameter: Record<string, unknown>,
@@ -70,7 +73,7 @@ export function fieldSpansFull(
 ): boolean {
   if ((columns ?? 1) < 2) return true;
   if (parameter.span === "full") return true;
-  return FULL_WIDTH_PARAM_TYPES.has(String(parameter.type ?? ""));
+  return FULL_WIDTH_WIDGET_KINDS.has(widgetKind(parameter));
 }
 
 import type { Snippet } from "svelte";

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

@@ -15,6 +15,18 @@
  * Svelte component owns the reactive plumbing; this module owns the shape.
  */
 export type RendererMode = "admin-preview" | "admin-execute" | "public-submit" | "adapter-preview";
+/** #41 (atelier#669 V1, operator decision D3) — readonly across the two param
+ *  shapes: the form-surface.v1 summary says `visibility: "readonly"` (a
+ *  STRING); the action lane says `visibility: {editable: false}` (an object,
+ *  mirrored onto `editable` by the schema builders). */
+export declare function isReadonlyParam(parameter: Record<string, unknown>): boolean;
+/** #41 / D3 — whether a param's value belongs in `form.raw_values`:
+ *  an explicit `payload: "include" | "exclude"` always wins; the
+ *  form-surface.v1 lane (string visibility) defaults readonly OUT of the
+ *  wire; the LEGACY action lane (object visibility, no payload key) keeps
+ *  its #252 ride-the-payload behavior — flipping it would silently drop
+ *  citizen identity prefills from deployed intake forms. */
+export declare function isPayloadIncluded(parameter: Record<string, unknown>): boolean;
 /**
  * Minimal action/placement references the payload builder reads. Callers may
  * pass a full ontology Entity; this narrower shape is what we actually rely

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

@@ -14,7 +14,38 @@
  * source_schema, raw_values, mode), returns the canonical payload. The
  * Svelte component owns the reactive plumbing; this module owns the shape.
  */
-export type RendererMode = "admin-preview" | "admin-execute" | "public-submit" | "adapter-preview";
+export type RendererMode =
+  "admin-preview" | "admin-execute" | "public-submit" | "adapter-preview";
+
+/** #41 (atelier#669 V1, operator decision D3) — readonly across the two param
+ *  shapes: the form-surface.v1 summary says `visibility: "readonly"` (a
+ *  STRING); the action lane says `visibility: {editable: false}` (an object,
+ *  mirrored onto `editable` by the schema builders). */
+export function isReadonlyParam(parameter: Record<string, unknown>): boolean {
+  if (parameter.editable === false) return true;
+  const visibility = parameter.visibility;
+  if (typeof visibility === "string") return visibility === "readonly";
+  if (
+    visibility &&
+    typeof visibility === "object" &&
+    !Array.isArray(visibility)
+  ) {
+    return (visibility as Record<string, unknown>).editable === false;
+  }
+  return false;
+}
+
+/** #41 / D3 — whether a param's value belongs in `form.raw_values`:
+ *  an explicit `payload: "include" | "exclude"` always wins; the
+ *  form-surface.v1 lane (string visibility) defaults readonly OUT of the
+ *  wire; the LEGACY action lane (object visibility, no payload key) keeps
+ *  its #252 ride-the-payload behavior — flipping it would silently drop
+ *  citizen identity prefills from deployed intake forms. */
+export function isPayloadIncluded(parameter: Record<string, unknown>): boolean {
+  if (parameter.payload === "include") return true;
+  if (parameter.payload === "exclude") return false;
+  return parameter.visibility !== "readonly";
+}
 
 /**
  * Minimal action/placement references the payload builder reads. Callers may
@@ -106,7 +137,9 @@ function defaultSurfaceFor(mode: RendererMode): string {
   return mode === "public-submit" ? "public_submit" : "admin_preview";
 }
 
-function pickScope(targetConfig: Record<string, unknown>): Record<string, unknown> {
+function pickScope(
+  targetConfig: Record<string, unknown>,
+): Record<string, unknown> {
   const scope: Record<string, unknown> = {};
   for (const [key, value] of Object.entries(targetConfig)) {
     if (RESERVED_TARGET_KEYS.has(key)) continue;
@@ -116,7 +149,17 @@ function pickScope(targetConfig: Record<string, unknown>): Record<string, unknow
 }
 
 export function buildActionPayload(args: BuildArgs): ActionPayload {
-  const { action, placement, targetConfig, sourceSchema, rawValues, schemaVersion, mode, attachmentKeys, attachmentsByParam } = args;
+  const {
+    action,
+    placement,
+    targetConfig,
+    sourceSchema,
+    rawValues,
+    schemaVersion,
+    mode,
+    attachmentKeys,
+    attachmentsByParam,
+  } = args;
 
   const sourceFromSchema = nullableString(sourceSchema.source);
   const targetModel =

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

@@ -0,0 +1,20 @@
+export type RelationshipMeta = {
+    relCode?: string;
+    targetTypeCode: string;
+    cardinality?: string;
+};
+type Entity = Record<string, unknown>;
+/** The relationship meta, from the field summary's `relationship` or the
+ *  derived-action param's `ui_schema.relationship`. Null for non-rel params. */
+export declare function relationshipMeta(parameter: Entity): RelationshipMeta | null;
+/** True for both rel lanes: the form-surface `relationship` summary and the
+ *  action-lane `object_reference` param. */
+export declare function isRelationshipParam(parameter: Entity): boolean;
+/** Multi-value (chips) when the param says `multiple: true` (derived-action
+ *  lane) or the relationship meta says many_to_many (form-surface lane). */
+export declare function isMultiRelationship(parameter: Entity): boolean;
+/** The entity type code the picker searches/hydrates against. */
+export declare function relationshipTypeCode(parameter: Entity): string;
+/** Normalize a rel value-bag entry onto the ID-list wire shape. */
+export declare function normalizeRelIds(value: unknown): string[];
+export {};

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

@@ -0,0 +1,77 @@
+// #34 (atelier#669 V1, operator decision D6) — cardinality-aware relationship
+// helpers for ActionFormRenderer. Pure functions over the two param shapes the
+// renderer meets:
+//   form-surface.v1 field summary — `type: "relationship"` with a top-level
+//     `relationship: {relCode, targetTypeCode, cardinality}`;
+//   derived-action param — `type: "object_reference"` with `object_type`,
+//     `multiple: true` for many_to_many, and the same relationship meta under
+//     `ui_schema.relationship` (see atelier derived_crud._member_to_param).
+
+export type RelationshipMeta = {
+  relCode?: string;
+  targetTypeCode: string;
+  cardinality?: string;
+};
+
+type Entity = Record<string, unknown>;
+
+function asRecord(value: unknown): Record<string, unknown> | null {
+  return value && typeof value === "object" && !Array.isArray(value)
+    ? (value as Record<string, unknown>)
+    : null;
+}
+
+/** The relationship meta, from the field summary's `relationship` or the
+ *  derived-action param's `ui_schema.relationship`. Null for non-rel params. */
+export function relationshipMeta(parameter: Entity): RelationshipMeta | null {
+  const carrier =
+    asRecord(parameter.relationship) ??
+    asRecord(asRecord(parameter.ui_schema)?.relationship);
+  if (!carrier) return null;
+  const targetTypeCode = String(
+    carrier.targetTypeCode ?? carrier.target_type_code ?? "",
+  );
+  if (!targetTypeCode) return null;
+  const relCode = carrier.relCode ?? carrier.rel_code;
+  const cardinality = carrier.cardinality;
+  return {
+    relCode: relCode ? String(relCode) : undefined,
+    targetTypeCode,
+    cardinality: cardinality ? String(cardinality) : undefined,
+  };
+}
+
+/** True for both rel lanes: the form-surface `relationship` summary and the
+ *  action-lane `object_reference` param. */
+export function isRelationshipParam(parameter: Entity): boolean {
+  const type = String(parameter.type ?? "");
+  return (
+    type === "relationship" ||
+    type === "object_reference" ||
+    relationshipMeta(parameter) !== null
+  );
+}
+
+/** Multi-value (chips) when the param says `multiple: true` (derived-action
+ *  lane) or the relationship meta says many_to_many (form-surface lane). */
+export function isMultiRelationship(parameter: Entity): boolean {
+  if (parameter.multiple === true) return true;
+  return relationshipMeta(parameter)?.cardinality === "many_to_many";
+}
+
+/** The entity type code the picker searches/hydrates against. */
+export function relationshipTypeCode(parameter: Entity): string {
+  return (
+    relationshipMeta(parameter)?.targetTypeCode ??
+    String(parameter.object_type ?? "")
+  );
+}
+
+/** Normalize a rel value-bag entry onto the ID-list wire shape. */
+export function normalizeRelIds(value: unknown): string[] {
+  if (Array.isArray(value)) {
+    return value.map((entry) => String(entry ?? "")).filter(Boolean);
+  }
+  if (typeof value === "string" && value) return [value];
+  return [];
+}

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

@@ -0,0 +1,39 @@
+type Entity = Record<string, unknown>;
+/** The render intent for a param: `widget` → `ui_schema.widget` → `type`. */
+export declare function widgetKind(parameter: Entity): string;
+/** Widget kinds that can never sit half-width in a two-column section —
+ *  they carry their own wide UI. Mirrors the CRUD form-surface compilers'
+ *  FULL_WIDTH_WIDGETS clamp (form-surface.ts / derived_crud.py). */
+export declare const FULL_WIDTH_WIDGET_KINDS: Set<string>;
+/** #37 — parse the platform's date-only wire shape (YYYY-MM-DD) onto a LOCAL
+ *  calendar date. Never routes through Date.parse/toISOString: a local
+ *  midnight serialized via UTC shifts a day across DST/negative-offset
+ *  timezones — the classic off-by-one. */
+export declare function dateOnlyToDate(value: unknown): Date | null;
+/** #37 — serialize a picked Date back onto YYYY-MM-DD from its LOCAL
+ *  calendar parts (no time component, no timezone shift). */
+export declare function dateToDateOnly(date: Date): string;
+export type GeoJsonPoint = {
+    type: "Point";
+    coordinates: [number, number];
+};
+/** #39 — hydrate the contract's GeoJSON value onto the MapPicker's
+ *  [lon, lat] prop edge. Empty → no pin, no error. A non-Point (or
+ *  malformed Point) fails LOUD: null coords + a named error the field
+ *  renders — never a silently-empty map over real data. */
+export declare function geoJsonPointToLonLat(value: unknown): {
+    coords: [number, number] | null;
+    error: string | null;
+};
+/** #39 — serialize a placed pin back onto the GeoJSON wire shape. */
+export declare function lonLatToGeoJsonPoint(coords: [number, number]): GeoJsonPoint;
+export type StoredFile = {
+    name: string;
+    url?: string;
+};
+/** #40 — normalize a file param's stored-current value (the edit form's
+ *  prefill) onto {name, url?}. Accepts a bare name, a URL string (name =
+ *  last path segment), or a {name?, url?} descriptor. Anything else → null
+ *  (no stored file → the legacy append-mode upload field). */
+export declare function storedFileDescriptor(value: unknown): StoredFile | null;
+export {};

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

@@ -0,0 +1,127 @@
+// #36/#37 (atelier#669 V1) — widget-first dispatch vocabulary + date-only
+// serialization for ActionFormRenderer. Pure functions.
+//
+// The form-surface.v1 field summary carries render intent in `widget`
+// (derived from the field type + legal refinements, both compilers);
+// derived-action params carry the same under `ui_schema.widget`. The
+// renderer dispatches on this kind and falls back to the param `type`, so
+// legacy action-lane params (no widget key) render byte-identically.
+
+type Entity = Record<string, unknown>;
+
+/** The render intent for a param: `widget` → `ui_schema.widget` → `type`. */
+export function widgetKind(parameter: Entity): string {
+  const direct = parameter.widget;
+  if (typeof direct === "string" && direct) return direct;
+  const uiSchema = parameter.ui_schema;
+  if (uiSchema && typeof uiSchema === "object" && !Array.isArray(uiSchema)) {
+    const widget = (uiSchema as Entity).widget;
+    if (typeof widget === "string" && widget) return widget;
+  }
+  return String(parameter.type ?? "string");
+}
+
+/** Widget kinds that can never sit half-width in a two-column section —
+ *  they carry their own wide UI. Mirrors the CRUD form-surface compilers'
+ *  FULL_WIDTH_WIDGETS clamp (form-surface.ts / derived_crud.py). */
+export const FULL_WIDTH_WIDGET_KINDS = new Set([
+  "geo",
+  "file",
+  "json",
+  "textarea",
+  "geometry",
+]);
+
+/** #37 — parse the platform's date-only wire shape (YYYY-MM-DD) onto a LOCAL
+ *  calendar date. Never routes through Date.parse/toISOString: a local
+ *  midnight serialized via UTC shifts a day across DST/negative-offset
+ *  timezones — the classic off-by-one. */
+export function dateOnlyToDate(value: unknown): Date | null {
+  if (typeof value !== "string") return null;
+  const match = /^(\d{4})-(\d{2})-(\d{2})$/.exec(value.trim());
+  if (!match) return null;
+  const [, year, month, day] = match;
+  const date = new Date(Number(year), Number(month) - 1, Number(day));
+  return Number.isNaN(date.getTime()) ? null : date;
+}
+
+/** #37 — serialize a picked Date back onto YYYY-MM-DD from its LOCAL
+ *  calendar parts (no time component, no timezone shift). */
+export function dateToDateOnly(date: Date): string {
+  const year = String(date.getFullYear()).padStart(4, "0");
+  const month = String(date.getMonth() + 1).padStart(2, "0");
+  const day = String(date.getDate()).padStart(2, "0");
+  return `${year}-${month}-${day}`;
+}
+
+export type GeoJsonPoint = { type: "Point"; coordinates: [number, number] };
+
+/** #39 — hydrate the contract's GeoJSON value onto the MapPicker's
+ *  [lon, lat] prop edge. Empty → no pin, no error. A non-Point (or
+ *  malformed Point) fails LOUD: null coords + a named error the field
+ *  renders — never a silently-empty map over real data. */
+export function geoJsonPointToLonLat(value: unknown): {
+  coords: [number, number] | null;
+  error: string | null;
+} {
+  if (value === null || value === undefined || value === "") {
+    return { coords: null, error: null };
+  }
+  if (value && typeof value === "object" && !Array.isArray(value)) {
+    const row = value as Record<string, unknown>;
+    if (row.type === "Point" && Array.isArray(row.coordinates)) {
+      const [lon, lat] = row.coordinates as unknown[];
+      if (typeof lon === "number" && typeof lat === "number") {
+        return { coords: [lon, lat], error: null };
+      }
+      return {
+        coords: null,
+        error: "Unsupported geometry: malformed Point coordinates",
+      };
+    }
+    return {
+      coords: null,
+      error: `Unsupported geometry: expected a GeoJSON Point, got ${String(row.type ?? "unknown")}`,
+    };
+  }
+  return {
+    coords: null,
+    error: "Unsupported geometry: expected a GeoJSON Point",
+  };
+}
+
+/** #39 — serialize a placed pin back onto the GeoJSON wire shape. */
+export function lonLatToGeoJsonPoint(coords: [number, number]): GeoJsonPoint {
+  return { type: "Point", coordinates: [coords[0], coords[1]] };
+}
+
+export type StoredFile = { name: string; url?: string };
+
+/** #40 — normalize a file param's stored-current value (the edit form's
+ *  prefill) onto {name, url?}. Accepts a bare name, a URL string (name =
+ *  last path segment), or a {name?, url?} descriptor. Anything else → null
+ *  (no stored file → the legacy append-mode upload field). */
+export function storedFileDescriptor(value: unknown): StoredFile | null {
+  if (typeof value === "string") {
+    const trimmed = value.trim();
+    if (!trimmed) return null;
+    if (/^https?:\/\//i.test(trimmed)) {
+      const segments = trimmed.split("?")[0].split("/").filter(Boolean);
+      return { name: segments[segments.length - 1] || trimmed, url: trimmed };
+    }
+    return { name: trimmed };
+  }
+  if (value && typeof value === "object" && !Array.isArray(value)) {
+    const row = value as Record<string, unknown>;
+    const url = typeof row.url === "string" && row.url ? row.url : undefined;
+    const name =
+      typeof row.name === "string" && row.name
+        ? row.name
+        : url
+          ? (url.split("?")[0].split("/").filter(Boolean).pop() ?? url)
+          : null;
+    if (!name) return null;
+    return url ? { name, url } : { name };
+  }
+  return null;
+}

package/components/index.d.ts

@@ -12,6 +12,9 @@ export { default as Checkbox } from "./Checkbox.svelte";
 export { default as Label } from "./Label.svelte";
 export { default as FileUpload } from "./FileUpload.svelte";
 export { default as FileUploadItem } from "./FileUploadItem.svelte";
+export { default as MultiSelectCombobox } from "./MultiSelectCombobox.svelte";
+export { default as MoneyInput } from "./MoneyInput.svelte";
+export { default as JsonEditor } from "./JsonEditor.svelte";
 export { default as Separator } from "./Separator.svelte";
 export { default as Progress } from "./Progress.svelte";
 export { default as List } from "./List.svelte";

package/components/index.js

@@ -25,6 +25,9 @@ export { default as Checkbox } from "./Checkbox.svelte";
 export { default as Label } from "./Label.svelte";
 export { default as FileUpload } from "./FileUpload.svelte";
 export { default as FileUploadItem } from "./FileUploadItem.svelte";
+export { default as MultiSelectCombobox } from "./MultiSelectCombobox.svelte";
+export { default as MoneyInput } from "./MoneyInput.svelte";
+export { default as JsonEditor } from "./JsonEditor.svelte";
 
 // Layout
 export { default as Separator } from "./Separator.svelte";

package/components/json-editor-contract.d.ts

@@ -0,0 +1,11 @@
+export type JsonDraftResult = {
+    ok: true;
+    value: unknown;
+} | {
+    ok: false;
+    error: string;
+};
+/** Pretty-print a value into the editor. Null/undefined → empty editor. */
+export declare function formatJsonValue(value: unknown): string;
+/** Evaluate the operator's raw text. */
+export declare function evaluateJsonDraft(text: string): JsonDraftResult;

package/components/json-editor-contract.ts

@@ -0,0 +1,33 @@
+// #38 (atelier#669 V1) — the JsonEditor's parse/emit contract, pure.
+// Invalid text NEVER silently drops or half-parses: evaluation either
+// yields `{ok: true, value}` (emit) or `{ok: false, error}` (surface the
+// parse error, block submit via the renderer's error seam, emit NOTHING).
+// Empty and `{}` are distinct: empty text is `{ok: true, value: null}`.
+
+export type JsonDraftResult =
+  { ok: true; value: unknown } | { ok: false; error: string };
+
+/** Pretty-print a value into the editor. Null/undefined → empty editor. */
+export function formatJsonValue(value: unknown): string {
+  if (value === null || value === undefined) return "";
+  try {
+    return JSON.stringify(value, null, 2) ?? "";
+  } catch {
+    // Circular or non-serializable host value — start the editor empty
+    // rather than exploding the form.
+    return "";
+  }
+}
+
+/** Evaluate the operator's raw text. */
+export function evaluateJsonDraft(text: string): JsonDraftResult {
+  const trimmed = text.trim();
+  if (!trimmed) return { ok: true, value: null };
+  try {
+    return { ok: true, value: JSON.parse(trimmed) };
+  } catch (parseError) {
+    const detail =
+      parseError instanceof Error ? parseError.message : String(parseError);
+    return { ok: false, error: `Invalid JSON: ${detail}` };
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aiaiai-pt/design-system",
-  "version": "0.45.0",
+  "version": "0.46.0",
   "description": "Design system tokens and Svelte components for aiaiai products",
   "license": "MIT",
   "type": "module",
@@ -35,6 +35,18 @@
       "types": "./components/action-form-visibility.d.ts",
       "default": "./components/action-form-visibility.ts"
     },
+    "./components/action-form-renderer-relationships": {
+      "types": "./components/action-form-renderer-relationships.d.ts",
+      "default": "./components/action-form-renderer-relationships.ts"
+    },
+    "./components/action-form-renderer-widgets": {
+      "types": "./components/action-form-renderer-widgets.d.ts",
+      "default": "./components/action-form-renderer-widgets.ts"
+    },
+    "./components/json-editor-contract": {
+      "types": "./components/json-editor-contract.d.ts",
+      "default": "./components/json-editor-contract.ts"
+    },
     "./components/*.svelte": {
       "types": "./components/*.svelte.d.ts",
       "svelte": "./components/*.svelte",