@tonycodes-ui/mortar 0.0.0-stage → 0.11.0

package/dist/auth.d.ts

@@ -0,0 +1,121 @@
+import { type InputHTMLAttributes, type ReactNode } from "react";
+import { type FieldDescription } from "./primitives.js";
+import { type HeadingLevel } from "./heading.js";
+/** A sign-in provider such as GitHub or Google; the auth SDK handles `onSelect`. */
+export interface SignInProvider {
+    id: string;
+    label: string;
+    /** Decorative logo; the label stays the accessible name. */
+    icon?: ReactNode;
+    onSelect: () => void;
+}
+export interface ProviderButtonsProps {
+    providers: SignInProvider[];
+    /** `grid` sets the buttons side by side where they fit, e.g. two short labels. */
+    layout?: "list" | "grid";
+    /** Names the group of buttons, e.g. "Sign in with". */
+    label?: string;
+    className?: string;
+}
+/**
+ * One full-width secondary button per sign-in provider. Pair it with a
+ * labelled Divider ("or continue with") above or below the email form.
+ */
+export declare function ProviderButtons({ providers, layout, label, className, }: ProviderButtonsProps): import("react").JSX.Element;
+/** The logo, heading and description that open an auth panel (internal). */
+export declare function AuthHeader({ logo, title, description, headingLevel, headingId, className, titleClassName, }: {
+    logo?: ReactNode;
+    title: string;
+    description?: ReactNode;
+    headingLevel: HeadingLevel;
+    headingId: string;
+    className?: string;
+    titleClassName: string;
+}): import("react").JSX.Element;
+export interface AuthLayoutProps {
+    /** The screen's heading, e.g. "Sign in to your account". */
+    title: string;
+    description?: ReactNode;
+    /** Logo node above the heading. */
+    logo?: ReactNode;
+    /**
+     * `center` sets the form on the page, `cards` on a raised card, and `split`
+     * beside the `aside` on wide screens.
+     */
+    layout?: "center" | "cards" | "split";
+    /** The page's h1 by default; lower it only when another h1 precedes the layout. */
+    headingLevel?: HeadingLevel;
+    /** The form. A `<form>` placed directly here stacks its fields, and its direct Button children fill the width. */
+    children: ReactNode;
+    /** Text under the form, e.g. "Don't have an account? Sign up". */
+    footer?: ReactNode;
+    /**
+     * Image, quote or product art beside the form; shown only with `layout="split"`.
+     * On narrow screens text moves below the form and a lone image or video is hidden.
+     */
+    aside?: ReactNode;
+    id?: string;
+    className?: string;
+}
+/**
+ * The page shell for sign-in, sign-up, password reset and verification
+ * screens. It renders the page's `main` landmark, named by the heading.
+ */
+export declare function AuthLayout({ title, description, logo, layout, headingLevel, children, footer, aside, id, className, }: AuthLayoutProps): import("react").JSX.Element;
+export interface PasswordRequirement {
+    /** Shown before the password is typed, e.g. "At least 12 characters". */
+    label: string;
+    met: boolean;
+}
+export interface PasswordStrength {
+    /** 0 (very weak) to 4 (very strong), e.g. from zxcvbn's score. */
+    value: 0 | 1 | 2 | 3 | 4;
+    /** Visible and announced value, e.g. "Strong". */
+    label: string;
+}
+export interface PasswordInputProps extends Omit<InputHTMLAttributes<HTMLInputElement>, "type">, FieldDescription {
+    /**
+     * `current` (sign-in) sets autocomplete="current-password"; `new` (sign-up,
+     * reset) sets "new-password" so password managers offer to generate one.
+     */
+    purpose?: "current" | "new";
+    /** Rules shown under the field from the start, each marked met or not met as the person types. */
+    requirements?: PasswordRequirement[];
+    /** Strength meter under the field. */
+    strength?: PasswordStrength;
+    /** Accessible name of the show/hide toggle; its pressed state says whether the password is visible. */
+    toggleLabel?: string;
+}
+/**
+ * Password field with a show/hide toggle, optional requirement checklist and
+ * strength meter. Paste is never blocked.
+ */
+export declare const PasswordInput: import("react").ForwardRefExoticComponent<PasswordInputProps & import("react").RefAttributes<HTMLInputElement>>;
+export interface CodeInputProps extends FieldDescription {
+    /** Number of characters; one visual cell each. */
+    length?: number;
+    /** Controlled value; pair with `onChange`. */
+    value?: string;
+    defaultValue?: string;
+    /** The cleaned code after each edit: allowed characters only, at most `length`. */
+    onChange?: (value: string) => void;
+    /**
+     * Called once when the code reaches `length` characters, by typing, paste or
+     * autofill. Submitting here is opt-in; without it the person submits the form.
+     */
+    onComplete?: (code: string) => void;
+    /** Accept letters as well as digits (upper-cased); digits only by default. */
+    alphanumeric?: boolean;
+    /** Id of the input, e.g. the target of an error summary link. */
+    id?: string;
+    name?: string;
+    required?: boolean;
+    disabled?: boolean;
+    autoFocus?: boolean;
+}
+/**
+ * One-time code field: a single input shown as one cell per character, so
+ * screen readers, paste and SMS or password-manager autofill all see one
+ * field (autocomplete="one-time-code").
+ */
+export declare const CodeInput: import("react").ForwardRefExoticComponent<CodeInputProps & import("react").RefAttributes<HTMLInputElement>>;

