@velastack/cms 0.5.0 → 0.5.1

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

@@ -0,0 +1,46 @@
+/**
+ * What the generic structured editor renders for a shape. A component's
+ * schema lists its fields; the popover walks them and draws one input per
+ * field. `list` fields hold items (stable `id` each) with their own fields,
+ * so a collection item's details or a pricing tier's features are edited in
+ * place. Templates never see this: they get the typed value.
+ */
+import type { Tree } from '../path.js';
+import { type Structured, type StructuredSchema } from '../structured.js';
+export type FormFieldType = 'text' | 'long-string' | 'html' | 'number' | 'boolean' | 'date' | 'time' | 'url' | 'image' | 'images' | 'enum' | 'link' | 'strings' | 'rating' | 'list';
+export type FormField = {
+    /** Dotted path within the object being edited (`name`, `price.amount`). */
+    key: string;
+    label: string;
+    type: FormFieldType;
+    placeholder?: string;
+    /** `enum`: the stored values, and optional display names. */
+    values?: readonly string[];
+    names?: Readonly<Record<string, string>>;
+    /** Share a row with the next field. */
+    half?: boolean;
+    /** Tab the field sits in. Fields without a group share the first tab. */
+    group?: string;
+    /** `list`: what one item is called ("tier"), its fields, a blank item
+     * (without `id`) and which field titles a collapsed card. */
+    itemLabel?: string;
+    fields?: readonly FormField[];
+    blank?: () => Tree;
+    titleKey?: string;
+};
+export type FormShape<T extends Tree> = Structured<T> & {
+    /** Popover header, e.g. "Opening hours". */
+    label: string;
+    fields: readonly FormField[];
+};
+export declare const defineForm: <T extends Tree>(schema: StructuredSchema<T> & {
+    label: string;
+    fields: readonly FormField[];
+}) => FormShape<T>;
+/** Shared vocabulary for the list-shaped components: `{ v: 1, items }`. */
+export type ListValue<I extends {
+    id: string;
+}> = {
+    v: 1;
+    items: I[];
+};

package/dist/core/shapes/form.js

@@ -0,0 +1,7 @@
+import { defineStructured } from '../structured.js';
+import { registerStructured } from '../structured-registry.js';
+export const defineForm = (schema) => {
+    const { label, fields, ...rest } = schema;
+    const structured = registerStructured(defineStructured(rest));
+    return { ...structured, label, fields };
+};

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

