@glw907/cairn-cms 0.9.0 → 0.10.0

package/dist/render/component-grammar.js

@@ -0,0 +1,140 @@
+import { unified } from 'unified';
+import remarkParse from 'remark-parse';
+import remarkDirective from 'remark-directive';
+import remarkStringify from 'remark-stringify';
+const COLON = ':';
+function attrBlock(def, values) {
+    const parts = [];
+    for (const field of def.attributes ?? []) {
+        const v = values.attributes[field.key];
+        if (field.type === 'boolean') {
+            if (v === true)
+                parts.push(`${field.key}="true"`);
+        }
+        else if (typeof v === 'string' && v !== '') {
+            // The directive attribute grammar (mdast-util-directive) treats a literal `"` as the value
+            // terminator and decodes HTML entities, so a backslash escape does not survive a round-trip.
+            // Encode `&` first (so existing entities are not double-decoded) then `"`; the parser decodes
+            // both back. A backslash is literal in this grammar and needs no escaping.
+            const escaped = v.replace(/&/g, '&').replace(/"/g, '"');
+            parts.push(`${field.key}="${escaped}"`);
+        }
+    }
+    return parts.length ? `{${parts.join(' ')}}` : '';
+}
+function slotByName(def, name) {
+    return (def.slots ?? []).find((s) => s.name === name);
+}
+function nestedSlots(def) {
+    return (def.slots ?? []).filter((s) => s.name !== 'title' && s.name !== 'body');
+}
+export function serializeComponent(def, values) {
+    const fence = COLON.repeat(nestedSlots(def).length > 0 ? 4 : 3);
+    const title = slotByName(def, 'title') ? values.slots.title ?? '' : '';
+    // Escape brackets in the label so a `[` or `]` in the title does not break the directive label
+    // grammar; remark un-escapes them back to literal text on parse, so readLabel recovers them.
+    const label = title ? `[${title.replace(/\[/g, '\\[').replace(/\]/g, '\\]')}]` : '';
+    const open = `${fence}${def.name}${label}${attrBlock(def, values)}`;
+    const lines = [open];
+    const body = slotByName(def, 'body') ? values.slots.body ?? '' : '';
+    if (body)
+        lines.push(body);
+    for (const slot of nestedSlots(def)) {
+        const raw = values.slots[slot.name];
+        const content = slot.kind === 'repeatable'
+            ? (Array.isArray(raw) ? raw : []).filter((i) => i !== '').map((i) => `- ${i}`).join('\n')
+            : (raw ?? '');
+        if (!content)
+            continue;
+        if (lines.length > 1)
+            lines.push(''); // blank line before this block
+        lines.push(`${COLON.repeat(3)}${slot.name}`, content, COLON.repeat(3));
+    }
+    lines.push(fence);
+    return lines.join('\n');
+}
+function isContainer(node) {
+    return node.type === 'containerDirective';
+}
+// Pin the bullet to `-` so a markdown body or slot that uses dash bullets round-trips unchanged
+// rather than drifting to remark-stringify's default `*`, which would silently mutate author content.
+const toMd = unified().use(remarkStringify, { bullet: '-' });
+/** Render mdast children back to trimmed markdown text. */
+function childrenToText(children) {
+    const root = { type: 'root', children };
+    return String(toMd.stringify(root)).trim();
+}
+/** Parse a serialized component directive back into guided-form values, the inverse of
+ *  {@link serializeComponent}. The grammar is reversible, so the editor can round-trip a
+ *  saved directive through the form. */
+export async function parseComponent(markdown, def) {
+    const tree = unified().use(remarkParse).use(remarkDirective).parse(markdown);
+    const root = tree.children.find((c) => isContainer(c) && c.name === def.name);
+    const values = emptyComponentValues(def);
+    if (!root)
+        return values;
+    for (const field of def.attributes ?? []) {
+        const raw = root.attributes?.[field.key];
+        if (field.type === 'boolean')
+            values.attributes[field.key] = raw === 'true';
+        else if (typeof raw === 'string')
+            values.attributes[field.key] = raw;
+    }
+    const titleSlot = slotByName(def, 'title');
+    const bodySlot = slotByName(def, 'body');
+    const nested = nestedSlots(def);
+    const nestedNames = new Set(nested.map((s) => s.name));
+    const directChildren = root.children.filter((c) => !(isContainer(c) && nestedNames.has(c.name)) && !isDirectiveLabel(c));
+    const nestedChildren = root.children.filter((c) => isContainer(c) && nestedNames.has(c.name));
+    if (titleSlot)
+        values.slots.title = readLabel(root) ?? '';
+    if (bodySlot)
+        values.slots.body = childrenToText(directChildren);
+    for (const slot of nested) {
+        const node = nestedChildren.find((c) => c.name === slot.name);
+        if (!node)
+            continue;
+        if (slot.kind === 'repeatable')
+            values.slots[slot.name] = readListItems(node.children);
+        else
+            values.slots[slot.name] = childrenToText(node.children);
+    }
+    return values;
+}
+/** The raw attribute keys present on the component's opening directive, read from the parsed tree
+ *  (quote-aware, unlike a regex over the source). Used by validation to flag unknown keys. */
+export function parseRawAttributeKeys(markdown, def) {
+    const tree = unified().use(remarkParse).use(remarkDirective).parse(markdown);
+    const root = tree.children.find((c) => isContainer(c) && c.name === def.name);
+    return Object.keys(root?.attributes ?? {});
+}
+// A bare parse base: empty strings, false, and empty lists, with no attribute defaults applied. The
+// `emptyValues` helper in registry.ts seeds form defaults instead, so it is deliberately not reused
+// here; the parse must overwrite only the fields actually present in the markdown.
+function emptyComponentValues(def) {
+    const attributes = {};
+    for (const f of def.attributes ?? [])
+        attributes[f.key] = f.type === 'boolean' ? false : '';
+    const slots = {};
+    for (const s of def.slots ?? [])
+        slots[s.name] = s.kind === 'repeatable' ? [] : '';
+    return { attributes, slots };
+}
+// mdast-util-directive carries the `[label]` as a paragraph whose `data.directiveLabel` is set.
+function isDirectiveLabel(node) {
+    return Boolean(node.data?.directiveLabel);
+}
+function readLabel(root) {
+    for (const child of root.children) {
+        const p = child;
+        if (p.type === 'paragraph' && p.data?.directiveLabel)
+            return (p.children ?? []).map((c) => c.value ?? '').join('');
+    }
+    return undefined;
+}
+function readListItems(children) {
+    const list = children.find((c) => c.type === 'list');
+    if (!list?.children)
+        return [];
+    return list.children.map((li) => childrenToText(li.children ?? []));
+}

package/dist/render/component-insert.d.ts

@@ -0,0 +1,14 @@
+import type { ComponentDef, ComponentValues } from './registry.js';
+/** The outcome of preparing a guided-form component for insertion: the markdown to insert, or the
+ *  field-keyed errors to show on the form. */
+export type ComponentInsert = {
+    ok: true;
+    markdown: string;
+} | {
+    ok: false;
+    errors: Record<string, string>;
+};
+/** Serialize a component's form values, then validate the result against its schema. Returns the
+ *  markdown to insert at the cursor, or the field errors keyed by attribute key or slot name. */
+export declare function buildComponentInsert(def: ComponentDef, values: ComponentValues): Promise<ComponentInsert>;
+//# sourceMappingURL=component-insert.d.ts.map

package/dist/render/component-insert.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"component-insert.d.ts","sourceRoot":"","sources":["../../src/lib/render/component-insert.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,YAAY,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAEnE;8CAC8C;AAC9C,MAAM,MAAM,eAAe,GAAG;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,EAAE,MAAM,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAAE,CAAC;AAE7G;iGACiG;AACjG,wBAAsB,oBAAoB,CAAC,GAAG,EAAE,YAAY,EAAE,MAAM,EAAE,eAAe,GAAG,OAAO,CAAC,eAAe,CAAC,CAI/G"}

package/dist/render/component-insert.js

@@ -0,0 +1,9 @@
+import { serializeComponent } from './component-grammar.js';
+import { validateComponent } from './component-validate.js';
+/** Serialize a component's form values, then validate the result against its schema. Returns the
+ *  markdown to insert at the cursor, or the field errors keyed by attribute key or slot name. */
+export async function buildComponentInsert(def, values) {
+    const markdown = serializeComponent(def, values);
+    const verdict = await validateComponent(markdown, def);
+    return verdict.ok ? { ok: true, markdown } : { ok: false, errors: verdict.errors };
+}

package/dist/render/component-reference.d.ts

@@ -0,0 +1,11 @@
+import { type ComponentRegistry } from './registry.js';
+export interface ReferenceOptions {
+    /** The H1 title of the reference document. */
+    title: string;
+    /** The one-line blockquote summary under the title. */
+    summary: string;
+}
+/** Build a self-contained markdown reference (the llms-full.txt shape) for a component registry, for
+ *  authors and for pointing an LLM at one curated file. */
+export declare function generateComponentReference(registry: ComponentRegistry, opts: ReferenceOptions): string;
+//# sourceMappingURL=component-reference.d.ts.map

package/dist/render/component-reference.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"component-reference.d.ts","sourceRoot":"","sources":["../../src/lib/render/component-reference.ts"],"names":[],"mappings":"AACA,OAAO,EAAkC,KAAK,iBAAiB,EAAwB,MAAM,eAAe,CAAC;AAE7G,MAAM,WAAW,gBAAgB;IAC/B,8CAA8C;IAC9C,KAAK,EAAE,MAAM,CAAC;IACd,uDAAuD;IACvD,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;2DAC2D;AAC3D,wBAAgB,0BAA0B,CAAC,QAAQ,EAAE,iBAAiB,EAAE,IAAI,EAAE,gBAAgB,GAAG,MAAM,CAGtG"}