package/dist/auth.js

@@ -0,0 +1,97 @@
+import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
+// Sign-in and registration building blocks: the auth page shell, provider
+// buttons and the password and one-time-code fields. See docs/auth-flows.md.
+import { forwardRef, useId, useState, } from "react";
+import { Button, FieldLabel } from "./primitives.js";
+import { BrandMark } from "./layout.js";
+import { Check, Circle, Eye, EyeOff } from "./icons.js";
+import { headingTag } from "./heading.js";
+import { FieldFeedback, componentRoot, cx, useField } from "./internal.js";
+/**
+ * One full-width secondary button per sign-in provider. Pair it with a
+ * labelled Divider ("or continue with") above or below the email form.
+ */
+export function ProviderButtons({ providers, layout = "list", label, className, }) {
+    return (_jsx("div", { ...componentRoot("ProviderButtons"), className: cx("m-provider-buttons", className), role: label ? "group" : undefined, "aria-label": label, "data-layout": layout === "list" ? undefined : layout, children: providers.map((provider) => (_jsx(Button, { variant: "secondary", icon: provider.icon, onClick: provider.onSelect, children: provider.label }, provider.id))) }));
+}
+/** The logo, heading and description that open an auth panel (internal). */
+export function AuthHeader({ logo, title, description, headingLevel, headingId, className, titleClassName, }) {
+    const Heading = headingTag(headingLevel);
+    return (_jsxs("header", { className: className, children: [logo && _jsx(BrandMark, { logo: logo }), _jsx(Heading, { id: headingId, className: titleClassName, children: title }), description && _jsx("p", { children: description })] }));
+}
+/**
+ * The page shell for sign-in, sign-up, password reset and verification
+ * screens. It renders the page's `main` landmark, named by the heading.
+ */
+export function AuthLayout({ title, description, logo, layout = "center", headingLevel = 1, children, footer, aside, id, className, }) {
+    const headingId = useId();
+    return (_jsxs("div", { id: id, ...componentRoot("AuthLayout"), className: cx("m-auth", className), "data-layout": layout === "center" ? undefined : layout, children: [_jsx("main", { className: "m-auth-main", "aria-labelledby": headingId, children: _jsxs("div", { className: "m-auth-panel", children: [_jsx(AuthHeader, { className: "m-auth-header", titleClassName: "m-auth-title", logo: logo, title: title, description: description, headingLevel: headingLevel, headingId: headingId }), _jsx("div", { className: "m-auth-body", children: children }), footer && _jsx("footer", { className: "m-auth-footer", children: footer })] }) }), layout === "split" && aside && (_jsx("aside", { className: "m-auth-aside", children: aside }))] }));
+}
+/**
+ * Password field with a show/hide toggle, optional requirement checklist and
+ * strength meter. Paste is never blocked.
+ */
+export const PasswordInput = forwardRef(function PasswordInput({ label, hint, error, id, className, purpose = "current", requirements, strength, toggleLabel = "Show password", autoComplete, ...props }, ref) {
+    const [visible, setVisible] = useState(false);
+    const requirementsId = useId();
+    const { fieldId, messageId, describedBy } = useField({
+        id,
+        hint,
+        error,
+        describedBy: props["aria-describedby"],
+    });
+    const allMet = !!requirements?.length && requirements.every((r) => r.met);
+    // The status region speaks only when the overall state flips, not on
+    // every keystroke: silent until every rule has been met once.
+    const [everMet, setEverMet] = useState(false);
+    if (allMet && !everMet)
+        setEverMet(true);
+    const status = allMet
+        ? "All password requirements met."
+        : everMet
+            ? "Password no longer meets every requirement."
+            : "";
+    return (_jsxs("div", { ...componentRoot("PasswordInput"), className: cx("m-field", "m-password", className), children: [_jsx(FieldLabel, { htmlFor: fieldId, label: label, required: props.required }), _jsxs("div", { className: "m-input-group", "data-invalid": !!error || undefined, children: [_jsx("input", { ...props, ref: ref, id: fieldId, type: visible ? "text" : "password", autoComplete: autoComplete ??
+                            (purpose === "new" ? "new-password" : "current-password"), autoCapitalize: "off", spellCheck: false, "aria-invalid": !!error || props["aria-invalid"], "aria-describedby": [describedBy, requirements?.length && requirementsId]
+                            .filter(Boolean)
+                            .join(" ") || undefined }), _jsxs("button", { type: "button", className: "m-password-toggle", "aria-pressed": visible, "aria-controls": fieldId, disabled: props.disabled, 
+                        // A pointer press keeps focus where it was (usually the field).
+                        onMouseDown: (event) => event.preventDefault(), onClick: () => setVisible((v) => !v), children: [visible ? _jsx(EyeOff, {}) : _jsx(Eye, {}), _jsx("span", { className: "m-sr-only", children: toggleLabel })] })] }), _jsx(FieldFeedback, { id: messageId, hint: hint, error: error }), strength && _jsx(StrengthMeter, { strength: strength }), requirements && requirements.length > 0 && (_jsxs(_Fragment, { children: [_jsx("ul", { id: requirementsId, className: "m-password-requirements", "aria-label": "Password requirements", children: requirements.map((rule) => (_jsxs("li", { "data-met": rule.met || undefined, children: [rule.met ? _jsx(Check, {}) : _jsx(Circle, {}), _jsx("span", { children: rule.label }), _jsx("span", { className: "m-sr-only", children: rule.met ? ", met" : ", not met" })] }, rule.label))) }), _jsx("p", { role: "status", className: "m-sr-only", children: status })] }))] }));
+});
+function StrengthMeter({ strength }) {
+    const labelId = useId();
+    const value = Math.max(0, Math.min(4, Math.round(strength.value)));
+    return (_jsxs("div", { className: "m-password-strength", "data-value": value, children: [_jsx("span", { id: labelId, className: "m-sr-only", children: "Password strength" }), _jsx("div", { className: "m-password-meter", role: "meter", "aria-labelledby": labelId, "aria-valuemin": 0, "aria-valuemax": 4, "aria-valuenow": value, "aria-valuetext": strength.label, children: [1, 2, 3, 4].map((step) => (_jsx("span", { "data-on": value >= step || undefined }, step))) }), _jsx("span", { "aria-hidden": "true", children: strength.label })] }));
+}
+/**
+ * One-time code field: a single input shown as one cell per character, so
+ * screen readers, paste and SMS or password-manager autofill all see one
+ * field (autocomplete="one-time-code").
+ */
+export const CodeInput = forwardRef(function CodeInput({ label, hint, error, className, length = 6, value: controlled, defaultValue = "", onChange, onComplete, alphanumeric = false, id, name, required, disabled, autoFocus, }, ref) {
+    const clean = (text) => (alphanumeric
+        ? text.replace(/[^a-z0-9]/gi, "").toUpperCase()
+        : text.replace(/\D/g, "")).slice(0, length);
+    const [local, setLocal] = useState(() => clean(defaultValue));
+    const value = controlled === undefined ? local : clean(controlled);
+    const [focused, setFocused] = useState(false);
+    const { fieldId, messageId, describedBy } = useField({ id, hint, error });
+    const active = focused ? Math.min(value.length, length - 1) : -1;
+    return (_jsxs("div", { ...componentRoot("CodeInput"), className: cx("m-field", "m-code-input", className), "data-disabled": disabled || undefined, children: [_jsx(FieldLabel, { htmlFor: fieldId, label: label, required: required }), _jsxs("div", { className: "m-code-control", "data-invalid": !!error || undefined, style: { "--m-code-length": length }, children: [_jsx("input", { ref: ref, id: fieldId, name: name, type: "text", inputMode: alphanumeric ? "text" : "numeric", autoComplete: "one-time-code", autoCapitalize: alphanumeric ? "characters" : "off", autoCorrect: "off", spellCheck: false, pattern: alphanumeric ? `[A-Za-z0-9]{${length}}` : `[0-9]{${length}}`, required: required, disabled: disabled, autoFocus: autoFocus, value: value, "aria-invalid": !!error || undefined, "aria-describedby": describedBy, onFocus: () => setFocused(true), onBlur: () => setFocused(false), 
+                        // Keep the caret after the last character, so typing fills the
+                        // next cell and Backspace clears the previous one.
+                        onSelect: (event) => {
+                            const input = event.currentTarget;
+                            const end = input.value.length;
+                            if (input.selectionStart === input.selectionEnd &&
+                                input.selectionStart !== end)
+                                input.setSelectionRange(end, end);
+                        }, onChange: (event) => {
+                            const next = clean(event.target.value);
+                            if (controlled === undefined)
+                                setLocal(next);
+                            onChange?.(next);
+                            if (next !== value && next.length === length)
+                                onComplete?.(next);
+                        } }), _jsx("div", { className: "m-code-cells", "aria-hidden": "true", children: Array.from({ length }, (_, index) => (_jsx("span", { className: "m-code-cell", "data-filled": index < value.length || undefined, "data-active": index === active || undefined, children: value[index] }, index))) })] }), _jsx(FieldFeedback, { id: messageId, hint: hint, error: error })] }));
+});

