@aiaiai-pt/design-system 0.7.0 → 0.8.0

package/components/ValueSourcePicker.helpers.d.ts

@@ -0,0 +1,101 @@
+/**
+ * Convert a ValueSourceValue into wire form ready to persist.
+ *
+ * @param {ValueSourceValue} v
+ * @returns {SerializedValueSource}
+ */
+export function serializeValueSource(v: ValueSourceValue): SerializedValueSource;
+/**
+ * Convert wire form back into a ValueSourceValue.
+ * Returns null when value is null/undefined and no functionArgs were supplied.
+ *
+ * @param {unknown} wire
+ * @param {Record<string, unknown> | null | undefined} [functionArgs]
+ * @returns {ValueSourceValue | null}
+ */
+export function parseValueSource(wire: unknown, functionArgs?: Record<string, unknown> | null | undefined): ValueSourceValue | null;
+export namespace _internal {
+    export { CREATED_REF_RE };
+}
+export type ValueSourceMode = "literal" | "parameter" | "entity-field" | "user-field" | "now" | "source-id" | "created-field" | "config-list" | "function" | "expression";
+export type ValueSourceValue = ({
+    mode: "literal";
+    value: string | number | boolean | null;
+} | {
+    mode: "parameter";
+    key: string;
+} | {
+    mode: "entity-field";
+    field: string;
+} | {
+    mode: "user-field";
+    key: string;
+} | {
+    mode: "now";
+} | {
+    mode: "source-id";
+} | {
+    mode: "created-field";
+    index: number;
+    field: string;
+} | {
+    mode: "config-list";
+    configType: string;
+} | {
+    mode: "function";
+    name: string;
+    args: Record<string, ValueSourceValue>;
+} | {
+    mode: "expression";
+    expr: string;
+});
+export type SerializedValueSource = {
+    /**
+     *   The wire scalar/string going into the slot
+     *   (e.g. ActionEdit.value, ParamValuesSource.config_query.filter[key]).
+     */
+    value: unknown;
+    /**
+     * Resolved function args dict — only set when v.mode === 'function'.
+     * Values are wire scalars/strings (recursively serialized).
+     */
+    functionArgs?: Record<string, unknown> | undefined;
+};
+/**
+ * Helpers for ValueSourcePicker — translate between the picker's
+ * structured ValueSourceValue object and the wire format the action
+ * engine reads (admin-api/app/actions/refs.py and edits.py).
+ *
+ * Mode catalog and wire formats — see
+ * dev_docs/specs/action-editor-parity-value-source-picker.md §3.
+ */
+/**
+ * @typedef {'literal' | 'parameter' | 'entity-field' | 'user-field'
+ *           | 'now' | 'source-id' | 'created-field'
+ *           | 'config-list' | 'function' | 'expression'} ValueSourceMode
+ */
+/**
+ * @typedef {(
+ *   { mode: 'literal', value: string | number | boolean | null }
+ *   | { mode: 'parameter', key: string }
+ *   | { mode: 'entity-field', field: string }
+ *   | { mode: 'user-field', key: string }
+ *   | { mode: 'now' }
+ *   | { mode: 'source-id' }
+ *   | { mode: 'created-field', index: number, field: string }
+ *   | { mode: 'config-list', configType: string }
+ *   | { mode: 'function', name: string, args: Record<string, ValueSourceValue> }
+ *   | { mode: 'expression', expr: string }
+ * )} ValueSourceValue
+ */
+/**
+ * @typedef {Object} SerializedValueSource
+ * @property {unknown} value
+ *   The wire scalar/string going into the slot
+ *   (e.g. ActionEdit.value, ParamValuesSource.config_query.filter[key]).
+ * @property {Record<string, unknown> | undefined} [functionArgs]
+ *   Resolved function args dict — only set when v.mode === 'function'.
+ *   Values are wire scalars/strings (recursively serialized).
+ */
+declare const CREATED_REF_RE: RegExp;
+export {};

package/components/ValueSourcePicker.helpers.js

