@vamos-ui/react 0.0.0-stage → 0.2.0

package/dist/blocks/site/shared/opening-hours.js

@@ -0,0 +1,245 @@
+// OpeningHours — pure, React-free, works in RSC, edge and the browser.
+// Every computation happens in the business's IANA time zone, so "open now" is right for a
+// visitor in another zone and on a server running in UTC. Ranges with close <= open run past
+// midnight ("18:00"–"02:00"); "00:00"–"24:00" (or open == close) is open all day.
+import { formatMessage } from "../../../lib/message-format.js";
+/** Monday-first, the ISO order. */
+export const WEEKDAYS = ["mon", "tue", "wed", "thu", "fri", "sat", "sun"];
+const DAY_MS = 86_400_000;
+const SHORT_TO_WEEKDAY = { Mon: "mon", Tue: "tue", Wed: "wed", Thu: "thu", Fri: "fri", Sat: "sat", Sun: "sun" };
+const partsCache = new Map();
+function zoneFormat(timeZone) {
+    let f = partsCache.get(timeZone);
+    if (!f) {
+        f = new Intl.DateTimeFormat("en-US", { timeZone, year: "numeric", month: "2-digit", day: "2-digit", weekday: "short", hour: "2-digit", minute: "2-digit", hourCycle: "h23" });
+        partsCache.set(timeZone, f);
+    }
+    return f;
+}
+/** The wall-clock date, weekday and minute of `at` in `timeZone`. */
+export function zonedMoment(at, timeZone) {
+    const d = at instanceof Date ? at : new Date(at);
+    const p = {};
+    for (const part of zoneFormat(timeZone).formatToParts(d))
+        p[part.type] = part.value;
+    const hour = Number(p.hour) % 24;
+    return { date: `${p.year}-${p.month}-${p.day}`, weekday: SHORT_TO_WEEKDAY[p.weekday] ?? "mon", minutes: hour * 60 + Number(p.minute) };
+}
+/** "09:30" → 570; "24:00" → 1440. */
+export const toMinutes = (hhmm) => {
+    const [h, m] = hhmm.split(":").map(Number);
+    return (h ?? 0) * 60 + (m ?? 0);
+};
+const fromMinutes = (min) => {
+    const m = ((min % 1440) + 1440) % 1440;
+    return `${String(Math.floor(m / 60)).padStart(2, "0")}:${String(m % 60).padStart(2, "0")}`;
+};
+/** Calendar arithmetic on `YYYY-MM-DD` strings (UTC-anchored, never shifts a day). */
+export function addDays(date, n) {
+    const [y, m, d] = date.split("-").map(Number);
+    const t = Date.UTC(y, m - 1, d) + n * DAY_MS;
+    return new Date(t).toISOString().slice(0, 10);
+}
+/** The weekday of a `YYYY-MM-DD` date. */
+export function weekdayOf(date) {
+    const [y, m, d] = date.split("-").map(Number);
+    const js = new Date(Date.UTC(y, m - 1, d)).getUTCDay(); // 0 = Sunday
+    return WEEKDAYS[(js + 6) % 7];
+}
+/** Hours for one date (special days win over the weekly schedule). */
+export function hoursOn(hours, date) {
+    const weekday = weekdayOf(date);
+    const special = hours.special?.find((s) => s.date === date);
+    if (special) {
+        const ranges = special.closed ? [] : (special.ranges ?? hours.weekly[weekday] ?? []);
+        const note = typeof special.note === "string" ? special.note : undefined;
+        return { date, weekday, ranges, closed: ranges.length === 0, special: { note } };
+    }
+    const ranges = hours.weekly[weekday] ?? [];
+    return { date, weekday, ranges, closed: ranges.length === 0 };
+}
+/** A range as [start, end) in minutes from `date`'s midnight; past-midnight ends exceed 1440. */
+function span(r) {
+    const a = toMinutes(r.open);
+    let b = toMinutes(r.close);
+    if (b <= a)
+        b += 1440; // past midnight, or open == close → 24 h
+    return [a, b];
+}
+/** Open intervals around `date`, in minutes relative to its midnight, merged and sorted. */
+function intervals(hours, date, fromDay, toDay) {
+    const out = [];
+    for (let d = fromDay; d <= toDay; d++) {
+        const day = hoursOn(hours, addDays(date, d));
+        for (const r of day.ranges) {
+            const [a, b] = span(r);
+            out.push([a + d * 1440, b + d * 1440]);
+        }
+    }
+    out.sort((x, y) => x[0] - y[0]);
+    const merged = [];
+    for (const iv of out) {
+        const last = merged[merged.length - 1];
+        if (last && iv[0] <= last[1])
+            last[1] = Math.max(last[1], iv[1]);
+        else
+            merged.push([...iv]);
+    }
+    return merged;
+}
+/** True when the business is open at `at` (default now). Handles past-midnight and special days. */
+export function isOpenAt(hours, at = Date.now()) {
+    const z = zonedMoment(at, hours.timeZone);
+    return intervals(hours, z.date, -1, 0).some(([a, b]) => z.minutes >= a && z.minutes < b);
+}
+/**
+ * Open / closing soon / closed at `at`, with the closing or next opening time.
+ *
+ * ```ts
+ * hoursStatus(hours, new Date()) // { state: "open", closesAt: "22:00", minutesLeft: 95, … }
+ * ```
+ */
+export function hoursStatus(hours, at = Date.now(), opts = {}) {
+    const soon = opts.soonMinutes ?? 60;
+    const z = zonedMoment(at, hours.timeZone);
+    const day = hoursOn(hours, z.date);
+    const base = { today: { date: z.date, weekday: z.weekday }, special: day.special ? { closed: day.closed, note: day.special.note } : undefined };
+    const ivs = intervals(hours, z.date, -1, 8);
+    const current = ivs.find(([a, b]) => z.minutes >= a && z.minutes < b);
+    if (current) {
+        const left = current[1] - z.minutes;
+        const allDay = left >= 1440;
+        return {
+            ...base,
+            state: !allDay && left <= soon ? "closing-soon" : "open",
+            closesAt: allDay ? undefined : fromMinutes(current[1]),
+            minutesLeft: allDay ? undefined : left,
+            allDay: allDay || undefined,
+        };
+    }
+    const next = ivs.find(([a]) => a > z.minutes);
+    if (!next)
+        return { ...base, state: "closed" };
+    const dayOffset = Math.floor(next[0] / 1440);
+    const date = addDays(z.date, dayOffset);
+    return { ...base, state: "closed", minutesLeft: next[0] - z.minutes, opensAt: { time: fromMinutes(next[0]), weekday: weekdayOf(date), dayOffset, date } };
+}
+/* ------------------------------------------------------------------ */
+/* Locale formatting                                                    */
+/* ------------------------------------------------------------------ */
+const REF_MONDAY = Date.UTC(2024, 0, 1); // 2024-01-01 was a Monday
+/** Weekday name from the locale ("Monday" / "Pazartesi"). */
+export function weekdayName(day, locale = "en-US", style = "long") {
+    const t = REF_MONDAY + WEEKDAYS.indexOf(day) * DAY_MS;
+    return new Intl.DateTimeFormat(locale, { weekday: style, timeZone: "UTC" }).format(t);
+}
+/** Local `HH:mm` → "9:00 AM" (en-US) / "09:00" (tr). Whole hours drop ":00" in 12-hour locales. */
+export function formatTime(hhmm, locale = "en-US") {
+    const min = toMinutes(hhmm) % 1440;
+    const d = Date.UTC(2000, 0, 1, Math.floor(min / 60), min % 60);
+    const h12 = new Intl.DateTimeFormat(locale, { hour: "numeric" }).resolvedOptions().hourCycle?.startsWith("h1");
+    const opts = h12 && min % 60 === 0 ? { hour: "numeric", timeZone: "UTC" } : { hour: h12 ? "numeric" : "2-digit", minute: "2-digit", timeZone: "UTC" };
+    return new Intl.DateTimeFormat(locale, opts).format(d).replace(/[  ]/g, " ");
+}
+/** "09:00–22:00" / "9 AM–10 PM". */
+export const formatRange = (r, locale = "en-US") => `${formatTime(r.open, locale)}–${formatTime(r.close, locale)}`;
+/** First day of the week for a locale: 1 = Monday … 7 = Sunday. */
+export function weekStartOf(locale = "en-US") {
+    try {
+        const loc = new Intl.Locale(locale);
+        const info = loc.getWeekInfo?.() ?? loc.weekInfo;
+        if (info?.firstDay)
+            return info.firstDay;
+    }
+    catch {
+        /* fall through */
+    }
+    const region = locale.split("-")[1]?.toUpperCase();
+    return region && ["US", "CA", "JP", "BR", "MX", "IL", "PH", "SA", "IN"].includes(region) ? 7 : 1;
+}
+/** The week in the locale's order (Sunday first for en-US, Monday first for tr). */
+export function orderedWeek(locale = "en-US") {
+    const start = weekStartOf(locale) - 1;
+    return [...WEEKDAYS.slice(start), ...WEEKDAYS.slice(0, start)];
+}
+/**
+ * The 7 rows of an hours table in locale order. With `at`, rows carry this week's dates, so
+ * special days (holidays) replace the weekly hours, and `today` is marked.
+ */
+export function weekRows(hours, opts = {}) {
+    const locale = opts.locale ?? "en-US";
+    const z = opts.at !== undefined ? zonedMoment(opts.at, hours.timeZone) : undefined;
+    const todayIdx = z ? WEEKDAYS.indexOf(z.weekday) : -1;
+    return orderedWeek(locale).map((weekday) => {
+        let ranges = hours.weekly[weekday] ?? [];
+        let date;
+        let note;
+        if (z) {
+            // Upcoming occurrence of this weekday (today counts), so the table shows the coming week.
+            const offset = (WEEKDAYS.indexOf(weekday) - todayIdx + 7) % 7;
+            date = addDays(z.date, offset);
+            const day = hoursOn(hours, date);
+            ranges = day.ranges;
+            note = day.special?.note;
+        }
+        const allDay = ranges.some((r) => span(r)[1] - span(r)[0] >= 1440);
+        return {
+            weekday,
+            label: weekdayName(weekday, locale, opts.style ?? "long"),
+            ranges,
+            text: ranges.map((r) => formatRange(r, locale)).join(", "),
+            closed: ranges.length === 0,
+            allDay,
+            today: z ? z.weekday === weekday : false,
+            date,
+            note,
+        };
+    });
+}
+/** Consecutive days with identical hours collapsed: [{ days: "Mon–Fri", text: "09:00–18:00" }]. */
+export function summarizeHours(hours, locale = "en-US") {
+    const rows = weekRows(hours, { locale, style: "short" });
+    const groups = [];
+    for (const r of rows) {
+        const key = r.text || "closed";
+        const g = groups[groups.length - 1];
+        if (g && g.key === key)
+            g.to = r;
+        else
+            groups.push({ from: r, to: r, key });
+    }
+    return groups.map((g) => ({ days: g.from === g.to ? g.from.label : `${g.from.label}–${g.to.label}`, text: g.from.text, closed: g.from.closed }));
+}
+const SCHEMA_DAY = { mon: "Monday", tue: "Tuesday", wed: "Wednesday", thu: "Thursday", fri: "Friday", sat: "Saturday", sun: "Sunday" };
+/** schema.org `OpeningHoursSpecification[]` for JSON-LD (weekly + special days). */
+export function openingHoursJsonLd(hours) {
+    const out = [];
+    for (const day of WEEKDAYS) {
+        for (const r of hours.weekly[day] ?? [])
+            out.push({ "@type": "OpeningHoursSpecification", dayOfWeek: `https://schema.org/${SCHEMA_DAY[day]}`, opens: r.open, closes: r.close === "24:00" ? "23:59" : r.close });
+    }
+    for (const s of hours.special ?? []) {
+        if (s.closed || !s.ranges?.length)
+            out.push({ "@type": "OpeningHoursSpecification", validFrom: s.date, validThrough: s.date, opens: "00:00", closes: "00:00" });
+        else
+            for (const r of s.ranges)
+                out.push({ "@type": "OpeningHoursSpecification", validFrom: s.date, validThrough: s.date, opens: r.open, closes: r.close });
+    }
+    return out;
+}
+/** The status sentence: "Open now · closes at 22:00", "Closed · opens Thu at 12:00". */
+export function describeStatus(s, labels, locale = "en-US") {
+    const f = (tpl, vars) => formatMessage(tpl, vars, locale);
+    if (s.state !== "closed") {
+        if (s.allDay)
+            return { head: f(labels.openNow), tail: f(labels.open24h) };
+        const tail = f(labels.closesAt, { time: formatTime(s.closesAt, locale) });
+        return { head: f(s.state === "closing-soon" ? labels.closingSoon : labels.openNow), tail };
+    }
+    const head = s.special?.closed ? (s.special.note ? `${f(labels.closedToday)} · ${s.special.note}` : f(labels.closedToday)) : f(labels.closed);
+    if (!s.opensAt)
+        return { head };
+    const time = formatTime(s.opensAt.time, locale);
+    const tail = s.opensAt.dayOffset === 0 ? f(labels.opensTodayAt, { time }) : f(labels.opensAt, { day: weekdayName(s.opensAt.weekday, locale, "short"), time });
+    return { head, tail };
+}