package/dist/brand.d.ts

@@ -0,0 +1,69 @@
+export interface BrandAppearanceTokens {
+    primary?: string;
+    primaryHover?: string;
+    primaryActive?: string;
+    onPrimary?: string;
+    accent?: string;
+    onAccent?: string;
+    focus?: string;
+    link?: string;
+    selected?: string;
+    /** The page background. */
+    paper?: string;
+    /** Cards, panels and raised controls. */
+    surface?: string;
+    /** Recessed areas: wells, muted bands and hover fills. */
+    sunken?: string;
+    /**
+     * An optional accent fill: `linear-gradient()`, `radial-gradient()` or
+     * `conic-gradient()` (or a `repeating-` form) whose stops are colours. Only
+     * components that opt in paint it (Button `variant="accent"`, and
+     * `tone="accent"` on CallToAction, Hero and Banner), with `onAccent` text,
+     * so `onAccent` must reach 4.5:1 against every stop. The flat `accent`
+     * stays the fallback and the input for derived colours.
+     */
+    accentGradient?: string;
+}
+/** Font stacks, the same in light and dark. */
+export interface BrandFonts {
+    /** Body text: a font-family list, e.g. `"Inter", sans-serif`. */
+    body?: string;
+    /** Headings and component titles. Defaults to the body font. */
+    heading?: string;
+}
+/** A brand's light and dark values. Inverse bands use the other appearance's. */
+export interface BrandDefinition {
+    light?: BrandAppearanceTokens;
+    dark?: BrandAppearanceTokens;
+    fonts?: BrandFonts;
+}
+/**
+ * True for colour syntax only: hex, a colour name (including `transparent`
+ * and `currentcolor`), or rgb(), rgba(), hsl(), hsla(), hwb(), lab(), lch(),
+ * oklab(), oklch(), color(), color-mix(), light-dark() or var(), whose
+ * arguments may nest those functions and calc(), min(), max() or clamp().
+ */
+export declare function isBrandColour(value: string): boolean;
+/**
+ * True for a CSS gradient whose stops are colour syntax: linear-, radial- or
+ * conic-gradient() (or a repeating- form) with at least two colour stops.
+ * Angles, positions, percentages and keywords such as `to right` are allowed;
+ * other functions (url(), image-set(), attr() …) are not.
+ */
+export declare function isBrandGradient(value: string): boolean;
+/**
+ * True for a font-family list: family names, quoted names, generic families
+ * and bare `var(--name)` references (as framework font loaders hand out),
+ * separated by commas. No other functions, url() or CSS punctuation.
+ */
+export declare function isBrandFont(value: string): boolean;
+/** The brand's custom properties, validated, as `--m-brand-*` entries. */
+export declare function brandToStyle(brand: BrandDefinition): Record<`--m-brand-${string}`, string>;
+/** The brand as a CSS rule, for a stylesheet or a `<style>` element. */
+export declare function brandToCss(name: string, brand: BrandDefinition): string;
+/**
+ * Adds the brand's stylesheet to the document, for apps that don't use
+ * ThemeProvider's `brandTokens`. Each call returns a disposer; the stylesheet
+ * stays until every caller for that name has disposed.
+ */
+export declare function registerBrand(name: string, brand: BrandDefinition): () => void;