@@ -0,0 +1,91 @@
+/**
+ * `CmsHours`: a week of opening hours in the business's timezone, with
+ * holiday exceptions and the labels a template needs around them. The
+ * stored value is data only; `hoursView` derives what the template renders
+ * (folded rows, today, open-now) in the visitor's locale.
+ */
+import type { Tree } from '../path.js';
+export declare const DAY_KEYS: readonly ["mon", "tue", "wed", "thu", "fri", "sat", "sun"];
+export type DayKey = (typeof DAY_KEYS)[number];
+/** `HH:MM`, 24-hour. */
+export type HoursRange = {
+    open: string;
+    close: string;
+};
+export type DayHours = {
+    closed: boolean;
+    ranges: HoursRange[];
+};
+export type HoursException = {
+    id: string;
+    /** `YYYY-MM-DD` */
+    date: string;
+    label: string;
+    closed: boolean;
+    ranges: HoursRange[];
+};
+export type HoursLabels = {
+    closed: string;
+    today: string;
+    openNow: string;
+    closedNow: string;
+};
+export type CmsHoursValue = {
+    v: 1;
+    /** IANA zone, e.g. `Europe/Madrid`. Empty means the visitor's zone. */
+    timezone: string;
+    days: Record<DayKey, DayHours>;
+    note: string;
+    exceptions: HoursException[];
+    labels: HoursLabels;
+};
+export declare const DEFAULT_HOURS_LABELS: HoursLabels;
+export declare const cmsHours: import("./form.js").FormShape<CmsHoursValue>;
+/** `09:00` → `9:00 AM` (en) / `9:00` (es). */
+export declare const formatTime: (hhmm: string, locale: string) => string;
+/** `9:00 AM – 5:00 PM, 6:00 – 10:00 PM`, or the closed label. */
+export declare const formatRanges: (ranges: HoursRange[], locale: string, closedLabel: string) => string;
+/** Short weekday names in the visitor's locale, Monday first. */
+export declare const dayNames: (locale: string, weekday?: "short" | "long") => Record<DayKey, string>;
+/** The current weekday, date and minute in `timezone` (the visitor's zone when empty or invalid). */
+export declare const zonedNow: (timezone: string, now?: Date) => {
+    key: DayKey;
+    date: string;
+    minutes: number;
+};
+export type HoursRow = {
+    id: string;
+    keys: DayKey[];
+    /** `Mon – Fri`, `Sat`, `Sat, Sun` */
+    days: string;
+    /** Formatted ranges, or the closed label. */
+    text: string;
+    closed: boolean;
+};
+export type HoursToday = {
+    key: DayKey;
+    date: string;
+    /** The value's `labels.today`. */
+    label: string;
+    /** `Mon` in the visitor's locale. */
+    day: string;
+    text: string;
+    closed: boolean;
+    exception: HoursException | null;
+};
+export type HoursExceptionRow = HoursException & {
+    dateText: string;
+    text: string;
+};
+export type HoursView = CmsHoursValue & {
+    rows: HoursRow[];
+    today: HoursToday;
+    isOpenNow: boolean;
+    /** `labels.openNow` or `labels.closedNow`. */
+    status: string;
+    exceptionRows: HoursExceptionRow[];
+};
+export declare const formatDate: (iso: string, locale: string) => string;
+export declare const hoursView: (value: CmsHoursValue, locale: string, now?: Date) => HoursView;
+/** schema.org `openingHoursSpecification` entries, one per distinct range. */
+export declare const toOpeningHoursSpecification: (value: CmsHoursValue) => Tree[];

package/dist/core/shapes/hours.js