@@ -0,0 +1,157 @@
+/**
+ * Helpers for ValueSourcePicker — translate between the picker's
+ * structured ValueSourceValue object and the wire format the action
+ * engine reads (admin-api/app/actions/refs.py and edits.py).
+ *
+ * Mode catalog and wire formats — see
+ * dev_docs/specs/action-editor-parity-value-source-picker.md §3.
+ */
+
+/**
+ * @typedef {'literal' | 'parameter' | 'entity-field' | 'user-field'
+ *           | 'now' | 'source-id' | 'created-field'
+ *           | 'config-list' | 'function' | 'expression'} ValueSourceMode
+ */
+
+/**
+ * @typedef {(
+ *   { mode: 'literal', value: string | number | boolean | null }
+ *   | { mode: 'parameter', key: string }
+ *   | { mode: 'entity-field', field: string }
+ *   | { mode: 'user-field', key: string }
+ *   | { mode: 'now' }
+ *   | { mode: 'source-id' }
+ *   | { mode: 'created-field', index: number, field: string }
+ *   | { mode: 'config-list', configType: string }
+ *   | { mode: 'function', name: string, args: Record<string, ValueSourceValue> }
+ *   | { mode: 'expression', expr: string }
+ * )} ValueSourceValue
+ */
+
+/**
+ * @typedef {Object} SerializedValueSource
+ * @property {unknown} value
+ *   The wire scalar/string going into the slot
+ *   (e.g. ActionEdit.value, ParamValuesSource.config_query.filter[key]).
+ * @property {Record<string, unknown> | undefined} [functionArgs]
+ *   Resolved function args dict — only set when v.mode === 'function'.
+ *   Values are wire scalars/strings (recursively serialized).
+ */
+
+const CREATED_REF_RE = /^\$created\.(\d+)\.(\w+)$/;
+
+/**
+ * Convert a ValueSourceValue into wire form ready to persist.
+ *
+ * @param {ValueSourceValue} v
+ * @returns {SerializedValueSource}
+ */
+export function serializeValueSource(v) {
+  switch (v.mode) {
+    case "literal":
+      return { value: v.value };
+    case "parameter":
+      return { value: `$parameters.${v.key}` };
+    case "entity-field":
+      return { value: `$entity.${v.field}` };
+    case "user-field":
+      return { value: `$user.${v.key}` };
+    case "now":
+      return { value: "$now" };
+    case "source-id":
+      return { value: "$source.id" };
+    case "created-field":
+      return { value: `$created.${v.index}.${v.field}` };
+    case "config-list":
+      return { value: `$config.${v.configType}` };
+    case "expression":
+      return { value: `$expr(${v.expr})` };
+    case "function": {
+      /** @type {Record<string, unknown>} */
+      const functionArgs = {};
+      for (const [argKey, argValue] of Object.entries(v.args)) {
+        functionArgs[argKey] = serializeValueSource(argValue).value;
+      }
+      return { value: `$function.${v.name}`, functionArgs };
+    }
+    default: {
+      const exhaustive = /** @type {never} */ (v);
+      throw new Error(
+        `serializeValueSource: unknown mode ${JSON.stringify(exhaustive)}`,
+      );
+    }
+  }
+}
+
+/**
+ * Convert wire form back into a ValueSourceValue.
+ * Returns null when value is null/undefined and no functionArgs were supplied.
+ *
+ * @param {unknown} wire
+ * @param {Record<string, unknown> | null | undefined} [functionArgs]
+ * @returns {ValueSourceValue | null}
+ */
+export function parseValueSource(wire, functionArgs) {
+  if (wire === undefined) {
+    // Slot was absent from the stored JSON — picker shows empty.
+    return null;
+  }
+  if (wire === null) {
+    // Engine treats null wire as literal null (refs.py:42 falls through).
+    return { mode: "literal", value: null };
+  }
+
+  if (typeof wire !== "string") {
+    // Non-string scalar (number / bool) → literal as-is.
+    return { mode: "literal", value: /** @type {any} */ (wire) };
+  }
+
+  // Bare $now / $source.id (exact match).
+  if (wire === "$now") return { mode: "now" };
+  if (wire === "$source.id") return { mode: "source-id" };
+
+  // Prefixed refs.
+  if (wire.startsWith("$parameters.")) {
+    return { mode: "parameter", key: wire.slice("$parameters.".length) };
+  }
+  if (wire.startsWith("$entity.")) {
+    return { mode: "entity-field", field: wire.slice("$entity.".length) };
+  }
+  if (wire.startsWith("$user.")) {
+    return { mode: "user-field", key: wire.slice("$user.".length) };
+  }
+  if (wire.startsWith("$config.")) {
+    return { mode: "config-list", configType: wire.slice("$config.".length) };
+  }
+  if (wire.startsWith("$function.")) {
+    const name = wire.slice("$function.".length);
+    /** @type {Record<string, ValueSourceValue>} */
+    const args = {};
+    if (functionArgs) {
+      for (const [argKey, argWire] of Object.entries(functionArgs)) {
+        const parsed = parseValueSource(argWire);
+        if (parsed !== null) {
+          args[argKey] = parsed;
+        }
+      }
+    }
+    return { mode: "function", name, args };
+  }
+  if (wire.startsWith("$expr(") && wire.endsWith(")")) {
+    return { mode: "expression", expr: wire.slice("$expr(".length, -1) };
+  }
+  const createdMatch = CREATED_REF_RE.exec(wire);
+  if (createdMatch) {
+    return {
+      mode: "created-field",
+      index: Number.parseInt(createdMatch[1], 10),
+      field: createdMatch[2],
+    };
+  }
+
+  // No recognized prefix → literal string. Matches engine's fall-through
+  // in refs.py:75 (`return value`).
+  return { mode: "literal", value: wire };
+}
+
+export const _internal = { CREATED_REF_RE };

