@glw907/cairn-cms 0.56.1 → 0.56.2

package/dist/render/component-grammar.js

@@ -58,7 +58,7 @@ function isContainer(node) {
 }
 // Pin the bullet to `-` so a markdown body or slot that uses dash bullets round-trips unchanged
 // rather than drifting to remark-stringify's default `*`, which would silently mutate author content.
-const toMd = unified().use(remarkStringify, { bullet: '-' });
+const toMd = unified().use(remarkDirective).use(remarkStringify, { bullet: '-' });
 /** Render mdast children back to trimmed markdown text. */
 function childrenToText(children) {
     const root = { type: 'root', children };
@@ -120,6 +120,40 @@ export async function parseComponent(markdown, def) {
 export function parseRawAttributeKeys(markdown, def) {
     return rawKeysFromRoot(findComponentRoot(markdown, def));
 }
+/** Decide whether guided edit of this placed block is provably lossless. A block a person typed by
+ *  hand can carry more than the schema models (an attribute the def does not list, a child container
+ *  the def does not declare, slot content the form cannot represent stably), and parsing such a block
+ *  into the form then re-serializing would silently drop it. The edit affordance is offered only when
+ *  this returns `{ safe: true }`. Checks run in order and return the first failure:
+ *
+ *  1. `not-a-component`: the def's opening container is not present.
+ *  2. `unknown-attribute`: the block carries an attribute key the def does not declare.
+ *  3. `undeclared-child`: the root has a direct child container directive that is not a declared
+ *     nested slot. Such a child would otherwise fold into the body slot and move on re-serialize.
+ *  4. `not-idempotent`: `parse -> serialize -> parse` does not recover the same values. */
+export async function componentRoundTripSafety(markdown, def) {
+    const root = findComponentRoot(markdown, def);
+    if (!root)
+        return { safe: false, reason: 'not-a-component' };
+    const declaredKeys = new Set((def.attributes ?? []).map((f) => f.key));
+    for (const key of parseRawAttributeKeys(markdown, def)) {
+        if (!declaredKeys.has(key))
+            return { safe: false, reason: 'unknown-attribute' };
+    }
+    const slotNames = new Set(nestedSlots(def).map((s) => s.name));
+    for (const child of root.children) {
+        if (isContainer(child) && !slotNames.has(child.name)) {
+            return { safe: false, reason: 'undeclared-child' };
+        }
+    }
+    // The values are plain strings, booleans, and string arrays in declared (object-key) order, so a
+    // stable JSON.stringify is a sufficient deep-equal.
+    const v1 = await parseComponent(markdown, def);
+    const v2 = await parseComponent(serializeComponent(def, v1), def);
+    if (JSON.stringify(v1) !== JSON.stringify(v2))
+        return { safe: false, reason: 'not-idempotent' };
+    return { safe: true };
+}
 /** Parse the component once and derive both the guided-form values and the raw attribute keys.
  *  Validation needs both, so this seam spares it the double parse that calling
  *  {@link parseComponent} and {@link parseRawAttributeKeys} separately would cost. */
@@ -146,8 +180,18 @@ function isDirectiveLabel(node) {
 function readLabel(root) {
     for (const child of root.children) {
         const p = child;
-        if (p.type === 'paragraph' && p.data?.directiveLabel)
-            return (p.children ?? []).map((c) => c.value ?? '').join('');
+        if (p.type !== 'paragraph' || !p.data?.directiveLabel)
+            continue;
+        const kids = p.children ?? [];
+        // When every label child is a plain text node, join the raw `.value`s. That keeps the pure-text
+        // path identical to before, so a literal `[` or `]` in the title is not re-escaped by the
+        // stringifier (serializeComponent already escapes brackets, and remark un-escapes them on parse).
+        // When the label carries inline markdown (a link, bold, emphasis), the text-only join would drop
+        // the markup, so stringify the children to recover the full inline source losslessly.
+        if (kids.every((c) => c.type === 'text')) {
+            return kids.map((c) => c.value ?? '').join('');
+        }
+        return childrenToText(kids);
     }
     return undefined;
 }

package/dist/render/component-validate.js

@@ -12,6 +12,16 @@ export async function validateComponent(markdown, def) {
         }
         if (field.type === 'select' && typeof v === 'string' && v !== '' && !(field.options ?? []).includes(v)) {
             errors[field.key] = `${field.label} must be one of: ${(field.options ?? []).join(', ')}.`;
+            continue;
+        }
+        if (field.pattern && typeof v === 'string' && v !== '' && !new RegExp(field.pattern.source).test(v)) {
+            errors[field.key] = field.pattern.message;
+            continue;
+        }
+        if (field.validate) {
+            const message = runFieldValidator(def, field.key, () => field.validate(v, values));
+            if (typeof message === 'string')
+                errors[field.key] = message;
         }
     }
     for (const key of rawKeys) {
@@ -28,3 +38,15 @@ export async function validateComponent(markdown, def) {
     }
     return Object.keys(errors).length ? { ok: false, errors } : { ok: true };
 }
+// Run a site-supplied attribute validator. The validator is author code, so a throw is contained:
+// the field is treated as valid and a dev-time warning names the component and field so the author
+// can find the bug. A returned string is the field error; anything else (null) is clean.
+function runFieldValidator(def, key, call) {
+    try {
+        return call();
+    }
+    catch (err) {
+        console.warn(`cairn: validate() for component "${def.name}" field "${key}" threw; treating the field as valid.`, err);
+        return null;
+    }
+}

package/dist/render/registry.d.ts

@@ -15,6 +15,15 @@ export interface AttributeField {
     options?: readonly string[];
     /** Helper text shown under the field. */
     help?: string;
+    /** A RegExp `source` to validate the value against, plus the message to show on a mismatch. */
+    pattern?: {
+        source: string;
+        message: string;
+    };
+    /** A pure, browser-safe cross-field validator. Returns an error string, or null when valid.
+     *  Receives the field's value and the full {@link ComponentValues} so a rule can read sibling
+     *  fields. The picker wraps the call in try/catch so an author's throw never crashes the form. */
+    validate?: (value: string | boolean, all: ComponentValues) => string | null;
 }
 export type SlotKind = 'markdown' | 'inline' | 'repeatable';
 /** One named content region of a component. The slots named `title` and `body` are special: `title`
@@ -27,6 +36,9 @@ export interface SlotDef {
     help?: string;
     /** For `kind: 'repeatable'`: the fields composing each list item (v1 uses the first field). */
     itemFields?: AttributeField[];
+    /** For `kind: 'repeatable'`: derives a row's label from its item values and zero-based index.
+     *  When it returns nothing, the picker falls back to `${label} ${index + 1}`. */
+    itemLabel?: (item: Record<string, string | boolean>, index: number) => string;
 }
 /** The structured input a component's `build` receives. The engine stamps the component's
  *  attributes and partitions its slots from the rendered hast, so `build` arranges hast and
@@ -64,6 +76,18 @@ export interface ComponentDef {
     attributes?: AttributeField[];
     /** The named content regions this component accepts. */
     slots?: SlotDef[];
+    /** A glyph key from the site IconSet, shown beside the label in the picker. */
+    icon?: string;
+    /** A category heading for the picker. Components order by declaration within a group. */
+    group?: string;
+    /** Omit from the top-level picker (for a nested or round-trip-only component). */
+    hidden?: boolean;
+    /** A structured sample the picker seeds the form with and renders through the same path a real
+     *  insert takes. Declaring `preview` is what opts the component into the two-pane configure layout. */
+    preview?: {
+        attributes?: Record<string, string | boolean>;
+        slots?: Record<string, string | string[]>;
+    };
 }
 export interface ComponentRegistry {
     defs: ComponentDef[];
@@ -93,3 +117,7 @@ export interface ComponentValues {
 /** Seed an empty {@link ComponentValues} from a component's schema: attribute defaults (or '' / false)
  *  and empty slot values ([] for repeatable, '' otherwise). */
 export declare function emptyValues(def: ComponentDef): ComponentValues;
+/** Seed {@link ComponentValues} from a component's `preview` sample: the {@link emptyValues} base
+ *  with `def.preview.attributes` and `def.preview.slots` overlaid (a shallow merge per side). When
+ *  the def declares no `preview`, returns exactly the {@link emptyValues} output. */
+export declare function previewValues(def: ComponentDef): ComponentValues;

package/dist/render/registry.js

@@ -45,3 +45,15 @@ export function emptyValues(def) {
     }
     return { attributes, slots };
 }
+/** Seed {@link ComponentValues} from a component's `preview` sample: the {@link emptyValues} base
+ *  with `def.preview.attributes` and `def.preview.slots` overlaid (a shallow merge per side). When
+ *  the def declares no `preview`, returns exactly the {@link emptyValues} output. */
+export function previewValues(def) {
+    const base = emptyValues(def);
+    if (!def.preview)
+        return base;
+    return {
+        attributes: { ...base.attributes, ...def.preview.attributes },
+        slots: { ...base.slots, ...def.preview.slots },
+    };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@glw907/cairn-cms",
-  "version": "0.56.1",
+  "version": "0.56.2",
   "description": "Embedded, magic-link, GitHub-committing CMS for SvelteKit/Cloudflare sites.",
   "type": "module",
   "sideEffects": [
@@ -32,6 +32,7 @@
     "check:reference:signatures": "npm run package && node scripts/check-reference-signatures.mjs",
     "check:readiness": "npm run package && node scripts/check-readiness.mjs",
     "check:docs": "node scripts/docs-links.mjs",
+    "check:version": "node scripts/check-version.mjs",
     "check:prose": "node scripts/check-admin-prose.mjs",
     "prepare": "npm run package",
     "check": "svelte-check --tsconfig ./tsconfig.json",

package/src/lib/components/ComponentForm.svelte

@@ -1,13 +1,17 @@
 <!--
 @component
-The schema-driven fill form for one component. It holds the working ComponentValues, seeded from
-emptyValues(def), and renders attribute fields and the title/body and other non-repeatable slots.
-Submit (Task 6) serializes and validates through buildComponentInsert and calls onInsert with the
-markdown. Back returns to the picker. This is not a nested HTML form; Insert calls a callback.
+The schema-driven fill form for one component, the left column of the configure step. It holds the
+working ComponentValues, seeded from previewValues(def) (the emptyValues base with any declared
+preview sample overlaid), and renders attribute fields and the title/body and other slots. Required
+fields carry an asterisk and aria-required, and Insert disables while any required field is empty.
+Submit serializes and validates through buildComponentInsert and calls onInsert with the markdown.
+This is not a nested HTML form; Insert calls a callback. The dialog owns the header (the Insert >
+group breadcrumb and the Back control) and, in the two-pane case, the preview pane; this component
+binds out its live `values` and `incomplete` so the dialog can render that preview.
 -->
 <script lang="ts">
   import { untrack } from 'svelte';
-  import { emptyValues, type ComponentDef } from '../render/registry.js';
+  import { previewValues, type ComponentDef, type ComponentValues } from '../render/registry.js';
   import { buildComponentInsert } from '../render/component-insert.js';
   import type { IconSet } from '../render/glyph.js';
   import IconPicker from './IconPicker.svelte';
@@ -17,15 +21,39 @@ markdown. Back returns to the picker. This is not a nested HTML form; Insert cal
     icons?: IconSet;
     /** Called with the serialized markdown when the form validates. */
     onInsert: (markdown: string) => void;
-    /** Return to the picker. */
-    onBack: () => void;
+    /** The live working values, bound out so a host (the dialog) can render a preview from them. */
+    values?: ComponentValues;
+    /** True while a required attribute or slot is still empty, bound out so the host's preview can
+     *  show the incomplete state and the host can mirror the disabled Insert. */
+    incomplete?: boolean;
+    /** Seed the working values from these instead of the schema's preview sample. The dialog passes
+     *  it in edit mode to re-open a placed component into its own values; the catalog insert path
+     *  leaves it unset and keeps the previewValues seed. */
+    initial?: ComponentValues;
+    /** The submit button's label. The dialog passes 'Update' in edit mode; the insert path keeps
+     *  the default. */
+    submitLabel?: string;
   }
 
-  let { def, icons, onInsert, onBack }: Props = $props();
+  let {
+    def,
+    icons,
+    onInsert,
+    values = $bindable(),
+    incomplete = $bindable(),
+    initial,
+    submitLabel = 'Insert',
+  }: Props = $props();
 
-  // Working values, seeded once from the schema. $state makes the nested records deeply reactive.
-  // untrack marks the seed as a deliberate one-time read of the initial def, not a reactive miss.
-  let values = $state(untrack(() => emptyValues(def)));
+  // Working values, seeded once from `initial` in edit mode, otherwise from the schema and any
+  // declared preview sample. $state makes the nested records deeply reactive. untrack marks the
+  // seed as a deliberate one-time read, not a reactive miss. previewValues falls back to
+  // emptyValues when no preview.
+  let working = $state(untrack(() => initial ?? previewValues(def)));
+  // Mirror the working values out to the bindable prop so the dialog's preview reads them live.
+  $effect(() => {
+    values = working;
+  });
 
   const attributes = $derived(def.attributes ?? []);
   // Non-repeatable slots render here; the repeatable list is handled separately.
@@ -34,22 +62,32 @@ markdown. Back returns to the picker. This is not a nested HTML form; Insert cal
 
   // The live $state proxy array for a repeatable slot, so push/splice stay reactive.
   function slotItems(name: string): string[] {
-    const v = values.slots[name];
+    const v = working.slots[name];
     return Array.isArray(v) ? v : [];
   }
 
   // Stable per-item ids run parallel to each repeatable slot's value array, so the {#each} keys by
   // identity instead of index. A mid-list removal then drops the right DOM node and the focused
   // item follows the data. Ids come from a monotonic module-local counter, never Math.random or
-  // Date.now. The value arrays in values.slots stay the canonical string lists serializeComponent
-  // reads, so the emitted markdown is unchanged. emptyValues seeds every repeatable slot to [], so
-  // the id lists start empty and stay in lockstep with the values through addItem/removeItem.
+  // Date.now. The value arrays in working.slots stay the canonical string lists serializeComponent
+  // reads, so the emitted markdown is unchanged. The preview seed can fill a repeatable slot, so
+  // each seeded item needs a parallel id from the start.
   let nextId = 0;
   const itemIds = $state<Record<string, number[]>>(
-    untrack(() => Object.fromEntries((def.slots ?? []).filter((s) => s.kind === 'repeatable').map((s) => [s.name, []]))),
+    untrack(() =>
+      Object.fromEntries(
+        (def.slots ?? [])
+          .filter((s) => s.kind === 'repeatable')
+          .map((s) => {
+            const seeded = working.slots[s.name];
+            const count = Array.isArray(seeded) ? seeded.length : 0;
+            return [s.name, Array.from({ length: count }, () => nextId++)];
+          }),
+      ),
+    ),
   );
 
-  // emptyValues and the itemIds seed both cover every repeatable slot, so this read always hits.
+  // previewValues and the itemIds seed both cover every repeatable slot, so this read always hits.
   function slotIds(name: string): number[] {
     return itemIds[name] ?? [];
   }
@@ -64,41 +102,106 @@ markdown. Back returns to the picker. This is not a nested HTML form; Insert cal
     slotIds(name).splice(index, 1);
   }
 
+  // The row label for a repeatable item: the slot's itemLabel over the item's values and index,
+  // falling back to `${label} ${i + 1}` when it returns nothing. v1 repeatable items hold a single
+  // string under the first item field's key, so the item record passed to itemLabel carries it.
+  function rowLabel(slot: (typeof repeatableSlots)[number], value: string, index: number): string {
+    const fallback = `${slot.label} ${index + 1}`;
+    if (!slot.itemLabel) return fallback;
+    const key = slot.itemFields?.[0]?.key ?? 'text';
+    const derived = slot.itemLabel({ [key]: value }, index);
+    return derived && derived.trim() ? derived : fallback;
+  }
+
   // Typed accessors over the unions so explicit value targets stay sound.
   function asString(key: string): string {
-    const v = values.attributes[key];
+    const v = working.attributes[key];
     return typeof v === 'string' ? v : '';
   }
   function asBool(key: string): boolean {
-    return values.attributes[key] === true;
+    return working.attributes[key] === true;
   }
   function slotString(name: string): string {
-    const v = values.slots[name];
+    const v = working.slots[name];
     return typeof v === 'string' ? v : '';
   }
 
-  // Field-keyed validation errors from the last submit, keyed by attribute key or slot name.
-  let errors = $state<Record<string, string>>({});
+  // A required attribute is unmet only for a text/select/icon field left empty; a boolean is always
+  // met (its false is a real choice). A required slot is unmet when its string is empty or its
+  // repeatable list has no non-empty item. This drives the asterisk-marked fields, the disabled
+  // Insert, and (through the bound `incomplete`) the dialog's incomplete preview state.
+  const incompleteState = $derived.by(() => {
+    for (const field of attributes) {
+      if (!field.required || field.type === 'boolean') continue;
+      if (asString(field.key) === '') return true;
+    }
+    for (const slot of def.slots ?? []) {
+      if (!slot.required) continue;
+      const v = working.slots[slot.name];
+      const filled = Array.isArray(v) ? v.some((i) => i !== '') : typeof v === 'string' && v !== '';
+      if (!filled) return true;
+    }
+    return false;
+  });
+  $effect(() => {
+    incomplete = incompleteState;
+  });
+
+  // Field-keyed validation errors from the last submit (pattern, validate, select-domain), keyed by
+  // attribute key or slot name.
+  let submitErrors = $state<Record<string, string>>({});
+
+  // Fields the editor has touched, so a required-empty error shows after interaction rather than on
+  // a fresh open. Keyed by attribute key or slot name.
+  let touched = $state<Record<string, boolean>>({});
+  function markTouched(key: string): void {
+    touched[key] = true;
+  }
+
+  // The visible field errors. Only the required-empty message ("{label} is required.") shows live,
+  // for a touched-and-empty required field; pattern and validate errors surface on submit. Both are
+  // merged here, the submit errors last so a pattern or validate message wins. Insert stays disabled
+  // while incompleteState holds, so a required-empty field never serializes; this surfaces the why
+  // next to the field meanwhile.
+  const errors = $derived.by(() => {
+    const out: Record<string, string> = {};
+    for (const field of attributes) {
+      if (field.required && field.type !== 'boolean' && touched[field.key] && asString(field.key) === '') {
+        out[field.key] = `${field.label} is required.`;
+      }
+    }
+    for (const slot of def.slots ?? []) {
+      if (!slot.required) continue;
+      const v = working.slots[slot.name];
+      const filled = Array.isArray(v) ? v.some((i) => i !== '') : typeof v === 'string' && v !== '';
+      if (touched[slot.name] && !filled) out[slot.name] = `${slot.label} is required.`;
+    }
+    return { ...out, ...submitErrors };
+  });
+
+  // The form container. Once it is bound, focus its first focusable control so the editor types
+  // straight into the form. The effect tracks formEl so it runs when the node lands; the focus call
+  // is untracked so a later value change does not steal focus back to the first field.
+  let formEl = $state<HTMLElement | null>(null);
+  $effect(() => {
+    if (!formEl) return;
+    untrack(() => formEl!.querySelector<HTMLElement>('input, select, textarea')?.focus());
+  });
 
   // Serialize and validate through the pure helper. On success clear errors and emit the markdown;
   // on failure keep the field-keyed errors so each field can show its message and insert nothing.
   async function submit() {
-    const result = await buildComponentInsert(def, values);
+    const result = await buildComponentInsert(def, working);
     if (result.ok) {
-      errors = {};
+      submitErrors = {};
       onInsert(result.markdown);
     } else {
-      errors = result.errors;
+      submitErrors = result.errors;
     }
   }
 </script>
 
-<div class="flex flex-col gap-3">
-  <div class="flex items-center justify-between">
-    <h3 class="text-sm font-semibold">{def.label}</h3>
-    <button type="button" class="btn btn-ghost btn-xs" onclick={onBack}>Back</button>
-  </div>
-
+<div class="flex flex-col gap-3" bind:this={formEl}>
   {#each attributes as field (field.key)}
     {#if field.type === 'boolean'}
       <label class="label cursor-pointer justify-start gap-2">
@@ -108,19 +211,24 @@ markdown. Back returns to the picker. This is not a nested HTML form; Insert cal
           aria-invalid={Boolean(errors[field.key])}
           aria-describedby={errors[field.key] ? `err-${field.key}` : undefined}
           checked={asBool(field.key)}
-          onchange={(e) => (values.attributes[field.key] = e.currentTarget.checked)}
+          onchange={(e) => (working.attributes[field.key] = e.currentTarget.checked)}
         />
         <span class="text-sm">{field.label}</span>
       </label>
     {:else if field.type === 'select'}
       <label class="flex flex-col gap-1">
-        <span class="text-sm font-medium">{field.label}</span>
+        <span class="text-sm font-medium">{field.label}{#if field.required}<span data-testid="cairn-pk-req" class="text-error" aria-hidden="true">*</span>{/if}</span>
         <select
           class="select"
+          aria-required={field.required ? 'true' : undefined}
           aria-invalid={Boolean(errors[field.key])}
           aria-describedby={errors[field.key] ? `err-${field.key}` : undefined}
           value={asString(field.key)}
-          onchange={(e) => (values.attributes[field.key] = e.currentTarget.value)}
+          onchange={(e) => {
+            working.attributes[field.key] = e.currentTarget.value;
+            markTouched(field.key);
+          }}
+          onblur={() => markTouched(field.key)}
         >
           {#if !field.required}<option value="">—</option>{/if}
           {#each field.options ?? [] as opt (opt)}<option value={opt}>{opt}</option>{/each}
@@ -128,24 +236,29 @@ markdown. Back returns to the picker. This is not a nested HTML form; Insert cal
       </label>
     {:else if field.type === 'icon' && icons}
       <div class="flex flex-col gap-1">
-        <span class="text-sm font-medium">{field.label}</span>
+        <span class="text-sm font-medium">{field.label}{#if field.required}<span data-testid="cairn-pk-req" class="text-error" aria-hidden="true">*</span>{/if}</span>
         <IconPicker
           {icons}
           label={field.label}
           value={asString(field.key)}
           required={field.required ?? false}
-          onChange={(name) => (values.attributes[field.key] = name)}
+          onChange={(name) => (working.attributes[field.key] = name)}
         />
       </div>
     {:else}
       <label class="flex flex-col gap-1">
-        <span class="text-sm font-medium">{field.label}</span>
+        <span class="text-sm font-medium">{field.label}{#if field.required}<span data-testid="cairn-pk-req" class="text-error" aria-hidden="true">*</span>{/if}</span>
         <input
           class="input"
+          aria-required={field.required ? 'true' : undefined}
           aria-invalid={Boolean(errors[field.key])}
           aria-describedby={errors[field.key] ? `err-${field.key}` : undefined}
           value={asString(field.key)}
-          oninput={(e) => (values.attributes[field.key] = e.currentTarget.value)}
+          oninput={(e) => {
+            working.attributes[field.key] = e.currentTarget.value;
+            markTouched(field.key);
+          }}
+          onblur={() => markTouched(field.key)}
         />
       </label>
     {/if}
@@ -155,25 +268,35 @@ markdown. Back returns to the picker. This is not a nested HTML form; Insert cal
   {#each flatSlots as slot (slot.name)}
     {#if slot.kind === 'markdown'}
       <label class="flex flex-col gap-1">
-        <span class="text-sm font-medium">{slot.label}</span>
+        <span class="text-sm font-medium">{slot.label}{#if slot.required}<span data-testid="cairn-pk-req" class="text-error" aria-hidden="true">*</span>{/if}</span>
         <textarea
           class="textarea"
+          aria-required={slot.required ? 'true' : undefined}
           aria-invalid={Boolean(errors[slot.name])}
           aria-describedby={errors[slot.name] ? `err-${slot.name}` : undefined}
           rows={3}
           value={slotString(slot.name)}
-          oninput={(e) => (values.slots[slot.name] = e.currentTarget.value)}
+          oninput={(e) => {
+            working.slots[slot.name] = e.currentTarget.value;
+            markTouched(slot.name);
+          }}
+          onblur={() => markTouched(slot.name)}
         ></textarea>
       </label>
     {:else}
       <label class="flex flex-col gap-1">
-        <span class="text-sm font-medium">{slot.label}</span>
+        <span class="text-sm font-medium">{slot.label}{#if slot.required}<span data-testid="cairn-pk-req" class="text-error" aria-hidden="true">*</span>{/if}</span>
         <input
           class="input"
+          aria-required={slot.required ? 'true' : undefined}
           aria-invalid={Boolean(errors[slot.name])}
           aria-describedby={errors[slot.name] ? `err-${slot.name}` : undefined}
           value={slotString(slot.name)}
-          oninput={(e) => (values.slots[slot.name] = e.currentTarget.value)}
+          oninput={(e) => {
+            working.slots[slot.name] = e.currentTarget.value;
+            markTouched(slot.name);
+          }}
+          onblur={() => markTouched(slot.name)}
         />
       </label>
     {/if}
@@ -184,11 +307,17 @@ markdown. Back returns to the picker. This is not a nested HTML form; Insert cal
     {@const items = slotItems(slot.name)}
     {@const ids = slotIds(slot.name)}
     <fieldset class="rounded-box border border-[var(--cairn-card-border)] flex flex-col gap-2 p-2">
-      <legend class="text-sm font-medium">{slot.label}</legend>
-      <!-- Keyed by the parallel stable id so a mid-list removal drops the right node and focus follows the data; the value still binds to the canonical items[i] string the serializer reads. -->
+      <legend class="text-sm font-medium">{slot.label}{#if slot.required}<span data-testid="cairn-pk-req" class="text-error" aria-hidden="true">*</span>{/if}</legend>
+      <!-- Keyed by the parallel stable id so a mid-list removal drops the right node and focus follows the data; the value still binds to the canonical items[i] string the serializer reads. The visible row tag derives from itemLabel, falling back to the indexed label. -->
       {#each ids as id, i (id)}
+        {@const label = rowLabel(slot, items[i] ?? '', i)}
         <div class="flex items-center gap-2">
-          <input class="input input-sm flex-1" aria-label={`${slot.label} ${i + 1}`} bind:value={items[i]} />
+          <span class="flex-none text-xs text-[var(--color-muted)]">{label}</span>
+          <input
+            class="input input-sm flex-1"
+            aria-label={`${slot.label} ${i + 1}`}
+            bind:value={items[i]}
+          />
           <button type="button" class="btn btn-ghost btn-sm" aria-label={`Remove item ${i + 1}`} onclick={() => removeItem(slot.name, i)}>✕</button>
         </div>
       {/each}
@@ -197,5 +326,5 @@ markdown. Back returns to the picker. This is not a nested HTML form; Insert cal
     </fieldset>
   {/each}
 
-  <button type="button" class="btn btn-primary btn-sm mt-2" onclick={submit}>Insert</button>
+  <button type="button" class="btn btn-primary btn-sm mt-2 self-start" disabled={incompleteState} onclick={submit}>{submitLabel}</button>
 </div>