@aiaiai-pt/design-system 0.43.0 → 0.44.1

package/components/ActionFormRenderer.svelte

@@ -5,6 +5,8 @@
   import Button from "./Button.svelte";
   import Alert from "./Alert.svelte";
   import CodeBlock from "./CodeBlock.svelte";
+  import Combobox from "./Combobox.svelte";
+  import DateTimePicker from "./DateTimePicker.svelte";
   import Input from "./Input.svelte";
   import MapPicker from "./MapPicker.svelte";
   import FileUpload from "./FileUpload.svelte";
@@ -69,6 +71,17 @@
      *  the attachment_keys payload contract; the CONSUMER owns transport/auth
      *  (FileUpload philosophy). Omitted → file params render disabled. */
     uploadFile?: (file: File) => Promise<{ key: string } | { error: string }>;
+    /** Lookup for `object_reference`-typed parameters (#629 PR1b): receives the
+     *  parameter's `object_type` (the entity type code), the operator's query,
+     *  and the parameter's optional `object_filter`; returns picker items. The
+     *  renderer owns the Combobox UI + value plumbing; the CONSUMER owns
+     *  transport/auth/tenancy (the uploadFile seam pattern — the DS stays
+     *  presentation-only). Omitted → object_reference params render disabled. */
+    searchEntities?: (
+      typeCode: string,
+      query: string,
+      filter?: Record<string, string>,
+    ) => Promise<SelectOption[]>;
     /** Environment-specific captcha (e.g. Turnstile), rendered above the button
      *  in submit modes. */
     captcha?: Snippet;
@@ -112,6 +125,7 @@
     schema = null,
     onApply = undefined,
     uploadFile = undefined,
+    searchEntities = undefined,
     captcha = undefined,
     submitLabel = "Submit",
     boundary = undefined,
@@ -264,14 +278,20 @@
   }
 
   function sectionName(parameter: Entity): string {
-    const visibility = parameter.visibility;
-    if (visibility && typeof visibility === "object" && !Array.isArray(visibility)) {
-      const section = (visibility as Record<string, unknown>).section;
-      if (section) return String(section);
-    }
+    // Mirrors the BFF `_parameter_section` precedence (action_schema.py):
+    // ui_schema.section_label → ui_schema.section → visibility.section_label
+    // → visibility.section → "Details". `||` (not `??`) to match Python `or`
+    // falsy-chaining — an empty string falls through to the next rung.
     const uiSchema = parameter.ui_schema;
     if (uiSchema && typeof uiSchema === "object" && !Array.isArray(uiSchema)) {
-      const section = (uiSchema as Record<string, unknown>).section;
+      const row = uiSchema as Record<string, unknown>;
+      const section = row.section_label || row.section;
+      if (section) return String(section);
+    }
+    const visibility = parameter.visibility;
+    if (visibility && typeof visibility === "object" && !Array.isArray(visibility)) {
+      const row = visibility as Record<string, unknown>;
+      const section = row.section_label || row.section;
       if (section) return String(section);
     }
     return "Details";
@@ -400,6 +420,54 @@
     }
   }
 
