@velastack/cms 0.4.0 → 0.5.1

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/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/shapes/collection.d.ts

@@ -0,0 +1,60 @@
+/**
+ * `CmsCollection`: services, rooms, programmes, tours, projects, case
+ * studies. One fixed core plus a `details` key-value list for kind-specific
+ * facts. Lists only: an item's `link` covers "read more".
+ */
+import type { Tree } from '../path.js';
+import { type ListValue } from './form.js';
+import { type CmsImageValue } from './image.js';
+import { type CmsLinkValue } from './link.js';
+export type CollectionDetail = {
+    id: string;
+    label: string;
+    value: string;
+};
+export type CollectionPrice = {
+    amount: number | null;
+    /** ISO 4217, e.g. `EUR`. */
+    currency: string;
+    /** `night`, `person`, `hour`… shown after the amount. */
+    period: string;
+    /** `from`, shown before the amount. */
+    prefix: string;
+};
+export type CollectionItem = {
+    id: string;
+    title: string;
+    summary: string;
+    body: string;
+    image: CmsImageValue | null;
+    gallery: CmsImageValue[];
+    price: CollectionPrice;
+    duration: string;
+    link: CmsLinkValue | null;
+    tags: string[];
+    features: string[];
+    featured: boolean;
+    hidden: boolean;
+    details: CollectionDetail[];
+};
+export type CmsCollectionValue = ListValue<CollectionItem>;
+export type CollectionItemView = CollectionItem & {
+    href: string | null;
+};
+export declare const cmsCollection: import("./form.js").FormShape<CmsCollectionValue>;
+export type CollectionSlice = {
+    /** At most this many items. */
+    limit?: number;
+    /** Only featured items. */
+    featured?: boolean;
+    /** Only items carrying this tag. */
+    tag?: string;
+};
+/** Visible items (not hidden, with a title), optionally sliced. */
+export declare const collectionView: (value: CmsCollectionValue, slice?: CollectionSlice) => CollectionItemView[];
+/** Every tag in use, in first-seen order. */
+export declare const collectionTags: (value: CmsCollectionValue) => string[];
+/** `from €120 / night`, or empty when there is no amount. */
+export declare const formatCollectionPrice: (price: CollectionPrice, locale: string) => string;
+/** A schema.org `ItemList` of the visible items. */
+export declare const toItemList: (value: CmsCollectionValue, baseUrl?: string) => Tree;

package/dist/core/shapes/collection.js