@@ -0,0 +1,325 @@
+import { asBoolean, asItems, asString, isPlainObject } from '../structured.js';
+import { defineForm } from './form.js';
+export const DAY_KEYS = ['mon', 'tue', 'wed', 'thu', 'fri', 'sat', 'sun'];
+const TIME = /^([01]\d|2[0-3]):[0-5]\d$/;
+const asTime = (v, fallback) => typeof v === 'string' && TIME.test(v) ? v : fallback;
+const asRanges = (v) => {
+    if (!Array.isArray(v))
+        return [];
+    const out = [];
+    for (const r of v) {
+        if (!isPlainObject(r))
+            continue;
+        out.push({ open: asTime(r.open, '09:00'), close: asTime(r.close, '17:00') });
+    }
+    return out.slice(0, 2);
+};
+const asDay = (v) => {
+    if (!isPlainObject(v))
+        return { closed: true, ranges: [] };
+    const ranges = asRanges(v.ranges);
+    return { closed: asBoolean(v.closed, ranges.length === 0), ranges };
+};
+export const DEFAULT_HOURS_LABELS = {
+    closed: 'Closed',
+    today: 'Today',
+    openNow: 'Open now',
+    closedNow: 'Closed now'
+};
+const emptyDays = () => {
+    const out = {};
+    for (const k of DAY_KEYS)
+        out[k] = { closed: true, ranges: [] };
+    return out;
+};
+export const cmsHours = defineForm({
+    component: 'CmsHours',
+    label: 'Opening hours',
+    version: 1,
+    translatable: ['note', 'labels.closed', 'labels.today', 'labels.openNow', 'labels.closedNow'],
+    items: { key: 'exceptions', translatable: ['label'] },
+    normalize: (raw) => {
+        const r = isPlainObject(raw) ? raw : {};
+        const days = isPlainObject(r.days) ? r.days : {};
+        const labels = isPlainObject(r.labels) ? r.labels : {};
+        const out = {
+            v: 1,
+            timezone: asString(r.timezone),
+            days: emptyDays(),
+            note: asString(r.note),
+            exceptions: asItems(r.exceptions, (e) => {
+                const ranges = asRanges(e.ranges);
+                return {
+                    date: asString(e.date),
+                    label: asString(e.label),
+                    closed: asBoolean(e.closed, ranges.length === 0),
+                    ranges
+                };
+            }),
+            labels: {
+                closed: asString(labels.closed, DEFAULT_HOURS_LABELS.closed),
+                today: asString(labels.today, DEFAULT_HOURS_LABELS.today),
+                openNow: asString(labels.openNow, DEFAULT_HOURS_LABELS.openNow),
+                closedNow: asString(labels.closedNow, DEFAULT_HOURS_LABELS.closedNow)
+            }
+        };
+        for (const k of DAY_KEYS)
+            if (k in days)
+                out.days[k] = asDay(days[k]);
+        return out;
+    },
+    empty: () => ({
+        v: 1,
+        timezone: '',
+        days: emptyDays(),
+        note: '',
+        exceptions: [],
+        labels: { ...DEFAULT_HOURS_LABELS }
+    }),
+    // The week grid is a bespoke editor (cms-hours-editable); these are the
+    // fields it renders below the grid through the generic form.
+    fields: [
+        { key: 'note', label: 'Note', type: 'text', placeholder: 'Closed on public holidays' },
+        {
+            key: 'exceptions',
+            label: 'Exceptions',
+            type: 'list',
+            itemLabel: 'exception',
+            titleKey: 'label',
+            blank: () => ({ date: '', label: '', closed: true, ranges: [] }),
+            fields: [
+                { key: 'date', label: 'Date', type: 'date', half: true },
+                { key: 'label', label: 'Label', type: 'text', placeholder: 'Christmas Day' },
+                { key: 'closed', label: 'Closed all day', type: 'boolean' }
+            ]
+        },
+        {
+            key: 'timezone',
+            label: 'Timezone',
+            type: 'text',
+            placeholder: 'Europe/Madrid',
+            group: 'Labels'
+        },
+        { key: 'labels.closed', label: '“Closed”', type: 'text', half: true, group: 'Labels' },
+        { key: 'labels.today', label: '“Today”', type: 'text', group: 'Labels' },
+        { key: 'labels.openNow', label: '“Open now”', type: 'text', half: true, group: 'Labels' },
+        { key: 'labels.closedNow', label: '“Closed now”', type: 'text', group: 'Labels' }
+    ]
+});
+// ---------------------------------------------------------------------------
+// Derived views
+// ---------------------------------------------------------------------------
+const minutesOf = (hhmm) => {
+    const [h, m] = hhmm.split(':').map(Number);
+    return h * 60 + m;
+};
+/** `09:00` → `9:00 AM` (en) / `9:00` (es). */
+export const formatTime = (hhmm, locale) => {
+    if (!TIME.test(hhmm))
+        return hhmm;
+    const [h, m] = hhmm.split(':').map(Number);
+    try {
+        return new Intl.DateTimeFormat(locale, {
+            hour: 'numeric',
+            minute: '2-digit',
+            timeZone: 'UTC'
+        }).format(new Date(Date.UTC(2024, 0, 1, h, m)));
+    }
+    catch {
+        return hhmm;
+    }
+};
+/** `9:00 AM – 5:00 PM, 6:00 – 10:00 PM`, or the closed label. */
+export const formatRanges = (ranges, locale, closedLabel) => ranges.length === 0
+    ? closedLabel
+    : ranges
+        .map((r) => `${formatTime(r.open, locale)} – ${formatTime(r.close, locale)}`)
+        .join(', ');
+/** Short weekday names in the visitor's locale, Monday first. */
+export const dayNames = (locale, weekday = 'short') => {
+    const out = {};
+    let fmt = null;
+    try {
+        fmt = new Intl.DateTimeFormat(locale, { weekday, timeZone: 'UTC' });
+    }
+    catch {
+        fmt = null;
+    }
+    DAY_KEYS.forEach((k, i) => {
+        // 2024-01-01 is a Monday.
+        out[k] = fmt ? fmt.format(new Date(Date.UTC(2024, 0, 1 + i))) : k;
+    });
+    return out;
+};
+/** The current weekday, date and minute in `timezone` (the visitor's zone when empty or invalid). */
+export const zonedNow = (timezone, now = new Date()) => {
+    const keyOf = (weekday) => {
+        const k = weekday.slice(0, 3).toLowerCase();
+        return DAY_KEYS.includes(k) ? k : 'mon';
+    };
+    if (timezone) {
+        try {
+            const parts = new Intl.DateTimeFormat('en-US', {
+                timeZone: timezone,
+                weekday: 'short',
+                year: 'numeric',
+                month: '2-digit',
+                day: '2-digit',
+                hour: '2-digit',
+                minute: '2-digit',
+                hourCycle: 'h23'
+            }).formatToParts(now);
+            const p = (t) => parts.find((x) => x.type === t)?.value ?? '';
+            return {
+                key: keyOf(p('weekday')),
+                date: `${p('year')}-${p('month')}-${p('day')}`,
+                minutes: Number(p('hour')) * 60 + Number(p('minute'))
+            };
+        }
+        catch {
+            /* fall through to the visitor's zone */
+        }
+    }
+    const pad = (n) => String(n).padStart(2, '0');
+    const day = (now.getDay() + 6) % 7; // Sunday → 6
+    return {
+        key: DAY_KEYS[day],
+        date: `${now.getFullYear()}-${pad(now.getMonth() + 1)}-${pad(now.getDate())}`,
+        minutes: now.getHours() * 60 + now.getMinutes()
+    };
+};
+const sameHours = (a, b) => a.closed === b.closed &&
+    a.ranges.length === b.ranges.length &&
+    a.ranges.every((r, i) => r.open === b.ranges[i].open && r.close === b.ranges[i].close);
+const effective = (d) => d.closed ? [] : d.ranges;
+const isOpenAt = (ranges, minutes) => ranges.some((r) => {
+    const open = minutesOf(r.open);
+    const close = minutesOf(r.close);
+    if (close <= open)
+        return minutes >= open || minutes < close; // overnight
+    return minutes >= open && minutes < close;
+});
+export const formatDate = (iso, locale) => {
+    const m = /^(\d{4})-(\d{2})-(\d{2})$/.exec(iso);
+    if (!m)
+        return iso;
+    try {
+        return new Intl.DateTimeFormat(locale, {
+            day: 'numeric',
+            month: 'short',
+            timeZone: 'UTC'
+        }).format(new Date(Date.UTC(Number(m[1]), Number(m[2]) - 1, Number(m[3]))));
+    }
+    catch {
+        return iso;
+    }
+};
+export const hoursView = (value, locale, now = new Date()) => {
+    const names = dayNames(locale);
+    const closedLabel = value.labels.closed;
+    const rows = [];
+    for (const key of DAY_KEYS) {
+        const day = value.days[key];
+        const last = rows[rows.length - 1];
+        if (last && sameHours(value.days[last.keys[last.keys.length - 1]], day)) {
+            last.keys.push(key);
+            continue;
+        }
+        rows.push({
+            id: key,
+            keys: [key],
+            days: '',
+            text: formatRanges(effective(day), locale, closedLabel),
+            closed: day.closed
+        });
+    }
+    for (const row of rows) {
+        const first = names[row.keys[0]];
+        const lastName = names[row.keys[row.keys.length - 1]];
+        row.days =
+            row.keys.length === 1
+                ? first
+                : row.keys.length === 2
+                    ? `${first}, ${lastName}`
+                    : `${first} – ${lastName}`;
+    }
+    const z = zonedNow(value.timezone, now);
+    const exception = value.exceptions.find((e) => e.date === z.date) ?? null;
+    const todayRanges = effective(exception ?? value.days[z.key]);
+    const today = {
+        key: z.key,
+        date: z.date,
+        label: value.labels.today,
+        day: names[z.key],
+        text: formatRanges(todayRanges, locale, closedLabel),
+        closed: todayRanges.length === 0,
+        exception
+    };
+    const isOpenNow = isOpenAt(todayRanges, z.minutes);
+    const exceptionRows = value.exceptions
+        .filter((e) => e.date !== '')
+        .map((e) => ({
+        ...e,
+        dateText: formatDate(e.date, locale),
+        text: formatRanges(effective(e), locale, closedLabel)
+    }));
+    return {
+        ...value,
+        rows,
+        today,
+        isOpenNow,
+        status: isOpenNow ? value.labels.openNow : value.labels.closedNow,
+        exceptionRows
+    };
+};
+const SCHEMA_DAYS = {
+    mon: 'Monday',
+    tue: 'Tuesday',
+    wed: 'Wednesday',
+    thu: 'Thursday',
+    fri: 'Friday',
+    sat: 'Saturday',
+    sun: 'Sunday'
+};
+/** schema.org `openingHoursSpecification` entries, one per distinct range. */
+export const toOpeningHoursSpecification = (value) => {
+    const byRange = new Map();
+    for (const key of DAY_KEYS) {
+        for (const r of effective(value.days[key])) {
+            const k = `${r.open}-${r.close}`;
+            const entry = byRange.get(k) ?? { opens: r.open, closes: r.close, days: [] };
+            entry.days.push(SCHEMA_DAYS[key]);
+            byRange.set(k, entry);
+        }
+    }
+    const out = [...byRange.values()].map((e) => ({
+        '@type': 'OpeningHoursSpecification',
+        dayOfWeek: e.days,
+        opens: e.opens,
+        closes: e.closes
+    }));
+    for (const e of value.exceptions) {
+        if (!e.date)
+            continue;
+        if (e.closed || e.ranges.length === 0) {
+            out.push({
+                '@type': 'OpeningHoursSpecification',
+                validFrom: e.date,
+                validThrough: e.date,
+                opens: '00:00',
+                closes: '00:00'
+            });
+            continue;
+        }
+        for (const r of e.ranges) {
+            out.push({
+                '@type': 'OpeningHoursSpecification',
+                validFrom: e.date,
+                validThrough: e.date,
+                opens: r.open,
+                closes: r.close
+            });
+        }
+    }
+    return out;
+};

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

