@velastack/cms 0.3.1 → 0.5.0

package/dist/components/cms/cms-text.svelte

@@ -1,30 +1,29 @@
 <script lang="ts">
 	import type { Snippet } from 'svelte';
-	import { getCmsScope } from './scope.js';
-	import { cmsStore, type CmsScopeRef } from './cms-store.svelte.js';
+	import { useCmsField } from './use-cms-field.svelte.js';
 
 	type Props = {
 		name: string;
+		/** `'root'` for the root layout scope, or an explicit scope id. */
+		scope?: string;
 		fallback?: string;
-		/** Per-item override used by `CmsRepeater`. */
+		/** Per-item override used by structured components. */
 		value?: unknown;
 		children?: Snippet;
 	};
 
-	let { name, fallback, value, children }: Props = $props();
+	let { name, scope, fallback, value, children }: Props = $props();
 
-	const scope = getCmsScope();
-	const ref = $derived<CmsScopeRef | null>(
-		scope ? { scopeId: scope.scopeId, routeId: scope.routeId, params: scope.params } : null
+	// `undefined` → fallback (or children); `null` → cleared, shown empty.
+	const field = useCmsField(
+		() => ({ name, scope, value }),
+		(raw): string | undefined => {
+			if (raw === undefined) return fallback;
+			return typeof raw === 'string' ? raw : '';
+		}
 	);
 
-	const resolved = $derived.by(() => {
-		if (value !== undefined) return value;
-		return ref ? cmsStore.getValue(ref, name) : undefined;
-	});
-
-	const display = $derived(typeof resolved === 'string' ? resolved : (fallback ?? ''));
-	const editable = $derived(cmsStore.isEditing && value === undefined && !!ref);
+	const display = $derived(field.current ?? '');
 
 	let el = $state<HTMLSpanElement>();
 	let childrenEl = $state<HTMLElement>();
@@ -32,17 +31,13 @@
 	let composing = false;
 
 	$effect.pre(() => {
-		if (editable && childrenEl && initialFromChildren === undefined) {
+		if (field.editable && childrenEl && initialFromChildren === undefined) {
 			const text = childrenEl.textContent?.trim();
 			initialFromChildren = text || undefined;
 		}
 	});
 
-	const editValue = $derived.by(() => {
-		if (typeof resolved === 'string') return resolved;
-		if (fallback !== undefined) return fallback;
-		return initialFromChildren ?? '';
-	});
+	const editValue = $derived(field.current ?? initialFromChildren ?? '');
 
 	$effect(() => {
 		if (!el) return;
@@ -52,14 +47,9 @@
 		el.textContent = target;
 	});
 
-	const writeValue = (text: string) => {
-		if (!ref) return;
-		cmsStore.setValue(ref, name, text);
-	};
-
 	const onInput = (e: Event) => {
 		if (composing) return;
-		writeValue((e.currentTarget as HTMLElement).textContent ?? '');
+		field.set((e.currentTarget as HTMLElement).textContent ?? '');
 	};
 
 	const onKeydown = (e: KeyboardEvent) => {
@@ -68,11 +58,11 @@
 
 	const onCompositionEnd = (e: CompositionEvent) => {
 		composing = false;
-		writeValue((e.currentTarget as HTMLElement).textContent ?? '');
+		field.set((e.currentTarget as HTMLElement).textContent ?? '');
 	};
 </script>
 
-{#if editable && ref}
+{#if field.editable && field.ref}
 	<!-- Mounted straight into edit mode (navigation while editing): the
 	     children branch below never rendered, so render it hidden once to
 	     capture the default text. Removed as soon as it's captured. -->
@@ -85,7 +75,7 @@
 		contenteditable="plaintext-only"
 		data-placeholder={name}
 		data-cms-name={name}
-		data-cms-scope={scope?.scopeId ?? '?'}
+		data-cms-scope={field.ref.scopeId}
 		role="textbox"
 		tabindex="0"
 		aria-multiline="false"
@@ -98,10 +88,13 @@
 	></span>
 {:else if display}
 	{display}
+{:else if field.raw === null}
+	<!-- cleared by the editor: render nothing -->
 {:else if children}
 	<span bind:this={childrenEl} class="cms-text-children">{@render children()}</span>
 {:else}
-	<span class="cms-missing" data-cms-name={name} data-cms-scope={scope?.scopeId ?? '?'}>{name}</span
+	<span class="cms-missing" data-cms-name={name} data-cms-scope={field.ref?.scopeId ?? '?'}
+		>{name}</span
 	>
 {/if}
 

package/dist/components/cms/cms-text.svelte.d.ts

@@ -1,8 +1,10 @@
 import type { Snippet } from 'svelte';
 type Props = {
     name: string;
+    /** `'root'` for the root layout scope, or an explicit scope id. */
+    scope?: string;
     fallback?: string;
-    /** Per-item override used by `CmsRepeater`. */
+    /** Per-item override used by structured components. */
     value?: unknown;
     children?: Snippet;
 };

package/dist/components/cms/scope.d.ts

@@ -5,6 +5,16 @@ export type CmsScope = {
     routeId: string;
     params: Record<string, string>;
 };
+/**
+ * One CMS component usage as recorded by the Vite plugin: which value it
+ * reads and which component type reads it.
+ */
+export type CmsManifestUsage = {
+    name: string;
+    /** Canonical exported component name (`CmsText`, `CmsHours`, …). */
+    component: string;
+    preset?: string;
+};
 export type CmsScopeEntry = {
     scopeId: string;
     kind: 'layout' | 'page';
@@ -15,23 +25,31 @@ export type CmsScopeEntry = {
      * `metadata` branch shows up here too (e.g. `'metadata.title'`).
      */
     fields: string[];
+    /** The usages behind `fields`, with component types. Absent on hand-built manifests. */
+    usages?: CmsManifestUsage[];
 };
 /**
- * Schema for the project-wide site scope. Authored on `createCms({ site })`.
- * Top-level keys are sections rendered as groups in the Site Settings panel;
- * each section's `fields` keys become path segments in the stored tree
- * (`branding.name`, `social.twitter`).
+ * Schema for the project-wide site scope: the **Site Options** panel.
+ * Authored on `createCms({ site })`. Top-level keys are sections rendered as
+ * groups; each section's `fields` keys become path segments in the stored
+ * tree (`seo.schemaType`, `seo.shareImage`).
+ *
+ * Site options are for values that never render on the page — the schema.org
+ * type, the default share image, enabled locales. Anything a visitor sees
+ * belongs in the root layout scope, edited where it renders.
  *
  * `type` selects the input widget. Storage is unconstrained — the schema is
  * a UI hint, not an enforced type for the underlying tree (to keep the data
  * model uniform with pages/layouts and avoid destructive prunes when fields
  * are added/removed).
  */
-export type SiteFieldType = 'text' | 'markdown' | 'number' | 'datetime' | 'url' | 'color' | 'image';
+export type SiteFieldType = 'text' | 'markdown' | 'number' | 'datetime' | 'url' | 'color' | 'image' | 'enum' | 'boolean';
 export type SiteFieldSchema = {
     type: SiteFieldType;
     label: string;
     placeholder?: string;
+    /** Options for `enum` fields. */
+    values?: readonly string[];
 };
 export type SiteSectionSchema = {
     label: string;
@@ -104,6 +122,8 @@ export type CmsManifestScope = {
      * `metadata` branch shows up here too (e.g. `'metadata.title'`).
      */
     fields: string[];
+    /** The usages behind `fields`, with component types. Absent on hand-built manifests. */
+    usages?: CmsManifestUsage[];
 };
 export type CmsManifestRoute = {
     scopes: CmsManifestScope[];

package/dist/components/cms/structured-registry.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Which exported component reads which structured shape. Structured
+ * components register their schema at module load, so the Locales panel can
+ * count translatable strings for every usage the manifest recorded on the
+ * current route without importing the components themselves.
+ */
+import type { Structured } from '../../core/structured.js';
+import type { Tree } from '../../core/path.js';
+export declare const registerStructured: <T extends Tree>(schema: Structured<T>) => Structured<T>;
+export declare const getStructured: (component: string) => Structured<Tree> | undefined;

package/dist/components/cms/structured-registry.js

@@ -0,0 +1,6 @@
+const registry = new Map();
+export const registerStructured = (schema) => {
+    registry.set(schema.component, schema);
+    return schema;
+};
+export const getStructured = (component) => registry.get(component);

package/dist/components/cms/use-cms-field.svelte.d.ts

@@ -0,0 +1,54 @@
+/**
+ * The one piece of plumbing every display component shares: find the scope,
+ * read the value, decide whether it is editable, write it back.
+ *
+ * Scope resolution (`scope` prop):
+ * - absent → the enclosing route scope from context, installed by the plugin
+ *   into every `+layout.svelte` / `+page.svelte`.
+ * - `'root'` → the root layout scope `layout:/`, so a page can read and write
+ *   a value that lives site-wide (hours, contact, navigation, branding). The
+ *   payload already carries every enclosing layout tree, and the root layout
+ *   encloses everything.
+ * - any other string → that scope id verbatim (`layout:/(public)`), for a
+ *   value owned by an intermediate layout. Only param-less scopes can be
+ *   addressed this way.
+ *
+ * Read rule (see `core/structured.ts`): `undefined` means nothing is stored
+ * and the component shows its fallback; `null` means the editor cleared the
+ * field, and the component shows it empty. Never conflate the two — that is
+ * the bug where a cleared field reverts to the template's demo copy.
+ */
+import { type CmsScope } from './scope.js';
+import { type CmsScopeRef } from './cms-store.svelte.js';
+export declare const ROOT_SCOPE_ID = "layout:/";
+export type CmsFieldInput = {
+    name: string;
+    scope?: string;
+    /** Per-item override: disables editing and scope lookup. */
+    value?: unknown;
+};
+export declare const resolveScopeRef: (scope: string | undefined, context: CmsScope | undefined) => CmsScopeRef | null;
+export type CmsField<T> = {
+    /** Resolved scope, or `null` outside any route scope. */
+    readonly ref: CmsScopeRef | null;
+    /** Raw stored value: `undefined` (nothing), `null` (cleared) or the value. */
+    readonly raw: unknown;
+    /** What to render, per the component's `read`. */
+    readonly current: T;
+    readonly editable: boolean;
+    readonly name: string;
+    /** Write the whole value into the draft. Pass `null` to clear. `locale`
+     * defaults to the locale being edited; structured editors pass the
+     * default locale for structure and another locale for its `$t` strings. */
+    set: (next: unknown, locale?: string) => void;
+    /** Write a value at a sub-path of this field, e.g. a `$t` string. */
+    setAt: (subPath: string, next: unknown, locale?: string) => void;
+    /** Read this field (or a sub-path of it) in a specific locale. */
+    getIn: (locale: string, subPath?: string) => unknown;
+    clear: () => void;
+};
+/**
+ * Call once at component init. `input` is an accessor so prop changes flow
+ * through; `read` turns the raw stored value into what the component renders.
+ */
+export declare const useCmsField: <T>(input: () => CmsFieldInput, read: (raw: unknown) => T) => CmsField<T>;

package/dist/components/cms/use-cms-field.svelte.js

@@ -0,0 +1,83 @@
+/**
+ * The one piece of plumbing every display component shares: find the scope,
+ * read the value, decide whether it is editable, write it back.
+ *
+ * Scope resolution (`scope` prop):
+ * - absent → the enclosing route scope from context, installed by the plugin
+ *   into every `+layout.svelte` / `+page.svelte`.
+ * - `'root'` → the root layout scope `layout:/`, so a page can read and write
+ *   a value that lives site-wide (hours, contact, navigation, branding). The
+ *   payload already carries every enclosing layout tree, and the root layout
+ *   encloses everything.
+ * - any other string → that scope id verbatim (`layout:/(public)`), for a
+ *   value owned by an intermediate layout. Only param-less scopes can be
+ *   addressed this way.
+ *
+ * Read rule (see `core/structured.ts`): `undefined` means nothing is stored
+ * and the component shows its fallback; `null` means the editor cleared the
+ * field, and the component shows it empty. Never conflate the two — that is
+ * the bug where a cleared field reverts to the template's demo copy.
+ */
+import { getCmsScope } from './scope.js';
+import { cmsStore } from './cms-store.svelte.js';
+export const ROOT_SCOPE_ID = 'layout:/';
+export const resolveScopeRef = (scope, context) => {
+    if (scope === 'root')
+        return { scopeId: ROOT_SCOPE_ID, routeId: '/', params: {} };
+    if (scope) {
+        const colon = scope.indexOf(':');
+        const routeId = colon === -1 ? scope : scope.slice(colon + 1);
+        return { scopeId: colon === -1 ? `layout:${scope}` : scope, routeId, params: {} };
+    }
+    if (!context)
+        return null;
+    return { scopeId: context.scopeId, routeId: context.routeId, params: context.params };
+};
+/**
+ * Call once at component init. `input` is an accessor so prop changes flow
+ * through; `read` turns the raw stored value into what the component renders.
+ */
+export const useCmsField = (input, read) => {
+    const context = getCmsScope();
+    const ref = $derived(resolveScopeRef(input().scope, context));
+    const raw = $derived.by(() => {
+        const { name, value } = input();
+        if (value !== undefined)
+            return value;
+        return ref ? cmsStore.getValue(ref, name) : undefined;
+    });
+    const current = $derived(read(raw));
+    const editable = $derived(cmsStore.isEditing && input().value === undefined && !!ref);
+    const set = (next, locale) => {
+        if (ref)
+            cmsStore.setValue(ref, input().name, next, locale);
+    };
+    const setAt = (subPath, next, locale) => {
+        if (ref)
+            cmsStore.setValue(ref, `${input().name}.${subPath}`, next, locale);
+    };
+    const getIn = (locale, subPath) => ref
+        ? cmsStore.getValue(ref, subPath ? `${input().name}.${subPath}` : input().name, locale)
+        : undefined;
+    return {
+        get ref() {
+            return ref;
+        },
+        get raw() {
+            return raw;
+        },
+        get current() {
+            return current;
+        },
+        get editable() {
+            return editable;
+        },
+        get name() {
+            return input().name;
+        },
+        set,
+        setAt,
+        getIn,
+        clear: () => set(null)
+    };
+};

package/dist/core/metadata.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Page metadata → `svelte-meta-tags` props.
+ *
+ * The page scope's `metadata` branch holds what the SEO panel edits (see
+ * `DEFAULT_METADATA_SCHEMA`). This maps it onto the object
+ * `definePageMetaTags` / `<MetaTags>` accept, so a template's root layout is
+ * one line: `deepMerge(baseMetaTags, toMetaTags(cms.metadata, { siteName }))`.
+ * Share fields fall back to the search fields, and the site name — read from
+ * the root layout's `branding.name` — supplies the title template and the
+ * Open Graph site name.
+ */
+export type MetaTagsInput = Record<string, unknown>;
+export type MetaTagsOptions = {
+    /** The root layout's `branding.name`; drives `titleTemplate` and `openGraph.siteName`. */
+    siteName?: string;
+    /** Title template when `siteName` is set. `%s` is the page title. Default `'%s · <siteName>'`. */
+    titleTemplate?: string;
+    /** Absolute URL of the page, for `openGraph.url` when no canonical is set. */
+    url?: string;
+};
+export type MetaTagsOutput = {
+    title?: string;
+    titleTemplate?: string;
+    description?: string;
+    canonical?: string;
+    robots?: string;
+    openGraph?: {
+        title?: string;
+        description?: string;
+        url?: string;
+        siteName?: string;
+        images?: Array<{
+            url: string;
+            alt?: string;
+        }>;
+    };
+    twitter?: {
+        cardType?: 'summary' | 'summary_large_image';
+        title?: string;
+        description?: string;
+        image?: string;
+    };
+};
+export declare const toMetaTags: (metadata: MetaTagsInput, options?: MetaTagsOptions) => MetaTagsOutput;

package/dist/core/metadata.js

@@ -0,0 +1,59 @@
+const str = (v) => (typeof v === 'string' && v !== '' ? v : undefined);
+const imageUrl = (v) => {
+    if (typeof v === 'string')
+        return v ? { url: v } : undefined;
+    if (v && typeof v === 'object' && !Array.isArray(v)) {
+        const r = v;
+        if (typeof r.url === 'string' && r.url) {
+            return typeof r.alt === 'string' && r.alt ? { url: r.url, alt: r.alt } : { url: r.url };
+        }
+    }
+    return undefined;
+};
+export const toMetaTags = (metadata, options = {}) => {
+    const title = str(metadata.title);
+    const description = str(metadata.description);
+    const ogTitle = str(metadata.ogTitle) ?? title;
+    const ogDescription = str(metadata.ogDescription) ?? description;
+    const image = imageUrl(metadata.ogImage);
+    const canonical = str(metadata.canonical);
+    const card = str(metadata.twitterCard);
+    const out = {};
+    if (title)
+        out.title = title;
+    if (options.siteName)
+        out.titleTemplate = options.titleTemplate ?? `%s · ${options.siteName}`;
+    if (description)
+        out.description = description;
+    if (canonical)
+        out.canonical = canonical;
+    if (metadata.noindex === true)
+        out.robots = 'noindex, nofollow';
+    const og = {};
+    if (ogTitle)
+        og.title = ogTitle;
+    if (ogDescription)
+        og.description = ogDescription;
+    if (canonical ?? options.url)
+        og.url = canonical ?? options.url;
+    if (options.siteName)
+        og.siteName = options.siteName;
+    if (image)
+        og.images = [image];
+    if (Object.keys(og).length > 0)
+        out.openGraph = og;
+    const tw = {};
+    if (card === 'summary' || card === 'summary_large_image')
+        tw.cardType = card;
+    else if (image)
+        tw.cardType = 'summary_large_image';
+    if (ogTitle)
+        tw.title = ogTitle;
+    if (ogDescription)
+        tw.description = ogDescription;
+    if (image)
+        tw.image = image.url;
+    if (Object.keys(tw).length > 0)
+        out.twitter = tw;
+    return out;
+};

package/dist/core/structured.d.ts

@@ -0,0 +1,108 @@
+/**
+ * Structured values: the shapes behind the editor components (hours, team,
+ * testimonials, …) and the two rules every one of them follows.
+ *
+ * 1. **Versioned shapes, whole-object writes.** A structured value is a plain
+ *    object with a `v` version number. Components never patch a leaf inside
+ *    it; they read the whole value through the schema's `normalize`, change
+ *    it, and write the whole object back. A field the editor clears is
+ *    written as `null`, never dropped: the draft and release trees deep-merge
+ *    over the published tree, and a missing key merges to "unchanged" while
+ *    `null` merges to "cleared". That is what stops a cleared field from
+ *    reverting to the template's demo copy.
+ *
+ * 2. **Localisation is a string overlay, never a second structure.** The
+ *    default locale stores the full value at `<name>`. Every other locale
+ *    stores only strings, at `<name>.$t.<id>.<field>`, keyed by the stable
+ *    `id` of the list item they translate (the reserved id `_` addresses the
+ *    value's own root fields). Because objects deep-merge across locales,
+ *    reading `es` yields the default structure plus the `es` overlay, and
+ *    {@link applyTranslations} folds the strings in. Structure edits happen in
+ *    the default locale only, so the item list can never fork between
+ *    languages.
+ */
+import { type Tree } from './path.js';
+/** Branch under a structured value that holds a locale's string overlay. */
+export declare const TRANSLATIONS_KEY = "$t";
+/** Overlay id that addresses the structured value's root fields. */
+export declare const ROOT_ID = "_";
+/** `{ [itemId]: { [field]: string } }` — what a non-default locale stores. */
+export type TranslationOverlay = Record<string, Record<string, string>>;
+export type StructuredItem = {
+    id: string;
+} & Record<string, unknown>;
+export type StructuredSchema<T extends Tree> = {
+    /** Exported component name, e.g. `'CmsHours'`. Recorded in the manifest. */
+    component: string;
+    /** Current shape version, written as `v` on every value. */
+    version: number;
+    /** Root-level fields holding translatable strings, e.g. `['note']`. */
+    translatable: readonly string[];
+    /** The item list, when the value has one, and the item fields that translate. */
+    items?: {
+        key: string;
+        translatable: readonly string[];
+    };
+    /**
+     * Turn anything the store may hold — an older version, a hand-seeded
+     * partial object, garbage — into the current shape. Must never throw.
+     */
+    normalize: (raw: unknown) => T;
+    /** The cleared value: what an editor gets after "Clear". */
+    empty: () => T;
+};
+export type Structured<T extends Tree> = StructuredSchema<T> & {
+    /**
+     * Resolve a stored value the way a display component reads it:
+     * `undefined` (nothing stored) → the fallback; `null` (cleared) → empty;
+     * anything else → normalized, with the locale overlay applied.
+     */
+    read: (raw: unknown, fallback: T | undefined) => T;
+};
+export declare const isPlainObject: (v: unknown) => v is Tree;
+export declare const defineStructured: <T extends Tree>(schema: StructuredSchema<T>) => Structured<T>;
+/** Path of one translated string: `<name>.$t.<id>.<field>`. */
+export declare const translationPath: (name: string, id: string, field: string) => string;
+/** The `$t` branch of a stored value, when it is one. */
+export declare const extractTranslations: (raw: unknown) => TranslationOverlay | undefined;
+/** A copy of `raw` without its `$t` branch, so a whole-object write in the
+ * default locale never carries another locale's strings. */
+export declare const stripTranslations: (raw: unknown) => unknown;
+/**
+ * Fold a locale's string overlay into a normalized default-locale value.
+ * Root fields come from the `_` id; item fields from the item's own `id`.
+ * Only non-empty strings override, so an untranslated field shows the
+ * default-locale text rather than a blank.
+ */
+export declare const applyTranslations: <T extends Tree>(value: T, overlay: TranslationOverlay | undefined, schema: Pick<StructuredSchema<T>, "translatable" | "items">) => T;
+export type TranslatableField = {
+    /** Overlay id: an item id, or `_` for a root field. */
+    id: string;
+    field: string;
+    /** The default-locale string being translated. */
+    source: string;
+};
+/**
+ * Every translatable, non-empty string in a normalized default-locale value.
+ * Drives the popover's translation tab and the Locales panel's counts.
+ */
+export declare const translatableFields: <T extends Tree>(value: T, schema: Pick<StructuredSchema<T>, "translatable" | "items">) => TranslatableField[];
+/** How many translatable strings a locale's overlay still lacks. */
+export declare const countTranslations: <T extends Tree>(value: T, overlay: TranslationOverlay | undefined, schema: Pick<StructuredSchema<T>, "translatable" | "items">) => {
+    total: number;
+    missing: number;
+};
+export declare const asString: (v: unknown, fallback?: string) => string;
+export declare const asNumber: (v: unknown, fallback?: number | null) => number | null;
+export declare const asBoolean: (v: unknown, fallback?: boolean) => boolean;
+/**
+ * Normalize a list of items, guaranteeing every item carries a string `id`.
+ * An item without one (a hand-written seed, say) gets a deterministic
+ * `item-<index>` so reads stay stable until the editor next writes the list,
+ * at which point the ids are persisted.
+ */
+export declare const asItems: <I extends StructuredItem>(raw: unknown, normalizeItem: (item: Tree, index: number) => Omit<I, "id">) => I[];
+/** A short random id for a newly added item. Stable once written. */
+export declare const newItemId: () => string;
+/** Read a structured value's overlay for one locale out of a whole scope tree. */
+export declare const overlayAt: (tree: Tree | undefined, name: string) => TranslationOverlay | undefined;