package/dist/blocks/site/shared/site-accent.d.ts

@@ -0,0 +1,48 @@
+/** Text contrast target (WCAG 1.4.3 AA). */
+export declare const SITE_TEXT_CONTRAST = 4.5;
+/** Built-in accent presets of styles.css; these are used by name, not recomputed. */
+export declare const BUILT_IN_SITE_ACCENTS: readonly ["lime", "ocean", "ember", "rose", "graphite"];
+export declare const isBuiltInAccent: (v: string) => boolean;
+export interface SiteAccentPalette {
+    /** The colour as given. */
+    source: string;
+    base: string;
+    fg: string;
+    inkLight: string;
+    inkDark: string;
+    /** Dark-mode fill, when the base would vanish on dark surfaces (or `dark` was given). */
+    dark?: {
+        base: string;
+        fg: string;
+    };
+    /** Measured contrast ratios (rounded down). */
+    contrast: {
+        fgOnBase: number;
+        inkLightOnLight: number;
+        inkDarkOnDark: number;
+        darkFgOnBase?: number;
+    };
+    /** What was adjusted, in plain words. Empty = used as given. */
+    warnings: string[];
+}
+export interface SiteAccentOptions {
+    /** Explicit dark-mode fill. */
+    dark?: string;
+}
+/**
+ * The four accent variables for one brand colour (hex, rgb() or oklch()).
+ * Throws a TypeError when the colour cannot be read.
+ *
+ * ```ts
+ * siteAccent("#B4532A"); // { base: "oklch(…)", fg: "#fff", inkLight: "oklch(…)", inkDark: "oklch(…)", … }
+ * ```
+ */
+export declare function siteAccent(colour: string, options?: SiteAccentOptions): SiteAccentPalette;
+/** A stable attribute value for a palette (`b4532a`-like), safe inside a quoted CSS selector. */
+export declare function siteAccentKey(colour: string): string;
+/**
+ * The scoped stylesheet for a palette under `[data-site-accent="<key>"]`: the four variables,
+ * plus the dark-mode fill for dark pages, dark sections inside the site and light sections
+ * inside those. Pair it with `data-accent` on the same element so the derived values recompute.
+ */
+export declare function siteAccentCss(palette: SiteAccentPalette, key: string): string;