@@ -0,0 +1,15 @@
+/**
+ * Stored shape of an image slot. Seeds and fallbacks may pass a bare URL
+ * string; it is normalized to `{ url }`. A cleared slot stores `url: null`.
+ */
+export type CmsImageValue = {
+    url?: string | null;
+    alt?: string | null;
+    width?: number;
+    height?: number;
+};
+export declare const normalizeImage: (raw: unknown) => CmsImageValue;
+/** An image inside a structured value: `null` when there is no URL. */
+export declare const asImage: (raw: unknown) => CmsImageValue | null;
+/** A list of images, dropping entries without a URL. */
+export declare const asImages: (raw: unknown) => CmsImageValue[];

package/dist/core/shapes/image.js

@@ -0,0 +1,27 @@
+export const normalizeImage = (raw) => {
+    if (raw == null)
+        return {};
+    if (typeof raw === 'string')
+        return { url: raw };
+    if (typeof raw === 'object' && !Array.isArray(raw)) {
+        const r = raw;
+        const out = {};
+        if (typeof r.url === 'string')
+            out.url = r.url;
+        if (typeof r.alt === 'string')
+            out.alt = r.alt;
+        if (typeof r.width === 'number')
+            out.width = r.width;
+        if (typeof r.height === 'number')
+            out.height = r.height;
+        return out;
+    }
+    return {};
+};
+/** An image inside a structured value: `null` when there is no URL. */
+export const asImage = (raw) => {
+    const img = normalizeImage(raw);
+    return img.url ? img : null;
+};
+/** A list of images, dropping entries without a URL. */
+export const asImages = (raw) => Array.isArray(raw) ? raw.map(asImage).filter((i) => i !== null) : [];

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