package/dist/render/component-reference.js

@@ -0,0 +1,34 @@
+import { serializeComponent } from './component-grammar.js';
+import { emptyValues } from './registry.js';
+/** Build a self-contained markdown reference (the llms-full.txt shape) for a component registry, for
+ *  authors and for pointing an LLM at one curated file. */
+export function generateComponentReference(registry, opts) {
+    const sections = registry.defs.map((def) => componentSection(def));
+    return `# ${opts.title}\n\n> ${opts.summary}\n\n${sections.join('\n\n')}\n`;
+}
+function componentSection(def) {
+    const lines = [`## ${def.label} (\`:::${def.name}\`)`, '', def.description ?? ''];
+    if (def.use)
+        lines.push('', `**When to use:** ${def.use}`);
+    lines.push('', '```', serializeComponent(def, exampleValues(def)), '```');
+    return lines.join('\n');
+}
+/** Seed example values that show every declared field: an ellipsis for strings, one sample list item. */
+function exampleValues(def) {
+    const values = emptyValues(def);
+    for (const field of def.attributes ?? []) {
+        if (field.type === 'boolean')
+            values.attributes[field.key] = false;
+        else
+            values.attributes[field.key] = field.options?.[0] ?? '…';
+    }
+    for (const slot of def.slots ?? []) {
+        if (slot.kind === 'repeatable')
+            values.slots[slot.name] = ['…'];
+        else if (slot.name === 'title')
+            values.slots[slot.name] = 'Title';
+        else
+            values.slots[slot.name] = '…';
+    }
+    return values;
+}