package/components/ValueSourcePicker.svelte

@@ -0,0 +1,592 @@
+<!--
+  @component ValueSourcePicker
+
+  One picker for every action-engine slot that accepts "literal-or-reference".
+  Authoring affordance for action editors (Foundry-style declarative actions):
+  every Edit value, Create field, function arg, and config-query filter shares
+  this control. Wire format matches admin-api/app/actions/refs.py byte-for-byte.
+
+  Pair with the helpers shipped alongside (ValueSourcePicker.helpers.js):
+    serializeValueSource(v) → { value, functionArgs? }
+    parseValueSource(wire, functionArgs?) → ValueSourceValue | null
+
+  Allowed modes are narrowed per consumer — see the per-consumer matrix in
+  the consumer's spec (see issue #28 of the action-editor parity work).
+
+  @example Edits' value slot
+  <ValueSourcePicker
+    label="VALUE"
+    bind:value={editValue}
+    allowed={['literal', 'parameter', 'function', 'now', 'expression']}
+    context={{ parameters, functions }}
+    expectedType={field.type}
+  />
+
+  @example Function arg (recursive — depth 2)
+  <ValueSourcePicker
+    label={argName}
+    bind:value={argValue}
+    allowed={['literal', 'parameter', 'entity-field', 'user-field', 'config-list']}
+    context={{ parameters, entitySchema, userFields, configTypes }}
+  />
+-->
+<script module>
+  let _vspUid = 0;
+</script>
+
+<script>
+  /**
+   * @typedef {import('./ValueSourcePicker.helpers.js').ValueSourceMode} ValueSourceMode
+   * @typedef {import('./ValueSourcePicker.helpers.js').ValueSourceValue} ValueSourceValue
+   *
+   * @typedef {{ key: string, label: string, type: string }} ParameterField
+   * @typedef {{ name: string, label?: string, argSchema: Record<string, SchemaField> }} FunctionDefinition
+   * @typedef {{ key: string, label: string, description?: string }} UserField
+   * @typedef {{ index: number, entityType: string, fields: string[] }} PriorCreate
+   * @typedef {{ code: string, label: string }} ConfigType
+   * @typedef {{ type: string, enum?: string[], format?: string, required?: boolean }} SchemaField
+   *
+   * @typedef {Object} ValueSourceContext
+   * @property {ParameterField[]} [parameters]
+   * @property {{ type: string, properties: Record<string, SchemaField> }} [entitySchema]
+   * @property {UserField[]} [userFields]
+   * @property {FunctionDefinition[]} [functions]
+   * @property {PriorCreate[]} [priorCreates]
+   * @property {ConfigType[]} [configTypes]
+   */
+
+  import Select from "./Select.svelte";
+  import Combobox from "./Combobox.svelte";
+  import Input from "./Input.svelte";
+  import Badge from "./Badge.svelte";
+  import Button from "./Button.svelte";
+  import Label from "./Label.svelte";
+  import ValueSourcePicker from "./ValueSourcePicker.svelte";
+
+  let {
+    /** @type {ValueSourceValue | null} */
+    value = $bindable(null),
+    /** @type {((next: ValueSourceValue | null) => void) | undefined} */
+    onchange = undefined,
+    /** @type {ValueSourceMode[]} */
+    allowed = [
+      "literal",
+      "parameter",
+      "entity-field",
+      "user-field",
+      "now",
+      "source-id",
+      "created-field",
+      "config-list",
+      "function",
+      "expression",
+    ],
+    /** @type {ValueSourceContext} */
+    context = {},
+    /** @type {string | undefined} */
+    expectedType = undefined,
+    /** @type {string | undefined} */
+    label = undefined,
+    /** @type {boolean} */
+    required = false,
+    /** @type {boolean} */
+    disabled = false,
+    /** @type {string | undefined} */
+    id = undefined,
+    /** @type {string} */
+    class: className = "",
+    ...rest
+  } = $props();
+
+  const uid = `vsp-${_vspUid++}`;
+  const groupId = $derived(id ?? uid);
+
+  const MODE_LABEL = /** @type {Record<ValueSourceMode, string>} */ ({
+    literal: "Literal",
+    parameter: "Parameter",
+    "entity-field": "Entity field",
+    "user-field": "User field",
+    now: "Current time",
+    "source-id": "Source entity id",
+    "created-field": "Prior-created entity",
+    "config-list": "Config rows",
+    function: "Function",
+    expression: "Expression",
+  });
+
+  const MODE_DESCRIPTION = /** @type {Record<ValueSourceMode, string>} */ ({
+    literal: "A typed-in value",
+    parameter: "Value of an action input",
+    "entity-field": "A field of the source entity",
+    "user-field": "A claim from the caller's JWT",
+    now: "ISO 8601 UTC timestamp at execution time",
+    "source-id": "ID of the entity being acted upon",
+    "created-field": "Field of an entity created earlier in this action",
+    "config-list": "List of org-scoped config rows",
+    function: "Result of a registered action function",
+    expression: "Inline arithmetic over $entity / $parameters / $user",
+  });
+
+  const modeOptions = $derived(
+    allowed.map((mode) => ({ value: mode, label: MODE_LABEL[mode] })),
+  );
+
+  const currentMode = $derived(value?.mode ?? null);
+
+  const isStoredModeForbidden = $derived(
+    currentMode !== null && !allowed.includes(currentMode),
+  );
+
+  function emit(next) {
+    value = next;
+    onchange?.(next);
+  }
+
+  function pickMode(/** @type {string} */ next) {
+    const mode = /** @type {ValueSourceMode} */ (next);
+    if (mode === currentMode) return;
+    emit(makeBlankForMode(mode));
+  }
+
+  /** @returns {ValueSourceValue} */
+  function makeBlankForMode(/** @type {ValueSourceMode} */ mode) {
+    switch (mode) {
+      case "literal":
+        return { mode, value: "" };
+      case "parameter":
+        return { mode, key: "" };
+      case "entity-field":
+        return { mode, field: "" };
+      case "user-field":
+        return { mode, key: "" };
+      case "now":
+        return { mode };
+      case "source-id":
+        return { mode };
+      case "created-field":
+        return { mode, index: 0, field: "id" };
+      case "config-list":
+        return { mode, configType: "" };
+      case "function":
+        return { mode, name: "", args: {} };
+      case "expression":
+        return { mode, expr: "" };
+      default: {
+        const exhaustive = /** @type {never} */ (mode);
+        throw new Error(`makeBlankForMode: ${String(exhaustive)}`);
+      }
+    }
+  }
+
+  function clear() {
+    emit(null);
+  }
+
+  // ----------- per-mode helpers -----------
+
+  function paramOptions() {
+    return (context.parameters ?? []).map((p) => ({
+      value: p.key,
+      label: `${p.label || p.key}`,
+      description: p.type,
+    }));
+  }
+  function entityFieldOptions() {
+    const props = context.entitySchema?.properties ?? {};
+    return Object.entries(props).map(([key, schema]) => ({
+      value: key,
+      label: key,
+      description: schema.type,
+    }));
+  }
+  function userFieldOptions() {
+    return (context.userFields ?? []).map((u) => ({
+      value: u.key,
+      label: u.label,
+      description: u.description,
+    }));
+  }
+  function functionOptions() {
+    return (context.functions ?? []).map((fn) => ({
+      value: fn.name,
+      label: fn.label || fn.name,
+    }));
+  }
+  function priorCreateOptions() {
+    return (context.priorCreates ?? []).map((c) => ({
+      value: String(c.index),
+      label: `${c.index}: ${c.entityType}`,
+    }));
+  }
+  function priorCreateFieldOptions() {
+    if (value?.mode !== "created-field") return [];
+    const c = (context.priorCreates ?? []).find(
+      (p) => p.index === value.index,
+    );
+    return (c?.fields ?? ["id"]).map((f) => ({ value: f, label: f }));
+  }
+  function configTypeOptions() {
+    return (context.configTypes ?? []).map((c) => ({
+      value: c.code,
+      label: c.label || c.code,
+    }));
+  }
+
+  // dangling-ref detector — true when the stored ref names something not in context
+  const isDangling = $derived.by(() => {
+    if (!value) return false;
+    switch (value.mode) {
+      case "parameter":
+        return (
+          value.key !== "" &&
+          !(context.parameters ?? []).some((p) => p.key === value.key)
+        );
+      case "entity-field":
+        return (
+          value.field !== "" &&
+          !((context.entitySchema?.properties ?? {})[value.field])
+        );
+      case "user-field":
+        return (
+          value.key !== "" &&
+          !(context.userFields ?? []).some((u) => u.key === value.key)
+        );
+      case "function":
+        return (
+          value.name !== "" &&
+          !(context.functions ?? []).some((fn) => fn.name === value.name)
+        );
+      case "config-list":
+        return (
+          value.configType !== "" &&
+          !(context.configTypes ?? []).some((c) => c.code === value.configType)
+        );
+      case "created-field":
+        return !((context.priorCreates ?? []).some((p) => p.index === value.index));
+      default:
+        return false;
+    }
+  });
+
+  // type-mismatch detector — yellow soft warn (never blocks submit)
+  const typeMismatch = $derived.by(() => {
+    if (!expectedType || !value) return false;
+    switch (value.mode) {
+      case "parameter": {
+        const p = (context.parameters ?? []).find((pp) => pp.key === value.key);
+        return p ? !typesCompatible(p.type, expectedType) : false;
+      }
+      case "entity-field": {
+        const f = (context.entitySchema?.properties ?? {})[value.field];
+        return f ? !typesCompatible(f.type, expectedType) : false;
+      }
+      case "now":
+        return !typesCompatible("datetime", expectedType);
+      case "config-list":
+        return !typesCompatible("list", expectedType);
+      default:
+        return false;
+    }
+  });
+
+  function typesCompatible(/** @type {string} */ a, /** @type {string} */ b) {
+    if (a === b) return true;
+    // engine coerces freely between string ↔ number / datetime;
+    // only flag obvious mismatches.
+    const numericLike = new Set(["int", "float", "number"]);
+    if (numericLike.has(a) && numericLike.has(b)) return true;
+    return false;
+  }
+
+  // function-arg child editor — each arg is itself a ValueSourcePicker.
+  function updateFunctionArg(/** @type {string} */ key, /** @type {ValueSourceValue | null} */ next) {
+    if (value?.mode !== "function") return;
+    const args = { ...value.args };
+    if (next === null) delete args[key];
+    else args[key] = next;
+    emit({ ...value, args });
+  }
+
+  function functionArgAllowed() {
+    // Args use the four context-ref modes plus literal and config-list.
+    // Function-as-arg is forbidden by the engine's resolver layering — depth ≤ 2.
+    return /** @type {ValueSourceMode[]} */ ([
+      "literal",
+      "parameter",
+      "entity-field",
+      "user-field",
+      "config-list",
+    ]);
+  }
+
+  function functionDef() {
+    if (value?.mode !== "function") return null;
+    return (context.functions ?? []).find((fn) => fn.name === value.name) ?? null;
+  }
+
+  function literalPlaceholder(/** @type {string | undefined} */ t) {
+    switch (t) {
+      case "int":
+      case "float":
+      case "number":
+        return "0";
+      case "bool":
+        return "true";
+      case "datetime":
+        return "2026-01-01T00:00:00Z";
+      case "uuid":
+        return "00000000-0000-0000-0000-000000000000";
+      default:
+        return "Type a value";
+    }
+  }
+
+  function coerceLiteral(/** @type {string} */ raw, /** @type {string | undefined} */ t) {
+    switch (t) {
+      case "int":
+        return raw === "" ? null : Number.parseInt(raw, 10);
+      case "float":
+      case "number":
+        return raw === "" ? null : Number.parseFloat(raw);
+      case "bool":
+        return raw === "true";
+      default:
+        return raw;
+    }
+  }
+</script>
+
+<div
+  class="vsp {className}"
+  class:vsp-disabled={disabled}
+  role="group"
+  aria-labelledby={label ? `${groupId}-label` : undefined}
+  {...rest}
+>
+  {#if label}
+    <Label for={`${groupId}-mode`} id={`${groupId}-label`}>
+      {label}{#if required}<span class="vsp-required" aria-hidden="true">*</span>{/if}
+    </Label>
+  {/if}
+
+  <div class="vsp-row">
+    <div class="vsp-mode">
+      <Select
+        id={`${groupId}-mode`}
+        size="sm"
+        placeholder={value === null ? "Pick a source" : undefined}
+        value={currentMode ?? ""}
+        options={modeOptions}
+        onchange={pickMode}
+        {disabled}
+      />
+    </div>
+
+    <div class="vsp-detail">
+      {#if isStoredModeForbidden && value}
+        <div class="vsp-error-row">
+          <Badge variant="error">no longer allowed: {MODE_LABEL[value.mode]}</Badge>
+          <Button variant="ghost" size="sm" onclick={clear}>Clear</Button>
+        </div>
+      {:else if value === null}
+        <span class="vsp-placeholder">{MODE_DESCRIPTION[allowed[0]] ?? ""}</span>
+      {:else if value.mode === "literal"}
+        <Input
+          size="sm"
+          placeholder={literalPlaceholder(expectedType)}
+          value={String(value.value ?? "")}
+          oninput={(e) => emit({ mode: "literal", value: coerceLiteral(/** @type {HTMLInputElement} */ (e.target).value, expectedType) })}
+          {disabled}
+        />
+      {:else if value.mode === "parameter"}
+        <Combobox
+          size="sm"
+          placeholder="Pick a parameter"
+          items={paramOptions()}
+          value={value.key}
+          onchange={(k) => emit({ mode: "parameter", key: k })}
+          {disabled}
+        />
+      {:else if value.mode === "entity-field"}
+        <Combobox
+          size="sm"
+          placeholder="Pick a field"
+          items={entityFieldOptions()}
+          value={value.field}
+          onchange={(f) => emit({ mode: "entity-field", field: f })}
+          {disabled}
+        />
+      {:else if value.mode === "user-field"}
+        <Combobox
+          size="sm"
+          placeholder="Pick a user claim"
+          items={userFieldOptions()}
+          value={value.key}
+          onchange={(k) => emit({ mode: "user-field", key: k })}
+          {disabled}
+        />
+      {:else if value.mode === "now"}
+        <Badge variant="info">$now — current UTC timestamp</Badge>
+      {:else if value.mode === "source-id"}
+        <Badge variant="info">$source.id — id of the entity being acted upon</Badge>
+      {:else if value.mode === "config-list"}
+        <Combobox
+          size="sm"
+          placeholder="Pick a config type"
+          items={configTypeOptions()}
+          value={value.configType}
+          onchange={(c) => emit({ mode: "config-list", configType: c })}
+          {disabled}
+        />
+        <Badge variant="neutral">list</Badge>
+      {:else if value.mode === "expression"}
+        <Input
+          size="sm"
+          placeholder="$entity.X + 1"
+          value={value.expr}
+          oninput={(e) => emit({ mode: "expression", expr: /** @type {HTMLInputElement} */ (e.target).value })}
+          {disabled}
+        />
+      {:else if value.mode === "created-field"}
+        <div class="vsp-inline">
+          <Combobox
+            size="sm"
+            placeholder="prior create"
+            items={priorCreateOptions()}
+            value={String(value.index)}
+            onchange={(i) => emit({ mode: "created-field", index: Number(i), field: value.field })}
+            {disabled}
+          />
+          <Combobox
+            size="sm"
+            placeholder="field"
+            items={priorCreateFieldOptions()}
+            value={value.field}
+            onchange={(f) => emit({ mode: "created-field", index: value.index, field: f })}
+            {disabled}
+          />
+        </div>
+      {:else if value.mode === "function"}
+        <Combobox
+          size="sm"
+          placeholder="Pick a function"
+          items={functionOptions()}
+          value={value.name}
+          onchange={(n) => emit({ mode: "function", name: n, args: {} })}
+          {disabled}
+        />
+      {/if}
+
+      {#if value && !isStoredModeForbidden}
+        {#if isDangling}
+          <Badge variant="error">removed from context</Badge>
+          <Button variant="ghost" size="sm" onclick={clear}>Clear</Button>
+        {:else if typeMismatch}
+          <Badge variant="warning">type mismatch · expected {expectedType}</Badge>
+        {/if}
+      {/if}
+    </div>
+  </div>
+
+  {#if value?.mode === "function" && value.name}
+    {@const fn = functionDef()}
+    {#if fn}
+      <div class="vsp-args" role="group" aria-label={`${value.name} args`}>
+        <span class="vsp-args-title">Args</span>
+        {#each Object.entries(fn.argSchema) as [argKey, argSchema]}
+          <ValueSourcePicker
+            label={argKey}
+            value={value.args[argKey] ?? null}
+            allowed={functionArgAllowed()}
+            {context}
+            expectedType={argSchema.type}
+            onchange={(next) => updateFunctionArg(argKey, next)}
+            {disabled}
+          />
+        {/each}
+      </div>
+    {:else}
+      <Badge variant="error">function "{value.name}" not in registry</Badge>
+    {/if}
+  {/if}
+</div>
+
+<style>
+  .vsp {
+    display: flex;
+    flex-direction: column;
+    gap: var(--space-xs);
+  }
+
+  .vsp-required {
+    color: var(--color-text-error);
+    margin-inline-start: var(--space-3xs);
+  }
+
+  .vsp-row {
+    display: grid;
+    grid-template-columns: minmax(0, 11rem) minmax(0, 1fr);
+    gap: var(--space-sm);
+    align-items: center;
+  }
+
+  .vsp-mode {
+    min-width: 0;
+  }
+
+  .vsp-detail {
+    display: flex;
+    flex-wrap: wrap;
+    gap: var(--space-2xs);
+    align-items: center;
+    min-width: 0;
+  }
+
+  .vsp-detail :global(.input-group) {
+    flex: 1 1 auto;
+    min-width: 0;
+  }
+
+  .vsp-error-row {
+    display: flex;
+    gap: var(--space-2xs);
+    align-items: center;
+  }
+
+  .vsp-placeholder {
+    color: var(--color-text-muted);
+    font-family: var(--type-body-font);
+    font-size: var(--type-body-size);
+  }
+
+  .vsp-inline {
+    display: flex;
+    gap: var(--space-2xs);
+    flex: 1 1 auto;
+    min-width: 0;
+  }
+
+  .vsp-args {
+    margin-inline-start: var(--space-md);
+    padding: var(--space-sm);
+    border: var(--border-width) solid var(--color-border-subtle);
+    border-radius: var(--radius-md);
+    background: var(--color-surface-secondary);
+    display: flex;
+    flex-direction: column;
+    gap: var(--space-sm);
+  }
+
+  .vsp-args-title {
+    font-family: var(--type-label-font);
+    font-size: var(--type-label-size);
+    letter-spacing: var(--type-label-tracking);
+    text-transform: uppercase;
+    color: var(--color-text-muted);
+  }
+
+  .vsp-disabled {
+    opacity: 0.6;
+    pointer-events: none;
+  }
+</style>

package/components/ValueSourcePicker.svelte.d.ts

@@ -0,0 +1,105 @@
+export default ValueSourcePicker;
+export type ValueSourceMode = import("./ValueSourcePicker.helpers.js").ValueSourceMode;
+export type ValueSourceValue = import("./ValueSourcePicker.helpers.js").ValueSourceValue;
+export type ParameterField = {
+    key: string;
+    label: string;
+    type: string;
+};
+export type FunctionDefinition = {
+    name: string;
+    label?: string;
+    argSchema: Record<string, SchemaField>;
+};
+export type UserField = {
+    key: string;
+    label: string;
+    description?: string;
+};
+export type PriorCreate = {
+    index: number;
+    entityType: string;
+    fields: string[];
+};
+export type ConfigType = {
+    code: string;
+    label: string;
+};
+export type SchemaField = {
+    type: string;
+    enum?: string[];
+    format?: string;
+    required?: boolean;
+};
+export type ValueSourceContext = {
+    parameters?: ParameterField[];
+    entitySchema?: {
+        type: string;
+        properties: Record<string, SchemaField>;
+    };
+    userFields?: UserField[];
+    functions?: FunctionDefinition[];
+    priorCreates?: PriorCreate[];
+    configTypes?: ConfigType[];
+};
+type ValueSourcePicker = {
+    $on?(type: string, callback: (e: any) => void): () => void;
+    $set?(props: Partial<$$ComponentProps>): void;
+};
+/**
+ * ValueSourcePicker
+ *
+ * One picker for every action-engine slot that accepts "literal-or-reference".
+ * Authoring affordance for action editors (Foundry-style declarative actions):
+ * every Edit value, Create field, function arg, and config-query filter shares
+ * this control. Wire format matches admin-api/app/actions/refs.py byte-for-byte.
+ *
+ * Pair with the helpers shipped alongside (ValueSourcePicker.helpers.js):
+ *   serializeValueSource(v) → { value, functionArgs? }
+ *   parseValueSource(wire, functionArgs?) → ValueSourceValue | null
+ *
+ * Allowed modes are narrowed per consumer — see the per-consumer matrix in
+ * the consumer's spec (see issue #28 of the action-editor parity work).
+ *
+ * @example Edits' value slot
+ * <ValueSourcePicker
+ *   label="VALUE"
+ *   bind:value={editValue}
+ *   allowed={['literal', 'parameter', 'function', 'now', 'expression']}
+ *   context={{ parameters, functions }}
+ *   expectedType={field.type}
+ * />
+ *
+ * @example Function arg (recursive — depth 2)
+ * <ValueSourcePicker
+ *   label={argName}
+ *   bind:value={argValue}
+ *   allowed={['literal', 'parameter', 'entity-field', 'user-field', 'config-list']}
+ *   context={{ parameters, entitySchema, userFields, configTypes }}
+ * />
+ */
+declare const ValueSourcePicker: import("svelte").Component<{
+    value?: any;
+    onchange?: any;
+    allowed?: any[];
+    context?: Record<string, any>;
+    expectedType?: any;
+    label?: any;
+    required?: boolean;
+    disabled?: boolean;
+    id?: any;
+    class?: string;
+} & Record<string, any>, {}, "value">;
+import ValueSourcePicker from "./ValueSourcePicker.svelte";
+type $$ComponentProps = {
+    value?: any;
+    onchange?: any;
+    allowed?: any[];
+    context?: Record<string, any>;
+    expectedType?: any;
+    label?: any;
+    required?: boolean;
+    disabled?: boolean;
+    id?: any;
+    class?: string;
+} & Record<string, any>;

package/components/index.js

@@ -76,6 +76,11 @@ export { default as BottomNavItem } from "./BottomNavItem.svelte";
 
 // Complex
 export { default as Stepper } from "./Stepper.svelte";
+export { default as ValueSourcePicker } from "./ValueSourcePicker.svelte";
+export {
+  serializeValueSource,
+  parseValueSource,
+} from "./ValueSourcePicker.helpers.js";
 export { default as CodeBlock } from "./CodeBlock.svelte";
 export { default as CodeEditor } from "./CodeEditor.svelte";
 export { default as CollapsibleSection } from "./CollapsibleSection.svelte";

package/package.json

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