package/dist/brand.js

@@ -0,0 +1,266 @@
+/* Programmatic brands. Mirrors the brand contract in tokens.css, so an app can
+   define a brand from a config object, a CMS value or a tenant record without
+   shipping brand CSS. Every value is optional; omitted values derive from
+   primary, or keep Mortar's defaults, exactly as the CSS layer does. */
+const KEYS = {
+    primary: "primary",
+    primaryHover: "primary-hover",
+    primaryActive: "primary-active",
+    onPrimary: "on-primary",
+    accent: "accent",
+    onAccent: "on-accent",
+    focus: "focus",
+    link: "link",
+    selected: "selected",
+    paper: "paper",
+    surface: "surface",
+    sunken: "sunken",
+    accentGradient: "accent-gradient",
+};
+const FONT_KEYS = {
+    body: "font",
+    heading: "font-heading",
+};
+const NAME = /^[a-z0-9][a-z0-9-]*$/i;
+/* Value validation. A value from tenant data must be colour (or gradient, or
+   font-family) syntax and nothing else, so it can neither end the declaration
+   nor inject other CSS, and a value of the wrong kind throws here instead of
+   failing silently in the browser. Values are tokenised, and every function is
+   checked against an allowlist, recursively. */
+const NAMED = new Set(("transparent currentcolor aliceblue antiquewhite aqua aquamarine azure beige bisque black " +
+    "blanchedalmond blue blueviolet brown burlywood cadetblue chartreuse chocolate coral " +
+    "cornflowerblue cornsilk crimson cyan darkblue darkcyan darkgoldenrod darkgray darkgreen " +
+    "darkgrey darkkhaki darkmagenta darkolivegreen darkorange darkorchid darkred darksalmon " +
+    "darkseagreen darkslateblue darkslategray darkslategrey darkturquoise darkviolet deeppink " +
+    "deepskyblue dimgray dimgrey dodgerblue firebrick floralwhite forestgreen fuchsia gainsboro " +
+    "ghostwhite gold goldenrod gray green greenyellow grey honeydew hotpink indianred indigo " +
+    "ivory khaki lavender lavenderblush lawngreen lemonchiffon lightblue lightcoral lightcyan " +
+    "lightgoldenrodyellow lightgray lightgreen lightgrey lightpink lightsalmon lightseagreen " +
+    "lightskyblue lightslategray lightslategrey lightsteelblue lightyellow lime limegreen linen " +
+    "magenta maroon mediumaquamarine mediumblue mediumorchid mediumpurple mediumseagreen " +
+    "mediumslateblue mediumspringgreen mediumturquoise mediumvioletred midnightblue mintcream " +
+    "mistyrose moccasin navajowhite navy oldlace olive olivedrab orange orangered orchid " +
+    "palegoldenrod palegreen paleturquoise palevioletred papayawhip peachpuff peru pink plum " +
+    "powderblue purple rebeccapurple red rosybrown royalblue saddlebrown salmon sandybrown " +
+    "seagreen seashell sienna silver skyblue slateblue slategray slategrey snow springgreen " +
+    "steelblue tan teal thistle tomato turquoise violet wheat white whitesmoke yellow yellowgreen").split(" "));
+const COLOUR_FUNCTIONS = new Set([
+    "rgb",
+    "rgba",
+    "hsl",
+    "hsla",
+    "hwb",
+    "lab",
+    "lch",
+    "oklab",
+    "oklch",
+    "color",
+    "color-mix",
+    "light-dark",
+    "var",
+]);
+/** Allowed only inside a colour or gradient, e.g. for relative colour channels. */
+const MATH_FUNCTIONS = new Set(["calc", "min", "max", "clamp"]);
+const GRADIENTS = new Set(["linear-gradient", "radial-gradient", "conic-gradient"].flatMap((name) => [
+    name,
+    `repeating-${name}`,
+]));
+// One token per match: whitespace, #hash, function name with its "(", ident
+// (including --custom-property), number with optional unit, ")", ",", "/" or
+// an arithmetic operator. Anything else (quotes, ; { } < > comments, bare
+// parentheses, backslashes) fails to tokenise.
+const TOKEN = /(\s+)|(#[0-9a-z]+)|(-{0,2}[a-z_][a-z0-9_-]*)\(|(-{0,2}[a-z_][a-z0-9_-]*)|([+-]?(?:\d+\.?\d*|\.\d+)(?:e[+-]?\d+)?(?:%|[a-z]+)?)|(\))|(,)|(\/)|([*+-])/giy;
+/** The value as a tree of functions and tokens, or undefined if it holds anything else. */
+function parse(value) {
+    const root = [];
+    const open = [];
+    TOKEN.lastIndex = 0;
+    while (TOKEN.lastIndex < value.length) {
+        const at = TOKEN.lastIndex;
+        const m = TOKEN.exec(value);
+        if (!m || m.index !== at)
+            return undefined;
+        const [, space, hash, fn, ident, number, close, comma, slash, op] = m;
+        const top = open.length ? open[open.length - 1].args : root;
+        if (space)
+            continue;
+        if (fn) {
+            const node = { kind: "function", name: fn.toLowerCase(), args: [] };
+            top.push(node);
+            open.push(node);
+        }
+        else if (close) {
+            if (!open.pop())
+                return undefined;
+        }
+        else if (hash)
+            top.push({ kind: "hash", value: hash });
+        else if (ident)
+            top.push({ kind: "ident", value: ident.toLowerCase() });
+        else if (number)
+            top.push({ kind: "number", value: number });
+        else if (comma)
+            top.push({ kind: "comma", value: comma });
+        else if (slash)
+            top.push({ kind: "slash", value: slash });
+        else if (op)
+            top.push({ kind: "op", value: op });
+    }
+    return open.length ? undefined : root;
+}
+/** Arguments of an allowed function: plain tokens and allowed functions only. */
+function validArgs(fn) {
+    if (fn.name === "var") {
+        const [name, next] = fn.args;
+        if (name?.kind !== "ident" || !name.value.startsWith("--"))
+            return false;
+        if (next && next.kind !== "comma")
+            return false;
+    }
+    return fn.args.every((node) => node.kind !== "function" ||
+        ((COLOUR_FUNCTIONS.has(node.name) || MATH_FUNCTIONS.has(node.name)) &&
+            validArgs(node)));
+}
+function isColourNode(node) {
+    if (node.kind === "hash")
+        return /^#(?:[0-9a-f]{3,4}|[0-9a-f]{6}|[0-9a-f]{8})$/i.test(node.value);
+    if (node.kind === "ident")
+        return NAMED.has(node.value);
+    return (node.kind === "function" &&
+        COLOUR_FUNCTIONS.has(node.name) &&
+        validArgs(node));
+}
+/**
+ * True for colour syntax only: hex, a colour name (including `transparent`
+ * and `currentcolor`), or rgb(), rgba(), hsl(), hsla(), hwb(), lab(), lch(),
+ * oklab(), oklch(), color(), color-mix(), light-dark() or var(), whose
+ * arguments may nest those functions and calc(), min(), max() or clamp().
+ */
+export function isBrandColour(value) {
+    const nodes = parse(value.trim());
+    return nodes?.length === 1 && isColourNode(nodes[0]);
+}
+/**
+ * True for a CSS gradient whose stops are colour syntax: linear-, radial- or
+ * conic-gradient() (or a repeating- form) with at least two colour stops.
+ * Angles, positions, percentages and keywords such as `to right` are allowed;
+ * other functions (url(), image-set(), attr() …) are not.
+ */
+export function isBrandGradient(value) {
+    const nodes = parse(value.trim());
+    if (nodes?.length !== 1)
+        return false;
+    const [gradient] = nodes;
+    if (gradient.kind !== "function" || !GRADIENTS.has(gradient.name))
+        return false;
+    if (!validArgs(gradient))
+        return false;
+    const segments = [[]];
+    for (const node of gradient.args)
+        if (node.kind === "comma")
+            segments.push([]);
+        else
+            segments[segments.length - 1].push(node);
+    return segments.filter((s) => s.some(isColourNode)).length >= 2;
+}
+const FAMILY = /\s*("[^"]*"|'[^']*'|-?[a-z_][a-z0-9_-]*(?:\s+-?[a-z_][a-z0-9_-]*)*)\s*(,|$)/iy;
+/**
+ * True for a font-family list: family names, quoted names, generic families
+ * and bare `var(--name)` references (as framework font loaders hand out),
+ * separated by commas. No other functions, url() or CSS punctuation.
+ */
+export function isBrandFont(value) {
+    // A bare var(--name) stands in for one whole entry, like a quoted name, so
+    // two in a row without a comma fail. Anything else with parentheses (a
+    // fallback, url(), local()) is still rejected.
+    const text = value.trim().replace(/var\(\s*--[a-z0-9_-]+\s*\)/gi, '""');
+    if (!text || /[;{}<>\\()]|\/\*/.test(text))
+        return false;
+    FAMILY.lastIndex = 0;
+    let last = "";
+    while (FAMILY.lastIndex < text.length) {
+        const at = FAMILY.lastIndex;
+        const m = FAMILY.exec(text);
+        if (!m || m.index !== at)
+            return false;
+        last = m[2];
+    }
+    return last !== ",";
+}
+function assertName(name) {
+    if (!NAME.test(name))
+        throw new Error(`Mortar brand names use letters, digits and hyphens: "${name}"`);
+}
+const COLOUR_SYNTAX = "a hex value, a colour name, or rgb(), hsl(), hwb(), lab(), lch(), oklab(), oklch(), color(), color-mix(), light-dark() or var()";
+/** The brand's custom properties, validated, as `--m-brand-*` entries. */
+export function brandToStyle(brand) {
+    const out = {};
+    for (const [prefix, mode, tokens] of [
+        ["l", "light", brand.light],
+        ["d", "dark", brand.dark],
+    ]) {
+        if (!tokens)
+            continue;
+        for (const key of Object.keys(KEYS)) {
+            const value = tokens[key]?.trim();
+            if (!value)
+                continue;
+            if (key === "accentGradient") {
+                if (!isBrandGradient(value))
+                    throw new Error(`Invalid Mortar brand gradient for ${mode}.${key}: "${value}". Use linear-gradient(), radial-gradient() or conic-gradient(), or a repeating- form, with at least two colour stops, each ${COLOUR_SYNTAX}.`);
+            }
+            else if (!isBrandColour(value))
+                throw new Error(`Invalid Mortar brand colour for ${mode}.${key}: "${value}". Use ${COLOUR_SYNTAX}.`);
+            out[`--m-brand-${prefix}-${KEYS[key]}`] = value;
+        }
+    }
+    for (const key of Object.keys(FONT_KEYS)) {
+        const value = brand.fonts?.[key]?.trim();
+        if (!value)
+            continue;
+        if (!isBrandFont(value))
+            throw new Error(`Invalid Mortar brand font for fonts.${key}: "${value}". Use family names, quoted names and generic families separated by commas, e.g. "Inter", sans-serif.`);
+        out[`--m-brand-${FONT_KEYS[key]}`] = value;
+    }
+    return out;
+}
+/** The brand as a CSS rule, for a stylesheet or a `<style>` element. */
+export function brandToCss(name, brand) {
+    assertName(name);
+    const body = Object.entries(brandToStyle(brand))
+        .map(([property, value]) => `  ${property}: ${value};`)
+        .join("\n");
+    return `[data-mortar-brand="${name}"] {\n${body}\n}`;
+}
+const registered = new Map();
+/**
+ * Adds the brand's stylesheet to the document, for apps that don't use
+ * ThemeProvider's `brandTokens`. Each call returns a disposer; the stylesheet
+ * stays until every caller for that name has disposed.
+ */
+export function registerBrand(name, brand) {
+    const css = brandToCss(name, brand);
+    if (typeof document === "undefined")
+        return () => { };
+    let entry = registered.get(name);
+    if (!entry) {
+        const element = document.createElement("style");
+        element.dataset.mortarBrandStyle = name;
+        document.head.append(element);
+        entry = { element, count: 0 };
+        registered.set(name, entry);
+    }
+    entry.element.textContent = css;
+    entry.count += 1;
+    let disposed = false;
+    return () => {
+        if (disposed || !entry)
+            return;
+        disposed = true;
+        entry.count -= 1;
+        if (entry.count === 0) {
+            entry.element.remove();
+            registered.delete(name);
+        }
+    };
+}

package/dist/calendar.d.ts

@@ -0,0 +1,75 @@
+import type React from "react";
+import { type ReactNode } from "react";
+import { type HeadingLevel } from "./heading.js";
+export interface CalendarEvent {
+    id: string;
+    /** Day of the event as YYYY-MM-DD. */
+    date: string;
+    title: string;
+    /** Display time, e.g. "10:00". */
+    time?: string;
+    /** Start as HH:MM; positions the event in week and day views. Omit for all-day. */
+    start?: string;
+    /** End as HH:MM; defaults to an hour after start. */
+    end?: string;
+    /** Avatar or icon beside the event in the month view's `agenda`. */
+    media?: ReactNode;
+}
+export type CalendarView = "year" | "month" | "week" | "day";
+export interface CalendarProps {
+    /** Displayed month as YYYY-MM. Omit to follow `date`. */
+    month?: string;
+    /** Called with YYYY-MM whenever the current date moves into another month, in any view. */
+    onMonthChange?: (month: string) => void;
+    /**
+     * The current date as YYYY-MM-DD: the month view's focusable day, the
+     * year shown in the year view and the week or day shown in the time views.
+     * Omit to let the calendar manage it; it starts at `selected` or today.
+     */
+    date?: string;
+    /** Called with the new current date after navigation in any view. */
+    onDateChange?: (date: string) => void;
+    /** Selected day as YYYY-MM-DD. */
+    selected?: string;
+    onSelect?: (date: string) => void;
+    events?: CalendarEvent[];
+    /** Month view only: `full` lists each day's events in its cell. */
+    variant?: "compact" | "full";
+    weekStartsOn?: 0 | 1;
+    /** Override today's date (YYYY-MM-DD), e.g. for tests or a user's time zone. */
+    today?: string;
+    locale?: string;
+    /** Month view with `variant="full"` only: events listed per day before "+N more". */
+    maxEvents?: number;
+    /** Twelve months, one month grid, or a time grid for one week or one day. */
+    view?: CalendarView;
+    /** Shows a Year/Month/Week/Day switcher when provided. */
+    onViewChange?: (view: CalendarView) => void;
+    /** Makes events in week and day views, and in the agenda, buttons. */
+    onEventSelect?: (id: string) => void;
+    /**
+     * Month view only: lists the events of the selected day (or the current
+     * date when nothing is selected) beside the month, or below it when
+     * narrow, under a "Schedule for" heading one level below the title.
+     */
+    agenda?: boolean;
+    /**
+     * First and last hour shown in week and day views. Events that start or
+     * end outside them are drawn at the edge with a dashed border and keep
+     * their real times in their text.
+     */
+    dayStartHour?: number;
+    dayEndHour?: number;
+    /** Level of the title (month, year, week or day); month and day headings are one below. */
+    headingLevel?: HeadingLevel;
+    id?: string;
+    className?: string;
+}
+/**
+ * Calendar with year, month, week and day views. One current date (`date`)
+ * is shared by every view, so moving through months and then switching to
+ * the week view shows a week of the month you reached. The month and year
+ * views are grids with keyboard navigation; the week and day views place
+ * timed events on an hour grid.
+ */
+export declare function Calendar({ month: controlledMonth, onMonthChange, date: controlledDate, onDateChange, selected, onSelect, events, variant, weekStartsOn, today: todayProp, locale, maxEvents, view, onViewChange, onEventSelect, agenda, dayStartHour, dayEndHour, headingLevel, id, className, }: CalendarProps): React.JSX.Element;