package/dist/render/component-validate.d.ts

@@ -0,0 +1,10 @@
+import type { ComponentDef } from './registry.js';
+/** A validation verdict: ok, or field-keyed error messages. */
+export type ComponentValidation = {
+    ok: true;
+} | {
+    ok: false;
+    errors: Record<string, string>;
+};
+export declare function validateComponent(markdown: string, def: ComponentDef): Promise<ComponentValidation>;
+//# sourceMappingURL=component-validate.d.ts.map

package/dist/render/component-validate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"component-validate.d.ts","sourceRoot":"","sources":["../../src/lib/render/component-validate.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,eAAe,CAAC;AAElD,+DAA+D;AAC/D,MAAM,MAAM,mBAAmB,GAAG;IAAE,EAAE,EAAE,IAAI,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAA;CAAE,CAAC;AAE/F,wBAAsB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,EAAE,GAAG,EAAE,YAAY,GAAG,OAAO,CAAC,mBAAmB,CAAC,CA6BzG"}

package/dist/render/component-validate.js

@@ -0,0 +1,30 @@
+import { parseComponent, parseRawAttributeKeys } from './component-grammar.js';
+export async function validateComponent(markdown, def) {
+    const values = await parseComponent(markdown, def);
+    const errors = {};
+    const declared = new Set((def.attributes ?? []).map((f) => f.key));
+    for (const field of def.attributes ?? []) {
+        const v = values.attributes[field.key];
+        const filled = field.type === 'boolean' ? true : typeof v === 'string' && v !== '';
+        if (field.required && !filled) {
+            errors[field.key] = `${field.label} is required.`;
+            continue;
+        }
+        if (field.type === 'select' && typeof v === 'string' && v !== '' && !(field.options ?? []).includes(v)) {
+            errors[field.key] = `${field.label} must be one of: ${(field.options ?? []).join(', ')}.`;
+        }
+    }
+    for (const key of parseRawAttributeKeys(markdown, def)) {
+        if (!declared.has(key))
+            errors[key] = `Unknown attribute "${key}".`;
+    }
+    for (const slot of def.slots ?? []) {
+        if (!slot.required)
+            continue;
+        const v = values.slots[slot.name];
+        const filled = Array.isArray(v) ? v.length > 0 : typeof v === 'string' && v !== '';
+        if (!filled)
+            errors[slot.name] = `${slot.label} is required.`;
+    }
+    return Object.keys(errors).length ? { ok: false, errors } : { ok: true };
+}

