@sepale/components 0.0.0-stage → 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,73 @@
+export { default as Button } from './components/Button.svelte';
+export { default as Input } from './components/Input.svelte';
+export { default as Textarea } from './components/Textarea.svelte';
+export { default as Select } from './components/Select.svelte';
+export { default as Combobox, type ComboboxSource } from './components/Combobox.svelte';
+export { default as ChipsInput, type ChipsInputField } from './components/ChipsInput.svelte';
+export { default as FileInput } from './components/FileInput.svelte';
+export { default as FileDropzone } from './components/FileDropzone.svelte';
+export { default as Calendar } from './components/Calendar.svelte';
+export { default as DatePicker } from './components/DatePicker.svelte';
+export { default as Checkbox } from './components/Checkbox.svelte';
+export { default as Radio } from './components/Radio.svelte';
+export { default as Toggle } from './components/Toggle.svelte';
+export { default as Range } from './components/Range.svelte';
+export { default as Fieldset } from './components/Fieldset.svelte';
+export { default as Label } from './components/Label.svelte';
+export { default as FloatingLabel } from './components/FloatingLabel.svelte';
+export { default as Switch } from './components/Switch.svelte';
+export { default as NumberInput } from './components/NumberInput.svelte';
+export { default as Avatar } from './components/Avatar.svelte';
+export { default as Bubble } from './components/Bubble.svelte';
+export { default as Chip } from './components/Chip.svelte';
+export { default as Badge } from './components/Badge.svelte';
+export { default as Swatch } from './components/Swatch.svelte';
+export { default as ColorPicker } from './components/ColorPicker.svelte';
+export { default as Loading } from './components/Loading.svelte';
+export { default as Progress } from './components/Progress.svelte';
+export { default as RadialProgress } from './components/RadialProgress.svelte';
+export { default as Skeleton } from './components/Skeleton.svelte';
+export { default as List } from './components/List.svelte';
+export { default as Card } from './components/Card.svelte';
+export { default as Stat } from './components/Stat.svelte';
+export { default as Stats } from './components/Stats.svelte';
+export { default as Carousel } from './components/Carousel.svelte';
+export { default as Text } from './components/Text.svelte';
+export { default as Title } from './components/Title.svelte';
+export { default as Subtitle } from './components/Subtitle.svelte';
+export { default as Divider } from './components/Divider.svelte';
+export { default as Alert } from './components/Alert.svelte';
+export { default as Toast, type ToastOptions } from './components/Toast.svelte';
+export { default as Tooltip } from './components/Tooltip.svelte';
+export { default as Collapse } from './components/Collapse.svelte';
+export { default as Accordion } from './components/Accordion.svelte';
+export { default as Rating } from './components/Rating.svelte';
+export { default as Editable, type EditableKind, type EditableTrigger, type EditableControl } from './components/Editable.svelte';
+export { default as EmptyState } from './components/EmptyState.svelte';
+export { default as Hero } from './components/Hero.svelte';
+export { default as Footer, type FooterSection } from './components/Footer.svelte';
+export { default as MobileFrame } from './components/MobileFrame.svelte';
+export { default as WindowFrame } from './components/WindowFrame.svelte';
+export { default as LaptopFrame } from './components/LaptopFrame.svelte';
+export { default as Sidebar } from './components/Sidebar.svelte';
+export { default as Drawer, type DrawerState } from './components/Drawer.svelte';
+export { default as Menu, type MenuNode } from './components/Menu.svelte';
+export { default as Navbar } from './components/Navbar.svelte';
+export { default as Breadcrumbs } from './components/Breadcrumbs.svelte';
+export { default as Pagination } from './components/Pagination.svelte';
+export { default as Steps, type Step, type StepState } from './components/Steps.svelte';
+export { default as Dock } from './components/Dock.svelte';
+export { default as Tabs, type TabItem } from './components/Tabs.svelte';
+export { default as DataHandler, DataHandlerState, parseQuery, parseFilterValues, filterValuesToParams, type DataHandlerOptions, type DataHandlerMessages, type DataRow, type DiscardChoice, type EntityValue, type EntitySuggestion, type Filter, type FilterValues, type GetParams, type GetResult, type HandledFilter, type Identifier, type Navigation, type Sort } from './components/DataHandler.svelte';
+export { default as DataControl, LABELS as DATA_CONTROL_LABELS, type DataControlLabels } from './components/DataControl.svelte';
+export { default as Table, type TableColumn, type TableSort, type TableSortDirection } from './components/Table.svelte';
+export { default as Grid } from './components/Grid.svelte';
+export { default as Kanban, type KanbanColumn, type KanbanMove } from './components/Kanban.svelte';
+export { default as FileExplorer, type FileNode, type FileDrop } from './components/FileExplorer.svelte';
+export { FILE_ICONS, extensionOf, type FileIcon } from './components/file-icons.js';
+export { default as Dialog } from './components/Dialog.svelte';
+export { default as Dropdown, type DropdownTrigger } from './components/Dropdown.svelte';
+export { default as Join } from './components/Join.svelte';
+export { type Axis, type AxisProps, type Values } from './variants.js';
+export { families, themesByFamily, type ThemeData } from './generated/registry.js';
+export { defaultTheme, familyCategory, cloneTheme, serializeTheme, tokensToInlineStyle, tokensForFamily, parseTheme, type ThemeToken, type TokenType } from './theme.js';

