@vamos-ui/react 0.0.0-stage → 0.3.0

package/dist/blocks/schema/rich-doc.js

@@ -0,0 +1,62 @@
+// RichDoc — the frozen rich-text format (BLOCK-FORMAT.md §3). Types + pure helpers, no zod,
+// no React: the site renderer, the editor converters and server code all import this file.
+export const RICH_NODE_TYPES = ["paragraph", "heading", "list", "blockquote", "code", "hr"];
+export const RICH_MARK_TYPES = ["bold", "italic", "underline", "strike", "code", "highlight", "sub", "sup", "link"];
+export const isBreak = (n) => n.type === "br";
+/** Builds a doc from plain paragraphs (blank line = new paragraph, single newline = `br`). */
+export function richFromText(text) {
+    const paras = text.replace(/\r\n?/g, "\n").split(/\n{2,}/).map((p) => p.trim()).filter(Boolean);
+    return {
+        type: "doc",
+        content: paras.map((p) => ({
+            type: "paragraph",
+            content: p.split("\n").flatMap((line, i) => (i === 0 ? [{ text: line }] : [{ type: "br" }, { text: line }])),
+        })),
+    };
+}
+/** Plain text of inline runs (`br` → newline). */
+export function inlineToText(content) {
+    if (!content)
+        return "";
+    return content.map((n) => (isBreak(n) ? "\n" : n.text)).join("");
+}
+function blockToText(b) {
+    switch (b.type) {
+        case "paragraph":
+        case "heading":
+            return inlineToText(b.content);
+        case "code":
+            return b.text;
+        case "hr":
+            return "";
+        case "blockquote":
+            return b.content.map(blockToText).filter(Boolean).join("\n\n");
+        case "list":
+            return b.items.map((it) => it.content.map(blockToText).filter(Boolean).join("\n")).join("\n");
+    }
+}
+/** Plain text of a doc (paragraphs separated by a blank line). Search indexes, meta descriptions, reading time. */
+export function richToText(doc) {
+    if (!doc)
+        return "";
+    const blocks = Array.isArray(doc) ? doc : doc.content;
+    return blocks.map(blockToText).filter(Boolean).join("\n\n");
+}
+/** Word count (Unicode-aware; works for Turkish, German, etc.). */
+export function countWords(text) {
+    return (text.match(/[\p{L}\p{N}][\p{L}\p{N}'’-]*/gu) ?? []).length;
+}
+/** Visits every inline run in a doc. */
+export function forEachRun(doc, visit) {
+    const walk = (blocks) => {
+        for (const b of blocks) {
+            if (b.type === "paragraph" || b.type === "heading")
+                b.content?.forEach((n) => !isBreak(n) && visit(n));
+            else if (b.type === "blockquote")
+                walk(b.content);
+            else if (b.type === "list")
+                b.items.forEach((it) => walk(it.content));
+        }
+    };
+    walk(doc.content);
+}

package/dist/blocks/schema/safety.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Returns a safe href or `null`. Allows relative paths, `#anchors`, `?query`, `//host`, http(s),
+ * mailto, tel and sms. Rejects `javascript:`, `data:`, `vbscript:` and any other scheme —
+ * also when hidden behind whitespace, control characters or entity-like tricks.
+ *
+ * ```ts
+ * sanitizeHref("/menu");              // "/menu"
+ * sanitizeHref(" javascript:alert(1)") // null
+ * ```
+ */
+export declare function sanitizeHref(href: unknown): string | null;
+/** `true` for absolute URLs on another origin (`https://…`, `//host`). mailto/tel are not "external". */
+export declare function isExternalUrl(href: string): boolean;
+/** Link kinds a `LinkRef` can declare (for editors and analytics). */
+export type LinkKind = "url" | "anchor" | "tel" | "mailto" | "whatsapp" | "file";
+/** Infers the kind of a link from its href. */
+export declare function linkKindOf(href: string): LinkKind;
+/** Emoji (pictographs), excluding ©, ® and ™ which legitimately appear in footers. */
+export declare const EMOJI_RE: RegExp;
+export declare const hasEmoji: (s: string) => boolean;

package/dist/blocks/schema/safety.js

@@ -0,0 +1,49 @@
+// Pure guards shared by the schema (layer 2) and the components (layer 1). No zod, no React.
+const BLOCKED_SCHEMES = /^(javascript|data|vbscript|file|blob):/i;
+const ALLOWED_SCHEMES = /^(https?|mailto|tel|sms):/i;
+/**
+ * Returns a safe href or `null`. Allows relative paths, `#anchors`, `?query`, `//host`, http(s),
+ * mailto, tel and sms. Rejects `javascript:`, `data:`, `vbscript:` and any other scheme —
+ * also when hidden behind whitespace, control characters or entity-like tricks.
+ *
+ * ```ts
+ * sanitizeHref("/menu");              // "/menu"
+ * sanitizeHref(" javascript:alert(1)") // null
+ * ```
+ */
+export function sanitizeHref(href) {
+    if (typeof href !== "string")
+        return null;
+    const trimmed = href.trim();
+    if (!trimmed)
+        return null;
+    // Browsers strip tabs/newlines/control chars inside the scheme ("java\tscript:").
+    const probe = trimmed.replace(/[\u0000- \u007f-\u009f]/g, "");
+    if (BLOCKED_SCHEMES.test(probe))
+        return null;
+    const scheme = /^([a-z][a-z\d+.-]*):/i.exec(probe);
+    if (scheme && !ALLOWED_SCHEMES.test(probe))
+        return null;
+    return trimmed;
+}
+/** `true` for absolute URLs on another origin (`https://…`, `//host`). mailto/tel are not "external". */
+export function isExternalUrl(href) {
+    return /^(https?:)?\/\//i.test(href);
+}
+/** Infers the kind of a link from its href. */
+export function linkKindOf(href) {
+    if (href.startsWith("#"))
+        return "anchor";
+    if (/^tel:/i.test(href))
+        return "tel";
+    if (/^mailto:/i.test(href))
+        return "mailto";
+    if (/^https?:\/\/(wa\.me|api\.whatsapp\.com)\//i.test(href))
+        return "whatsapp";
+    if (/\.(pdf|docx?|xlsx?|pptx?|zip|csv)(\?|#|$)/i.test(href))
+        return "file";
+    return "url";
+}
+/** Emoji (pictographs), excluding ©, ® and ™ which legitimately appear in footers. */
+export const EMOJI_RE = /(?![©®™])\p{Extended_Pictographic}/u;
+export const hasEmoji = (s) => EMOJI_RE.test(s);

package/dist/blocks/schema/types.d.ts

@@ -0,0 +1,172 @@
+import type { Localized, LocaleCode } from "./localized.js";
+import type { RichInline } from "./rich-doc.js";
+import type { LinkKind } from "./safety.js";
+export type BuiltInAccent = "lime" | "ocean" | "ember" | "rose" | "graphite";
+/** Per-section token axes. Every key is optional; missing = inherit from the page. */
+export interface BlockTheme {
+    /** `light`/`dark` re-theme the subtree; `inherit` (default) keeps the page theme. */
+    mode?: "inherit" | "light" | "dark";
+    /** Section background. `media` paints `background` under a scrim and forces dark text-on-photo. */
+    surface?: "scene" | "surface" | "surface-2" | "accent" | "media";
+    /** A built-in accent or a custom `oklch(…)` colour. */
+    accent?: BuiltInAccent | (string & {});
+    material?: "inherit" | "glass" | "solid";
+    density?: "inherit" | "comfortable" | "compact";
+    /** Vertical padding: tight ×0.55, normal, loose ×1.35. */
+    rhythm?: "tight" | "normal" | "loose";
+    /** Background image for `surface: "media"`. */
+    background?: ImageRef;
+}
+/** An image as stored in content. `alt` is required unless `decorative`. */
+export interface ImageRef {
+    src: string;
+    alt?: Localized<string>;
+    width: number;
+    height: number;
+    /** Tiny LQIP data URL shown while loading. */
+    blurDataURL?: string;
+    /** 0..1 in image space; drives object-position when cropped. Default centre. */
+    focal?: {
+        x: number;
+        y: number;
+    };
+    /** Purely decorative: rendered with `alt=""`. */
+    decorative?: boolean;
+    /** CMS asset id (Media library). Components ignore it; the renderer may resolve it. */
+    assetId?: string;
+}
+/** A link as stored in content. `href` is localized so each locale can point at its own page. */
+export interface LinkRef {
+    href: Localized<string>;
+    label: Localized<string>;
+    kind?: LinkKind;
+    newTab?: boolean;
+}
+export type CtaStyle = "primary" | "secondary" | "link";
+export interface CtaRef {
+    link: LinkRef;
+    style: CtaStyle;
+}
+/** Money is a decimal string (X11), never a float. */
+export interface MoneyValue {
+    amount: string;
+    /** ISO 4217, e.g. "TRY", "EUR". */
+    currency: string;
+}
+export interface AddressValue {
+    line: string;
+    district?: string;
+    city: string;
+    region?: string;
+    postalCode?: string;
+    /** ISO 3166-1 alpha-2. */
+    country: string;
+    geo?: {
+        lat: number;
+        lng: number;
+    };
+}
+export type Weekday = "mon" | "tue" | "wed" | "thu" | "fri" | "sat" | "sun";
+/** `"09:00"`–`"22:00"`; `close` < `open` means the range runs past midnight. */
+export interface TimeRange {
+    open: string;
+    close: string;
+}
+export interface OpeningHours {
+    /** IANA zone of the business, e.g. "Europe/Istanbul". */
+    timeZone: string;
+    /** Missing or empty day = closed. */
+    weekly: Partial<Record<Weekday, TimeRange[]>>;
+    /** Date-only `YYYY-MM-DD` exceptions (holidays, events). */
+    special?: {
+        date: string;
+        closed?: boolean;
+        ranges?: TimeRange[];
+        note?: Localized<string>;
+    }[];
+}
+export interface QueryValue {
+    kind: "latest" | "category" | "manual";
+    limit?: number;
+    category?: string;
+    ids?: string[];
+}
+export interface EmbedValue {
+    provider: "youtube" | "vimeo" | "google-maps" | "openstreetmap" | "calendly";
+    url: string;
+}
+export type SocialNetwork = "instagram" | "facebook" | "linkedin" | "x" | "youtube" | "tiktok" | "whatsapp" | "telegram" | "google-maps" | "apple-maps" | "yandex-maps";
+export interface SocialLink {
+    network: SocialNetwork;
+    href: string;
+}
+export interface BlockSchedule {
+    /** ISO datetime with zone (`2026-12-01T00:00:00Z`). */
+    from?: string;
+    until?: string;
+}
+/**
+ * One block in a document. Component blocks (hero, faq…) carry `props` + `v`; text blocks
+ * (paragraph, heading…) carry inline `content`; layout blocks carry child blocks in `slots`.
+ */
+export interface BlockNode<P = Record<string, unknown>> {
+    /** Stable, unique within the doc: editor selection, comments, diffs, analytics, React key. */
+    id: string;
+    /** Registry key, kebab-case, never renamed. */
+    type: string;
+    /** Schema version of `props` (component blocks). Missing = 1. */
+    v?: number;
+    /** One of the block's declared variants. */
+    variant?: string;
+    props?: P;
+    /** Inline runs for text blocks (`paragraph`, `heading`, `code`, `list-item`). */
+    content?: RichInline[];
+    /** Named child lists for layout blocks (`columns.items`, `quote.items`). */
+    slots?: Record<string, BlockNode[]>;
+    theme?: BlockTheme;
+    /** Section anchor (`#menu`). */
+    anchor?: string;
+    hidden?: boolean;
+    schedule?: BlockSchedule;
+}
+export interface SeoMeta {
+    title?: Localized<string>;
+    description?: Localized<string>;
+    image?: ImageRef;
+    canonical?: string;
+    noindex?: boolean;
+}
+export interface DocMeta {
+    wordCount?: number;
+    readingTime?: number;
+    toc?: {
+        id: string;
+        level: number;
+        text: string;
+    }[];
+}
+/**
+ * The storage format of every page and post (VamosDoc v1 = PageDoc). Editor-independent;
+ * the site renders it without loading the editor.
+ */
+export interface VamosDoc {
+    $schema?: string;
+    version: 1;
+    /** Document-level locale (one doc per locale, linked by `translationKey`). */
+    lang?: LocaleCode;
+    /** Field-level locales stored in this doc (`["tr", "en"]`). First = default. */
+    locales?: LocaleCode[];
+    translationKey?: string;
+    seo?: SeoMeta;
+    blocks: BlockNode[];
+    /** Shared site regions. */
+    layout?: {
+        header?: BlockNode[];
+        footer?: BlockNode[];
+        overlay?: BlockNode[];
+    };
+    /** Derived by the editor, never the source of truth. */
+    meta?: DocMeta;
+}
+/** Alias kept for plan 06 vocabulary. */
+export type PageDoc = VamosDoc;

package/dist/blocks/schema/types.js

@@ -0,0 +1,3 @@
+// Frozen data formats (BLOCK-FORMAT.md). Plain TypeScript, no runtime code: components (layer 1)
+// import these with `import type`, so zod never reaches a client bundle.
+export {};

package/dist/blocks/schema/validate.d.ts

@@ -0,0 +1,17 @@
+import type { z } from "zod";
+import type { AnyBlockDefinition } from "./define-block.js";
+import type { BlockNode } from "./types.js";
+export interface ValidationResult<P = Record<string, unknown>> {
+    ok: boolean;
+    /** Parsed props (defaults applied). Present when `ok`. */
+    data?: P;
+    /** Top-level fields replaced by sample/default values. */
+    replaced: string[];
+    issues: z.core.$ZodIssue[];
+}
+/**
+ * Validates a node's props against its definition. When invalid, every top-level field that fails
+ * is replaced by the block's sample value (or dropped to its default), so one bad field never
+ * blanks the whole block. `ok: false` only when even that cannot produce valid props.
+ */
+export declare function validateNode(node: BlockNode, def: AnyBlockDefinition): ValidationResult;

package/dist/blocks/schema/validate.js

@@ -0,0 +1,32 @@
+// Render-time validation with salvage: keep every valid field, replace only the broken ones.
+/**
+ * Validates a node's props against its definition. When invalid, every top-level field that fails
+ * is replaced by the block's sample value (or dropped to its default), so one bad field never
+ * blanks the whole block. `ok: false` only when even that cannot produce valid props.
+ */
+export function validateNode(node, def) {
+    const props = node.props ?? {};
+    const first = def.schema.safeParse(props);
+    if (first.success)
+        return { ok: true, data: first.data, replaced: [], issues: [] };
+    const shape = def.schema.shape;
+    const sample = (def.sample(node.variant) ?? {});
+    const fixed = {};
+    const replaced = [];
+    for (const key of Object.keys(shape)) {
+        const field = shape[key];
+        const value = props[key];
+        if (field.safeParse(value).success) {
+            if (value !== undefined)
+                fixed[key] = value;
+            continue;
+        }
+        replaced.push(key);
+        if (sample[key] !== undefined && field.safeParse(sample[key]).success)
+            fixed[key] = sample[key];
+    }
+    const second = def.schema.safeParse(fixed);
+    return second.success
+        ? { ok: true, data: second.data, replaced, issues: first.error.issues }
+        : { ok: false, replaced, issues: first.error.issues };
+}

package/dist/blocks/schema/walk.d.ts

@@ -0,0 +1,22 @@
+import type { z } from "zod";
+import { type FieldMeta } from "./fields.js";
+export interface FieldVisit {
+    schema: z.ZodType;
+    meta?: FieldMeta;
+    value: unknown;
+    /** Dot path from the props root ("items.2.title"). */
+    path: string;
+    /** The value is a Localized<T> (plain or locale map). */
+    localized: boolean;
+}
+/** Return `{ replace }` to substitute the value (and stop descending), `"skip"` to stop descending. */
+export type FieldVisitor = (visit: FieldVisit) => {
+    replace: unknown;
+} | "skip" | void;
+/**
+ * Walks `value` alongside `schema`, calling `visit` for every node. Returns the (possibly
+ * transformed) value; the input is never mutated.
+ */
+export declare function mapFields(schema: z.ZodType, value: unknown, visit: FieldVisitor, path?: string): unknown;
+/** Read-only walk. */
+export declare function walkFields(schema: z.ZodType, value: unknown, visit: (v: FieldVisit) => "skip" | void): void;

package/dist/blocks/schema/walk.js

@@ -0,0 +1,60 @@
+// Schema-driven traversal of block props. Powers localize(), lintPage() and resolver lookup.
+import { getFieldMeta, isLocalizedSchema, unwrapSchema } from "./fields.js";
+const defOf = (s) => s._zod.def;
+const join = (a, b) => (a ? `${a}.${b}` : String(b));
+/**
+ * Walks `value` alongside `schema`, calling `visit` for every node. Returns the (possibly
+ * transformed) value; the input is never mutated.
+ */
+export function mapFields(schema, value, visit, path = "") {
+    if (value === undefined)
+        return value;
+    const localized = isLocalizedSchema(schema);
+    const result = visit({ schema, meta: getFieldMeta(schema), value, path, localized });
+    if (result && typeof result === "object" && "replace" in result)
+        return result.replace;
+    if (result === "skip" || localized)
+        return value;
+    let s = unwrapSchema(schema);
+    for (let i = 0; i < 5; i++) {
+        const d = defOf(s);
+        if (d.type === "lazy" && d.getter)
+            s = unwrapSchema(d.getter());
+        else if (d.type === "pipe" && d.in)
+            s = unwrapSchema(d.in);
+        else
+            break;
+    }
+    const def = defOf(s);
+    if (def.type === "object" && def.shape && value && typeof value === "object" && !Array.isArray(value)) {
+        const src = value;
+        let out;
+        for (const key of Object.keys(def.shape)) {
+            if (!(key in src))
+                continue;
+            const next = mapFields(def.shape[key], src[key], visit, join(path, key));
+            if (next !== src[key])
+                (out ??= { ...src })[key] = next;
+        }
+        return out ?? value;
+    }
+    if (def.type === "array" && def.element && Array.isArray(value)) {
+        let out;
+        value.forEach((item, i) => {
+            const next = mapFields(def.element, item, visit, join(path, i));
+            if (next !== item)
+                (out ??= [...value])[i] = next;
+        });
+        return out ?? value;
+    }
+    if (def.type === "union" && def.options) {
+        const match = def.options.find((o) => o.safeParse(value).success);
+        if (match)
+            return mapFields(match, value, visit, path);
+    }
+    return value;
+}
+/** Read-only walk. */
+export function walkFields(schema, value, visit) {
+    mapFields(schema, value, (v) => visit(v) ?? undefined);
+}

package/dist/blocks/section-header.d.ts

@@ -0,0 +1,38 @@
+import * as React from "react";
+import type { BlockLabels } from "./labels.js";
+export interface SectionHeaderProps extends Omit<React.HTMLAttributes<HTMLDivElement>, "title"> {
+    /** Small mono line above the title ("Menu", "Since 1998"). */
+    eyebrow?: React.ReactNode;
+    /** Index before the eyebrow ("01"). */
+    index?: string;
+    /** Title; a string supports one `*emphasis*`. */
+    title?: React.ReactNode;
+    /** Intro paragraph. */
+    lead?: React.ReactNode;
+    /** Buttons / links (one primary at most). */
+    actions?: React.ReactNode;
+    /**
+     * start (default): stacked, start-aligned, capped at 64ch.
+     * split: on wide containers the title takes 5 of 12 columns, lead + actions the other 7.
+     * center: narrow measure — only for statement heroes and minimal CTAs.
+     */
+    align?: "start" | "split" | "center";
+    /** Title size: m = section h2, l = large section title. Default `"m"`. */
+    size?: "m" | "l";
+    /** Heading level. Default 2. */
+    headingLevel?: 1 | 2 | 3;
+    /** Id for the title — pass the same value to `Section headingId`. */
+    headingId?: string;
+    editMode?: boolean;
+    labels?: Partial<BlockLabels>;
+    locale?: string;
+}
+/**
+ * The heading group at the top of a block: eyebrow, title, lead, actions. Start-aligned by
+ * default (D6-2). Server component.
+ *
+ * ```tsx
+ * <SectionHeader eyebrow="Private dining" title="Rooms for *twelve* or forty" lead="…" align="split" headingId="rooms" />
+ * ```
+ */
+export declare const SectionHeader: React.ForwardRefExoticComponent<SectionHeaderProps & React.RefAttributes<HTMLDivElement>>;

package/dist/blocks/section-header.js

@@ -0,0 +1,22 @@
+import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
+import * as React from "react";
+import { cn } from "../lib/cn.js";
+import { BlockHeading, renderEmphasis } from "./block-heading.js";
+/**
+ * The heading group at the top of a block: eyebrow, title, lead, actions. Start-aligned by
+ * default (D6-2). Server component.
+ *
+ * ```tsx
+ * <SectionHeader eyebrow="Private dining" title="Rooms for *twelve* or forty" lead="…" align="split" headingId="rooms" />
+ * ```
+ */
+export const SectionHeader = React.forwardRef(function SectionHeader({ eyebrow, index, title, lead, actions, align = "start", size = "m", headingLevel = 2, headingId, editMode, labels, locale, className, ...props }, ref) {
+    const heading = (_jsx(BlockHeading, { id: headingId, level: headingLevel, size: size === "l" ? "display-l" : "display-m", text: title, editMode: editMode, field: "props.title", labels: labels, locale: locale }));
+    const eyebrowEl = eyebrow || index ? (_jsxs("p", { className: cn("flex items-center gap-3 font-mono text-eyebrow uppercase tracking-[0.08em] text-fg-muted", align === "center" && "justify-center"), "data-field": editMode ? "props.eyebrow" : undefined, children: [index ? (_jsxs(_Fragment, { children: [_jsx("span", { className: "tabular text-fg", children: index }), _jsx("span", { "aria-hidden": true, className: "h-px w-6 bg-current opacity-40" })] })) : null, eyebrow ? _jsx("span", { children: renderEmphasis(eyebrow) }) : null] })) : null;
+    const leadEl = lead ? (_jsx("p", { className: "vb-lead max-w-(--measure) text-lead text-fg-muted", "data-field": editMode ? "props.lead" : undefined, children: lead })) : null;
+    const actionsEl = actions ? _jsx("div", { className: cn("flex flex-wrap items-center gap-3", align === "center" && "justify-center"), children: actions }) : null;
+    if (align === "split") {
+        return (_jsxs("div", { ref: ref, "data-align": "split", className: cn("grid gap-x-(--gutter) gap-y-6 @4xl:grid-cols-12 @4xl:items-end", className), ...props, children: [_jsxs("div", { className: "flex flex-col gap-5 @4xl:col-span-6 @6xl:col-span-5", children: [eyebrowEl, heading] }), leadEl || actionsEl ? (_jsxs("div", { className: "flex flex-col gap-6 @4xl:col-span-6 @4xl:col-start-7 @6xl:col-span-6 @6xl:col-start-7 [&_.vb-lead]:max-w-[52ch]", children: [leadEl, actionsEl] })) : null] }));
+    }
+    return (_jsxs("div", { ref: ref, "data-align": align, className: cn("flex flex-col gap-5", align === "center" ? "mx-auto max-w-(--prose) items-center text-center [&_.vb-lead]:mx-auto" : "max-w-(--measure)", className), ...props, children: [eyebrowEl, heading, leadEl ? _jsx("div", { className: "pt-1", children: leadEl }) : null, actionsEl ? _jsx("div", { className: "pt-3", children: actionsEl }) : null] }));
+});

package/dist/blocks/section.d.ts

@@ -0,0 +1,59 @@
+import * as React from "react";
+import { type BlockLabels } from "./labels.js";
+import type { BlockAdapters } from "./types.js";
+import type { BlockTheme } from "./schema/types.js";
+/** Readable text colour for a custom `oklch(L C H)` accent: dark ink on light accents, white on dark. */
+export declare function accentForeground(oklch: string): string;
+/** The `data-*`/class/style a theme maps to. Exported for blocks that render their own root. */
+export declare function sectionThemeAttributes(theme: BlockTheme | undefined): {
+    className?: string;
+    style?: React.CSSProperties;
+    attrs: Record<string, string | undefined>;
+};
+export interface SectionProps extends Omit<React.HTMLAttributes<HTMLElement>, "id"> {
+    /** Landmark element. Default `"section"`. */
+    as?: "section" | "div" | "header" | "footer" | "aside" | "article" | "nav";
+    /** Per-section token axes: mode, surface, accent, material, density, rhythm, background. */
+    theme?: BlockTheme;
+    /** Section id / URL anchor (`#menu`). */
+    anchor?: string;
+    /** Id of the section's heading; sets `aria-labelledby`. */
+    headingId?: string;
+    /** Node id; emitted as `data-block-id` in edit mode. */
+    blockId?: string;
+    /** Block type; emitted as `data-block-type` in edit mode. */
+    blockType?: string;
+    editMode?: boolean;
+    /** Load the media background eagerly (above the fold). */
+    priority?: boolean;
+    /** Framework bindings for the media background. */
+    components?: BlockAdapters;
+    labels?: Partial<BlockLabels>;
+}
+/**
+ * The root of every block: maps `theme` onto subtree token axes, sets the container query
+ * context, vertical rhythm and the landmark's accessible name. Server component.
+ *
+ * ```tsx
+ * <Section theme={{ mode: "dark", surface: "accent", accent: "ember" }} anchor="book" headingId="book-title">
+ *   <Container>…</Container>
+ * </Section>
+ * ```
+ */
+export declare const Section: React.ForwardRefExoticComponent<SectionProps & React.RefAttributes<HTMLElement>>;
+export type ContainerSize = "content" | "wide" | "prose" | "full";
+export interface ContainerProps extends React.HTMLAttributes<HTMLDivElement> {
+    /** content = 76rem, wide = 90rem, prose = 42rem, full = edge to edge (gutters kept). Default `"content"`. */
+    size?: ContainerSize;
+    asChild?: never;
+}
+/** Centres content at a token width with fluid gutters (`--gutter`). Server component. */
+export declare const Container: React.ForwardRefExoticComponent<ContainerProps & React.RefAttributes<HTMLDivElement>>;
+export interface SkipLinkProps extends React.AnchorHTMLAttributes<HTMLAnchorElement> {
+    /** Target id. Default `"content"`. */
+    target?: string;
+    labels?: Partial<BlockLabels>;
+    locale?: string;
+}
+/** "Skip to content" — the first focusable element of a site, before the navbar. */
+export declare function SkipLink({ target, labels, locale, className, children, ...props }: SkipLinkProps): React.JSX.Element;

package/dist/blocks/section.js

@@ -0,0 +1,66 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import * as React from "react";
+import { cn } from "../lib/cn.js";
+import { BlockImage } from "./block-image.js";
+import { blockText } from "./labels.js";
+const BUILT_IN_ACCENTS = new Set(["lime", "ocean", "ember", "rose", "graphite"]);
+/** Readable text colour for a custom `oklch(L C H)` accent: dark ink on light accents, white on dark. */
+export function accentForeground(oklch) {
+    const m = /oklch\(\s*([\d.]+)(%?)/.exec(oklch);
+    const l = m ? Number(m[1]) / (m[2] ? 100 : 1) : 0.6;
+    return l >= 0.68 ? "oklch(0.18 0.02 120)" : "#fff";
+}
+/** The `data-*`/class/style a theme maps to. Exported for blocks that render their own root. */
+export function sectionThemeAttributes(theme) {
+    if (!theme)
+        return { attrs: {} };
+    const mode = theme.mode && theme.mode !== "inherit" ? theme.mode : undefined;
+    // A media surface is always dark: text sits on a photo under a scrim.
+    const effectiveMode = theme.surface === "media" ? "dark" : mode;
+    const surface = theme.surface ?? (effectiveMode ? "scene" : undefined);
+    const accent = theme.accent;
+    const custom = accent && !BUILT_IN_ACCENTS.has(accent) ? accent : undefined;
+    const style = custom
+        ? { "--accent-base": custom, "--accent-fg": accentForeground(custom), "--accent-ink-light": `color-mix(in oklch, ${custom} 70%, black)`, "--accent-ink-dark": `color-mix(in oklch, ${custom} 72%, white)` }
+        : undefined;
+    return {
+        className: effectiveMode,
+        style: style,
+        attrs: {
+            "data-surface": surface,
+            "data-accent": custom ? "custom" : accent,
+            "data-material": theme.material && theme.material !== "inherit" ? theme.material : undefined,
+            "data-density": theme.density && theme.density !== "inherit" ? theme.density : undefined,
+            "data-rhythm": theme.rhythm && theme.rhythm !== "normal" ? theme.rhythm : undefined,
+            "data-tone": surface && surface !== "media" ? `${surface}/${effectiveMode ?? "inherit"}` : undefined,
+        },
+    };
+}
+/**
+ * The root of every block: maps `theme` onto subtree token axes, sets the container query
+ * context, vertical rhythm and the landmark's accessible name. Server component.
+ *
+ * ```tsx
+ * <Section theme={{ mode: "dark", surface: "accent", accent: "ember" }} anchor="book" headingId="book-title">
+ *   <Container>…</Container>
+ * </Section>
+ * ```
+ */
+export const Section = React.forwardRef(function Section({ as: Comp = "section", theme, anchor, headingId, blockId, blockType, editMode, priority, components, labels, className, style, children, ...props }, ref) {
+    const t = sectionThemeAttributes(theme);
+    const bg = theme?.surface === "media" ? theme.background : undefined;
+    return (_jsxs(Comp, { ref: ref, id: anchor, "aria-labelledby": headingId, className: cn("vb-section", t.className, className), style: t.style || style ? { ...t.style, ...style } : undefined, "data-block-id": editMode ? blockId : undefined, "data-block-type": editMode ? blockType : undefined, ...t.attrs, ...props, children: [bg ? _jsx(SectionMedia, { image: bg, priority: priority, components: components, labels: labels }) : null, children] }));
+});
+function SectionMedia({ image, priority, components, labels }) {
+    // The photo is atmosphere; the content above carries the meaning, so it's decorative here.
+    return (_jsx("div", { className: "vb-section-media", "aria-hidden": "true", children: _jsx(BlockImage, { src: image.src, width: image.width, height: image.height, blurDataURL: image.blurDataURL, focal: image.focal, decorative: true, priority: priority, sizes: "100vw", components: components, labels: labels }) }));
+}
+/** Centres content at a token width with fluid gutters (`--gutter`). Server component. */
+export const Container = React.forwardRef(function Container({ size = "content", className, ...props }, ref) {
+    return _jsx("div", { ref: ref, "data-size": size === "content" ? undefined : size, className: cn("vb-container", className), ...props });
+});
+/** "Skip to content" — the first focusable element of a site, before the navbar. */
+export function SkipLink({ target = "content", labels, locale, className, children, ...props }) {
+    const t = blockText(labels, locale);
+    return (_jsx("a", { href: `#${target}`, className: cn("vb-skip surface-popover rounded-ui px-4 py-2.5 text-sm font-medium text-fg focus-ring", className), ...props, children: children ?? t("skipToContent") }));
+}