@@ -0,0 +1,31 @@
+/**
+ * The structured value shapes behind the editor components. Importing this
+ * module registers every schema, so the Locales panel can count translatable
+ * strings for any usage the manifest recorded.
+ */
+export type { FormField, FormFieldType, FormShape, ListValue } from './form.js';
+export { defineForm } from './form.js';
+export { normalizeLink, asLink, linkHref } from './link.js';
+export type { CmsLinkValue } from './link.js';
+export { normalizeImage, asImage, asImages } from './image.js';
+export type { CmsImageValue } from './image.js';
+export { cmsNav, navView, isActive } from './nav.js';
+export type { CmsNavValue, NavItem, NavItemView } from './nav.js';
+export { cmsHours, hoursView, formatTime, formatRanges, formatDate, dayNames, zonedNow, toOpeningHoursSpecification, DAY_KEYS, DEFAULT_HOURS_LABELS } from './hours.js';
+export type { CmsHoursValue, DayKey, DayHours, HoursRange, HoursException, HoursLabels, HoursRow, HoursToday, HoursExceptionRow, HoursView } from './hours.js';
+export { cmsContact, contactView, formatAddress, telHref, whatsappHref, toPostalAddress, DEFAULT_CONTACT_LABELS } from './contact.js';
+export type { CmsContactValue, ContactAddress, ContactEmail, ContactLabels, ContactPhone, ContactView } from './contact.js';
+export { cmsSocialLinks, socialLinksView, toSameAs, SOCIAL_PLATFORMS, SOCIAL_PLATFORM_NAMES } from './social-links.js';
+export type { CmsSocialLinksValue, SocialLink, SocialLinkView, SocialPlatform } from './social-links.js';
+export { cmsTeam, teamView } from './team.js';
+export type { CmsTeamValue, TeamLink, TeamMember } from './team.js';
+export { cmsTestimonials, testimonialsView, toReview } from './testimonials.js';
+export type { CmsTestimonialsValue, Testimonial } from './testimonials.js';
+export { cmsCollection, collectionView, collectionTags, formatCollectionPrice, toItemList } from './collection.js';
+export type { CmsCollectionValue, CollectionDetail, CollectionItem, CollectionItemView, CollectionPrice, CollectionSlice } from './collection.js';
+export { cmsPricing, pricingView, formatPrice } from './pricing.js';
+export type { CmsPricingValue, PricingFeature, PricingTier, PricingTierView } from './pricing.js';
+export { cmsFaq, faqView, toFaqPage } from './faq.js';
+export type { CmsFaqValue, FaqItem } from './faq.js';
+export { cmsStats, cmsSteps, cmsTimeline, cmsGallery, cmsLogos, cmsSchedule, logosView, scheduleByDay } from './presets.js';
+export type { CmsStatsValue, StatItem, CmsStepsValue, StepItem, CmsTimelineValue, TimelineItem, CmsGalleryValue, GalleryItem, CmsLogosValue, LogoItem, LogoItemView, CmsScheduleValue, ScheduleItem } from './presets.js';