package/dist/index.js

@@ -0,0 +1,99 @@
+// Sepale — the Svelte layer.
+//
+// Every component emits the class names of whatever family stylesheet is
+// loaded; bring `families/<name>.css` and a theme alongside. A component
+// declares its own vocabulary in AXES and FLAGS blocks, and the build writes a
+// copy per family as plain code — props typed to exactly the classes the family
+// ships, nothing generic, nothing to import — so an exported component cannot
+// offer a variant its stylesheet has never heard of.
+//
+// `link` and `validator` have no component here on purpose: they are one
+// class on one element, with no axis and no structure, and a wrapper would only
+// add an import. Write `<a class="link">`. Text does have wrappers — `Text`,
+// `Title`, `Subtitle` — because it has three axes (size, weight, colour) and
+// a heading has a tag to choose.
+//
+// A component draws its own inner parts rather than exposing them as separate
+// wrappers: `Menu` renders its rows from `items`, `Tabs` its tabs from `tabs`,
+// `List` its rows from `rows`. One stylesheet, one namespace, one component
+// (ADR 0009).
+export { default as Button } from './components/Button.svelte';
+// Form
+export { default as Input } from './components/Input.svelte';
+export { default as Textarea } from './components/Textarea.svelte';
+export { default as Select } from './components/Select.svelte';
+export { default as Combobox } from './components/Combobox.svelte';
+export { default as ChipsInput } from './components/ChipsInput.svelte';
+export { default as FileInput } from './components/FileInput.svelte';
+export { default as FileDropzone } from './components/FileDropzone.svelte';
+export { default as Calendar } from './components/Calendar.svelte';
+export { default as DatePicker } from './components/DatePicker.svelte';
+export { default as Checkbox } from './components/Checkbox.svelte';
+export { default as Radio } from './components/Radio.svelte';
+export { default as Toggle } from './components/Toggle.svelte';
+export { default as Range } from './components/Range.svelte';
+export { default as Fieldset } from './components/Fieldset.svelte';
+export { default as Label } from './components/Label.svelte';
+export { default as FloatingLabel } from './components/FloatingLabel.svelte';
+export { default as Switch } from './components/Switch.svelte';
+export { default as NumberInput } from './components/NumberInput.svelte';
+// Display
+export { default as Avatar } from './components/Avatar.svelte';
+export { default as Bubble } from './components/Bubble.svelte';
+export { default as Chip } from './components/Chip.svelte';
+export { default as Badge } from './components/Badge.svelte';
+export { default as Swatch } from './components/Swatch.svelte';
+export { default as ColorPicker } from './components/ColorPicker.svelte';
+export { default as Loading } from './components/Loading.svelte';
+export { default as Progress } from './components/Progress.svelte';
+export { default as RadialProgress } from './components/RadialProgress.svelte';
+export { default as Skeleton } from './components/Skeleton.svelte';
+export { default as List } from './components/List.svelte';
+export { default as Card } from './components/Card.svelte';
+export { default as Stat } from './components/Stat.svelte';
+export { default as Stats } from './components/Stats.svelte';
+export { default as Carousel } from './components/Carousel.svelte';
+export { default as Text } from './components/Text.svelte';
+export { default as Title } from './components/Title.svelte';
+export { default as Subtitle } from './components/Subtitle.svelte';
+export { default as Divider } from './components/Divider.svelte';
+export { default as Alert } from './components/Alert.svelte';
+export { default as Toast } from './components/Toast.svelte';
+export { default as Tooltip } from './components/Tooltip.svelte';
+export { default as Collapse } from './components/Collapse.svelte';
+export { default as Accordion } from './components/Accordion.svelte';
+export { default as Rating } from './components/Rating.svelte';
+export { default as Editable } from './components/Editable.svelte';
+export { default as EmptyState } from './components/EmptyState.svelte';
+export { default as Hero } from './components/Hero.svelte';
+export { default as Footer } from './components/Footer.svelte';
+export { default as MobileFrame } from './components/MobileFrame.svelte';
+export { default as WindowFrame } from './components/WindowFrame.svelte';
+export { default as LaptopFrame } from './components/LaptopFrame.svelte';
+export { default as Sidebar } from './components/Sidebar.svelte';
+export { default as Drawer } from './components/Drawer.svelte';
+// Navigation
+export { default as Menu } from './components/Menu.svelte';
+export { default as Navbar } from './components/Navbar.svelte';
+export { default as Breadcrumbs } from './components/Breadcrumbs.svelte';
+export { default as Pagination } from './components/Pagination.svelte';
+export { default as Steps } from './components/Steps.svelte';
+export { default as Dock } from './components/Dock.svelte';
+export { default as Tabs } from './components/Tabs.svelte';
+// Data
+export { default as DataHandler, DataHandlerState, parseQuery, parseFilterValues, filterValuesToParams } from './components/DataHandler.svelte';
+export { default as DataControl, LABELS as DATA_CONTROL_LABELS } from './components/DataControl.svelte';
+export { default as Table } from './components/Table.svelte';
+export { default as Grid } from './components/Grid.svelte';
+export { default as Kanban } from './components/Kanban.svelte';
+export { default as FileExplorer } from './components/FileExplorer.svelte';
+export { FILE_ICONS, extensionOf } from './components/file-icons.js';
+// Overlay
+export { default as Dialog } from './components/Dialog.svelte';
+export { default as Dropdown } from './components/Dropdown.svelte';
+// Other
+export { default as Join } from './components/Join.svelte';
+export {} from './variants.js';
+// Registry of style families + their themes, auto-generated from src/scss.
+export { families, themesByFamily } from './generated/registry.js';
+export { defaultTheme, familyCategory, cloneTheme, serializeTheme, tokensToInlineStyle, tokensForFamily, parseTheme } from './theme.js';

