@aiaiai-pt/design-system 0.44.1 → 0.46.0

package/components/MultiSelectCombobox.svelte

@@ -0,0 +1,140 @@
+<!--
+  @component MultiSelectCombobox
+
+  Multi-value picking: removable Tag chips over a search-to-add Combobox
+  (the Carbon MultiSelect / Polaris tag-combobox pattern). Presentation-only:
+  the parent owns the selection list AND the async item source — the widget
+  never holds the selection in its input (a single-pick replace of a
+  multi-value field is impossible by construction).
+
+  @example
+  <MultiSelectCombobox
+    label="INSPECTORS"
+    items={searchResults}
+    selected={[{ value: 'u-1', label: 'Ana Silva' }]}
+    onsearch={(q) => search(q)}
+    onadd={(value) => add(value)}
+    onremove={(value) => remove(value)}
+  />
+-->
+<script module>
+  let _mscUid = 0;
+</script>
+
+<script>
+  /**
+   * @typedef {{ value: string, label: string, group?: string, description?: string }} ComboboxItem
+   */
+
+  import Combobox from './Combobox.svelte';
+  import Tag from './Tag.svelte';
+
+  let {
+    /** @type {ComboboxItem[]} — the search-result pool (parent-owned; async via onsearch) */
+    items = [],
+    /** @type {ComboboxItem[]} — the current selection, WITH display labels */
+    selected = [],
+    /** @type {string | undefined} */
+    label = undefined,
+    /** @type {string | undefined} */
+    placeholder = 'Search...',
+    /** @type {boolean} */
+    disabled = false,
+    /** @type {boolean} */
+    loading = false,
+    /** @type {string | undefined} */
+    error = undefined,
+    /** @type {string | undefined} */
+    help = undefined,
+    /** @type {boolean} */
+    required = false,
+    /** @type {string} */
+    size = 'md',
+    /** @type {((value: string) => void) | undefined} — a NEW value was picked */
+    onadd = undefined,
+    /** @type {((value: string) => void) | undefined} — a chip was removed */
+    onremove = undefined,
+    /** @type {((query: string) => void) | undefined} — async search; parent owns items */
+    onsearch = undefined,
+    /** @type {string} */
+    class: className = '',
+    ...rest
+  } = $props();
+
+  const mscId = `msc-${_mscUid++}`;
+
+  // The draft is WIDGET-internal: it exists only to drive the Combobox and is
+  // cleared after every pick, so the input never displays a "selection".
+  let draft = $state('');
+
+  // An already-picked value never re-offers (no double-add by construction).
+  const available = $derived(
+    items.filter((item) => !selected.some((entry) => entry.value === item.value)),
+  );
+
+  /** @param {string} value */
+  function handlePick(value) {
+    if (value && !selected.some((entry) => entry.value === value)) {
+      onadd?.(value);
+    }
+    draft = '';
+  }
+</script>
+
+<div
+  class="msc {className}"
+  role="group"
+  aria-labelledby={label ? `${mscId}-label` : undefined}
+  {...rest}
+>
+  {#if label}
+    <span id={`${mscId}-label`} class="msc-label"
+      >{label}{required ? ' (required)' : ''}</span
+    >
+  {/if}
+
+  {#if selected.length}
+    <div class="msc-chips">
+      {#each selected as entry (entry.value)}
+        <Tag removable={!disabled} onremove={() => onremove?.(entry.value)}>
+          {entry.label}
+        </Tag>
+      {/each}
+    </div>
+  {/if}
+
+  <Combobox
+    items={available}
+    bind:value={draft}
+    {placeholder}
+    {disabled}
+    {loading}
+    {error}
+    {help}
+    {size}
+    onsearch={onsearch}
+    onchange={handlePick}
+  />
+</div>
+
+<style>
+  .msc {
+    display: flex;
+    flex-direction: column;
+    gap: var(--space-xs);
+    width: 100%;
+  }
+
+  .msc-label {
+    font-family: var(--input-label-font);
+    font-size: var(--input-label-size);
+    letter-spacing: var(--input-label-tracking);
+    color: var(--input-label-color);
+  }
+
+  .msc-chips {
+    display: flex;
+    flex-wrap: wrap;
+    gap: var(--space-xs);
+  }
+</style>

package/components/MultiSelectCombobox.svelte.d.ts

@@ -0,0 +1,62 @@
+export default MultiSelectCombobox;
+export type ComboboxItem = {
+    value: string;
+    label: string;
+    group?: string;
+    description?: string;
+};
+type MultiSelectCombobox = {
+    $on?(type: string, callback: (e: any) => void): () => void;
+    $set?(props: Partial<$$ComponentProps>): void;
+};
+/**
+ * MultiSelectCombobox
+ *
+ * Multi-value picking: removable Tag chips over a search-to-add Combobox
+ * (the Carbon MultiSelect / Polaris tag-combobox pattern). Presentation-only:
+ * the parent owns the selection list AND the async item source — the widget
+ * never holds the selection in its input (a single-pick replace of a
+ * multi-value field is impossible by construction).
+ *
+ * @example
+ * <MultiSelectCombobox
+ *   label="INSPECTORS"
+ *   items={searchResults}
+ *   selected={[{ value: 'u-1', label: 'Ana Silva' }]}
+ *   onsearch={(q) => search(q)}
+ *   onadd={(value) => add(value)}
+ *   onremove={(value) => remove(value)}
+ * />
+ */
+declare const MultiSelectCombobox: import("svelte").Component<{
+    items?: any[];
+    selected?: any[];
+    label?: any;
+    placeholder?: string;
+    disabled?: boolean;
+    loading?: boolean;
+    error?: any;
+    help?: any;
+    required?: boolean;
+    size?: string;
+    onadd?: any;
+    onremove?: any;
+    onsearch?: any;
+    class?: string;
+} & Record<string, any>, {}, "">;
+type $$ComponentProps = {
+    items?: any[];
+    selected?: any[];
+    label?: any;
+    placeholder?: string;
+    disabled?: boolean;
+    loading?: boolean;
+    error?: any;
+    help?: any;
+    required?: boolean;
+    size?: string;
+    onadd?: any;
+    onremove?: any;
+    onsearch?: any;
+    class?: string;
+} & Record<string, any>;

package/components/Tag.svelte

@@ -33,7 +33,11 @@
     {@render children()}
   {/if}
   {#if removable}
+    <!-- type="button": inside a <form> (e.g. ActionFormRenderer m2m chips) a
+         typeless button is a SUBMIT button — removing a chip must never
+         submit the form. -->
     <button
+      type="button"
       class="tag-remove"
       aria-label="Remove tag"
       onclick={(e) => {

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

@@ -34,7 +34,27 @@ 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 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 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,39 @@ 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;
+}
+
+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 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>,
+  columns: number | undefined,
+): boolean {
+  if ((columns ?? 1) < 2) return true;
+  if (parameter.span === "full") return true;
+  return FULL_WIDTH_WIDGET_KINDS.has(widgetKind(parameter));
 }
 
 import type { Snippet } from "svelte";
@@ -56,9 +89,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 +114,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-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;
+}