package/dist/core/shapes/index.js

@@ -0,0 +1,13 @@
+export { defineForm } from './form.js';
+export { normalizeLink, asLink, linkHref } from './link.js';
+export { normalizeImage, asImage, asImages } from './image.js';
+export { cmsNav, navView, isActive } from './nav.js';
+export { cmsHours, hoursView, formatTime, formatRanges, formatDate, dayNames, zonedNow, toOpeningHoursSpecification, DAY_KEYS, DEFAULT_HOURS_LABELS } from './hours.js';
+export { cmsContact, contactView, formatAddress, telHref, whatsappHref, toPostalAddress, DEFAULT_CONTACT_LABELS } from './contact.js';
+export { cmsSocialLinks, socialLinksView, toSameAs, SOCIAL_PLATFORMS, SOCIAL_PLATFORM_NAMES } from './social-links.js';
+export { cmsTeam, teamView } from './team.js';
+export { cmsTestimonials, testimonialsView, toReview } from './testimonials.js';
+export { cmsCollection, collectionView, collectionTags, formatCollectionPrice, toItemList } from './collection.js';
+export { cmsPricing, pricingView, formatPrice } from './pricing.js';
+export { cmsFaq, faqView, toFaqPage } from './faq.js';
+export { cmsStats, cmsSteps, cmsTimeline, cmsGallery, cmsLogos, cmsSchedule, logosView, scheduleByDay } from './presets.js';

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

