@glw907/cairn-cms 0.60.0 → 0.62.1

package/src/lib/components/EditPage.svelte

@@ -90,6 +90,11 @@ count, the Prose/Markup posture pair, the focus and typewriter toggles, and the
 
   let { data, registry, render, icons, form }: Props = $props();
 
+  /** One action row in an advisory notice: an `href` row renders a link, an `onAct` row a button. */
+  type AdvisoryRow = { rowLabel?: string; rowCode?: boolean; label: string; href?: string; onAct?: () => void };
+  /** A notice ready to render: the server advisory and the client needs-alt notice both map to this. */
+  type RenderNotice = { kind: string; message: string; detail?: string; rows: AdvisoryRow[] };
+
   // The client-side tidy deadline (spec 2.1, Task 14): a slow call becomes a cancel/retry rather than a
   // hung review. Set above the action's own 30s Worker deadline so the server's retryable fail lands
   // first when the model is merely slow; this catches a stalled connection past that.
@@ -150,7 +155,6 @@ count, the Prose/Markup posture pair, the focus and typewriter toggles, and the
   const bodyDirty = $derived(body !== (form?.body ?? data.body));
   let fieldsDirty = $state(false);
   const dirty = $derived(bodyDirty || fieldsDirty);
-  // What the header's save-state indicator says.
   const saveState = $derived(dirty ? 'Unsaved changes' : data.saved ? 'Saved' : '');
   function onFormInput(e: Event) {
     const target = e.target as Element | null;
@@ -976,6 +980,41 @@ count, the Prose/Markup posture pair, the focus and typewriter toggles, and the
   const heroRows = $derived(imageFields.filter((f) => heroNeedsAlt[f.name]));
   const needsAltCount = $derived(needsAlt.length + heroRows.length);
 
+  // The advisory region renders two notice sources through one shape: the server's data-only
+  // advisories (an action carries an href) and the client-derived needs-alt notice (its rows carry
+  // callbacks the editor must run, so they cannot ride the serializable server shape). Both map into
+  // this local render type, where the snippet draws an href row as a link and an onAct row as a button.
+  const renderNotices = $derived<RenderNotice[]>([
+    ...data.advisories.map((notice) => ({
+      kind: notice.kind,
+      message: notice.message,
+      rows: (notice.actions ?? []).map((action) => ({ label: action.label, href: action.href })),
+    })),
+    ...(needsAltCount
+      ? [
+          {
+            kind: 'needs-alt',
+            message: `${needsAltCount} ${needsAltCount === 1 ? 'image needs' : 'images need'} alt text`,
+            detail:
+              'Alt text describes an image for readers who cannot see it. Add it now, or save and come back to it.',
+            rows: [
+              ...needsAlt.map((item) => ({
+                rowLabel: item.ref,
+                rowCode: true,
+                label: 'Add alt text',
+                onAct: () => selectRange(item.from, item.to),
+              })),
+              ...heroRows.map((hero) => ({
+                rowLabel: hero.label,
+                label: 'Add alt text',
+                onAct: () => heroFieldRefs[hero.name]?.focusAlt(),
+              })),
+            ],
+          },
+        ]
+      : []),
+  ]);
+
   // The delete guard's inbound linkers, from a refused delete (fail 409). Empty when the delete was
   // not refused. When set, a delete was blocked by a link that appeared since the page loaded.
   const deleteRefusedLinks = $derived(form?.inboundLinks ?? []);
@@ -1201,7 +1240,6 @@ count, the Prose/Markup posture pair, the focus and typewriter toggles, and the
     };
   });
 
-  // Coerce a frontmatter value to a string for text/date/textarea inputs.
   function str(v: unknown): string {
     return v == null ? '' : String(v);
   }
@@ -1216,6 +1254,11 @@ count, the Prose/Markup posture pair, the focus and typewriter toggles, and the
   const titleField = $derived(data.fields.find((f) => f.name === 'title'));
   const draftField = $derived(data.fields.find((f) => f.type === 'boolean' && f.name === 'draft'));
   const detailFields = $derived(data.fields.filter((f) => f !== titleField && f !== draftField));
+
+  // The built-in hint a date field carries when its adapter sets no description. The control reads as
+  // if it might schedule publishing, so this reassures the editor that the date is metadata and that
+  // publishing is the separate, deliberate step. A field-level description overrides it.
+  const DATE_PUBLISH_HINT = 'Sets the date for this post. Publishing is a separate step you choose.';
 </script>
 
 <!-- The desk controls live in the one header band: AdminLayout renders this snippet through the
@@ -1342,6 +1385,17 @@ count, the Prose/Markup posture pair, the focus and typewriter toggles, and the
   </div>
 {/snippet}
 