package/dist/sepale-types.d.ts

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+export type Decl = {
+    name: string;
+    prefix: string;
+    axes: Record<string, string[]>;
+    flags: string[];
+    parts: string[];
+};

package/dist/sepale-types.js

@@ -0,0 +1,200 @@
+#!/usr/bin/env node
+// @ts-nocheck — a Node command in a package whose types target the browser
+// (no @types/node here); its behaviour is checked against the build instead.
+/**
+ * sepale-types — write the types a family stylesheet carries (ADR 0015).
+ *
+ *   npx sepale-types orchid.css                    → orchid.css.d.ts beside it
+ *   npx sepale-types --components lib/components orchid.css
+ *
+ * For a stylesheet that never went through Sepale's build or app: one written
+ * by hand or by an assistant, or one you changed after downloading it. It does
+ * what they do — reads which axis value, flag or part each class is, from the
+ * components' own AXES / FLAGS / PARTS blocks — and writes the declaration
+ * with the same function (family-types). Never write that file by hand: it
+ * would say what you meant the stylesheet to draw, not what it draws.
+ *
+ * `--components` points at the components to read: by default the ones next
+ * to this script (the package's, or a bundle's `lib/components`). Point it at
+ * your own copies when you changed their AXES, so a variant you added is typed.
+ *
+ * Plain JavaScript, no dependency: it runs from node_modules and from a
+ * bundle's `lib/` alike. In a bundle, family-types is TypeScript, which Node
+ * runs as it is from 22.18 / 23.6.
+ */
+
+import { readFileSync, readdirSync, writeFileSync, existsSync } from 'node:fs';
+import { basename, dirname, join, resolve } from 'node:path';
+import { fileURLToPath, pathToFileURL } from 'node:url';
+
+const here = dirname(fileURLToPath(import.meta.url));
+
+/* Classes Sepale writes but does not own: never classified (scripts/prefix.mjs). */
+const EXTERNAL = new Set(['prose', 'filter']);
+const EXTERNAL_PREFIXES = ['air-datepicker'];
+const isExternal = (/** @type {string} */ cls) =>
+	EXTERNAL.has(cls) || EXTERNAL_PREFIXES.some((p) => cls.startsWith(p));
+
+/** The class suffix one axis value writes — the rules of variants.ts. */
+const axisSuffix = (/** @type {string} */ axis, /** @type {string} */ value) =>
+	value === 'none' ? `no${axis}` : /^\d+$/.test(value) ? `${axis}${value}` : value;
+
+/** Every class name in a stylesheet. */
+function classesIn(/** @type {string} */ css) {
+	const clean = css
+		.replace(/\/\*[\s\S]*?\*\//g, '')
+		.replace(/url\([^)]*\)/g, '')
+		.replace(/"[^"\n]*"|'[^'\n]*'/g, '');
+	return new Set([...clean.matchAll(/\.([a-z][a-z0-9]*(?:-[a-z0-9]+)*)/g)].map((m) => /** @type {string} */ (m[1])));
+}
+
+/**
+ * The literal after `export const NAME =` in a component: a string, an array
+ * or an object of strings. Parsed as data (quotes normalised to JSON), never
+ * evaluated.
+ * @param {string} src
+ * @param {string} name
+ * @returns {unknown}
+ */
+function readConst(src, name) {
+	const at = src.indexOf(`export const ${name} =`);
+	if (at < 0) return undefined;
+	const start = src.indexOf('=', at) + 1;
+	const from = start + src.slice(start).search(/[[{'"]/);
+	const open = src[from];
+	if (open === "'" || open === '"') return src.slice(from + 1, src.indexOf(open, from + 1));
+	const close = open === '[' ? ']' : '}';
+	let depth = 0;
+	for (let i = from; i < src.length; i++) {
+		if (src[i] === open) depth++;
+		else if (src[i] === close && --depth === 0) {
+			const json = src
+				.slice(from, i + 1)
+				.replace(/\/\*[\s\S]*?\*\//g, '')
+				.replace(/\/\/[^\n]*/g, '')
+				.replace(/'((?:[^'\\]|\\.)*)'/g, (_, s) => JSON.stringify(s.replace(/\\'/g, "'")))
+				.replace(/([{,]\s*)([A-Za-z_$][\w$-]*)\s*:/g, '$1"$2":')
+				.replace(/,(\s*[}\]])/g, '$1');
+			return JSON.parse(json);
+		}
+	}
+	return undefined;
+}
+
+/**
+ * @typedef {{ name: string, prefix: string, axes: Record<string, string[]>, flags: string[], parts: string[] }} Decl
+ */
+
+/** Every component with a namespace in `dir`, read from its module script. */
+function componentsIn(/** @type {string} */ dir) {
+	/** @type {Decl[]} */
+	const out = [];
+	for (const file of readdirSync(dir).filter((f) => f.endsWith('.svelte'))) {
+		const src = readFileSync(join(dir, file), 'utf8');
+		const prefix = readConst(src, 'PREFIX');
+		if (typeof prefix !== 'string') continue;
+		try {
+			const flags = /** @type {Record<string, string>} */ (readConst(src, 'FLAGS') ?? {});
+			out.push({
+				name: file.replace(/\.svelte$/, ''),
+				prefix,
+				axes: /** @type {Record<string, string[]>} */ (readConst(src, 'AXES') ?? {}),
+				flags: Object.keys(flags),
+				parts: /** @type {string[]} */ (readConst(src, 'PARTS') ?? [])
+			});
+		} catch (e) {
+			throw new Error(`${file}: its AXES / FLAGS / PARTS block is not plain data (${/** @type {Error} */ (e).message})`);
+		}
+	}
+	return out.sort((a, b) => b.prefix.length - a.prefix.length);
+}
+
+/**
+ * What each class of a stylesheet is, in the shape family-types reads.
+ * @param {string} css
+ * @param {Decl[]} decls longest prefix first
+ */
+function classify(css, decls) {
+	/** @type {Record<string, { kind: string, component?: string, axis?: string, value?: string }>} */
+	const classes = {};
+	/** @type {string[]} */
+	const unclassified = [];
+	for (const cls of [...classesIn(css)].sort()) {
+		if (isExternal(cls)) continue;
+		const owner = decls.find((c) => cls === c.prefix || cls.startsWith(`${c.prefix}-`));
+		if (!owner) continue;
+		if (cls === owner.prefix) {
+			classes[cls] = { kind: 'root', component: owner.name };
+			continue;
+		}
+		const suffix = cls.slice(owner.prefix.length + 1);
+		let info = null;
+		for (const [axis, values] of Object.entries(owner.axes)) {
+			const value = values.find((v) => axisSuffix(axis, v) === suffix);
+			if (value !== undefined) info = { kind: 'axis', component: owner.name, axis, value };
+		}
+		if (!info && owner.flags.includes(suffix)) info = { kind: 'flag', component: owner.name };
+		if (!info && owner.parts.includes(suffix)) info = { kind: 'part', component: owner.name };
+		if (!info) {
+			info = { kind: 'unclassified', component: owner.name };
+			unclassified.push(cls);
+		}
+		classes[cls] = info;
+	}
+	return { classes, unclassified };
+}
+
+/** family-types, as JavaScript (package) or TypeScript (bundle). */
+async function loadFamilyTypes() {
+	for (const file of ['family-types.js', 'family-types.ts']) {
+		const path = join(here, file);
+		if (existsSync(path)) return import(pathToFileURL(path).href);
+	}
+	throw new Error(`family-types not found next to ${here}`);
+}
+
+async function main(/** @type {string[]} */ argv) {
+	let componentsDir = join(here, 'components');
+	let help = false;
+	/** @type {string[]} */
+	const files = [];
+	for (let i = 0; i < argv.length; i++) {
+		const arg = /** @type {string} */ (argv[i]);
+		if (arg === '--components') componentsDir = resolve(/** @type {string} */ (argv[++i]));
+		else if (arg === '-h' || arg === '--help') help = true;
+		else files.push(arg);
+	}
+	if (help || !files.length) {
+		console.log('usage: sepale-types [--components <dir>] <family.css>…\n\nWrites <family>.css.d.ts beside each stylesheet: what it draws, as types.');
+		return help ? 0 : 1;
+	}
+	if (!existsSync(componentsDir)) throw new Error(`no components at ${componentsDir} (use --components <dir>)`);
+
+	const { familyShape, familyTypes } = await loadFamilyTypes();
+	const decls = componentsIn(componentsDir);
+	const schema = Object.fromEntries(decls.map((d) => [d.name, { prefix: d.prefix, flags: d.flags }]));
+
+	for (const file of files) {
+		const css = readFileSync(file, 'utf8');
+		const family = basename(file).replace(/\.css$/, '');
+		const { classes, unclassified } = classify(css, decls);
+		const out = `${file.replace(/\.css$/, '')}.css.d.ts`;
+		writeFileSync(out, familyTypes(family, familyShape(classes, schema, css)));
+		console.log(`sepale-types: ${family} -> ${out}`);
+		if (unclassified.length) {
+			console.warn(
+				`  ${unclassified.length} class(es) under a component's namespace that no AXES, FLAGS or PARTS block names — untyped:\n` +
+					unclassified.map((c) => `    .${c}`).join('\n')
+			);
+		}
+	}
+	return 0;
+}
+
+main(process.argv.slice(2)).then(
+	(code) => process.exit(code),
+	(e) => {
+		console.error(`sepale-types: ${e.message}`);
+		process.exit(1);
+	}
+);

