@glw907/cairn-cms 0.11.0 → 0.14.0

package/dist/render/rehype-dispatch.js

@@ -1,4 +1,5 @@
 import { h } from 'hastscript';
+import { dataAttrProp } from './registry.js';
 export function isElement(node) {
     return !!node && node.type === 'element';
 }
@@ -14,24 +15,6 @@ export function iconSpan(glyphEl, role) {
     const className = role === 'secondary' ? ['ec-icon', 'ec-icon-secondary'] : ['ec-icon'];
     return h('span', { className }, [glyphEl]);
 }
-// Pull the section's <h2> out, retag it .card-title, and build the .ec-head row
-// (optional icon + heading). Returns the head plus the remaining body children.
-// `makeIcon` (site-supplied) turns the stamped data-icon into an element; omit it
-// for a head with no icon.
-export function splitHead(node, makeIcon) {
-    const children = node.children;
-    const i = children.findIndex((c) => isElement(c) && c.tagName === 'h2');
-    const h2 = children[i];
-    h2.properties = { ...h2.properties, className: ['card-title'] };
-    const rest = children.filter((_, j) => j !== i);
-    const icon = strProp(node, 'dataIcon');
-    const role = strProp(node, 'dataRole');
-    const headKids = [];
-    if (makeIcon && icon)
-        headKids.push(makeIcon(icon, role));
-    headKids.push(h2);
-    return { head: h('div', { className: ['ec-head'] }, headKids), rest };
-}
 /** Section wrapper: `<section class=…><div class="card-body">…</div></section>`. */
 export function cardShell(classes, body) {
     return h('section', { className: classes }, [h('div', { className: ['card-body'] }, body)]);
@@ -58,11 +41,80 @@ function transformChildren(children, registry) {
         return c;
     });
 }