@@ -0,0 +1,15 @@
+export type CmsLinkValue = {
+    label?: string;
+    /** Raw URL — used when `routeId` is absent. */
+    href?: string;
+    /** SvelteKit route id, e.g. `/blog/[slug]`. Resolved at render time. */
+    routeId?: string;
+    params?: Record<string, string>;
+    newTab?: boolean;
+};
+export declare const normalizeLink: (raw: unknown) => CmsLinkValue;
+/** A link inside a structured value: `null` when nothing points anywhere. */
+export declare const asLink: (raw: unknown) => CmsLinkValue | null;
+/** The URL a link points at, or `fallback` when it points nowhere or the
+ * route cannot be resolved. */
+export declare const linkHref: (link: CmsLinkValue | null | undefined, fallback?: string) => string;

package/dist/core/shapes/link.js

@@ -0,0 +1,42 @@
+import { resolveRouteUrl } from '../../components/admin-bar/resolve-route.js';
+import { isPlainObject } from '../structured.js';
+export const normalizeLink = (raw) => {
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw))
+        return {};
+    const r = raw;
+    const out = {};
+    if (typeof r.label === 'string')
+        out.label = r.label;
+    if (typeof r.href === 'string')
+        out.href = r.href;
+    if (typeof r.routeId === 'string')
+        out.routeId = r.routeId;
+    if (r.params && typeof r.params === 'object' && !Array.isArray(r.params)) {
+        out.params = r.params;
+    }
+    if (typeof r.newTab === 'boolean')
+        out.newTab = r.newTab;
+    return out;
+};
+/** A link inside a structured value: `null` when nothing points anywhere. */
+export const asLink = (raw) => {
+    if (!isPlainObject(raw))
+        return null;
+    const link = normalizeLink(raw);
+    return link.href || link.routeId ? link : null;
+};
+/** The URL a link points at, or `fallback` when it points nowhere or the
+ * route cannot be resolved. */
+export const linkHref = (link, fallback = '') => {
+    if (!link)
+        return fallback;
+    if (link.routeId) {
+        try {
+            return resolveRouteUrl(link.routeId, link.params ?? {});
+        }
+        catch {
+            return fallback;
+        }
+    }
+    return link.href ?? fallback;
+};

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

@@ -0,0 +1,21 @@
+import { type ListValue } from './form.js';
+import { type CmsLinkValue } from './link.js';
+export type NavItem = {
+    id: string;
+    label: string;
+    link: CmsLinkValue | null;
+    children: NavItem[];
+};
+export type CmsNavValue = ListValue<NavItem>;
+export type NavItemView = {
+    id: string;
+    label: string;
+    href: string;
+    newTab: boolean;
+    children: NavItemView[];
+};
+export declare const cmsNav: import("./form.js").FormShape<CmsNavValue>;
+/** Items with resolved hrefs, dropping items that have no label. */
+export declare const navView: (value: CmsNavValue) => NavItemView[];
+/** Whether `item` (or one of its children) points at the current page. */
+export declare const isActive: (item: NavItemView, url: URL | string) => boolean;