+  // `object_reference` picker state (#629 PR1b): per-parameter items + loading
+  // for the lazy-search Combobox. A per-key generation counter drops stale
+  // responses (the host's validateGen pattern) so a slow early query can't
+  // clobber a fast later one.
+  let referenceItems = $state<Record<string, SelectOption[]>>({});
+  let referenceLoading = $state<Record<string, boolean>>({});
+  const referenceSearchGen: Record<string, number> = {};
+
+  function objectFilter(parameter: Entity): Record<string, string> | undefined {
+    const filter = parameter.object_filter;
+    return filter && typeof filter === "object" && !Array.isArray(filter)
+      ? (filter as Record<string, string>)
+      : undefined;
+  }
+
+  async function handleReferenceSearch(parameter: Entity, query: string) {
+    if (!searchEntities) return;
+    const key = parameterKey(parameter);
+    const gen = (referenceSearchGen[key] = (referenceSearchGen[key] ?? 0) + 1);
+    referenceLoading = { ...referenceLoading, [key]: true };
+    try {
+      const items = await searchEntities(
+        String(parameter.object_type ?? ""),
+        query,
+        objectFilter(parameter),
+      );
+      if (referenceSearchGen[key] !== gen) return;
+      referenceItems = { ...referenceItems, [key]: Array.isArray(items) ? items : [] };
+    } catch {
+      if (referenceSearchGen[key] === gen) referenceItems = { ...referenceItems, [key]: [] };
+    } finally {
+      if (referenceSearchGen[key] === gen)
+        referenceLoading = { ...referenceLoading, [key]: false };
+    }
+  }
+
+  // `datetime` params keep an ISO 8601 STRING in the value bag (the platform's
+  // datetime wire vocabulary — `$now` resolves to one) so the payload stays
+  // plain JSON; the DateTimePicker speaks Date on its prop edge.
+  function datetimeValue(value: unknown): Date | null {
+    if (value instanceof Date) return value;
+    if (typeof value === "string" && value) {
+      const parsed = new Date(value);
+      if (!Number.isNaN(parsed.getTime())) return parsed;
+    }
+    return null;
+  }
+
   function removeFile(key: string, storageKey: string) {
     fileUploads = {
       ...fileUploads,
@@ -411,6 +479,16 @@
     return Object.values(fileUploads).flatMap((list) => list.map((f) => f.key));
   }
 
+  /** #629 follow-up — the same keys ATTRIBUTED to the param each was
+   *  uploaded against, so consumers never have to guess positionally. */
+  function attachmentsByParam(): Record<string, string[]> {
+    const out: Record<string, string[]> = {};
+    for (const [paramKey, list] of Object.entries(fileUploads)) {
+      if (list.length) out[paramKey] = list.map((f) => f.key);
+    }
+    return out;
+  }
+
   function buildPayload(): Record<string, unknown> {
     return buildActionPayload({
       action: renderedAction ?? null,
@@ -419,6 +497,7 @@
       sourceSchema: sourceSchema(),
       rawValues: visibleValueBag(),
       attachmentKeys: allAttachmentKeys(),
+      attachmentsByParam: attachmentsByParam(),
       schemaVersion: schema?.schema_version ?? null,
       mode,
     }) as unknown as Record<string, unknown>;
@@ -490,6 +569,33 @@
       onchange={(value: string) => setValue(key, value === "true")}
       aria-required={ariaRequired}
     />
+  {:else if type === "datetime"}
+    <!-- `datetime` parameter (#629 PR1b): the DS date+time picker. The value
+         bag carries an ISO 8601 string (see datetimeValue). `datetime` is the
+         platform's one wire token today (sheets + ActionParam docs). -->
+    <DateTimePicker
+      label={String(parameter.label ?? key)}
+      value={datetimeValue(values[key])}
+      readonly={!editable}
+      onchange={(date: Date) => setValue(key, date.toISOString())}
+    />
+  {:else if type === "object_reference"}
+    <!-- `object_reference` parameter (#629 PR1b): lazy-search Combobox over
+         the entity type named by `object_type`; `object_filter` rides the
+         injected searchEntities seam. No seam → disabled (the file-param
+         convention for a missing consumer transport). -->
+    <Combobox
+      label={String(parameter.label ?? key)}
+      items={referenceItems[key] ?? []}
+      value={String(values[key] ?? "")}
+      placeholder={typeof parameter.object_type === "string" && parameter.object_type
+        ? `Search ${parameter.object_type}...`
+        : "Search..."}
+      disabled={!searchEntities || !editable}
+      loading={referenceLoading[key] ?? false}
+      onsearch={(query: string) => handleReferenceSearch(parameter, query)}
+      onchange={(value: string) => setValue(key, value)}
+    />
   {:else if type === "file"}
     <!-- `file` parameter (#75 M5 slice 4b): upload-as-you-attach. The keys
          ride payload.attachment_keys; raw_values never sees this param. -->
@@ -567,8 +673,10 @@
       aria-required={ariaRequired}
     />
   {/if}
-  {#if mode === "public-submit"}
-    <!-- Citizen-facing: just a quiet required hint, no operator type debug. -->
+  {#if isSubmitMode}
+    <!-- EXECUTE surfaces (citizen public-submit AND staff admin-execute,
+         #629 follow-up): just a quiet required hint — the "Required / type"
+         line is operator DEBUG chrome, preview modes only. -->
     {#if parameter.required}<p class="field-meta">Required</p>{/if}
   {:else}
     <p class="field-meta">
@@ -580,8 +688,12 @@
 <div class="renderer" data-testid={`action-form-renderer-${mode}`} data-layout={resolvedLayout.key}>
   <!-- Wizard pagination (#105 P6): the ServiceFlow shell owns the step
        heading, so the renderer's own action-title header is suppressed when a
-       section is active to avoid a duplicate heading per step. -->
-  {#if activeSectionKey == null}
+       section is active to avoid a duplicate heading per step.
+       admin-execute (#629 follow-up): the HOST container (drawer/modal) owns
+       the action heading — the renderer's header would duplicate it, and the
+       "Placement preview" eyebrow + placement Badge are authoring chrome that
+       has no meaning on an execute surface. -->
+  {#if activeSectionKey == null && mode !== "admin-execute"}
     <div class="renderer-header">
       <div>
         <!-- The placement-preview eyebrow + surface badge are operator chrome —

package/components/ActionFormRenderer.svelte.d.ts

@@ -8,6 +8,10 @@ import { type RendererMode } from "./action-form-renderer-payload";
  * compatible.
  */
 type Entity = Record<string, unknown>;
+type SelectOption = {
+    value: string;
+    label: string;
+};
 type ActionSchema = {
     found?: boolean;
     schema_version?: string;
@@ -54,6 +58,13 @@ interface Props {
     } | {
         error: string;
     }>;
+    /** Lookup for `object_reference`-typed parameters (#629 PR1b): receives the
+     *  parameter's `object_type` (the entity type code), the operator's query,
+     *  and the parameter's optional `object_filter`; returns picker items. The
+     *  renderer owns the Combobox UI + value plumbing; the CONSUMER owns
+     *  transport/auth/tenancy (the uploadFile seam pattern — the DS stays
+     *  presentation-only). Omitted → object_reference params render disabled. */
+    searchEntities?: (typeCode: string, query: string, filter?: Record<string, string>) => Promise<SelectOption[]>;
     /** Environment-specific captcha (e.g. Turnstile), rendered above the button
      *  in submit modes. */
     captcha?: Snippet;

package/components/Panel.svelte

@@ -18,6 +18,11 @@
   <Panel open persistent side="left" title="History">
     Always-visible sidebar content
   </Panel>
+
+  @example Modeless drawer (fixed slide-over, page behind stays interactive)
+  <Panel open modeless title="Execute action" onclose={() => showAction = false}>
+    Action form here — focus moves to the heading, Escape closes while inside
+  </Panel>
 -->
 <script module>
   let _panelUid = 0;
@@ -40,6 +45,14 @@
     side = 'right',
     /** @type {boolean} When true, removes backdrop and focus trap. Panel becomes an inline layout element. */
     persistent = false,
+    /** @type {boolean} Modeless drawer (#629): stays a FIXED slide-over like the
+     * default mode, but with no backdrop, no aria-modal, and no focus trap —
+     * the page behind remains browsable/interactive. On open the panel is a
+     * labelled region and focus MOVES to its heading (announced, not trapped);
+     * Escape closes only while focus is inside the panel; focus returns to the
+     * previously-focused element on close (the host owns any deep-link
+     * fallback). Ignored when `persistent` is set. */
+    modeless = false,
     /** @type {boolean} When false, body doesn't scroll — children manage their own overflow. */
     scrollBody = true,
     /** @type {(() => void) | undefined} */
@@ -62,10 +75,17 @@
 
   const FOCUSABLE = 'button, [href], input, select, textarea, [tabindex]:not([tabindex="-1"])';
 
+  // Resolved mode: persistent wins over modeless (persistent consumers are
+  // inline layout elements — a fixed slide-over would be a breaking change).
+  const isPersistent = $derived(persistent);
+  const isModeless = $derived(modeless && !persistent);
+  const isDialog = $derived(!persistent && !modeless);
+
   // Focus trap: save previous focus, trap Tab, restore on close
-  // Skipped in persistent mode (panel is inline, not modal)
+  // Skipped in persistent and modeless modes (persistent is inline; modeless
+  // deliberately leaves the page behind reachable — focus moved, not trapped)
   $effect(() => {
-    if (!open || !panelEl || persistent) return;
+    if (!open || !panelEl || !isDialog) return;
 
     const previouslyFocused = /** @type {HTMLElement | null} */ (document.activeElement);
 
@@ -107,11 +127,41 @@
   function handleBackdropClick() {
     onclose?.();
   }
+
+  // Modeless drawer (#629): initial focus to the panel heading (announces the
+  // labelled region without trapping), Escape scoped to the PANEL element so
+  // it closes only while focus is inside, previous focus restored on close.
+  $effect(() => {
+    if (!open || !panelEl || !isModeless) return;
+
+    const previouslyFocused = /** @type {HTMLElement | null} */ (document.activeElement);
+
+    const heading = /** @type {HTMLElement | null} */ (
+      panelEl.querySelector('.panel-heading-focus')
+    );
+    heading?.focus();
+
+    /** @param {KeyboardEvent} e */
+    function handlePanelKeydown(e) {
+      if (e.key === 'Escape') onclose?.();
+    }
+
+    panelEl.addEventListener('keydown', handlePanelKeydown);
+
+    return () => {
+      panelEl?.removeEventListener('keydown', handlePanelKeydown);
+      // Deep-link entries have no meaningful previous focus (body) — the HOST
+      // owns that fallback (e.g. page H1); restoring a disconnected node is a
+      // no-op by contract.
+      if (previouslyFocused?.isConnected) previouslyFocused.focus();
+    };
+  });
 </script>
 
 {#if open}
-  <!-- Backdrop (hidden in persistent mode) -->
-  {#if !persistent}
+  <!-- Backdrop (dialog mode only — persistent is inline, modeless leaves the
+       page behind visible and interactive) -->
+  {#if isDialog}
     <div
       class="panel-backdrop"
       onclick={handleBackdropClick}
@@ -122,18 +172,25 @@
   <!-- Panel -->
   <aside
     bind:this={panelEl}
-    class="panel panel-{width} panel-side-{side} {persistent ? 'panel-persistent' : ''} {className}"
-    role={persistent ? 'complementary' : 'dialog'}
-    aria-modal={persistent ? undefined : 'true'}
+    class="panel panel-{width} panel-side-{side} {isPersistent ? 'panel-persistent' : ''} {className}"
+    role={isPersistent ? 'complementary' : isModeless ? 'region' : 'dialog'}
+    aria-modal={isDialog ? 'true' : undefined}
     aria-label={!header ? title : undefined}
     aria-labelledby={header ? headerId : undefined}
     {...rest}
   >
     <div class="panel-header">
       {#if header}
-        <div id={headerId}>{@render header()}</div>
+        <div
+          id={headerId}
+          class="panel-heading-focus"
+          tabindex={isModeless ? -1 : undefined}
+        >{@render header()}</div>
       {:else if title}
-        <h2 class="panel-title">{title}</h2>
+        <h2
+          class="panel-title panel-heading-focus"
+          tabindex={isModeless ? -1 : undefined}
+        >{title}</h2>
       {/if}
       {#if !persistent}
         <button

package/components/Panel.svelte.d.ts

@@ -23,6 +23,11 @@ type Panel = {
  * <Panel open persistent side="left" title="History">
  *   Always-visible sidebar content
  * </Panel>
+ *
+ * @example Modeless drawer (fixed slide-over, page behind stays interactive)
+ * <Panel open modeless title="Execute action" onclose={() => showAction = false}>
+ *   Action form here — focus moves to the heading, Escape closes while inside
+ * </Panel>
  */
 declare const Panel: import("svelte").Component<{
     open?: boolean;
@@ -30,6 +35,7 @@ declare const Panel: import("svelte").Component<{
     width?: string;
     side?: string;
     persistent?: boolean;
+    modeless?: boolean;
     scrollBody?: boolean;
     onclose: any;
     class?: string;
@@ -43,6 +49,7 @@ type $$ComponentProps = {
     width?: string;
     side?: string;
     persistent?: boolean;
+    modeless?: boolean;
     scrollBody?: boolean;
     onclose: any;
     class?: string;

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

@@ -43,12 +43,20 @@ export interface BuildArgs {
      *  attachment contract: a TOP-LEVEL `attachment_keys` sibling, never part
      *  of raw_values (the form schema doesn't validate file params). */
     attachmentKeys?: string[];
+    /** #629 follow-up — the SAME storage keys, attributed to the file param
+     *  each was uploaded against (`{param_key: [keys]}`). Additive: consumers
+     *  that only read the flat `attachment_keys` are unaffected; consumers
+     *  that must map keys back to parameters (the staff execute adapter) read
+     *  this instead of guessing positionally. */
+    attachmentsByParam?: Record<string, string[]>;
     schemaVersion: string | null;
     mode: RendererMode;
 }
 export interface ActionPayload {
     /** Uploaded file storage keys (file-typed params) — absent when none. */
     attachment_keys?: string[];
+    /** Per-param attribution of the same keys — absent when none. */
+    attachments_by_param?: Record<string, string[]>;
     source: string;
     action: {
         id: string | null;

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

@@ -46,6 +46,12 @@ export interface BuildArgs {
    *  attachment contract: a TOP-LEVEL `attachment_keys` sibling, never part
    *  of raw_values (the form schema doesn't validate file params). */
   attachmentKeys?: string[];
+  /** #629 follow-up — the SAME storage keys, attributed to the file param
+   *  each was uploaded against (`{param_key: [keys]}`). Additive: consumers
+   *  that only read the flat `attachment_keys` are unaffected; consumers
+   *  that must map keys back to parameters (the staff execute adapter) read
+   *  this instead of guessing positionally. */
+  attachmentsByParam?: Record<string, string[]>;
   schemaVersion: string | null;
   mode: RendererMode;
 }
@@ -53,6 +59,8 @@ export interface BuildArgs {
 export interface ActionPayload {
   /** Uploaded file storage keys (file-typed params) — absent when none. */
   attachment_keys?: string[];
+  /** Per-param attribution of the same keys — absent when none. */
+  attachments_by_param?: Record<string, string[]>;
   source: string;
   action: {
     id: string | null;
@@ -108,7 +116,7 @@ function pickScope(targetConfig: Record<string, unknown>): Record<string, unknow
 }
 
 export function buildActionPayload(args: BuildArgs): ActionPayload {
-  const { action, placement, targetConfig, sourceSchema, rawValues, schemaVersion, mode, attachmentKeys } = args;
+  const { action, placement, targetConfig, sourceSchema, rawValues, schemaVersion, mode, attachmentKeys, attachmentsByParam } = args;
 
   const sourceFromSchema = nullableString(sourceSchema.source);
   const targetModel =
@@ -152,6 +160,9 @@ export function buildActionPayload(args: BuildArgs): ActionPayload {
     ...(attachmentKeys && attachmentKeys.length > 0
       ? { attachment_keys: attachmentKeys }
       : {}),
+    ...(attachmentsByParam && Object.keys(attachmentsByParam).length > 0
+      ? { attachments_by_param: attachmentsByParam }
+      : {}),
   };
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aiaiai-pt/design-system",
-  "version": "0.43.0",
+  "version": "0.44.1",
   "description": "Design system tokens and Svelte components for aiaiai products",
   "license": "MIT",
   "type": "module",