+// Read a stamped attribute back into its typed value. Booleans arrive as the strings
+// 'true'/'false'; everything else is the literal string the author wrote.
+function readAttributes(node, def) {
+    const out = {};
+    for (const field of def.attributes ?? []) {
+        const value = strProp(node, dataAttrProp(field.key));
+        if (value == null)
+            continue;
+        out[field.key] = field.type === 'boolean' ? value === 'true' : value;
+    }
+    return out;
+}
+// The title label paragraph carries data-slot="title"; build() wants its inline children, not
+// the marked paragraph. Return the paragraph's children.
+function stripSlotMarker(child) {
+    return isElement(child) ? child.children : [child];
+}
+// Split a component's stamped children into named slots and the default body. A child marked
+// data-slot="title"/<name> routes to that slot; an unmarked child is body. A repeatable slot
+// wraps a <ul>, so its items are that list's <li> children, one child-list per item.
+function partitionSlots(node) {
+    const named = new Map();
+    const body = [];
+    for (const child of node.children) {
+        const slotName = isElement(child) ? strProp(child, 'dataSlot') : undefined;
+        if (slotName === 'title')
+            named.set('title', stripSlotMarker(child));
+        else if (slotName)
+            named.set(slotName, [child]);
+        else
+            body.push(child);
+    }
+    return {
+        slot(name) {
+            if (name === 'body')
+                return body;
+            const wrap = named.get(name);
+            if (!wrap)
+                return [];
+            // For title we stored the label's own children, so return them as-is. For a markdown or
+            // inline named slot the wrapper <div> holds the rendered children; unwrap it.
+            if (name === 'title')
+                return wrap;
+            const div = wrap[0];
+            return isElement(div) ? div.children : wrap;
+        },
+        items(name) {
+            const wrap = named.get(name);
+            const div = wrap?.[0];
+            if (!div || !isElement(div))
+                return [];
+            const ul = div.children.find((c) => isElement(c) && c.tagName === 'ul');
+            if (!ul || !isElement(ul))
+                return [];
+            return ul.children
+                .filter((li) => isElement(li) && li.tagName === 'li')
+                .map((li) => li.children);
+        },
+    };
+}
 function transformNode(node, registry) {
     node.children = transformChildren(node.children, registry);
     const name = strProp(node, 'dataPrimitive');
     const def = name ? registry.get(name) : undefined;
-    return def ? def.build(node) : node;
+    if (!def)
+        return node;
+    const parts = partitionSlots(node);
+    const ctx = {
+        attributes: readAttributes(node, def),
+        slot: parts.slot,
+        items: parts.items,
+        node,
+    };
+    return def.build(ctx);
 }
 /** Rehype transformer: dispatch each stamped element through its registry `build`
  *  fn. When `stagger` is on, each top-level primitive gets a `data-rise` attribute

package/dist/render/remark-directives.d.ts

@@ -1,4 +1,4 @@
 import type { Root } from 'mdast';
-import type { ComponentRegistry } from './registry.js';
+import { type ComponentRegistry } from './registry.js';
 export declare function remarkDirectiveStamp(registry: ComponentRegistry): (tree: Root) => void;
 //# sourceMappingURL=remark-directives.d.ts.map

package/dist/render/remark-directives.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"remark-directives.d.ts","sourceRoot":"","sources":["../../src/lib/render/remark-directives.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAA8B,IAAI,EAAQ,MAAM,OAAO,CAAC;AAGpE,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAmCvD,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,iBAAiB,IAEtD,MAAM,IAAI,UA8BnB"}
+{"version":3,"file":"remark-directives.d.ts","sourceRoot":"","sources":["../../src/lib/render/remark-directives.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAA8B,IAAI,EAAQ,MAAM,OAAO,CAAC;AAGpE,OAAO,EAAgB,KAAK,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAkDrE,wBAAgB,oBAAoB,CAAC,QAAQ,EAAE,iBAAiB,IAEtD,MAAM,IAAI,UAqDnB"}

package/dist/render/remark-directives.js

@@ -1,4 +1,19 @@
 import { visit } from 'unist-util-visit';
+import { dataAttrProp } from './registry.js';
+// mdast-util-directive carries the `[label]` as a paragraph whose `data.directiveLabel` is set.
+function isDirectiveLabel(node) {
+    return Boolean(node.data?.directiveLabel);
+}
+// Stamp data-slot on a child so the rehype dispatch partitioner can route it. For a nested
+// container directive we also set hName so it renders as a <div> wrapper rather than being
+// dropped as an unknown directive.
+function markSlot(node, name) {
+    const n = node;
+    const data = n.data ?? (n.data = {});
+    if (n.type === 'containerDirective')
+        data.hName = 'div';
+    data.hProperties = { ...(data.hProperties ?? {}), dataSlot: name };
+}
 // Reconstruct a directive's authored attribute block (`{#id .class key="value"}`).
 // Accidental prose directives carry none, so this is almost always empty.
 function serializeAttributes(attributes) {
@@ -42,6 +57,7 @@ export function remarkDirectiveStamp(registry) {
         visit(tree, 'containerDirective', (node) => {
             if (!known.has(node.name))
                 return;
+            const def = registry.get(node.name);
             const attrs = node.attributes ?? {};
             const role = attrs.role || undefined;
             let icon = attrs.icon || undefined;
@@ -52,9 +68,30 @@ export function remarkDirectiveStamp(registry) {
                 properties.dataIcon = icon;
             if (role)
                 properties.dataRole = role;
+            // Carry every declared attribute to hast so the dispatch partitioner can build the
+            // component context. data-attr-<key> survives to the element; build() consumes it and
+            // returns a fresh element, so the marker never reaches the published DOM.
+            for (const field of def?.attributes ?? []) {
+                const raw = attrs[field.key];
+                if (raw != null)
+                    properties[dataAttrProp(field.key)] = raw;
+            }
             const data = node.data ?? (node.data = {});
             data.hName = 'div';
             data.hProperties = properties;
+            // Mark the title label paragraph and the nested slot directives so they survive to hast
+            // and the partitioner can find them. A slot named in the component schema (other than the
+            // default body) is a nested container directive; the title is the directive [label].
+            const slotNames = new Set((def?.slots ?? []).map((s) => s.name));
+            for (const child of node.children) {
+                if (isDirectiveLabel(child) && slotNames.has('title')) {
+                    markSlot(child, 'title');
+                }
+                else if (child.type === 'containerDirective' &&
+                    slotNames.has(child.name)) {
+                    markSlot(child, child.name);
+                }
+            }
         });
         visit(tree, ['textDirective', 'leafDirective'], (node, index, parent) => {
             if (!parent || index == null)

package/dist/sveltekit/public-routes.d.ts

@@ -17,6 +17,9 @@ export interface PublicRoutesDeps {
         rss?: string;
         json?: string;
     };
+    /** A site-wide default OG image, used when an entry declares none. Resolved to absolute like the
+     *  canonical URL, so a relative path such as "/og/default.png" works. */
+    defaultImage?: string;
 }
 /** The archive and tag list data: summaries the template renders. */
 export interface ListData {

package/dist/sveltekit/public-routes.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"public-routes.d.ts","sourceRoot":"","sources":["../../src/lib/sveltekit/public-routes.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,8BAA8B,CAAC;AACjF,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,2BAA2B,CAAC;AAE3D,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAElD,oDAAoD;AACpD,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,SAAS,CAAC;IAChB,MAAM,EAAE,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,OAAO,CAAA;KAAE,KAAK,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAC/E,MAAM,EAAE,MAAM,CAAC;IACf,mDAAmD;IACnD,QAAQ,EAAE,MAAM,CAAC;IACjB,uDAAuD;IACvD,WAAW,EAAE,MAAM,CAAC;IACpB,6DAA6D;IAC7D,KAAK,CAAC,EAAE;QAAE,GAAG,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;CACzC;AAED,qEAAqE;AACrE,MAAM,WAAW,QAAQ;IACvB,OAAO,EAAE,cAAc,EAAE,CAAC;CAC3B;AAED,uDAAuD;AACvD,MAAM,WAAW,OAAQ,SAAQ,QAAQ;IACvC,GAAG,EAAE,MAAM,CAAC;CACb;AAED,oDAAoD;AACpD,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;CACxC;AAED,oFAAoF;AACpF,MAAM,WAAW,SAAS;IACxB,KAAK,EAAE,YAAY,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,EAAE,MAAM,CAAC;IACrB,GAAG,EAAE,OAAO,CAAC;IACb,KAAK,CAAC,EAAE,cAAc,CAAC;IACvB,KAAK,CAAC,EAAE,cAAc,CAAC;CACxB;AAED,2DAA2D;AAC3D,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,gBAAgB;uBAWvB;QAAE,GAAG,EAAE,GAAG,CAAA;KAAE,KAAG,OAAO,CAAC,SAAS,CAAC;6BAoBjC,MAAM,KAAG,QAAQ;8BAKhB,MAAM,KAAG,YAAY;yBAK1B,MAAM,SAAS;QAAE,MAAM,EAAE;YAAE,GAAG,EAAE,MAAM,CAAA;SAAE,CAAA;KAAE,KAAG,OAAO;mBAO5D;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,EAAE;EAKvC"}
+{"version":3,"file":"public-routes.d.ts","sourceRoot":"","sources":["../../src/lib/sveltekit/public-routes.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,cAAc,EAAE,YAAY,EAAE,MAAM,8BAA8B,CAAC;AACjF,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,2BAA2B,CAAC;AAE3D,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,oBAAoB,CAAC;AAGlD,oDAAoD;AACpD,MAAM,WAAW,gBAAgB;IAC/B,IAAI,EAAE,SAAS,CAAC;IAChB,MAAM,EAAE,CAAC,EAAE,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,OAAO,CAAA;KAAE,KAAK,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;IAC/E,MAAM,EAAE,MAAM,CAAC;IACf,mDAAmD;IACnD,QAAQ,EAAE,MAAM,CAAC;IACjB,uDAAuD;IACvD,WAAW,EAAE,MAAM,CAAC;IACpB,6DAA6D;IAC7D,KAAK,CAAC,EAAE;QAAE,GAAG,CAAC,EAAE,MAAM,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACxC;6EACyE;IACzE,YAAY,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,qEAAqE;AACrE,MAAM,WAAW,QAAQ;IACvB,OAAO,EAAE,cAAc,EAAE,CAAC;CAC3B;AAED,uDAAuD;AACvD,MAAM,WAAW,OAAQ,SAAQ,QAAQ;IACvC,GAAG,EAAE,MAAM,CAAC;CACb;AAED,oDAAoD;AACpD,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE;QAAE,GAAG,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;CACxC;AAED,oFAAoF;AACpF,MAAM,WAAW,SAAS;IACxB,KAAK,EAAE,YAAY,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,YAAY,EAAE,MAAM,CAAC;IACrB,GAAG,EAAE,OAAO,CAAC;IACb,KAAK,CAAC,EAAE,cAAc,CAAC;IACvB,KAAK,CAAC,EAAE,cAAc,CAAC;CACxB;AAED,2DAA2D;AAC3D,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,gBAAgB;uBAWvB;QAAE,GAAG,EAAE,GAAG,CAAA;KAAE,KAAG,OAAO,CAAC,SAAS,CAAC;6BA0BjC,MAAM,KAAG,QAAQ;8BAKhB,MAAM,KAAG,YAAY;yBAK1B,MAAM,SAAS;QAAE,MAAM,EAAE;YAAE,GAAG,EAAE,MAAM,CAAA;SAAE,CAAA;KAAE,KAAG,OAAO;mBAO5D;QAAE,IAAI,EAAE,MAAM,CAAA;KAAE,EAAE;EAKvC"}

package/dist/sveltekit/public-routes.js

@@ -5,9 +5,10 @@
 // from globs, so it stays in the prerender graph and out of the runtime Worker.
 import { error } from '@sveltejs/kit';
 import { buildSeoMeta } from '../delivery/seo.js';
+import { readSeoFields, resolveImageUrl } from '../delivery/seo-fields.js';
 /** Build the public loaders for a site's unified index. */
 export function createPublicRoutes(deps) {
-    const { site, render, origin, siteName, description, feeds } = deps;
+    const { site, render, origin, siteName, description, feeds, defaultImage } = deps;
     /** Resolve one concept's index by id, or a 404 (the route names an unconfigured concept). */
     function indexOf(conceptId) {
         const index = site.concept(conceptId);
@@ -22,15 +23,21 @@ export function createPublicRoutes(deps) {
             throw error(404, `Not found: ${event.url.pathname}`);
         const { newer, older } = site.adjacent(entry);
         const canonicalUrl = origin + entry.permalink;
+        const fields = readSeoFields(entry.frontmatter);
+        const rawImage = fields.image ?? defaultImage;
+        const image = rawImage ? resolveImageUrl(rawImage, origin) : undefined;
         // A dated entry is an article; an undated one (a page) is a website.
         const seo = buildSeoMeta({
             title: entry.title,
-            description: entry.frontmatter.description || entry.excerpt || description,
+            description: fields.description || entry.excerpt || description,
             canonicalUrl,
             siteName,
             type: entry.date ? 'article' : 'website',
             ...(entry.date ? { published: entry.date } : {}),
             ...(entry.updated ? { modified: entry.updated } : {}),
+            ...(image ? { image } : {}),
+            ...(fields.robots ? { robots: fields.robots } : {}),
+            ...(fields.author ? { author: fields.author } : {}),
             feeds,
         });
         return { entry, html: await render(entry.body, { stagger: true }), canonicalUrl, seo, newer, older };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@glw907/cairn-cms",
-  "version": "0.11.0",
+  "version": "0.14.0",
   "description": "Embedded, magic-link, GitHub-committing CMS for SvelteKit/Cloudflare sites.",
   "type": "module",
   "sideEffects": [

package/src/lib/components/ComponentForm.svelte

@@ -38,6 +38,32 @@ markdown. Back returns to the picker. This is not a nested HTML form; Insert cal
     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.
+  let nextId = 0;
+  const itemIds = $state<Record<string, number[]>>(
+    untrack(() => Object.fromEntries((def.slots ?? []).filter((s) => s.kind === 'repeatable').map((s) => [s.name, []]))),
+  );
+
+  // emptyValues and the itemIds seed both cover every repeatable slot, so this read always hits.
+  function slotIds(name: string): number[] {
+    return itemIds[name] ?? [];
+  }
+
+  function addItem(name: string): void {
+    slotItems(name).push('');
+    slotIds(name).push(nextId++);
+  }
+
+  function removeItem(name: string, index: number): void {
+    slotItems(name).splice(index, 1);
+    slotIds(name).splice(index, 1);
+  }
+
   // Typed accessors over the unions so explicit value targets stay sound.
   function asString(key: string): string {
     const v = values.attributes[key];
@@ -79,7 +105,6 @@ markdown. Back returns to the picker. This is not a nested HTML form; Insert cal
         <input
           class="checkbox checkbox-sm"
           type="checkbox"
-          aria-label={field.label}
           aria-invalid={Boolean(errors[field.key])}
           aria-describedby={errors[field.key] ? `err-${field.key}` : undefined}
           checked={asBool(field.key)}
@@ -92,7 +117,6 @@ markdown. Back returns to the picker. This is not a nested HTML form; Insert cal
         <span class="text-sm font-medium">{field.label}</span>
         <select
           class="select"
-          aria-label={field.label}
           aria-invalid={Boolean(errors[field.key])}
           aria-describedby={errors[field.key] ? `err-${field.key}` : undefined}
           value={asString(field.key)}
@@ -107,6 +131,7 @@ markdown. Back returns to the picker. This is not a nested HTML form; Insert cal
         <span class="text-sm font-medium">{field.label}</span>
         <IconPicker
           {icons}
+          label={field.label}
           value={asString(field.key)}
           required={field.required ?? false}
           onChange={(name) => (values.attributes[field.key] = name)}
@@ -117,7 +142,6 @@ markdown. Back returns to the picker. This is not a nested HTML form; Insert cal
         <span class="text-sm font-medium">{field.label}</span>
         <input
           class="input"
-          aria-label={field.label}
           aria-invalid={Boolean(errors[field.key])}
           aria-describedby={errors[field.key] ? `err-${field.key}` : undefined}
           value={asString(field.key)}
@@ -134,7 +158,6 @@ markdown. Back returns to the picker. This is not a nested HTML form; Insert cal
         <span class="text-sm font-medium">{slot.label}</span>
         <textarea
           class="textarea"
-          aria-label={slot.label}
           aria-invalid={Boolean(errors[slot.name])}
           aria-describedby={errors[slot.name] ? `err-${slot.name}` : undefined}
           rows={3}
@@ -147,7 +170,6 @@ markdown. Back returns to the picker. This is not a nested HTML form; Insert cal
         <span class="text-sm font-medium">{slot.label}</span>
         <input
           class="input"
-          aria-label={slot.label}
           aria-invalid={Boolean(errors[slot.name])}
           aria-describedby={errors[slot.name] ? `err-${slot.name}` : undefined}
           value={slotString(slot.name)}
@@ -160,16 +182,17 @@ markdown. Back returns to the picker. This is not a nested HTML form; Insert cal
 
   {#each repeatableSlots as slot (slot.name)}
     {@const items = slotItems(slot.name)}
+    {@const ids = slotIds(slot.name)}
     <fieldset class="rounded-box border border-base-300 flex flex-col gap-2 p-2">
       <legend class="text-sm font-medium">{slot.label}</legend>
-      <!-- Index key is deliberate: items are bare strings with no stable id, so the value bindings and splice/push are index-based by design. -->
-      {#each items as _, i (i)}
+      <!-- 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. -->
+      {#each ids as id, i (id)}
         <div class="flex items-center gap-2">
-          <input class="input input-sm flex-1" aria-label={`${slot.label} item`} bind:value={items[i]} />
-          <button type="button" class="btn btn-ghost btn-sm" aria-label={`Remove item ${i + 1}`} onclick={() => items.splice(i, 1)}>✕</button>
+          <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}
-      <button type="button" class="btn btn-sm self-start" onclick={() => items.push('')}>Add item</button>
+      <button type="button" class="btn btn-sm self-start" onclick={() => addItem(slot.name)}>Add item</button>
       {#if errors[slot.name]}<span id={`err-${slot.name}`} role="alert" class="text-error text-xs">{errors[slot.name]}</span>{/if}
     </fieldset>
   {/each}

package/src/lib/components/IconPicker.svelte

@@ -1,10 +1,13 @@
 <!--
 @component
-A visual icon choice over the site's IconSet. Each glyph is a toggle button; the selected one carries
-aria-pressed. When the field is optional, a None button clears the value. The glyph renders inline from
-the IconSet path data, matching the renderer's 256-unit viewBox.
+A visual icon choice over the site's IconSet. The choices form a radiogroup; each glyph is a radio
+button carrying aria-checked, and the selected one carries btn-primary for the visible state. When the
+field is optional, a None radio clears the value. A roving tabindex keeps a single tab stop and arrow
+keys move the selection, the standard radiogroup keyboard model. The glyph renders inline from the
+IconSet path data, matching the renderer's 256-unit viewBox.
 -->
 <script lang="ts">
+  import { tick } from 'svelte';
   import type { IconSet } from '../render/glyph.js';
 
   interface Props {
@@ -16,20 +19,60 @@ the IconSet path data, matching the renderer's 256-unit viewBox.
     required: boolean;
     /** Called with the new glyph name (or '' for none). */
     onChange: (name: string) => void;
+    /** The group's accessible name, threaded from the field label. Defaults to Icon. */
+    label?: string;
   }
 
-  let { icons, value, required, onChange }: Props = $props();
+  let { icons, value, required, onChange, label = 'Icon' }: Props = $props();
+
+  // The radiogroup container, used to move focus with the selection per the ARIA radiogroup pattern.
+  let group: HTMLDivElement;
 
   const names = $derived(Object.keys(icons));
+  // The selectable keys in DOM order: the optional None choice ('') first, then each glyph name.
+  // Arrow-key navigation walks this list, and the roving tabindex marks the selected key (or the
+  // first key when nothing is selected) as the single tab stop.
+  const choices = $derived(required ? names : ['', ...names]);
+  const tabStop = $derived(choices.includes(value) ? value : choices[0]);
+
+  function move(delta: number): void {
+    // Navigate relative to the focused element (the current tab stop), not the bound value. In a
+    // required group with no value, tabStop is the first radio while value is '', so a value-based
+    // origin would skip the first step.
+    const from = Math.max(0, choices.indexOf(tabStop));
+    const next = (from + delta + choices.length) % choices.length;
+    onChange(choices[next]);
+    // The roving tabindex updates reactively, so wait for the DOM then move focus onto the new tab
+    // stop. The keydown handler runs only when focus is already inside the group, so this never
+    // steals focus on mount.
+    void tick().then(() => {
+      const target = group?.querySelector<HTMLElement>('[tabindex="0"]');
+      target?.focus();
+    });
+  }
+
+  function onKeydown(e: KeyboardEvent): void {
+    if (e.key === 'ArrowRight' || e.key === 'ArrowDown') {
+      e.preventDefault();
+      move(1);
+    } else if (e.key === 'ArrowLeft' || e.key === 'ArrowUp') {
+      e.preventDefault();
+      move(-1);
+    }
+  }
 </script>
 
-<div class="flex flex-wrap gap-2" role="group" aria-label="Icon">
+<div class="flex flex-wrap gap-2" role="radiogroup" aria-label={label} bind:this={group}>
   {#if !required}
     <button
       type="button"
       class="btn btn-sm"
       class:btn-primary={value === ''}
-      aria-pressed={value === ''}
+      role="radio"
+      aria-checked={value === ''}
+      aria-label="None"
+      tabindex={tabStop === '' ? 0 : -1}
+      onkeydown={onKeydown}
       onclick={() => onChange('')}
     >None</button>
   {/if}
@@ -38,8 +81,11 @@ the IconSet path data, matching the renderer's 256-unit viewBox.
       type="button"
       class="btn btn-sm gap-1"
       class:btn-primary={value === name}
-      aria-pressed={value === name}
+      role="radio"
+      aria-checked={value === name}
       aria-label={name}
+      tabindex={tabStop === name ? 0 : -1}
+      onkeydown={onKeydown}
       onclick={() => onChange(name)}
     >
       <svg class="ec-glyph" viewBox="0 0 256 256" fill="currentColor" aria-hidden="true" width="16" height="16">

package/src/lib/content/adapter.ts

@@ -0,0 +1,10 @@
+// cairn-cms: the adapter-authoring helper. A plain `const adapter: CairnAdapter = {...}` annotation
+// widens each concept's schema type away and breaks typed reads. defineAdapter captures the adapter
+// through a `const` type parameter, so each concept's concrete ConceptSchema<F> survives for the
+// full-auto typed reads in createSiteIndexes, while still checking the adapter against the contract.
+import type { CairnAdapter } from './types.js';
+
+/** Declare a site's adapter while preserving each concept's concrete schema type for typed reads. */
+export function defineAdapter<const A extends CairnAdapter>(adapter: A): A {
+  return adapter;
+}

package/src/lib/content/concepts.ts

@@ -51,8 +51,8 @@ export function normalizeConcepts(
       routing: routing[id] ?? DEFAULT_ROUTING,
       permalink: policy.permalink ?? defaultPermalink(id),
       datePrefix: policy.datePrefix ?? 'day',
-      fields: config.fields,
-      validate: config.validate,
+      fields: config.schema.fields,
+      validate: config.schema.validate,
     });
   }
   return descriptors;

package/src/lib/content/schema.ts

@@ -0,0 +1,133 @@
+// cairn-cms: the concept schema primitive (schema-source-of-truth design). One field
+// declaration yields a plain-data field projection for the editor form, a generated validator,
+// and an inferred frontmatter type. Plan 1 builds the additive primitive; the adapter-contract
+// cutover and the typed reads are Plan 2.
+import type { FrontmatterField, ValidationResult } from './types.js';
+import { validateFields } from './validate.js';
+
+/** The validate input the cairn adapter takes: the raw frontmatter and the body. */
+export interface StandardInput {
+  frontmatter: Record<string, unknown>;
+  body: string;
+}
+
+/** A minimal local copy of the Standard Schema v1 interface (https://standardschema.dev), so the
+ *  schema is a drop-in where the ecosystem accepts a validator, with no runtime dependency. */
+export interface StandardSchemaV1<Input = unknown, Output = Input> {
+  readonly '~standard': {
+    readonly version: 1;
+    readonly vendor: string;
+    readonly validate: (value: unknown) => StandardResult<Output>;
+    readonly types?: { readonly input: Input; readonly output: Output };
+  };
+}
+type StandardResult<Output> =
+  | { readonly value: Output; readonly issues?: undefined }
+  | { readonly issues: ReadonlyArray<{ readonly message: string; readonly path?: ReadonlyArray<PropertyKey> }> };
+
+/** Map one field descriptor to the TS type of its normalized value. text, textarea, and date
+ *  normalize to a string; a closed-vocabulary `tags` field to the option-union array. */
+type FieldValue<K extends FrontmatterField> = K extends { type: 'boolean' }
+  ? boolean
+  : K extends { type: 'tags'; options: readonly (infer O extends string)[] }
+    ? O[]
+    : K extends { type: 'tags' | 'freetags' }
+      ? string[]
+      : string;
+
+/** Flatten an intersection into a single readable object type. */
+type Prettify<T> = { [K in keyof T]: T[K] } & {};
+
+/** The normalized frontmatter type inferred from a field tuple. A field declared
+ *  `required: true` is a required key; every other field is optional. */
+export type InferFields<F extends readonly FrontmatterField[]> = Prettify<
+  { [K in F[number] as K extends { required: true } ? K['name'] : never]: FieldValue<K> } & {
+    [K in F[number] as K extends { required: true } ? never : K['name']]?: FieldValue<K>;
+  }
+>;
+
+/** A concept's schema: the plain-data field projection, the generated validator, and the
+ *  Standard Schema conformance property. */
+export interface ConceptSchema<F extends readonly FrontmatterField[] = readonly FrontmatterField[]> {
+  /** The declared fields as plain serializable data, for the editor form. */
+  readonly fields: FrontmatterField[];
+  /** Validate raw frontmatter, returning field-keyed errors or the normalized data. */
+  validate(frontmatter: Record<string, unknown>, body: string): ValidationResult;
+  /** Standard Schema v1 conformance, for ecosystem interop. A thin adapter over `validate`. */
+  readonly '~standard': StandardSchemaV1<StandardInput, InferFields<F>>['~standard'];
+}
+
+/** Extract the inferred frontmatter type from a `ConceptSchema`. */
+export type Infer<S> = S extends ConceptSchema<infer F> ? InferFields<F> : never;
+
+// Enforce the declarative per-field rules on an already-coerced value. Rules run only on a
+// present, non-empty string value, so an absent optional field is never flagged. The first
+// failing rule per field wins, so the author sees one clear message at a time.
+function applyRules(field: FrontmatterField, value: unknown, errors: Record<string, string>, patterns: Map<string, RegExp>): void {
+  if (typeof value !== 'string' || value === '') return;
+  if (field.type === 'text' || field.type === 'textarea') {
+    if (field.min != null && value.length < field.min) errors[field.name] = `${field.label} must be at least ${field.min} characters`;
+    else if (field.max != null && value.length > field.max) errors[field.name] = `${field.label} must be at most ${field.max} characters`;
+    else if (field.length != null && value.length !== field.length) errors[field.name] = `${field.label} must be exactly ${field.length} characters`;
+    else if (field.pattern != null) {
+      const re = patterns.get(field.name);
+      if (re && !re.test(value)) errors[field.name] = `${field.label} is not in the expected format`;
+    }
+  } else if (field.type === 'date') {
+    if (field.min != null && value < field.min) errors[field.name] = `${field.label} must be on or after ${field.min}`;
+    else if (field.max != null && value > field.max) errors[field.name] = `${field.label} must be on or before ${field.max}`;
+  }
+}
+
+/** Options for `defineFields`. `refine` runs after the per-field rules pass, for cross-field and
+ *  body-dependent checks. It is validation-only: it returns field-keyed errors to merge, or
+ *  nothing, and never transforms the data. */
+export interface DefineFieldsOptions<F extends readonly FrontmatterField[]> {
+  refine?: (data: InferFields<F>, body: string) => Record<string, string> | undefined;
+}
+
+// Compile each declared text/textarea pattern once, so a malformed pattern fails loudly at
+// declaration (a site config error) instead of throwing from inside validate() on every save.
+function compilePatterns(fields: FrontmatterField[]): Map<string, RegExp> {
+  const compiled = new Map<string, RegExp>();
+  for (const field of fields) {
+    if ((field.type === 'text' || field.type === 'textarea') && field.pattern != null) {
+      try {
+        compiled.set(field.name, new RegExp(field.pattern));
+      } catch (cause) {
+        throw new Error(`cairn: field "${field.name}" has an invalid pattern: ${field.pattern}`, { cause });
+      }
+    }
+  }
+  return compiled;
+}
+
+/** Declare a concept's fields once. Returns the schema's faces derived from that one declaration. */
+export function defineFields<const F extends readonly FrontmatterField[]>(
+  fields: F,
+  options: DefineFieldsOptions<F> = {},
+): ConceptSchema<F> {
+  const list = [...fields] as FrontmatterField[];
+  const patterns = compilePatterns(list);
+  const validate = (frontmatter: Record<string, unknown>, body: string): ValidationResult => {
+    const base = validateFields(list, frontmatter);
+    if (!base.ok) return base;
+    const errors: Record<string, string> = {};
+    for (const field of list) applyRules(field, base.data[field.name], errors, patterns);
+    if (Object.keys(errors).length > 0) return { ok: false, errors };
+    const refined = options.refine?.(base.data as InferFields<F>, body);
+    return refined && Object.keys(refined).length > 0 ? { ok: false, errors: refined } : base;
+  };
+  const standard: StandardSchemaV1<StandardInput, InferFields<F>>['~standard'] = {
+    version: 1,
+    vendor: 'cairn',
+    validate: (value) => {
+      const { frontmatter = {}, body = '' } = (value ?? {}) as Partial<StandardInput>;
+      const result = validate(frontmatter ?? {}, body ?? '');
+      return result.ok
+        ? { value: result.data as InferFields<F> }
+        : { issues: Object.entries(result.errors).map(([field, message]) => ({ message, path: [field] })) };
+    },
+  };
+  return { fields: list, validate, '~standard': standard };
+}