@@ -0,0 +1,194 @@
+import { asBoolean, asItems, asNumber, asString, asStrings, isPlainObject } from '../structured.js';
+import { defineForm } from './form.js';
+import { asImage, asImages } from './image.js';
+import { asLink, linkHref } from './link.js';
+export const cmsCollection = defineForm({
+    component: 'CmsCollection',
+    label: 'Collection',
+    version: 1,
+    translatable: [],
+    items: {
+        key: 'items',
+        translatable: [
+            'title',
+            'summary',
+            'body',
+            'duration',
+            'tags',
+            'features',
+            'price.period',
+            'price.prefix'
+        ],
+        items: { key: 'details', translatable: ['label', 'value'] }
+    },
+    normalize: (raw) => {
+        const items = Array.isArray(raw) ? raw : isPlainObject(raw) ? raw.items : [];
+        return {
+            v: 1,
+            items: asItems(items, (r) => {
+                const p = isPlainObject(r.price) ? r.price : {};
+                return {
+                    title: asString(r.title),
+                    summary: asString(r.summary),
+                    body: asString(r.body),
+                    image: asImage(r.image),
+                    gallery: asImages(r.gallery),
+                    price: {
+                        amount: asNumber(p.amount),
+                        currency: asString(p.currency),
+                        period: asString(p.period),
+                        prefix: asString(p.prefix)
+                    },
+                    duration: asString(r.duration),
+                    link: asLink(r.link),
+                    tags: asStrings(r.tags).filter((t) => t !== ''),
+                    features: asStrings(r.features).filter((f) => f !== ''),
+                    featured: asBoolean(r.featured),
+                    hidden: asBoolean(r.hidden),
+                    details: asItems(r.details, (d) => ({
+                        label: asString(d.label),
+                        value: asString(d.value)
+                    }))
+                };
+            })
+        };
+    },
+    empty: () => ({ v: 1, items: [] }),
+    fields: [
+        {
+            key: 'items',
+            label: 'Items',
+            type: 'list',
+            itemLabel: 'item',
+            titleKey: 'title',
+            blank: () => ({
+                title: '',
+                summary: '',
+                body: '',
+                image: null,
+                gallery: [],
+                price: { amount: null, currency: '', period: '', prefix: '' },
+                duration: '',
+                link: null,
+                tags: [],
+                features: [],
+                featured: false,
+                hidden: false,
+                details: []
+            }),
+            fields: [
+                { key: 'title', label: 'Title', type: 'text', group: 'Details' },
+                { key: 'summary', label: 'Summary', type: 'long-string', group: 'Details' },
+                { key: 'body', label: 'Body', type: 'html', group: 'Details' },
+                {
+                    key: 'duration',
+                    label: 'Duration',
+                    type: 'text',
+                    half: true,
+                    placeholder: '3 hours',
+                    group: 'Details'
+                },
+                { key: 'link', label: 'Link', type: 'link', group: 'Details' },
+                {
+                    key: 'tags',
+                    label: 'Tags',
+                    type: 'strings',
+                    placeholder: 'One per line',
+                    group: 'Details'
+                },
+                {
+                    key: 'features',
+                    label: 'Features',
+                    type: 'strings',
+                    placeholder: 'One per line',
+                    group: 'Details'
+                },
+                {
+                    key: 'details',
+                    label: 'Details',
+                    type: 'list',
+                    itemLabel: 'detail',
+                    titleKey: 'label',
+                    group: 'Details',
+                    blank: () => ({ label: '', value: '' }),
+                    fields: [
+                        { key: 'label', label: 'Label', type: 'text', half: true, placeholder: 'Sleeps' },
+                        { key: 'value', label: 'Value', type: 'text', placeholder: '4' }
+                    ]
+                },
+                { key: 'featured', label: 'Featured', type: 'boolean', group: 'Details' },
+                { key: 'hidden', label: 'Hidden', type: 'boolean', group: 'Details' },
+                { key: 'image', label: 'Image', type: 'image', group: 'Media' },
+                { key: 'gallery', label: 'Gallery', type: 'images', group: 'Media' },
+                {
+                    key: 'price.prefix',
+                    label: 'Prefix',
+                    type: 'text',
+                    half: true,
+                    placeholder: 'from',
+                    group: 'Pricing'
+                },
+                { key: 'price.amount', label: 'Amount', type: 'number', group: 'Pricing' },
+                {
+                    key: 'price.currency',
+                    label: 'Currency',
+                    type: 'text',
+                    half: true,
+                    placeholder: 'EUR',
+                    group: 'Pricing'
+                },
+                { key: 'price.period', label: 'Per', type: 'text', placeholder: 'night', group: 'Pricing' }
+            ]
+        }
+    ]
+});
+/** Visible items (not hidden, with a title), optionally sliced. */
+export const collectionView = (value, slice = {}) => {
+    let items = value.items.filter((i) => !i.hidden && i.title !== '');
+    if (slice.featured)
+        items = items.filter((i) => i.featured);
+    if (slice.tag)
+        items = items.filter((i) => i.tags.includes(slice.tag));
+    if (slice.limit !== undefined && slice.limit >= 0)
+        items = items.slice(0, slice.limit);
+    return items.map((i) => ({ ...i, href: i.link ? linkHref(i.link) || null : null }));
+};
+/** Every tag in use, in first-seen order. */
+export const collectionTags = (value) => {
+    const out = [];
+    for (const item of value.items)
+        for (const t of item.tags)
+            if (!out.includes(t))
+                out.push(t);
+    return out;
+};
+/** `from €120 / night`, or empty when there is no amount. */
+export const formatCollectionPrice = (price, locale) => {
+    if (price.amount === null)
+        return '';
+    let amount;
+    try {
+        amount = price.currency
+            ? new Intl.NumberFormat(locale, {
+                style: 'currency',
+                currency: price.currency,
+                maximumFractionDigits: Number.isInteger(price.amount) ? 0 : 2
+            }).format(price.amount)
+            : new Intl.NumberFormat(locale).format(price.amount);
+    }
+    catch {
+        amount = `${price.currency} ${price.amount}`.trim();
+    }
+    return [price.prefix, amount, price.period ? `/ ${price.period}` : ''].filter(Boolean).join(' ');
+};
+/** A schema.org `ItemList` of the visible items. */
+export const toItemList = (value, baseUrl = '') => ({
+    '@context': 'https://schema.org',
+    '@type': 'ItemList',
+    itemListElement: collectionView(value).map((i, n) => {
+        const item = { '@type': 'ListItem', position: n + 1, name: i.title };
+        if (i.href)
+            item.url = baseUrl + i.href;
+        return item;
+    })
+});

package/dist/core/shapes/contact.d.ts

@@ -0,0 +1,70 @@
+/**
+ * `CmsContact`: where and how to reach the business. Labels translate;
+ * addresses and numbers do not. `contactView` adds the hrefs and the
+ * formatted address a template renders.
+ */
+import type { Tree } from '../path.js';
+export type ContactPhone = {
+    id: string;
+    label: string;
+    number: string;
+};
+export type ContactEmail = {
+    id: string;
+    label: string;
+    address: string;
+};
+export type ContactAddress = {
+    lines: string[];
+    locality: string;
+    region: string;
+    postcode: string;
+    country: string;
+};
+export type ContactLabels = {
+    address: string;
+    phone: string;
+    email: string;
+    whatsapp: string;
+    directions: string;
+};
+export type CmsContactValue = {
+    v: 1;
+    name: string;
+    address: ContactAddress;
+    phones: ContactPhone[];
+    emails: ContactEmail[];
+    whatsapp: string;
+    directionsUrl: string;
+    geo: {
+        lat: number;
+        lng: number;
+    } | null;
+    labels: ContactLabels;
+};
+export declare const DEFAULT_CONTACT_LABELS: ContactLabels;
+export declare const cmsContact: import("./form.js").FormShape<CmsContactValue>;
+export declare const telHref: (number: string) => string;
+export declare const whatsappHref: (number: string) => string;
+/** Address lines in the country's conventional order, empty parts dropped. */
+export declare const formatAddress: (address: ContactAddress) => string[];
+export type ContactView = Omit<CmsContactValue, 'phones' | 'emails'> & {
+    phones: Array<ContactPhone & {
+        href: string;
+    }>;
+    emails: Array<ContactEmail & {
+        href: string;
+    }>;
+    /** First phone's `tel:` href, or `null`. */
+    telHref: string | null;
+    /** First email's `mailto:`, or `null`. */
+    mailto: string | null;
+    whatsappHref: string | null;
+    /** `directionsUrl`, else a Google Maps link from `geo` or the address. */
+    mapsHref: string | null;
+    formattedAddress: string[];
+    hasAddress: boolean;
+};
+export declare const contactView: (value: CmsContactValue) => ContactView;
+/** A schema.org `PostalAddress` node, or `null` without an address. */
+export declare const toPostalAddress: (value: CmsContactValue) => Tree | null;