package/dist/theme.d.ts

@@ -0,0 +1,123 @@
+/**
+ * Theme model.
+ *
+ * A *family* is a set of opinionated classes **with its own set of
+ * variables**. Sharing a variable name with another family is a convenience,
+ * never a rule. This module does not decide what a family exposes: it reads
+ * the declaration out of the registry and serialises the edited values back
+ * to a drop-in `:root { … }` stylesheet.
+ *
+ * Which inks are parameters is the family's call: daisy exposes every one
+ * (`--color-primary-content`, as daisyUI does), the others derive theirs in
+ * CSS (`--color-on-primary`, see each family's `_root.scss`). A colour token
+ * says which variable holds its ink through `on`; nothing here reads a name.
+ */
+/**
+ * `edge-width` and `shadows` are still ONE variable each — what changes is the
+ * control that edits it:
+ *
+ *   edge-width  a width and the edges it is drawn on, as the `border-width`
+ *               shorthand (`1px 0 1px 0`). The parts at `0` ARE the edges that
+ *               are off, so the value is its own record.
+ *   shadows     a whole `box-shadow` value, edited as a list of layers.
+ */
+export type TokenType = 'color' | 'length' | 'number' | 'text' | 'edge-width' | 'shadows';
+export interface ThemeToken {
+    /** CSS custom property name without the leading `--`. */
+    name: string;
+    label: string;
+    group: string;
+    type: TokenType;
+    value: string;
+    /** Short help text shown under the control, explaining what it tunes. */
+    description?: string;
+    /** Slider bounds for `number` and `length` tokens (rendered as range + number input). */
+    min?: number;
+    max?: number;
+    step?: number;
+    /** Unit of a `length` token, written back with the number (e.g. `rem`, `px`). */
+    unit?: string;
+    /** Units the editor offers for this token. A length with several units gets
+     *  a unit picker next to its number; the CSS never cares which one is used. */
+    units?: string[];
+    /** Colours only: `surface` (a ground), `accent` (a colour things are
+     *  painted with) or `ink` (text and lines drawn over both). */
+    kind?: string;
+    /** Colours only: the variable (without `--`) holding the ink written on
+     *  this colour — another token of the family, or a value it derives. */
+    on?: string;
+}
+/** Units offered for editable lengths. `%` is excluded on purpose: it is
+ *  meaningless on a border and unreadable on a slider. */
+export declare const LENGTH_UNITS: string[];
+/**
+ * Split a CSS length into its number and its unit (`"0.5rem"` → `[0.5, 'rem']`).
+ *
+ * A four-value shorthand — `1px 0 1px 0`, an edge set — reads back as its
+ * first non-zero part, which is exactly the number that was typed.
+ */
+export declare function splitLength(value: string, fallbackUnit?: string): [number, string];
+export interface Sides {
+    top: boolean;
+    right: boolean;
+    bottom: boolean;
+    left: boolean;
+}
+export interface EdgeWidth {
+    width: string;
+    sides: Sides;
+}
+export declare const SIDES: readonly ["top", "right", "bottom", "left"];
+/** A width and its edges as one shorthand. All four on → just the length. */
+export declare function edgeWidthToCss({ width, sides }: EdgeWidth): string;
+/** And back. A part at `0` is an edge that is off. */
+export declare function edgeWidthFromCss(raw: string, fallbackUnit?: string): EdgeWidth;
+export interface ShadowLayer {
+    x: string;
+    y: string;
+    blur: string;
+    spread: string;
+    color: string;
+    inset: boolean;
+}
+/** The layers as CSS. An empty list is `none`, not an empty string. */
+export declare function shadowsToCss(layers: ShadowLayer[]): string;
+/**
+ * And back. A layer is up to four lengths and a colour, in any order the
+ * spec allows; whatever is not a length is the colour.
+ */
+export declare function shadowsFromCss(raw: string): ShadowLayer[];
+/**
+ * Read a theme file — any stylesheet of `--name: value;` declarations — back
+ * into variables. A theme IS its variables, so this is all it takes; the
+ * family then keeps the ones it declares (see `tokensForFamily`).
+ */
+export declare function parseTheme(css: string): {
+    vars: Record<string, string>;
+    scheme?: string;
+};
+import type { FamilyParam } from './generated/registry.js';
+/** A neutral fallback for the rare caller with no family in hand. */
+export declare const defaultTheme: ThemeToken[];
+/** Human label of each family's design language, taken from its own header. */
+export declare const familyCategory: Record<string, string>;
+/** A custom property name (without `--`) safe to write. */
+export declare const isSafeName: (name: unknown) => name is string;
+/** A value safe to write after `--name:`: no way out of the declaration. */
+export declare function isSafeValue(value: unknown): value is string;
+/** A `color-scheme` keyword, or undefined. */
+export declare function safeScheme(scheme: unknown): string | undefined;
+/** Convert tokens into an inline `style` string for a preview element. */
+export declare function tokensToInlineStyle(tokens: ThemeToken[]): string;
+/** Serialise tokens into a drop-in `:root { … }` stylesheet. */
+export declare function serializeTheme(tokens: ThemeToken[], scheme?: string): string;
+/** Deep copy so callers can edit without mutating the schema. */
+export declare function cloneTheme(tokens?: ThemeToken[]): ThemeToken[];
+/**
+ * Editable tokens for a family: exactly the parameters that family declares,
+ * seeded from `vars` (a theme's parsed custom properties) where present and
+ * from the family's own default otherwise.
+ */
+export declare function tokensForFamily(family: string, vars?: Record<string, string>): ThemeToken[];
+/** The same, from a parameter list in hand — a family the build never saw. */
+export declare function tokensFrom(params: FamilyParam[], vars?: Record<string, string>): ThemeToken[];