package/dist/render/registry.d.ts

@@ -1,4 +1,33 @@
 import type { Element } from 'hast';
+/** The input types a component attribute or repeatable item field can take. */
+export type FieldType = 'text' | 'select' | 'icon' | 'boolean';
+/** One `{key="value"}` attribute on a component directive, or one field of a repeatable item. */
+export interface AttributeField {
+    /** The attribute name as it appears in the directive, e.g. `icon`. */
+    key: string;
+    /** The form label. */
+    label: string;
+    type: FieldType;
+    required?: boolean;
+    /** Initial value; a string for text/select/icon, a boolean for boolean. */
+    default?: string | boolean;
+    /** Allowed values for `type: 'select'`. */
+    options?: string[];
+    /** Helper text shown under the field. */
+    help?: string;
+}
+export type SlotKind = 'markdown' | 'inline' | 'repeatable';
+/** One named content region of a component. The slots named `title` and `body` are special: `title`
+ *  serializes to the directive `[label]` and `body` to the unmarked content (see the canonical grammar). */
+export interface SlotDef {
+    name: string;
+    label: string;
+    kind: SlotKind;
+    required?: boolean;
+    help?: string;
+    /** For `kind: 'repeatable'`: the fields composing each list item (v1 uses the first field). */
+    itemFields?: AttributeField[];
+}
 /** A site component: how it inserts (editor) and how it renders (rehype). */
 export interface ComponentDef {
     /** Directive name, e.g. 'card' (matches `:::card`). */
@@ -8,13 +37,19 @@ export interface ComponentDef {
     /** Palette description. */
     description: string;
     /** Markdown scaffold inserted at the cursor by the editor palette. */
-    insertTemplate: string;
+    insertTemplate?: string;
     /** Build the final hast element from the stamped directive element. The engine
      *  stamps the entrance-stagger ordinal (`data-rise`) on the top-level result, so a
      *  build fn stays free of any motion concern. */
     build: (node: Element) => Element;
     /** Optional role-to-default-icon, e.g. `{ caution: 'warning' }`. */
     defaultIconByRole?: Record<string, string>;
+    /** One line on when to reach for this component; feeds the picker and the reference file. */
+    use?: string;
+    /** The `{key="value"}` attributes this component accepts. */
+    attributes?: AttributeField[];
+    /** The named content regions this component accepts. */
+    slots?: SlotDef[];
 }
 export interface ComponentRegistry {
     defs: ComponentDef[];
@@ -29,4 +64,13 @@ export interface ComponentRegistry {
 export declare function defineRegistry({ components }: {
     components: ComponentDef[];
 }): ComponentRegistry;
+/** Guided-form values for one component: attribute values keyed by attribute key, slot values keyed
+ *  by slot name (a string, or a string list for a repeatable slot). */
+export interface ComponentValues {
+    attributes: Record<string, string | boolean>;
+    slots: Record<string, string | string[]>;
+}
+/** Seed an empty {@link ComponentValues} from a component's schema: attribute defaults (or '' / false)
+ *  and empty slot values ([] for repeatable, '' otherwise). */
+export declare function emptyValues(def: ComponentDef): ComponentValues;
 //# sourceMappingURL=registry.d.ts.map

package/dist/render/registry.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../src/lib/render/registry.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,MAAM,CAAC;AAEpC,6EAA6E;AAC7E,MAAM,WAAW,YAAY;IAC3B,uDAAuD;IACvD,IAAI,EAAE,MAAM,CAAC;IACb,qBAAqB;IACrB,KAAK,EAAE,MAAM,CAAC;IACd,2BAA2B;IAC3B,WAAW,EAAE,MAAM,CAAC;IACpB,sEAAsE;IACtE,cAAc,EAAE,MAAM,CAAC;IACvB;;qDAEiD;IACjD,KAAK,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,OAAO,CAAC;IAClC,oEAAoE;IACpE,iBAAiB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC5C;AAED,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,YAAY,EAAE,CAAC;IACrB,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,YAAY,GAAG,SAAS,CAAC;IAC5C,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;CAC9D;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,EAAE,UAAU,EAAE,EAAE;IAAE,UAAU,EAAE,YAAY,EAAE,CAAA;CAAE,GAAG,iBAAiB,CAQhG"}
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../../src/lib/render/registry.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,MAAM,CAAC;AAEpC,+EAA+E;AAC/E,MAAM,MAAM,SAAS,GAAG,MAAM,GAAG,QAAQ,GAAG,MAAM,GAAG,SAAS,CAAC;AAE/D,iGAAiG;AACjG,MAAM,WAAW,cAAc;IAC7B,sEAAsE;IACtE,GAAG,EAAE,MAAM,CAAC;IACZ,sBAAsB;IACtB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,SAAS,CAAC;IAChB,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,2EAA2E;IAC3E,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;IAC3B,2CAA2C;IAC3C,OAAO,CAAC,EAAE,MAAM,EAAE,CAAC;IACnB,yCAAyC;IACzC,IAAI,CAAC,EAAE,MAAM,CAAC;CACf;AAED,MAAM,MAAM,QAAQ,GAAG,UAAU,GAAG,QAAQ,GAAG,YAAY,CAAC;AAE5D;4GAC4G;AAC5G,MAAM,WAAW,OAAO;IACtB,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,QAAQ,CAAC;IACf,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,+FAA+F;IAC/F,UAAU,CAAC,EAAE,cAAc,EAAE,CAAC;CAC/B;AAED,6EAA6E;AAC7E,MAAM,WAAW,YAAY;IAC3B,uDAAuD;IACvD,IAAI,EAAE,MAAM,CAAC;IACb,qBAAqB;IACrB,KAAK,EAAE,MAAM,CAAC;IACd,2BAA2B;IAC3B,WAAW,EAAE,MAAM,CAAC;IACpB,sEAAsE;IACtE,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB;;qDAEiD;IACjD,KAAK,EAAE,CAAC,IAAI,EAAE,OAAO,KAAK,OAAO,CAAC;IAClC,oEAAoE;IACpE,iBAAiB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC3C,6FAA6F;IAC7F,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,6DAA6D;IAC7D,UAAU,CAAC,EAAE,cAAc,EAAE,CAAC;IAC9B,wDAAwD;IACxD,KAAK,CAAC,EAAE,OAAO,EAAE,CAAC;CACnB;AAED,MAAM,WAAW,iBAAiB;IAChC,IAAI,EAAE,YAAY,EAAE,CAAC;IACrB,KAAK,EAAE,MAAM,EAAE,CAAC;IAChB,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,YAAY,GAAG,SAAS,CAAC;IAC5C,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAC;CAC9D;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,EAAE,UAAU,EAAE,EAAE;IAAE,UAAU,EAAE,YAAY,EAAE,CAAA;CAAE,GAAG,iBAAiB,CAQhG;AAED;uEACuE;AACvE,MAAM,WAAW,eAAe;IAC9B,UAAU,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC;IAC7C,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC,CAAC;CAC1C;AAED;+DAC+D;AAC/D,wBAAgB,WAAW,CAAC,GAAG,EAAE,YAAY,GAAG,eAAe,CAU9D"}

package/dist/render/registry.js

@@ -11,3 +11,16 @@ export function defineRegistry({ components }) {
         defaultIcon: (name, role) => (role ? byName.get(name)?.defaultIconByRole?.[role] : undefined),
     };
 }
+/** Seed an empty {@link ComponentValues} from a component's schema: attribute defaults (or '' / false)
+ *  and empty slot values ([] for repeatable, '' otherwise). */
+export function emptyValues(def) {
+    const attributes = {};
+    for (const field of def.attributes ?? []) {
+        attributes[field.key] = field.default ?? (field.type === 'boolean' ? false : '');
+    }
+    const slots = {};
+    for (const slot of def.slots ?? []) {
+        slots[slot.name] = slot.kind === 'repeatable' ? [] : '';
+    }
+    return { attributes, slots };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@glw907/cairn-cms",
-  "version": "0.9.0",
+  "version": "0.10.0",
   "description": "Embedded, magic-link, GitHub-committing CMS for SvelteKit/Cloudflare sites.",
   "type": "module",
   "sideEffects": [
@@ -79,6 +79,7 @@
     "remark-gfm": "^4",
     "remark-parse": "^11.0.0",
     "remark-rehype": "^11.1.2",
+    "remark-stringify": "^11.0.0",
     "unified": "^11.0.5",
     "unist-util-visit": "^5.1.0",
     "yaml": "^2"

package/src/lib/components/ComponentForm.svelte

@@ -0,0 +1,178 @@
+<!--
+@component
+The schema-driven fill form for one component. It holds the working ComponentValues, seeded from
+emptyValues(def), and renders attribute fields and the title/body and other non-repeatable slots.
+Submit (Task 6) serializes and validates through buildComponentInsert and calls onInsert with the
+markdown. Back returns to the picker. This is not a nested HTML form; Insert calls a callback.
+-->
+<script lang="ts">
+  import { untrack } from 'svelte';
+  import { emptyValues, type ComponentDef } from '../render/registry.js';
+  import { buildComponentInsert } from '../render/component-insert.js';
+  import type { IconSet } from '../render/glyph.js';
+  import IconPicker from './IconPicker.svelte';
+
+  interface Props {
+    def: ComponentDef;
+    icons?: IconSet;
+    /** Called with the serialized markdown when the form validates. */
+    onInsert: (markdown: string) => void;
+    /** Return to the picker. */
+    onBack: () => void;
+  }
+
+  let { def, icons, onInsert, onBack }: Props = $props();
+
+  // Working values, seeded once from the schema. $state makes the nested records deeply reactive.
+  // untrack marks the seed as a deliberate one-time read of the initial def, not a reactive miss.
+  let values = $state(untrack(() => emptyValues(def)));
+
+  const attributes = $derived(def.attributes ?? []);
+  // Non-repeatable slots render here; the repeatable list is handled separately.
+  const flatSlots = $derived((def.slots ?? []).filter((s) => s.kind !== 'repeatable'));
+  const repeatableSlots = $derived((def.slots ?? []).filter((s) => s.kind === 'repeatable'));
+
+  // The live $state proxy array for a repeatable slot, so push/splice stay reactive.
+  function slotItems(name: string): string[] {
+    const v = values.slots[name];
+    return Array.isArray(v) ? v : [];
+  }
+
+  // Typed accessors over the unions so explicit value targets stay sound.
+  function asString(key: string): string {
+    const v = values.attributes[key];
+    return typeof v === 'string' ? v : '';
+  }
+  function asBool(key: string): boolean {
+    return values.attributes[key] === true;
+  }
+  function slotString(name: string): string {
+    const v = values.slots[name];
+    return typeof v === 'string' ? v : '';
+  }
+
+  // Field-keyed validation errors from the last submit, keyed by attribute key or slot name.
+  let errors = $state<Record<string, string>>({});
+
+  // Serialize and validate through the pure helper. On success clear errors and emit the markdown;
+  // on failure keep the field-keyed errors so each field can show its message and insert nothing.
+  async function submit() {
+    const result = await buildComponentInsert(def, values);
+    if (result.ok) {
+      errors = {};
+      onInsert(result.markdown);
+    } else {
+      errors = result.errors;
+    }
+  }
+</script>
+
+<div class="flex flex-col gap-3">
+  <div class="flex items-center justify-between">
+    <h3 class="text-sm font-semibold">{def.label}</h3>
+    <button type="button" class="btn btn-ghost btn-xs" onclick={onBack}>Back</button>
+  </div>
+
+  {#each attributes as field (field.key)}
+    {#if field.type === 'boolean'}
+      <label class="label cursor-pointer justify-start gap-2">
+        <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)}
+          onchange={(e) => (values.attributes[field.key] = e.currentTarget.checked)}
+        />
+        <span class="text-sm">{field.label}</span>
+      </label>
+    {:else if field.type === 'select'}
+      <label class="flex flex-col gap-1">
+        <span class="text-sm font-medium">{field.label}</span>
+        <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)}
+          onchange={(e) => (values.attributes[field.key] = e.currentTarget.value)}
+        >
+          {#if !field.required}<option value="">—</option>{/if}
+          {#each field.options ?? [] as opt (opt)}<option value={opt}>{opt}</option>{/each}
+        </select>
+      </label>
+    {:else if field.type === 'icon' && icons}
+      <div class="flex flex-col gap-1">
+        <span class="text-sm font-medium">{field.label}</span>
+        <IconPicker
+          {icons}
+          value={asString(field.key)}
+          required={field.required ?? false}
+          onChange={(name) => (values.attributes[field.key] = name)}
+        />
+      </div>
+    {:else}
+      <label class="flex flex-col gap-1">
+        <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)}
+          oninput={(e) => (values.attributes[field.key] = e.currentTarget.value)}
+        />
+      </label>
+    {/if}
+    {#if errors[field.key]}<span id={`err-${field.key}`} role="alert" class="text-error text-xs">{errors[field.key]}</span>{/if}
+  {/each}
+
+  {#each flatSlots as slot (slot.name)}
+    {#if slot.kind === 'markdown'}
+      <label class="flex flex-col gap-1">
+        <span class="text-sm font-medium">{slot.label}</span>
+        <textarea
+          class="textarea"
+          aria-label={slot.label}
+          aria-invalid={Boolean(errors[slot.name])}
+          aria-describedby={errors[slot.name] ? `err-${slot.name}` : undefined}
+          rows={3}
+          value={slotString(slot.name)}
+          oninput={(e) => (values.slots[slot.name] = e.currentTarget.value)}
+        ></textarea>
+      </label>
+    {:else}
+      <label class="flex flex-col gap-1">
+        <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)}
+          oninput={(e) => (values.slots[slot.name] = e.currentTarget.value)}
+        />
+      </label>
+    {/if}
+    {#if errors[slot.name]}<span id={`err-${slot.name}`} role="alert" class="text-error text-xs">{errors[slot.name]}</span>{/if}
+  {/each}
+
+  {#each repeatableSlots as slot (slot.name)}
+    {@const items = slotItems(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)}
+        <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>
+        </div>
+      {/each}
+      <button type="button" class="btn btn-sm self-start" onclick={() => items.push('')}>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}
+
+  <button type="button" class="btn btn-primary btn-sm mt-2" onclick={submit}>Insert</button>
+</div>

package/src/lib/components/ComponentInsertDialog.svelte

@@ -0,0 +1,92 @@
+<!--
+@component
+The Insert control and its modal. The picker lists each actionable component with its description and
+intended use. A component with a schema opens the guided ComponentForm; a template-only component
+inserts directly; a component with neither is not listed. Built on a native <dialog> for focus
+trapping and Escape, following the dropdown's a11y conventions used elsewhere in the admin.
+-->
+<script lang="ts">
+  import type { ComponentRegistry, ComponentDef } from '../render/registry.js';
+  import type { IconSet } from '../render/glyph.js';
+  import ComponentForm from './ComponentForm.svelte';
+
+  interface Props {
+    /** The site's component registry. */
+    registry?: ComponentRegistry;
+    /** Insert markdown at the editor cursor. */
+    insert: (text: string) => void;
+    /** The site's icon set, for icon fields. */
+    icons?: IconSet;
+  }
+
+  let { registry, insert, icons }: Props = $props();
+
+  let dialog = $state<HTMLDialogElement | null>(null);
+  let picked = $state<ComponentDef | null>(null);
+
+  function hasSchema(def: ComponentDef): boolean {
+    return (def.attributes?.length ?? 0) > 0 || (def.slots?.length ?? 0) > 0;
+  }
+  function actionable(def: ComponentDef): boolean {
+    return hasSchema(def) || Boolean(def.insertTemplate);
+  }
+
+  const defs = $derived((registry?.defs ?? []).filter(actionable));
+
+  function open() {
+    picked = null;
+    dialog?.showModal();
+  }
+  function close() {
+    picked = null;
+    dialog?.close();
+  }
+  function choose(def: ComponentDef) {
+    if (hasSchema(def)) {
+      picked = def;
+    } else {
+      insert(def.insertTemplate ?? '');
+      close();
+    }
+  }
+  function onInsert(markdown: string) {
+    insert(markdown);
+    close();
+  }
+</script>
+
+{#if defs.length > 0}
+  <button type="button" class="btn btn-sm btn-ghost" aria-haspopup="dialog" aria-label="Insert component" onclick={open}>Insert</button>
+
+  <dialog class="modal" aria-labelledby="cairn-insert-dialog-title" bind:this={dialog} onclose={() => (picked = null)}>
+    <div class="modal-box">
+      <div class="mb-3 flex items-center justify-between">
+        <h2 id="cairn-insert-dialog-title" class="text-base font-semibold">Insert component</h2>
+        <button type="button" class="btn btn-ghost btn-sm" aria-label="Close" onclick={close}>✕</button>
+      </div>
+
+      {#if picked}
+        {#key picked}
+          <ComponentForm def={picked} {icons} {onInsert} onBack={() => (picked = null)} />
+        {/key}
+      {:else}
+        <ul class="menu w-full">
+          {#each defs as def (def.name)}
+            <li>
+              <button type="button" onclick={() => choose(def)}>
+                <span class="flex flex-col items-start">
+                  <span class="font-medium">{def.label}</span>
+                  {#if def.description}<span class="text-xs text-[var(--color-muted)]">{def.description}</span>{/if}
+                  {#if def.use}<span class="text-xs text-[var(--color-muted)]">{def.use}</span>{/if}
+                </span>
+              </button>
+            </li>
+          {/each}
+        </ul>
+      {/if}
+    </div>
+    <form method="dialog" class="modal-backdrop">
+      <button tabindex="-1" aria-label="Close">close</button>
+    </form>
+  </dialog>
+{/if}