package/dist/blocks/site/shared/site-accent.js

@@ -0,0 +1,249 @@
+/**
+ * Site accent: one brand colour → the kit's four accent variables, with WCAG 2.x text contrast
+ * guaranteed (the same rules as `vamos-ui brand`, so a site and its panel derive identical
+ * values from one colour). Pure, React-free, server-safe.
+ *
+ *   --accent-base       fill (primary button, active state)
+ *   --accent-fg         text on the fill                    ≥ 4.5:1 on --accent-base
+ *   --accent-ink-light  accent text on light surfaces       ≥ 4.5:1 on the light scene and on accent-soft over it
+ *   --accent-ink-dark   accent text on dark surfaces        ≥ 4.5:1 on dark surface-2 and on accent-soft over it
+ *
+ * Very dark colours get a lighter dark-mode fill so buttons stay visible on dark surfaces.
+ */
+import { parseColor as parseRgba } from "../../../lib/color.js";
+/** Text contrast target (WCAG 1.4.3 AA). */
+export const SITE_TEXT_CONTRAST = 4.5;
+const UI_CONTRAST = 3;
+/** Hardest surfaces of each theme in styles.css (light scene, dark surface-2) and the plain surfaces. */
+const SURFACES = {
+    light: { surface: "#ffffff", hardest: "#eef0ea" },
+    dark: { surface: "#15180f", hardest: "#1b1e15" },
+};
+/** Built-in accent presets of styles.css; these are used by name, not recomputed. */
+export const BUILT_IN_SITE_ACCENTS = ["lime", "ocean", "ember", "rose", "graphite"];
+export const isBuiltInAccent = (v) => BUILT_IN_SITE_ACCENTS.includes(v);
+// ---------------------------------------------------------------- colour maths (sRGB 0–1)
+const toLinear = (v) => (v <= 0.04045 ? v / 12.92 : ((v + 0.055) / 1.055) ** 2.4);
+const toGamma = (v) => (v <= 0.0031308 ? 12.92 * v : 1.055 * v ** (1 / 2.4) - 0.055);
+function rgbToOklch(r, g, b) {
+    const lr = toLinear(r);
+    const lg = toLinear(g);
+    const lb = toLinear(b);
+    const l = Math.cbrt(0.4122214708 * lr + 0.5363325363 * lg + 0.0514459929 * lb);
+    const m = Math.cbrt(0.2119034982 * lr + 0.6806995451 * lg + 0.1073969566 * lb);
+    const s = Math.cbrt(0.0883024619 * lr + 0.2817188376 * lg + 0.6299787005 * lb);
+    const L = 0.2104542553 * l + 0.793617785 * m - 0.0040720468 * s;
+    const A = 1.9779984951 * l - 2.428592205 * m + 0.4505937099 * s;
+    const B = 0.0259040371 * l + 0.7827717662 * m - 0.808675766 * s;
+    const c = Math.sqrt(A * A + B * B);
+    let h = c < 1e-4 ? 0 : (Math.atan2(B, A) * 180) / Math.PI;
+    if (h < 0)
+        h += 360;
+    return { l: L, c, h };
+}
+/** OKLCH → sRGB, unclamped (may leave 0–1 when out of gamut). */
+function oklchToRgbRaw({ l: L, c, h }) {
+    const rad = (h * Math.PI) / 180;
+    const a = c * Math.cos(rad);
+    const b = c * Math.sin(rad);
+    const l = (L + 0.3963377774 * a + 0.2158037573 * b) ** 3;
+    const m = (L - 0.1055613458 * a - 0.0638541728 * b) ** 3;
+    const s = (L - 0.0894841775 * a - 1.291485548 * b) ** 3;
+    const g = (v) => (v < 0 ? -toGamma(-v) : toGamma(v));
+    return {
+        r: g(4.0767416621 * l - 3.3077115913 * m + 0.2309699292 * s),
+        g: g(-1.2684380046 * l + 2.6097574011 * m - 0.3413193965 * s),
+        b: g(-0.0041960863 * l - 0.7034186147 * m + 1.707614701 * s),
+    };
+}
+const EPS = 1e-6;
+const inGamut = (c) => {
+    const { r, g, b } = oklchToRgbRaw(c);
+    return [r, g, b].every((v) => v >= -EPS && v <= 1 + EPS);
+};
+/** Into sRGB by lowering chroma (hue and lightness kept). */
+function gamutMap(color) {
+    const base = { ...color, l: Math.min(1, Math.max(0, color.l)) };
+    if (inGamut(base))
+        return base;
+    let lo = 0;
+    let hi = base.c;
+    for (let i = 0; i < 24; i++) {
+        const mid = (lo + hi) / 2;
+        if (inGamut({ ...base, c: mid }))
+            lo = mid;
+        else
+            hi = mid;
+    }
+    return { ...base, c: lo };
+}
+const trim = (n, digits) => {
+    const s = n.toFixed(digits);
+    return s.includes(".") ? s.replace(/0+$/, "").replace(/\.$/, "") : s;
+};
+/** `oklch(0.64 0.17 245)`: the house format for accent values. */
+function formatOklch(color) {
+    const c = gamutMap(color);
+    const chroma = c.c < 0.0005 ? 0 : c.c;
+    return `oklch(${trim(c.l, 3)} ${trim(chroma, 3)} ${trim(chroma === 0 ? 0 : c.h, 1)})`;
+}
+const parse = (input) => {
+    const rgba = parseRgba(input);
+    return rgba ? rgbToOklch(rgba.r / 255, rgba.g / 255, rgba.b / 255) : null;
+};
+function luminance(color) {
+    const raw = oklchToRgbRaw(gamutMap(color));
+    const ch = (v) => toLinear(Math.min(1, Math.max(0, v)));
+    return 0.2126 * ch(raw.r) + 0.7152 * ch(raw.g) + 0.0722 * ch(raw.b);
+}
+function contrast(a, b) {
+    const pa = typeof a === "string" ? parse(a) : a;
+    const pb = typeof b === "string" ? parse(b) : b;
+    if (!pa || !pb)
+        return NaN;
+    const la = luminance(pa);
+    const lb = luminance(pb);
+    return (Math.max(la, lb) + 0.05) / (Math.min(la, lb) + 0.05);
+}
+/** Re-reads a formatted value: what the stylesheet gets is what is judged. */
+const asWritten = (c) => parseOklchString(formatOklch(c));
+function parseOklchString(s) {
+    const m = /oklch\(([\d.]+) ([\d.]+) ([\d.]+)\)/.exec(s);
+    return { l: Number(m[1]), c: Number(m[2]), h: Number(m[3]) };
+}
+const roundDown = (n) => Math.floor(n * 100) / 100;
+/**
+ * `color-mix(in oklch, base p%, transparent)` painted on `bg`: the browser blends the
+ * translucent colour in gamma-encoded sRGB. That is the `--accent-soft` chip behind accent text.
+ */
+function softOn(base, bg, amount) {
+    const b = parse(bg);
+    const fg = oklchToRgbRaw(gamutMap(base));
+    const bgRgb = oklchToRgbRaw(b);
+    const mix = (f, k) => Math.min(1, Math.max(0, f)) * amount + Math.min(1, Math.max(0, k)) * (1 - amount);
+    return rgbToOklch(mix(fg.r, bgRgb.r), mix(fg.g, bgRgb.g), mix(fg.b, bgRgb.b));
+}
+/** Accent-soft amounts of styles.css (light 22 %, dark 16 %). */
+const SOFT = { light: 0.22, dark: 0.16 };
+const WHITE = { l: 1, c: 0, h: 0 };
+const darkInk = (h) => ({ l: 0.18, c: 0.02, h });
+const fgString = (fg) => (fg.l === 1 && fg.c === 0 ? "#fff" : formatOklch(fg));
+function seekLightness(from, dir, ok) {
+    for (let i = 0; i <= 200; i++) {
+        const l = from.l + dir * i * 0.005;
+        if (l < 0 || l > 1)
+            break;
+        const c = gamutMap({ ...from, l });
+        if (ok(asWritten(c)))
+            return c;
+    }
+    return null;
+}
+function fillWithText(base, label, warnings) {
+    const cw = contrast(WHITE, base);
+    const cd = contrast(darkInk(base.h), base);
+    if (Math.max(cw, cd) >= SITE_TEXT_CONTRAST)
+        return { base, fg: cw >= cd ? WHITE : darkInk(base.h) };
+    const target = SITE_TEXT_CONTRAST + 0.05;
+    const forWhite = seekLightness(base, -1, (c) => contrast(WHITE, c) >= target);
+    const forDark = seekLightness(base, 1, (c) => contrast(darkInk(c.h), c) >= target);
+    const dW = forWhite ? base.l - forWhite.l : Infinity;
+    const dD = forDark ? forDark.l - base.l : Infinity;
+    const useWhite = dW <= dD;
+    const next = (useWhite ? forWhite : forDark) ?? base;
+    warnings.push(`${label} lightness ${base.l.toFixed(3)} → ${next.l.toFixed(3)} so ${useWhite ? "white" : "dark"} text on it reaches 4.5:1.`);
+    return { base: next, fg: useWhite ? WHITE : darkInk(next.h) };
+}
+/**
+ * The four accent variables for one brand colour (hex, rgb() or oklch()).
+ * Throws a TypeError when the colour cannot be read.
+ *
+ * ```ts
+ * siteAccent("#B4532A"); // { base: "oklch(…)", fg: "#fff", inkLight: "oklch(…)", inkDark: "oklch(…)", … }
+ * ```
+ */
+export function siteAccent(colour, options = {}) {
+    const parsed = parse(colour);
+    if (!parsed)
+        throw new TypeError(`"${colour}" is not a colour. Use hex (#1d4ed8), rgb() or oklch().`);
+    const warnings = [];
+    let base = gamutMap(parsed);
+    // 1. A near-white fill would lose its edge on white surfaces.
+    if (contrast(base, SURFACES.light.surface) < 1.25) {
+        const darker = seekLightness(base, -1, (c) => contrast(c, SURFACES.light.surface) >= 1.35);
+        if (darker) {
+            warnings.push(`Near-white colour: fill darkened so buttons stay visible on white.`);
+            base = darker;
+        }
+    }
+    // 2. Text on the fill.
+    const fill = fillWithText(base, "Fill", warnings);
+    base = fill.base;
+    const fg = fill.fg;
+    // 3. Ink on light surfaces: the scene and an accent-soft chip on it (accent badges, selected rows).
+    const softLight = softOn(base, SURFACES.light.hardest, SOFT.light);
+    const inkLightOk = (c) => Math.min(contrast(c, SURFACES.light.hardest), contrast(c, softLight)) >= SITE_TEXT_CONTRAST + 0.05;
+    let inkLight = base;
+    if (!inkLightOk(asWritten(base))) {
+        inkLight = seekLightness(base, -1, inkLightOk) ?? { ...base, l: 0.3 };
+    }
+    // 4. Dark-mode fill: explicit, or derived when the fill disappears on dark surfaces.
+    let dark;
+    if (options.dark) {
+        const pd = parse(options.dark);
+        if (!pd)
+            throw new TypeError(`"${options.dark}" (dark) is not a colour.`);
+        dark = fillWithText(gamutMap(pd), "Dark-mode fill", warnings);
+    }
+    else if (contrast(base, SURFACES.dark.surface) < 1.6) {
+        const lifted = base.c < 0.04
+            ? gamutMap({ ...base, l: Math.min(0.95, Math.max(0.88, 1 - base.l)) })
+            : seekLightness(base, 1, (c) => contrast(c, SURFACES.dark.surface) >= UI_CONTRAST) ?? { ...base, l: 0.7 };
+        dark = fillWithText(lifted, "Dark-mode fill", warnings);
+        warnings.push(`Very dark colour: dark mode uses a lighter fill so buttons stay visible.`);
+    }
+    // 5. Ink on dark surfaces: a light shade of the (dark-mode) fill.
+    const from = dark?.base ?? base;
+    const softDark = softOn(from, SURFACES.dark.hardest, SOFT.dark);
+    const inkDarkOk = (c) => Math.min(contrast(c, SURFACES.dark.hardest), contrast(c, softDark)) >= SITE_TEXT_CONTRAST + 0.05;
+    let inkDark = from;
+    if (from.l < 0.7 || !inkDarkOk(asWritten(from))) {
+        const start = gamutMap({ ...from, l: Math.max(from.l, 0.7), c: from.l < 0.7 ? from.c * 0.75 : from.c });
+        inkDark = inkDarkOk(asWritten(start)) ? start : seekLightness(start, 1, inkDarkOk) ?? { ...start, l: 0.9 };
+    }
+    const out = { base: formatOklch(base), fg: fgString(fg), inkLight: formatOklch(inkLight), inkDark: formatOklch(inkDark) };
+    const palette = {
+        source: colour,
+        ...out,
+        contrast: {
+            fgOnBase: roundDown(contrast(out.fg, out.base)),
+            inkLightOnLight: roundDown(contrast(out.inkLight, SURFACES.light.hardest)),
+            inkDarkOnDark: roundDown(contrast(out.inkDark, SURFACES.dark.hardest)),
+        },
+        warnings,
+    };
+    if (dark) {
+        palette.dark = { base: formatOklch(dark.base), fg: fgString(dark.fg) };
+        palette.contrast.darkFgOnBase = roundDown(contrast(palette.dark.fg, palette.dark.base));
+    }
+    return palette;
+}
+/** A stable attribute value for a palette (`b4532a`-like), safe inside a quoted CSS selector. */
+export function siteAccentKey(colour) {
+    return colour.trim().toLowerCase().replace(/[^a-z0-9]+/g, "-").replace(/^-|-$/g, "").slice(0, 48) || "accent";
+}
+/**
+ * The scoped stylesheet for a palette under `[data-site-accent="<key>"]`: the four variables,
+ * plus the dark-mode fill for dark pages, dark sections inside the site and light sections
+ * inside those. Pair it with `data-accent` on the same element so the derived values recompute.
+ */
+export function siteAccentCss(palette, key) {
+    const s = `[data-site-accent="${key.replace(/["\\]/g, "")}"]`;
+    const light = `--accent-base:${palette.base};--accent-fg:${palette.fg};`;
+    let css = `${s}{${light}--accent-ink-light:${palette.inkLight};--accent-ink-dark:${palette.inkDark};}`;
+    if (palette.dark) {
+        css += `.dark${s},.dark ${s},${s} .dark{--accent-base:${palette.dark.base};--accent-fg:${palette.dark.fg};}`;
+        css += `.dark ${s} .light,.dark${s} .light,${s} .dark .light{${light}}`;
+    }
+    return css;
+}