+<!-- The author-facing hint under a Details field. The id pairs with the input's aria-describedby
+     (`<name>-hint`); its uniqueness rests on schema field names being unique within a concept, which
+     is also the loop key. So assistive tech announces the sentence without bloating the accessible
+     name. Each field branch decides whether and where to render it; this snippet holds the one shape.
+     The `fld-hint` class is a styling hook with no rule today; the Tailwind utilities do the work. -->
+{#snippet fieldHint(name: string, text: string)}
+  <p id={`${name}-hint`} class="fld-hint mt-1 text-sm text-[var(--color-muted)]">
+    {text}
+  </p>
+{/snippet}
+
 <!-- The whole edit surface remounts when navigation lands on another entry (see the entryKey
      reset above); script-level state and the beforeNavigate registration sit outside the block,
      so only the template rebuilds. -->
@@ -1388,44 +1442,61 @@ count, the Prose/Markup posture pair, the focus and typewriter toggles, and the
     </ul>
   </div>
 {/if}
-<!-- The publish-time needs-alt notice: a non-blocking warning, never a block. Alt text is
-     accessibility debt, so the author can add it now or save without it; the count drops live as
-     each alt is filled and the notice clears at zero. The leading glyph carries the state alongside
-     the count, so the caution reads without relying on hue. Each row's jump control selects the
-     image in the source through the editor's select-range seam, landing the author on it to type
-     the alt. The role="status" live region renders unconditionally (present and empty at load), so
-     when the first debt appears its count change announces; a region conditionally mounted with its
-     first content may not be observed by assistive tech (WCAG 4.1.3). The visible alert chrome and
-     content gate on the count, so an empty region shows nothing. A plain wrapper (not display:contents)
-     carries the role, since some assistive tech drops a role off a display:contents box. -->
-<div role="status">
-  {#if needsAltCount}
+<!-- The shared advisory notices: one live-region surface for every non-blocking editor warning. It
+     carries the server's address-collision advisory and the client-derived needs-alt notice through
+     one snippet. Each renders as one alert-warning row: the caution glyph, the message, an optional
+     detail sentence, and a list of action rows. Each is a warning, never a block: the author can act
+     on it or save without it. The leading glyph carries the state alongside the message, so the
+     caution reads without relying on hue. A row with an href is a server advisory's link; a row with
+     onAct is the needs-alt jump that runs an editor callback (selecting the image source, or focusing
+     a hero alt input). -->
+<!-- Keyed by index, not by notice.kind: the kind is a free string with no uniqueness constraint, so
+     two notices of one kind would otherwise throw each_key_duplicate. The list is append-only and
+     never reordered, so the index is a stable key here. -->
+{#snippet advisoryNotices(notices: RenderNotice[])}
+  {#each notices as notice, i (i)}
     <div class="alert alert-warning mb-4 flex-col items-start text-sm">
       <p class="flex items-center gap-2 font-medium">
         <svg class="h-4 w-4 shrink-0" viewBox="0 0 24 24" fill="none" stroke="currentColor" aria-hidden="true">
           <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M12 9v4m0 4h.01M10.29 3.86 1.82 18a2 2 0 0 0 1.71 3h16.94a2 2 0 0 0 1.71-3L13.71 3.86a2 2 0 0 0-3.42 0z" />
         </svg>
-        <span>{needsAltCount} {needsAltCount === 1 ? 'image needs' : 'images need'} alt text</span>
+        <span>{notice.message}</span>
       </p>
-      <p>Alt text describes an image for readers who cannot see it. Add it now, or save and come back to it.</p>
-      <ul class="mt-1 w-full">
-        {#each needsAlt as item (item.from)}
-          <li class="flex items-center justify-between gap-2">
-            <code class="text-xs">{item.ref}</code>
-            <button type="button" class="btn btn-xs" onclick={() => selectRange(item.from, item.to)}>Add alt text</button>
-          </li>
-        {/each}
-        <!-- The frontmatter-hero rows: a hero has no body offset, so its action focuses the field's
-             own alt input rather than a source range. -->
-        {#each heroRows as hero (hero.name)}
-          <li class="flex items-center justify-between gap-2">
-            <span class="text-xs font-medium">{hero.label}</span>
-            <button type="button" class="btn btn-xs" onclick={() => heroFieldRefs[hero.name]?.focusAlt()}>Add alt text</button>
-          </li>
-        {/each}
-      </ul>
+      {#if notice.detail}
+        <p>{notice.detail}</p>
+      {/if}
+      {#if notice.rows.length}
+        <ul class="mt-1 w-full">
+          {#each notice.rows as row, i (i)}
+            <li class="flex items-center justify-between gap-2">
+              {#if row.rowLabel}
+                <!-- A body needs-alt row labels with its source reference in a code span; a hero row
+                     and any future labelled row use a plain label. -->
+                {#if row.rowCode}
+                  <code class="text-xs">{row.rowLabel}</code>
+                {:else}
+                  <span class="text-xs font-medium">{row.rowLabel}</span>
+                {/if}
+              {/if}
+              {#if row.href}
+                <a class="btn btn-xs" href={row.href}>{row.label}</a>
+              {:else}
+                <button type="button" class="btn btn-xs" onclick={row.onAct}>{row.label}</button>
+              {/if}
+            </li>
+          {/each}
+        </ul>
+      {/if}
     </div>
-  {/if}
+  {/each}
+{/snippet}
+<!-- The role="status" live region renders unconditionally (present and empty at load), so when the
+     first notice appears it announces; a region conditionally mounted with its first content may not
+     be observed by assistive tech (WCAG 4.1.3). The notices gate on their own presence, so an empty
+     region shows nothing. A plain wrapper (not display:contents) carries the role, since some
+     assistive tech drops a role off a display:contents box. -->
+<div role="status">
+  {@render advisoryNotices(renderNotices)}
 </div>
 {#if draftWarning}
   <div class="alert alert-warning mb-4 text-sm">
@@ -1817,23 +1888,37 @@ count, the Prose/Markup posture pair, the focus and typewriter toggles, and the
           {@const f = field as TextareaField}
           <label class="flex flex-col gap-1">
             <span class="text-sm font-medium">{f.label}</span>
-            <textarea class="textarea textarea-sm" name={f.name} aria-label={f.label} rows={f.rows ?? 3}>{str(data.frontmatter[f.name])}</textarea>
+            <textarea class="textarea textarea-sm" name={f.name} aria-label={f.label} aria-describedby={f.description ? `${f.name}-hint` : undefined} rows={f.rows ?? 3}>{str(data.frontmatter[f.name])}</textarea>
+            {#if f.description}
+              {@render fieldHint(f.name, f.description)}
+            {/if}
           </label>
         {:else if field.type === 'date'}
           <label class="flex flex-col gap-1">
             <span class="text-sm font-medium">{field.label}</span>
-            <input class="input input-sm" type="date" name={field.name} aria-label={field.label} value={str(data.frontmatter[field.name])} />
+            <!-- A date field always carries a hint: the adapter's description when set, else the
+                 built-in publish-clarity default. So aria-describedby always points at the paragraph. -->
+            <input class="input input-sm" type="date" name={field.name} aria-label={field.label} aria-describedby={`${field.name}-hint`} value={str(data.frontmatter[field.name])} />
+            {@render fieldHint(field.name, field.description || DATE_PUBLISH_HINT)}
           </label>
         {:else if field.type === 'boolean'}
-          <label class="label cursor-pointer justify-start gap-2">
-            <input class="checkbox checkbox-sm" type="checkbox" name={field.name} aria-label={field.label} checked={data.frontmatter[field.name] === true} />
-            <span class="text-sm">{field.label}</span>
-          </label>
+          <div class="flex flex-col gap-1">
+            <label class="label cursor-pointer justify-start gap-2">
+              <input class="checkbox checkbox-sm" type="checkbox" name={field.name} aria-label={field.label} aria-describedby={field.description ? `${field.name}-hint` : undefined} checked={data.frontmatter[field.name] === true} />
+              <span class="text-sm">{field.label}</span>
+            </label>
+            {#if field.description}
+              {@render fieldHint(field.name, field.description)}
+            {/if}
+          </div>
         {:else if field.type === 'tags'}
           {@const f = field as TagsField}
           {@const selected = (data.frontmatter[f.name] ?? []) as string[]}
-          <fieldset class="fieldset">
+          <fieldset class="fieldset" aria-describedby={f.description ? `${f.name}-hint` : undefined}>
             <legend class="fieldset-legend">{f.label}</legend>
+            {#if f.description}
+              {@render fieldHint(f.name, f.description)}
+            {/if}
             <div class="flex flex-wrap gap-2">
               {#each f.options as option (option)}
                 <label class="label cursor-pointer justify-start gap-2">
@@ -1858,9 +1943,13 @@ count, the Prose/Markup posture pair, the focus and typewriter toggles, and the
               class="input input-sm"
               name={f.name}
               aria-label={f.label}
+              aria-describedby={f.description ? `${f.name}-hint` : undefined}
               placeholder={f.placeholder}
               value={tagValue}
             />
+            {#if f.description}
+              {@render fieldHint(f.name, f.description)}
+            {/if}
           </label>
         {:else if field.type === 'image'}
           {@const heroValue = data.frontmatter[field.name] as ImageValue | undefined}
@@ -1879,7 +1968,10 @@ count, the Prose/Markup posture pair, the focus and typewriter toggles, and the
         {:else}
           <label class="flex flex-col gap-1">
             <span class="text-sm font-medium">{field.label}</span>
-            <input class="input input-sm" name={field.name} aria-label={field.label} value={str(data.frontmatter[field.name])} required={field.required} />
+            <input class="input input-sm" name={field.name} aria-label={field.label} aria-describedby={field.description ? `${field.name}-hint` : undefined} value={str(data.frontmatter[field.name])} required={field.required} />
+            {#if field.description}
+              {@render fieldHint(field.name, field.description)}
+            {/if}
           </label>
         {/if}
       {/each}