@glw907/cairn-cms 0.56.1 → 0.57.0

package/dist/components/MediaCaptureCard.svelte

@@ -0,0 +1,135 @@
+<!--
+@component
+The one-step capture card for a media insert. Shown when an author already has bytes in hand (a
+paste, a drop, or a chosen file), it captures three things and emits them to its host: the file, an
+editable display name, and the alt text. It is a presentational form card, not a dialog of its own;
+Task 6's insert popover hosts it.
+
+The display name pre-fills from proposedNameFor(file.name): a real specific stem (blue-shoes.png)
+arrives as a Suggested value, while a generic camera stem (IMG_4821.jpg) leaves the field empty and
+required with no tag, so the author never accepts machine noise.
+
+Alt is a real role="radiogroup" of two radios: write a description, or mark decorative. The
+requirement is surfaced through aria-describedby, never by disabling the submit. Insert is never
+disabled (the locked no-skipped-disabled-reason rule); an author may proceed with alt unset and the
+emitted record carries an empty alt, which the host treats as needs-alt debt. A decorative choice
+also resolves alt to the empty string. The committed reference keys off an empty alt as the
+needs-alt signal, so the emitted record uses an empty alt string for both the decorative and the
+left-blank cases, and a separate decorative flag distinguishes them for the host.
+-->
+<script lang="ts">
+  import { untrack } from 'svelte';
+  import { proposedNameFor } from './client-ingest.js';
+
+  /** The record the card emits to its host on insert. */
+  interface CaptureRecord {
+    /** The image bytes the author is placing. */
+    file: File;
+    /** The editable display name, the proposed stem or the author's edit. */
+    displayName: string;
+    /** The alt text. Empty for a decorative image or for an author who proceeded without alt; the
+     *  host commits an empty alt as the needs-alt signal in the `![](media:...)` reference. */
+    alt: string;
+    /** True when the author marked the image decorative, distinguishing a deliberate empty alt from
+     *  a left-blank one. The committed alt is empty either way. */
+    decorative: boolean;
+  }
+
+  interface Props {
+    /** The image to capture; the card previews it from a local object URL. */
+    file: File;
+    /** Emit the captured record to the host on insert. */
+    oncapture: (record: CaptureRecord) => void;
+  }
+
+  let { file, oncapture }: Props = $props();
+
+  // The proposed display name for this file, computed once. A real stem pre-fills the field and shows
+  // the Suggested tag; a generic stem yields null, leaving the field empty, required, and untagged.
+  const proposed = $derived(proposedNameFor(file.name));
+  // Seeded once from the file the card opened with; untrack marks it a deliberate one-time read, not
+  // a reactive miss. The card lives for one file, so a later file swap is out of scope.
+  let displayName = $state(untrack(() => proposedNameFor(file.name) ?? ''));
+
+  // The alt mode: unset until the author picks one, then 'describe' or 'decorative'. Unset emits an
+  // empty alt (needs-alt debt); insert never blocks on it.
+  let altMode = $state<'describe' | 'decorative' | null>(null);
+  let altText = $state('');
+
+  // A local object URL for the preview. Allocation and revoke live in ONE $effect keyed on the file,
+  // never in a $derived: a derivation that calls createObjectURL allocates a resource as a side
+  // effect, which can desync from the revoke (a re-derive leaks the prior URL). The matched effect
+  // revokes on teardown and on any file change, so the blob never leaks.
+  let previewUrl = $state('');
+  $effect(() => {
+    const url = URL.createObjectURL(file);
+    previewUrl = url;
+    return () => URL.revokeObjectURL(url);
+  });
+
+  function submit(e: SubmitEvent) {
+    e.preventDefault();
+    // Decorative and write-but-blank both commit an empty alt; the decorative flag distinguishes
+    // them for the host. A described image carries the trimmed alt text.
+    const alt = altMode === 'describe' ? altText.trim() : '';
+    oncapture({ file, displayName: displayName.trim(), alt, decorative: altMode === 'decorative' });
+  }
+</script>
+
+<form class="flex flex-col gap-4" onsubmit={submit}>
+  <div class="flex items-start gap-3">
+    <img
+      src={previewUrl}
+      alt=""
+      class="h-16 w-16 flex-none rounded-box border border-[var(--cairn-card-border)] object-cover"
+    />
+    <label class="flex flex-1 flex-col gap-1">
+      <span class="flex items-center gap-2 text-sm font-medium">
+        Name
+        {#if proposed !== null}
+          <span class="badge badge-ghost badge-sm">Suggested</span>
+        {/if}
+      </span>
+      <input
+        class="input w-full"
+        aria-required={proposed === null ? 'true' : undefined}
+        placeholder="What is this image?"
+        bind:value={displayName}
+      />
+    </label>
+  </div>
+
+  <fieldset
+    class="flex flex-col gap-2"
+    role="radiogroup"
+    aria-label="Alt text"
+    aria-required="true"
+    aria-describedby="cairn-capture-alt-note"
+  >
+    <legend class="text-sm font-medium">Alt text</legend>
+    <p id="cairn-capture-alt-note" class="text-xs text-[var(--color-muted)]">
+      Describe the image for screen readers, or mark it decorative. You can insert without alt text
+      and add it later.
+    </p>
+    <label class="flex cursor-pointer items-center gap-2">
+      <input type="radio" class="radio radio-sm" name="cairn-capture-alt" value="describe" bind:group={altMode} />
+      <span class="text-sm">Write a description</span>
+    </label>
+    {#if altMode === 'describe'}
+      <input
+        class="input input-sm ml-6 w-[calc(100%-1.5rem)]"
+        aria-label="Alt text description"
+        placeholder="A short description"
+        bind:value={altText}
+      />
+    {/if}
+    <label class="flex cursor-pointer items-center gap-2">
+      <input type="radio" class="radio radio-sm" name="cairn-capture-alt" value="decorative" bind:group={altMode} />
+      <span class="text-sm">Mark as decorative</span>
+    </label>
+  </fieldset>
+
+  <div class="flex justify-end">
+    <button type="submit" class="btn btn-sm btn-primary">Insert image</button>
+  </div>
+</form>

package/dist/components/MediaCaptureCard.svelte.d.ts

@@ -0,0 +1,40 @@
+/** The record the card emits to its host on insert. */
+interface CaptureRecord {
+    /** The image bytes the author is placing. */
+    file: File;
+    /** The editable display name, the proposed stem or the author's edit. */
+    displayName: string;
+    /** The alt text. Empty for a decorative image or for an author who proceeded without alt; the
+     *  host commits an empty alt as the needs-alt signal in the `![](media:...)` reference. */
+    alt: string;
+    /** True when the author marked the image decorative, distinguishing a deliberate empty alt from
+     *  a left-blank one. The committed alt is empty either way. */
+    decorative: boolean;
+}
+interface Props {
+    /** The image to capture; the card previews it from a local object URL. */
+    file: File;
+    /** Emit the captured record to the host on insert. */
+    oncapture: (record: CaptureRecord) => void;
+}
+/**
+ * The one-step capture card for a media insert. Shown when an author already has bytes in hand (a
+ * paste, a drop, or a chosen file), it captures three things and emits them to its host: the file, an
+ * editable display name, and the alt text. It is a presentational form card, not a dialog of its own;
+ * Task 6's insert popover hosts it.
+ *
+ * The display name pre-fills from proposedNameFor(file.name): a real specific stem (blue-shoes.png)
+ * arrives as a Suggested value, while a generic camera stem (IMG_4821.jpg) leaves the field empty and
+ * required with no tag, so the author never accepts machine noise.
+ *
+ * Alt is a real role="radiogroup" of two radios: write a description, or mark decorative. The
+ * requirement is surfaced through aria-describedby, never by disabling the submit. Insert is never
+ * disabled (the locked no-skipped-disabled-reason rule); an author may proceed with alt unset and the
+ * emitted record carries an empty alt, which the host treats as needs-alt debt. A decorative choice
+ * also resolves alt to the empty string. The committed reference keys off an empty alt as the
+ * needs-alt signal, so the emitted record uses an empty alt string for both the decorative and the
+ * left-blank cases, and a separate decorative flag distinguishes them for the host.
+ */
+declare const MediaCaptureCard: import("svelte").Component<Props, {}, "">;
+type MediaCaptureCard = ReturnType<typeof MediaCaptureCard>;
+export default MediaCaptureCard;

package/dist/components/MediaFigureControl.svelte

@@ -0,0 +1,247 @@
+<!--
+@component
+The figure control form: the caption and placement an author gives an inline media image. The host
+(EditPage) opens it over the media image at the caret, in `wrap` mode for a bare image or `edit` mode
+for an existing `:::figure`. It is the form CONTENT only; the host mounts it inside the Edit-block
+dialog. On submit it emits the chosen caption and role through `onapply`; in edit mode it also offers
+`onunwrap` to strip the figure back to the bare image.
+
+The caption is the visible line under the image, distinct from the alt text. The control surfaces the
+image's alt state (Described or Needs alt) that the host derives and passes; the deep needs-alt wiring
+is the host's. When the image is decorative AND the author gives it a caption, the control warns: a
+decorative image is hidden from screen readers, so a visible caption on it is a contradiction.
+
+The placement is a roving-tabindex radiogroup (Measure, Center, Wide, Full): one bordered group, the
+active segment tinted with a check glyph (the non-color state cue, WCAG 1.4.1), arrow keys move and
+select. Measure maps to the null role (the measure default, no role brace); the others map to their
+own name.
+-->
+<script lang="ts">
+  import { untrack } from 'svelte';
+  import type { FigureRole } from './markdown-format.js';
+
+  /** The roles the segmented control offers, with Measure standing for the null (measure-default)
+   *  role. Declared as a const tuple so the segment loop and the keyboard handler share one source. */
+  const ROLE_OPTIONS: { value: FigureRole | null; label: string }[] = [
+    { value: null, label: 'Measure' },
+    { value: 'center', label: 'Center' },
+    { value: 'wide', label: 'Wide' },
+    { value: 'full', label: 'Full' },
+  ];
+
+  interface Props {
+    /** The initial caption; the field seeds from it and the author edits a local copy. */
+    caption?: string;
+    /** The initial placement role, or null for the measure default. */
+    role?: FigureRole | null;
+    /** `wrap` for a bare image (the primary action wraps it), `edit` for an existing figure (the
+     *  primary action updates it and a ghost action unwraps it). */
+    mode?: 'wrap' | 'edit';
+    /** Whether the image's alt is empty or marked decorative; the host derives it. Drives the
+     *  alt-status row and the decorative-plus-caption warning. */
+    decorative?: boolean;
+    /** Emit the chosen caption and role: the host wraps (wrap mode) or updates (edit mode). */
+    onapply: (choice: { caption: string; role: FigureRole | null }) => void;
+    /** Emit the unwrap action (edit mode only); the host replaces the figure with its bare image. */
+    onunwrap?: () => void;
+  }
+
+  let { caption = '', role = null, mode = 'wrap', decorative = false, onapply, onunwrap }: Props =
+    $props();
+
+  // The author's working copies, seeded once from the props the control opened with. untrack marks
+  // the read a deliberate one-time seed (the control mounts fresh per image), not a reactive miss.
+  let captionValue = $state(untrack(() => caption));
+  let roleValue = $state<FigureRole | null>(untrack(() => role));
+
+  // The index of the active role in ROLE_OPTIONS, the roving-tabindex focus target.
+  const activeIndex = $derived(ROLE_OPTIONS.findIndex((o) => o.value === roleValue));
+
+  // The decorative-plus-caption contradiction: a decorative image is hidden from screen readers, so a
+  // visible caption on it is a state to flag (never blocked, surfaced for the author to resolve).
+  const decorativeWithCaption = $derived(decorative && captionValue.trim() !== '');
+
+  // The segment refs, so arrow-key navigation can move focus to the newly selected segment.
+  let segmentEls = $state<HTMLButtonElement[]>([]);
+
+  function pickRole(value: FigureRole | null) {
+    roleValue = value;
+  }
+
+  // Arrow keys move and select within the radiogroup (the roving-tabindex pattern); Home/End jump to
+  // the ends. Selection follows focus, the standard radiogroup behavior.
+  function onSegmentKeydown(e: KeyboardEvent, index: number) {
+    let next = index;
+    if (e.key === 'ArrowRight' || e.key === 'ArrowDown') next = (index + 1) % ROLE_OPTIONS.length;
+    else if (e.key === 'ArrowLeft' || e.key === 'ArrowUp')
+      next = (index - 1 + ROLE_OPTIONS.length) % ROLE_OPTIONS.length;
+    else if (e.key === 'Home') next = 0;
+    else if (e.key === 'End') next = ROLE_OPTIONS.length - 1;
+    else return;
+    e.preventDefault();
+    pickRole(ROLE_OPTIONS[next].value);
+    segmentEls[next]?.focus();
+  }
+
+  function submit(e: SubmitEvent) {
+    e.preventDefault();
+    onapply({ caption: captionValue.trim(), role: roleValue });
+  }
+</script>
+
+<form class="flex flex-col gap-4" onsubmit={submit}>
+  <div class="flex flex-col gap-1">
+    <label for="cairn-figure-caption" class="text-sm font-medium">Caption</label>
+    <input
+      id="cairn-figure-caption"
+      class="input w-full"
+      type="text"
+      placeholder="Describe what the image adds to the post"
+      aria-describedby="cairn-figure-caption-hint"
+      bind:value={captionValue}
+    />
+    <p id="cairn-figure-caption-hint" class="text-xs text-[var(--color-muted)]">
+      Shown under the image, for everyone. This is not the alt text.
+    </p>
+  </div>
+
+  <!-- The alt-status row: the image's alt state the host derives. Described or Needs alt, the latter
+       in the warning ink with a glyph so the state never rides hue alone (WCAG 1.4.1). -->
+  <div class="flex items-center gap-2 text-sm">
+    <span class="font-medium" aria-hidden="true">Alt text</span>
+    {#if decorative}
+      <span
+        class="inline-flex items-center gap-1 font-medium text-[var(--cairn-warning-ink)]"
+        data-cairn-alt-status="needs"
+        aria-label="Alt text: needs a description"
+      >
+        <svg
+          width="13"
+          height="13"
+          viewBox="0 0 24 24"
+          fill="none"
+          stroke="currentColor"
+          stroke-width="2.4"
+          stroke-linecap="round"
+          stroke-linejoin="round"
+          aria-hidden="true"
+        >
+          <path d="M10.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" />
+          <line x1="12" y1="9" x2="12" y2="13" />
+          <line x1="12" y1="17" x2="12.01" y2="17" />
+        </svg>
+        Needs alt
+      </span>
+    {:else}
+      <span
+        class="inline-flex items-center gap-1 text-[var(--color-muted)]"
+        data-cairn-alt-status="described"
+        aria-label="Alt text: described"
+      >
+        <svg
+          width="13"
+          height="13"
+          viewBox="0 0 24 24"
+          fill="none"
+          stroke="currentColor"
+          stroke-width="3"
+          stroke-linecap="round"
+          stroke-linejoin="round"
+          aria-hidden="true"
+        >
+          <path d="M20 6 9 17l-5-5" />
+        </svg>
+        Described
+      </span>
+    {/if}
+  </div>
+
+  <div class="flex flex-col gap-1">
+    <span id="cairn-figure-placement-label" class="text-sm font-medium">Placement</span>
+    <!-- The segmented control: one bordered group, borderless segments, the active one tinted with a
+         check glyph. A roving-tabindex radiogroup, so arrow keys move and select and one Tab stop
+         reaches the group. -->
+    <div
+      role="radiogroup"
+      aria-labelledby="cairn-figure-placement-label"
+      class="bg-base-100 inline-flex items-center self-start overflow-hidden rounded-lg border border-[var(--cairn-card-border)]"
+    >
+      {#each ROLE_OPTIONS as option, index (option.label)}
+        {@const pressed = roleValue === option.value}
+        <button
+          bind:this={segmentEls[index]}
+          type="button"
+          role="radio"
+          aria-checked={pressed}
+          tabindex={index === activeIndex ? 0 : -1}
+          class="inline-flex items-center gap-1 px-2.5 py-1 text-xs font-normal {index > 0
+            ? 'border-l border-[var(--cairn-card-border)]'
+            : ''} {pressed ? 'bg-primary/10 text-primary font-medium' : 'text-[var(--color-muted)]'}"
+          onclick={() => pickRole(option.value)}
+          onkeydown={(e) => onSegmentKeydown(e, index)}
+        >
+          {#if pressed}
+            <svg
+              class="h-3 w-3"
+              viewBox="0 0 24 24"
+              fill="none"
+              stroke="currentColor"
+              stroke-width="2.5"
+              stroke-linecap="round"
+              stroke-linejoin="round"
+              aria-hidden="true"
+            >
+              <path d="M20 6 9 17l-5-5" />
+            </svg>
+          {/if}
+          {option.label}
+        </button>
+      {/each}
+    </div>
+    <p class="text-xs text-[var(--color-muted)]">
+      Center suits an image narrower than the text column. Measure keeps it at the column width.
+    </p>
+  </div>
+
+  <!-- An always-present polite live region, so the contradiction announces when it appears in
+       response to the author's own typing (not only on the dialog's open read). Empty and invisible
+       until the warning fills it. -->
+  <div role="status" aria-live="polite">
+    {#if decorativeWithCaption}
+    <div
+      class="flex items-start gap-2 rounded-[0.55rem] p-2.5 text-[var(--cairn-warning-ink)]"
+      style="background: color-mix(in oklab, var(--cairn-warning-ink) 8%, transparent);"
+    >
+      <svg
+        width="14"
+        height="14"
+        viewBox="0 0 24 24"
+        fill="none"
+        stroke="currentColor"
+        stroke-width="2.2"
+        stroke-linecap="round"
+        stroke-linejoin="round"
+        class="mt-0.5 flex-none"
+        aria-hidden="true"
+      >
+        <path d="M10.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" />
+        <line x1="12" y1="9" x2="12" y2="13" />
+        <line x1="12" y1="17" x2="12.01" y2="17" />
+      </svg>
+      <p class="m-0 text-xs leading-relaxed">
+        A decorative image is hidden from screen readers, but this one has a caption. Describe it, or
+        remove the caption.
+      </p>
+    </div>
+    {/if}
+  </div>
+
+  <div class="flex justify-end gap-2">
+    {#if mode === 'edit'}
+      <button type="button" class="btn btn-sm btn-ghost" onclick={() => onunwrap?.()}>Unwrap</button>
+      <button type="submit" class="btn btn-sm btn-primary">Update figure</button>
+    {:else}
+      <button type="submit" class="btn btn-sm btn-primary">Wrap in figure</button>
+    {/if}
+  </div>
+</form>

package/dist/components/MediaFigureControl.svelte.d.ts

@@ -0,0 +1,40 @@
+import type { FigureRole } from './markdown-format.js';
+interface Props {
+    /** The initial caption; the field seeds from it and the author edits a local copy. */
+    caption?: string;
+    /** The initial placement role, or null for the measure default. */
+    role?: FigureRole | null;
+    /** `wrap` for a bare image (the primary action wraps it), `edit` for an existing figure (the
+     *  primary action updates it and a ghost action unwraps it). */
+    mode?: 'wrap' | 'edit';
+    /** Whether the image's alt is empty or marked decorative; the host derives it. Drives the
+     *  alt-status row and the decorative-plus-caption warning. */
+    decorative?: boolean;
+    /** Emit the chosen caption and role: the host wraps (wrap mode) or updates (edit mode). */
+    onapply: (choice: {
+        caption: string;
+        role: FigureRole | null;
+    }) => void;
+    /** Emit the unwrap action (edit mode only); the host replaces the figure with its bare image. */
+    onunwrap?: () => void;
+}
+/**
+ * The figure control form: the caption and placement an author gives an inline media image. The host
+ * (EditPage) opens it over the media image at the caret, in `wrap` mode for a bare image or `edit` mode
+ * for an existing `:::figure`. It is the form CONTENT only; the host mounts it inside the Edit-block
+ * dialog. On submit it emits the chosen caption and role through `onapply`; in edit mode it also offers
+ * `onunwrap` to strip the figure back to the bare image.
+ *
+ * The caption is the visible line under the image, distinct from the alt text. The control surfaces the
+ * image's alt state (Described or Needs alt) that the host derives and passes; the deep needs-alt wiring
+ * is the host's. When the image is decorative AND the author gives it a caption, the control warns: a
+ * decorative image is hidden from screen readers, so a visible caption on it is a contradiction.
+ *
+ * The placement is a roving-tabindex radiogroup (Measure, Center, Wide, Full): one bordered group, the
+ * active segment tinted with a check glyph (the non-color state cue, WCAG 1.4.1), arrow keys move and
+ * select. Measure maps to the null role (the measure default, no role brace); the others map to their
+ * own name.
+ */
+declare const MediaFigureControl: import("svelte").Component<Props, {}, "">;
+type MediaFigureControl = ReturnType<typeof MediaFigureControl>;
+export default MediaFigureControl;