package/dist/blocks/site/shared/site-form.d.ts

@@ -0,0 +1,79 @@
+import { type Site2BlockLabels } from "./labels-2.js";
+export type ContactFieldName = "name" | "email" | "phone" | "company" | "subject" | "budget" | "message" | "date";
+export interface ContactFieldConfig {
+    name: ContactFieldName;
+    required?: boolean;
+    /** Overrides the built-in label ("Full name"). */
+    label?: string;
+    /** subject / budget: a select with these options instead of free text. */
+    options?: string[];
+    placeholder?: string;
+    hint?: string;
+    /** Max characters. Defaults: message 2000, others 160. */
+    max?: number;
+}
+/** What the action returns; the form renders from it (also without JS, after a full round trip). */
+export interface SiteFormState {
+    status: "idle" | "success" | "error" | "invalid";
+    /** Field name → error message. */
+    errors?: Partial<Record<string, string>>;
+    /** Submitted values, so a failed submit keeps what the visitor typed. */
+    values?: Record<string, string>;
+    /** Server error detail (shown with the fallback phone number). */
+    message?: string;
+    /** Changes on every submit (remounts the fields with `values`). */
+    ts?: number;
+}
+export type SiteFormAction = (prev: SiteFormState, data: FormData) => Promise<SiteFormState>;
+/** Name of the honeypot input. Real visitors never see or fill it. */
+export declare const HONEYPOT_FIELD = "website";
+/** Hidden render timestamp for the time trap. */
+export declare const TIMESTAMP_FIELD = "_ts";
+export declare const PRIVACY_FIELD = "privacy";
+export declare const MARKETING_FIELD = "marketing";
+/** The label shown for a field: config label → `labels` → English. */
+export declare function contactFieldLabel(field: ContactFieldConfig, labels?: Site2BlockLabels | Record<string, string>): string;
+/** True for honeypot hits and submits faster than `minMs` after render (bots). */
+export declare function isSpam(data: FormData, opts?: {
+    minMs?: number;
+    now?: number;
+}): boolean;
+export interface ContactValidation {
+    ok: boolean;
+    /** Honeypot / time trap hit: answer with a fake success, store nothing. */
+    spam: boolean;
+    values: Record<string, string>;
+    errors: Partial<Record<string, string>>;
+    privacy: boolean;
+    marketing: boolean;
+    /** A ready state for `useActionState` (invalid with errors, or success for spam). */
+    state: SiteFormState;
+}
+/**
+ * Validates a submission against the field config the form was rendered with. Call it first in
+ * the app's server action — the browser runs it too, but only the server's verdict counts.
+ *
+ * ```ts
+ * "use server";
+ * export async function contact(prev: SiteFormState, data: FormData) {
+ *   const v = validateContactForm(fields, data, { privacyCheckbox: true });
+ *   if (v.spam) return { status: "success" };
+ *   if (!v.ok) return v.state;
+ *   await crm.createLead(v.values);
+ *   return { status: "success" };
+ * }
+ * ```
+ */
+export declare function validateContactForm(fields: readonly ContactFieldConfig[], data: FormData, opts?: {
+    privacyCheckbox?: boolean;
+    labels?: Site2BlockLabels | Record<string, string>;
+    locale?: string;
+    spamMinMs?: number;
+}): ContactValidation;
+/** HTML constraints for a field (the no-JS path relies on these). */
+export declare function fieldConstraints(f: ContactFieldConfig): {
+    type: string;
+    autoComplete?: string;
+    inputMode?: "tel" | "email" | "text";
+    maxLength: number;
+};