@glw907/cairn-cms 0.60.1 → 0.62.2

package/CHANGELOG.md

@@ -2,6 +2,84 @@
 
 All notable changes to this project are recorded here, most recent first.
 
+## 0.62.2
+
+The edit-load address-collision advisory now checks the published corpus only. It fires when an entry
+you are editing collides with an entry already published on `main`, and it no longer reads sibling
+`cairn/<concept>/<id>` branches when an editor opens an entry, so opening the editor adds no GitHub
+reads. The publish-time re-check is unchanged: it stays full cross-branch and still emits the
+`publish.address_collision` log event when a publish overrides another entry's address. No consumer
+action is required.
+
+## 0.62.1
+
+The entry editor gains an advisory channel and its first notice: a cross-branch address-collision
+warning. When another entry already resolves to the same public address, the editor shows a
+non-blocking warning that names that entry and links to it. The warning never blocks Publish. It makes
+the last-write-wins outcome visible instead of silent, since publishing replaces whatever currently
+lives at that address.
+
+The check runs at edit-load across `main` and every open `cairn/<concept>/<id>` branch. A publish
+re-checks the address and emits a `publish.address_collision` log event (level `warn`, fields `editor`,
+`address`, `displacedConcept`, `displacedId`) when it overrides one. The existing needs-alt notice now
+renders through the same advisory region, with its live count and per-row actions unchanged.
+
+This adds two exported types on `/sveltekit`, `AdvisoryNotice` and `AdvisoryAction`, the shape
+`EditData.advisories` carries. No consumer action is required.
+
+## 0.62.0
+
+<!-- release-size: minor -->
+
+The admin gains a Help home, the pull half of the in-admin editor help. It is a standing screen at
+`/admin/help`, reached from a labeled Help home pinned at the foot of the office sidebar (and from the
+Ctrl+K command palette).
+
+The screen carries three sections. A getting-started checklist derives its progress from what is
+really on the site: writing a post, publishing one, and creating a page. The count is never stored, so
+it always reflects the corpus, and the whole section drops away once all three steps are done. A hide
+control tucks it away per device. A formatting reference promotes the editor's Ctrl+/ cheat sheet to a
+standing two-column table. A support hand-off points a stuck author at the site's `supportContact`,
+shaped to the contact (an email opens a `mailto`, a URL opens a link, anything else shows as a note),
+and it renders only when the adapter sets one.
+
+This adds two exports: the `HelpHome` component on the `/components` subpath and the `HelpData` type on
+`/sveltekit`. The new `/admin/help` route is additive.
+
+No consumer action is required. A site that sets no `supportContact` sees the Help home with a
+self-serve line in place of the contact hand-off.
+
+This release also fixes the admin-copy prose gate (`check:prose`): a component whose `@component` doc
+comment wrote the literal `<style>` tag had its whole markup silently skipped, so its copy was never
+scanned. The gate now strips comments before the script and style blocks.
+
+## 0.61.0
+
+<!-- release-size: minor -->
+
+The editor gains the groundwork for in-admin help. This pass adds the engine seams and one built-in
+clarity default the help layer will build on.
+
+A frontmatter field can now carry a `description`: one author-facing sentence shown under the field in
+the editor's Details panel and tied to the input with `aria-describedby`. Set it on any field in a
+concept's `defineFields` schema.
+
+The `date` field ships a built-in publish-clarity hint ("Sets the date for this post. Publishing is a
+separate step you choose.") when the field sets no `description`, so a new site gets the reassurance
+without writing per-field copy. A field-level `description` overrides it; the hint cannot be turned
+off, only replaced.
+
+The adapter gains an optional `supportContact`: an email, a URL, or a name and instruction the
+in-admin help points a stuck editor to. It passes through to the runtime untouched, and the help
+renders the hand-off only when it is set, so there is never a button to a blank contact.
+
+The admin design system documents the recipes the help shell will follow, including the non-modal help
+region, the single right-slide-over slot, the disclosure-button ARIA contract, the getting-started
+progress checklist, and the empty-state starter slot.
+
+No consumer action is required. Every change is additive: the new field and adapter members are
+optional, and a site that sets neither sees only the date field's new default hint.
+
 ## 0.60.1
 
 A packaging fix so the library bundles cleanly in a Vite 8 consumer. It supersedes `0.60.0`, whose

package/dist/components/AdminLayout.svelte

@@ -21,6 +21,7 @@ import UsersIcon from "@lucide/svelte/icons/users";
 import ImageIcon from "@lucide/svelte/icons/image";
 import BlocksIcon from "@lucide/svelte/icons/blocks";
 import ExternalLinkIcon from "@lucide/svelte/icons/external-link";
+import HelpCircleIcon from "@lucide/svelte/icons/circle-help";
 import "./cairn-admin.css";
 let { data, children } = $props();
 setContext(CSRF_CONTEXT_KEY, () => data.csrf);
@@ -109,6 +110,7 @@ onMount(() => {
 });
 const paletteCommands = $derived([
   ...coreItems.map((item) => ({ label: item.label, icon: item.icon, href: item.href })),
+  { label: "Help", icon: HelpCircleIcon, href: "/admin/help" },
   { label: "View the live site", icon: ExternalLinkIcon, href: "/", external: true },
   theme === "cairn-admin" ? { label: "Switch to dark mode", icon: MoonIcon, action: toggleTheme } : { label: "Switch to light mode", icon: SunIcon, action: toggleTheme }
 ]);
@@ -379,6 +381,26 @@ provideTopbar(topbar);
           {/each}
         </div>
 
+        <!-- Help is a standing utility destination, pinned at the foot of the nav and set apart from
+             the content concepts by a top hairline. It is always present, labeled in plain text, and
+             styled as a peer of the nav items above it. -->
+        <div class="flex-none border-t border-[var(--cairn-card-border)] px-2 py-2">
+          <ul class="menu menu-sm w-full gap-0.5 p-0">
+            <li>
+              <a
+                href="/admin/help"
+                class={isActive('/admin/help')
+                  ? 'bg-primary/10 font-semibold text-primary'
+                  : 'font-medium text-[var(--color-subtle)]'}
+                aria-current={isActive('/admin/help') ? 'page' : undefined}
+              >
+                <HelpCircleIcon class="h-4 w-4" aria-hidden="true" />
+                Help
+              </a>
+            </li>
+          </ul>
+        </div>
+
         <div class="flex-none border-t border-[var(--cairn-card-border)] px-5 py-4">
           <div class="flex items-center gap-3">
             <div class="avatar avatar-placeholder">

package/dist/components/CairnAdmin.svelte

@@ -14,6 +14,7 @@ import ManageEditors from "./ManageEditors.svelte";
 import NavTree from "./NavTree.svelte";
 import CairnMediaLibrary from "./CairnMediaLibrary.svelte";
 import CairnTidySettings from "./CairnTidySettings.svelte";
+import HelpHome from "./HelpHome.svelte";
 let { data, form = null, render, registry, icons } = $props();
 </script>
 
@@ -40,6 +41,8 @@ let { data, form = null, render, registry, icons } = $props();
       <CairnMediaLibrary data={data.page} {form} />
     {:else if data.view === 'settings'}
       <CairnTidySettings data={data.page} />
+    {:else if data.view === 'help'}
+      <HelpHome data={data.page} />
     {/if}
   </AdminLayout>
 {/if}

package/dist/components/CairnTidySettings.svelte

@@ -8,7 +8,7 @@ Two tiers with a truthful visibility gate:
     that tidy is enabled, a key is configured, and which model runs, but cannot edit any of it. The
     literal deploy-time tokens sit in a marked "For your developer" sub-block.
   - The EDITOR tier (the per-convention config) renders ONLY when tidy is enabled AND the key is
-    present (`data.enabled`). When tidy is not enabled, the editor tier is genuinely ABSENT, replaced
+    present (`data.enabled`). When tidy is not enabled, the editor tier is ABSENT, replaced
     by an honest labelled gate region with a read-only "what your developer needs to do" checklist and
     a "spellcheck still works" reassurance. No teasing disabled controls sit in the tab order.
 
@@ -448,7 +448,7 @@ function segClass(on) {
       </div>
     </form>
   {:else}
-    <!-- THE VISIBILITY GATE: tidy NOT enabled by the developer. The convention list is genuinely
+    <!-- THE VISIBILITY GATE: tidy NOT enabled by the developer. The convention list is
          absent, not disabled. One honest labelled region names the deploy-time task and who does it,
          with no disabled controls in the tab order. -->
     <div role="region" aria-label="Tidy is not set up" class="mt-6 flex flex-col items-center gap-3 rounded-2xl border border-[var(--cairn-card-border)] bg-base-100 p-10 text-center shadow-[var(--cairn-shadow)]">

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

@@ -13,7 +13,7 @@ interface Props {
  *   that tidy is enabled, a key is configured, and which model runs, but cannot edit any of it. The
  *   literal deploy-time tokens sit in a marked "For your developer" sub-block.
  * - The EDITOR tier (the per-convention config) renders ONLY when tidy is enabled AND the key is
- *   present (`data.enabled`). When tidy is not enabled, the editor tier is genuinely ABSENT, replaced
+ *   present (`data.enabled`). When tidy is not enabled, the editor tier is ABSENT, replaced
  *   by an honest labelled gate region with a read-only "what your developer needs to do" checklist and
  *   a "spellcheck still works" reassurance. No teasing disabled controls sit in the tab order.
  *

package/dist/components/EditPage.svelte

@@ -560,6 +560,33 @@ const imageFields = $derived(
 );
 const heroRows = $derived(imageFields.filter((f) => heroNeedsAlt[f.name]));
 const needsAltCount = $derived(needsAlt.length + heroRows.length);
+const renderNotices = $derived([
+  ...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()
+        }))
+      ]
+    }
+  ] : []
+]);
 const deleteRefusedLinks = $derived(form?.inboundLinks ?? []);
 const formError = $derived(
   form?.error && !form.brokenLinks?.length && !form.inboundLinks?.length ? form.error : ""
@@ -715,6 +742,7 @@ const eyebrowClass = "mb-2 text-[0.6875rem] font-semibold uppercase tracking-[0.
 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));
+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
@@ -841,6 +869,17 @@ const detailFields = $derived(data.fields.filter((f) => f !== titleField && f !=
   </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. -->
@@ -887,44 +926,61 @@ const detailFields = $derived(data.fields.filter((f) => f !== titleField && f !=
     </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">
@@ -1316,23 +1372,37 @@ const detailFields = $derived(data.fields.filter((f) => f !== titleField && f !=
           {@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">
@@ -1357,9 +1427,13 @@ const detailFields = $derived(data.fields.filter((f) => f !== titleField && f !=
               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}
@@ -1378,7 +1452,10 @@ const detailFields = $derived(data.fields.filter((f) => f !== titleField && f !=
         {: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}