@sharedex/ui 0.0.0-stage → 0.10.0

package/dist/schema/define.d.ts

@@ -0,0 +1,29 @@
+import type { FieldFor, Schema, SchemaEntry, SchemaFamily } from "./types.js";
+type Keys<O> = keyof O & string;
+/**
+ * Describe the options of one factory.
+ *
+ * ```ts
+ * export const WATER_RIPPLE_SCHEMA = defineSchema<WaterRippleOptions>()({
+ *   id: "water-ripple", family: "background", factory: "waterRipple",
+ *   fields: { ...layerFields(), strength: { kind: "number", label: "Strength", min: 0, max: 1, step: 0.05, default: 0.8 }, … },
+ * });
+ * ```
+ *
+ * The type is the guarantee behind "every option is configurable": `fields`
+ * must have exactly one entry for every key of `Options` (inherited ones
+ * too) that is not listed in `code`, and each entry must be a field kind that
+ * fits the option's type. An effect that gains an option without a field, or
+ * keeps a field for an option it lost, fails `tsc`.
+ */
+export declare function defineSchema<Options>(): <const Code extends readonly Keys<Options>[] = readonly []>(schema: {
+    readonly id: string;
+    readonly family: SchemaFamily;
+    readonly factory: string;
+    readonly entry?: SchemaEntry;
+    readonly fields: { readonly [K in Exclude<Keys<Options>, Code[number]>]-?: FieldFor<NonNullable<Options[K]>>; };
+    readonly code?: Code;
+    /** Positional arguments instead of one options object (`pagedBy(n, maxPages)`). */
+    readonly args?: readonly Keys<Options>[];
+}) => Schema;
+export {};

package/dist/schema/define.js

@@ -0,0 +1,27 @@
+/**
+ * Describe the options of one factory.
+ *
+ * ```ts
+ * export const WATER_RIPPLE_SCHEMA = defineSchema<WaterRippleOptions>()({
+ *   id: "water-ripple", family: "background", factory: "waterRipple",
+ *   fields: { ...layerFields(), strength: { kind: "number", label: "Strength", min: 0, max: 1, step: 0.05, default: 0.8 }, … },
+ * });
+ * ```
+ *
+ * The type is the guarantee behind "every option is configurable": `fields`
+ * must have exactly one entry for every key of `Options` (inherited ones
+ * too) that is not listed in `code`, and each entry must be a field kind that
+ * fits the option's type. An effect that gains an option without a field, or
+ * keeps a field for an option it lost, fails `tsc`.
+ */
+export function defineSchema() {
+    return (schema) => ({
+        id: schema.id,
+        family: schema.family,
+        factory: schema.factory,
+        entry: schema.entry ?? "@sharedex/ui",
+        ...(schema.args ? { args: schema.args } : {}),
+        fields: schema.fields,
+        code: schema.code ?? [],
+    });
+}

package/dist/schema/forms.d.ts

@@ -0,0 +1,3 @@
+import type { Schema } from "./types.js";
+/** Every form effect's schema, with its registry metadata, in registry order. Throws if one is missing (caught by the tests). */
+export declare const FORM_SCHEMAS: Readonly<Record<string, Schema>>;

package/dist/schema/forms.js

@@ -0,0 +1,194 @@
+// The form effects' option schemas, keyed by id, in the order of FORM_EFFECTS. Imports only the schema files and the
+// registry, which import only types: this entry carries no effect code. Each schema gets its registry metadata here.
+import { FORM_EFFECTS } from "../forms/registry.js";
+import { INPUT_FLOAT_SCHEMA } from "../forms/effects/input/inputFloat.schema.js";
+import { INPUT_UNDERLINE_SCHEMA } from "../forms/effects/input/inputUnderline.schema.js";
+import { INPUT_DRAW_SCHEMA } from "../forms/effects/input/inputDraw.schema.js";
+import { INPUT_RISE_SCHEMA } from "../forms/effects/input/inputRise.schema.js";
+import { INPUT_ASIDE_SCHEMA } from "../forms/effects/input/inputAside.schema.js";
+import { INPUT_WAVY_SCHEMA } from "../forms/effects/input/inputWavy.schema.js";
+import { INPUT_RING_SCHEMA } from "../forms/effects/input/inputRing.schema.js";
+import { INPUT_SPOTLIGHT_SCHEMA } from "../forms/effects/input/inputSpotlight.schema.js";
+import { INPUT_ICON_SCHEMA } from "../forms/effects/input/inputIcon.schema.js";
+import { INPUT_SEARCH_SCHEMA } from "../forms/effects/input/inputSearch.schema.js";
+import { INPUT_NOTCH_SCHEMA } from "../forms/effects/input/inputNotch.schema.js";
+import { INPUT_SWAP_SCHEMA } from "../forms/effects/input/inputSwap.schema.js";
+import { INPUT_FRAME_SCHEMA } from "../forms/effects/input/inputFrame.schema.js";
+import { INPUT_FLAP_SCHEMA } from "../forms/effects/input/inputFlap.schema.js";
+import { INPUT_FLOOD_SCHEMA } from "../forms/effects/input/inputFlood.schema.js";
+import { INPUT_WAVE_SCHEMA } from "../forms/effects/input/inputWave.schema.js";
+import { INPUT_BEAM_SCHEMA } from "../forms/effects/input/inputBeam.schema.js";
+import { INPUT_DEPTH_SCHEMA } from "../forms/effects/input/inputDepth.schema.js";
+import { INPUT_SKELETON_SCHEMA } from "../forms/effects/input/inputSkeleton.schema.js";
+import { INPUT_CARET_SCHEMA } from "../forms/effects/input/inputCaret.schema.js";
+import { INPUT_COUNTER_SCHEMA } from "../forms/effects/input/inputCounter.schema.js";
+import { INPUT_REVEAL_SCHEMA } from "../forms/effects/input/inputReveal.schema.js";
+import { INPUT_STRENGTH_SCHEMA } from "../forms/effects/input/inputStrength.schema.js";
+import { INPUT_CYCLE_SCHEMA } from "../forms/effects/input/inputCycle.schema.js";
+import { VALID_COLOR_SCHEMA } from "../forms/effects/valid/validColor.schema.js";
+import { VALID_SHAKE_SCHEMA } from "../forms/effects/valid/validShake.schema.js";
+import { VALID_MESSAGE_SCHEMA } from "../forms/effects/valid/validMessage.schema.js";
+import { VALID_CHECK_SCHEMA } from "../forms/effects/valid/validCheck.schema.js";
+import { VALID_SWAP_SCHEMA } from "../forms/effects/valid/validSwap.schema.js";
+import { VALID_BUBBLE_SCHEMA } from "../forms/effects/valid/validBubble.schema.js";
+import { VALID_FLASH_SCHEMA } from "../forms/effects/valid/validFlash.schema.js";
+import { VALID_ASYNC_SCHEMA } from "../forms/effects/valid/validAsync.schema.js";
+import { CHECK_DRAW_SCHEMA } from "../forms/effects/check/checkDraw.schema.js";
+import { CHECK_POP_SCHEMA } from "../forms/effects/check/checkPop.schema.js";
+import { CHECK_MORPH_SCHEMA } from "../forms/effects/check/checkMorph.schema.js";
+import { CHECK_JELLY_SCHEMA } from "../forms/effects/check/checkJelly.schema.js";
+import { CHECK_SCRIBBLE_SCHEMA } from "../forms/effects/check/checkScribble.schema.js";
+import { CHECK_STRIKE_SCHEMA } from "../forms/effects/check/checkStrike.schema.js";
+import { CHECK_MIXED_SCHEMA } from "../forms/effects/check/checkMixed.schema.js";
+import { CHECK_CARD_SCHEMA } from "../forms/effects/check/checkCard.schema.js";
+import { CHECK_CONFETTI_SCHEMA } from "../forms/effects/check/checkConfetti.schema.js";
+import { CHECK_RIPPLE_SCHEMA } from "../forms/effects/check/checkRipple.schema.js";
+import { CHECK_HEART_SCHEMA } from "../forms/effects/check/checkHeart.schema.js";
+import { CHECK_MERGE_SCHEMA } from "../forms/effects/check/checkMerge.schema.js";
+import { RADIO_DOT_SCHEMA } from "../forms/effects/radio/radioDot.schema.js";
+import { RADIO_PULSE_SCHEMA } from "../forms/effects/radio/radioPulse.schema.js";
+import { RADIO_CIRCLE_SCHEMA } from "../forms/effects/radio/radioCircle.schema.js";
+import { RADIO_SEGMENT_SCHEMA } from "../forms/effects/radio/radioSegment.schema.js";
+import { RADIO_CARD_SCHEMA } from "../forms/effects/radio/radioCard.schema.js";
+import { RADIO_STARS_SCHEMA } from "../forms/effects/radio/radioStars.schema.js";
+import { RADIO_EMOJI_SCHEMA } from "../forms/effects/radio/radioEmoji.schema.js";
+import { RADIO_TRAVEL_SCHEMA } from "../forms/effects/radio/radioTravel.schema.js";
+import { RADIO_UNDERLINE_SCHEMA } from "../forms/effects/radio/radioUnderline.schema.js";
+import { RADIO_SCALE_SCHEMA } from "../forms/effects/radio/radioScale.schema.js";
+import { SWITCH_SLIDE_SCHEMA } from "../forms/effects/switch/switchSlide.schema.js";
+import { SWITCH_STRETCH_SCHEMA } from "../forms/effects/switch/switchStretch.schema.js";
+import { SWITCH_DAY_NIGHT_SCHEMA } from "../forms/effects/switch/switchDayNight.schema.js";
+import { SWITCH_BULB_SCHEMA } from "../forms/effects/switch/switchBulb.schema.js";
+import { SWITCH_NEON_SCHEMA } from "../forms/effects/switch/switchNeon.schema.js";
+import { SWITCH_FLIP_SCHEMA } from "../forms/effects/switch/switchFlip.schema.js";
+import { SWITCH_MORPH_SCHEMA } from "../forms/effects/switch/switchMorph.schema.js";
+import { SWITCH_GOO_SCHEMA } from "../forms/effects/switch/switchGoo.schema.js";
+import { SWITCH_FACE_SCHEMA } from "../forms/effects/switch/switchFace.schema.js";
+import { SWITCH_ICON_SCHEMA } from "../forms/effects/switch/switchIcon.schema.js";
+import { SWITCH_LABELS_SCHEMA } from "../forms/effects/switch/switchLabels.schema.js";
+import { PICKER_ARROW_SCHEMA } from "../forms/effects/picker/pickerArrow.schema.js";
+import { PICKER_OPEN_SCHEMA } from "../forms/effects/picker/pickerOpen.schema.js";
+import { PICKER_STAGGER_SCHEMA } from "../forms/effects/picker/pickerStagger.schema.js";
+import { LIST_HIGHLIGHT_SCHEMA } from "../forms/effects/picker/listHighlight.schema.js";
+import { CHIP_POP_SCHEMA } from "../forms/effects/picker/chipPop.schema.js";
+import { PICKER_CHECK_SCHEMA } from "../forms/effects/picker/pickerCheck.schema.js";
+import { PICKER_SHEET_SCHEMA } from "../forms/effects/picker/pickerSheet.schema.js";
+import { LIST_MATCH_SCHEMA } from "../forms/effects/picker/listMatch.schema.js";
+import { RANGE_THUMB_SCHEMA } from "../forms/effects/range/rangeThumb.schema.js";
+import { RANGE_FILL_SCHEMA } from "../forms/effects/range/rangeFill.schema.js";
+import { RANGE_BUBBLE_SCHEMA } from "../forms/effects/range/rangeBubble.schema.js";
+import { RANGE_ELASTIC_SCHEMA } from "../forms/effects/range/rangeElastic.schema.js";
+import { RANGE_TICKS_SCHEMA } from "../forms/effects/range/rangeTicks.schema.js";
+import { RANGE_FACE_SCHEMA } from "../forms/effects/range/rangeFace.schema.js";
+import { RANGE_HISTOGRAM_SCHEMA } from "../forms/effects/range/rangeHistogram.schema.js";
+import { CHIP_CHECK_SCHEMA } from "../forms/effects/chip/chipCheck.schema.js";
+import { CHIP_MERGE_SCHEMA } from "../forms/effects/chip/chipMerge.schema.js";
+import { FILE_DRAG_SCHEMA } from "../forms/effects/file/fileDrag.schema.js";
+import { FILE_BUTTON_SCHEMA } from "../forms/effects/file/fileButton.schema.js";
+import { FILE_CARDS_SCHEMA } from "../forms/effects/file/fileCards.schema.js";
+import { FILE_PROGRESS_SCHEMA } from "../forms/effects/file/fileProgress.schema.js";
+import { FILE_PREVIEW_SCHEMA } from "../forms/effects/file/filePreview.schema.js";
+import { FILE_PAGE_SCHEMA } from "../forms/effects/file/filePage.schema.js";
+import { FILE_REJECT_SCHEMA } from "../forms/effects/file/fileReject.schema.js";
+import { STEP_SLIDE_SCHEMA } from "../forms/effects/step/stepSlide.schema.js";
+import { STEP_PROGRESS_SCHEMA } from "../forms/effects/step/stepProgress.schema.js";
+const BY_ID = {
+    inputFloat: INPUT_FLOAT_SCHEMA,
+    inputUnderline: INPUT_UNDERLINE_SCHEMA,
+    inputDraw: INPUT_DRAW_SCHEMA,
+    inputRise: INPUT_RISE_SCHEMA,
+    inputAside: INPUT_ASIDE_SCHEMA,
+    inputWavy: INPUT_WAVY_SCHEMA,
+    inputRing: INPUT_RING_SCHEMA,
+    inputSpotlight: INPUT_SPOTLIGHT_SCHEMA,
+    inputIcon: INPUT_ICON_SCHEMA,
+    inputSearch: INPUT_SEARCH_SCHEMA,
+    inputNotch: INPUT_NOTCH_SCHEMA,
+    inputSwap: INPUT_SWAP_SCHEMA,
+    inputFrame: INPUT_FRAME_SCHEMA,
+    inputFlap: INPUT_FLAP_SCHEMA,
+    inputFlood: INPUT_FLOOD_SCHEMA,
+    inputWave: INPUT_WAVE_SCHEMA,
+    inputBeam: INPUT_BEAM_SCHEMA,
+    inputDepth: INPUT_DEPTH_SCHEMA,
+    inputSkeleton: INPUT_SKELETON_SCHEMA,
+    inputCaret: INPUT_CARET_SCHEMA,
+    inputCounter: INPUT_COUNTER_SCHEMA,
+    inputReveal: INPUT_REVEAL_SCHEMA,
+    inputStrength: INPUT_STRENGTH_SCHEMA,
+    inputCycle: INPUT_CYCLE_SCHEMA,
+    validColor: VALID_COLOR_SCHEMA,
+    validShake: VALID_SHAKE_SCHEMA,
+    validMessage: VALID_MESSAGE_SCHEMA,
+    validCheck: VALID_CHECK_SCHEMA,
+    validSwap: VALID_SWAP_SCHEMA,
+    validBubble: VALID_BUBBLE_SCHEMA,
+    validFlash: VALID_FLASH_SCHEMA,
+    validAsync: VALID_ASYNC_SCHEMA,
+    checkDraw: CHECK_DRAW_SCHEMA,
+    checkPop: CHECK_POP_SCHEMA,
+    checkMorph: CHECK_MORPH_SCHEMA,
+    checkJelly: CHECK_JELLY_SCHEMA,
+    checkScribble: CHECK_SCRIBBLE_SCHEMA,
+    checkStrike: CHECK_STRIKE_SCHEMA,
+    checkMixed: CHECK_MIXED_SCHEMA,
+    checkCard: CHECK_CARD_SCHEMA,
+    checkConfetti: CHECK_CONFETTI_SCHEMA,
+    checkRipple: CHECK_RIPPLE_SCHEMA,
+    checkHeart: CHECK_HEART_SCHEMA,
+    checkMerge: CHECK_MERGE_SCHEMA,
+    radioDot: RADIO_DOT_SCHEMA,
+    radioPulse: RADIO_PULSE_SCHEMA,
+    radioCircle: RADIO_CIRCLE_SCHEMA,
+    radioSegment: RADIO_SEGMENT_SCHEMA,
+    radioCard: RADIO_CARD_SCHEMA,
+    radioStars: RADIO_STARS_SCHEMA,
+    radioEmoji: RADIO_EMOJI_SCHEMA,
+    radioTravel: RADIO_TRAVEL_SCHEMA,
+    radioUnderline: RADIO_UNDERLINE_SCHEMA,
+    radioScale: RADIO_SCALE_SCHEMA,
+    switchSlide: SWITCH_SLIDE_SCHEMA,
+    switchStretch: SWITCH_STRETCH_SCHEMA,
+    switchDayNight: SWITCH_DAY_NIGHT_SCHEMA,
+    switchBulb: SWITCH_BULB_SCHEMA,
+    switchNeon: SWITCH_NEON_SCHEMA,
+    switchFlip: SWITCH_FLIP_SCHEMA,
+    switchMorph: SWITCH_MORPH_SCHEMA,
+    switchGoo: SWITCH_GOO_SCHEMA,
+    switchFace: SWITCH_FACE_SCHEMA,
+    switchIcon: SWITCH_ICON_SCHEMA,
+    switchLabels: SWITCH_LABELS_SCHEMA,
+    pickerArrow: PICKER_ARROW_SCHEMA,
+    pickerOpen: PICKER_OPEN_SCHEMA,
+    pickerStagger: PICKER_STAGGER_SCHEMA,
+    listHighlight: LIST_HIGHLIGHT_SCHEMA,
+    chipPop: CHIP_POP_SCHEMA,
+    pickerCheck: PICKER_CHECK_SCHEMA,
+    pickerSheet: PICKER_SHEET_SCHEMA,
+    listMatch: LIST_MATCH_SCHEMA,
+    rangeThumb: RANGE_THUMB_SCHEMA,
+    rangeFill: RANGE_FILL_SCHEMA,
+    rangeBubble: RANGE_BUBBLE_SCHEMA,
+    rangeElastic: RANGE_ELASTIC_SCHEMA,
+    rangeTicks: RANGE_TICKS_SCHEMA,
+    rangeFace: RANGE_FACE_SCHEMA,
+    rangeHistogram: RANGE_HISTOGRAM_SCHEMA,
+    chipCheck: CHIP_CHECK_SCHEMA,
+    chipMerge: CHIP_MERGE_SCHEMA,
+    fileDrag: FILE_DRAG_SCHEMA,
+    fileButton: FILE_BUTTON_SCHEMA,
+    fileCards: FILE_CARDS_SCHEMA,
+    fileProgress: FILE_PROGRESS_SCHEMA,
+    filePreview: FILE_PREVIEW_SCHEMA,
+    filePage: FILE_PAGE_SCHEMA,
+    fileReject: FILE_REJECT_SCHEMA,
+    stepSlide: STEP_SLIDE_SCHEMA,
+    stepProgress: STEP_PROGRESS_SCHEMA,
+};
+/** Every form effect's schema, with its registry metadata, in registry order. Throws if one is missing (caught by the tests). */
+export const FORM_SCHEMAS = Object.fromEntries(FORM_EFFECTS.map((m) => {
+    const schema = BY_ID[m.id];
+    if (!schema)
+        throw new Error(`[@sharedex/ui] no schema for form effect "${m.id}"`);
+    return [m.id, { ...schema, meta: { label: m.label, category: m.group, family: m.tech, tier: m.tier, modes: m.fits } }];
+}));

package/dist/schema/grid.d.ts

@@ -0,0 +1,5 @@
+import type { Schema } from "./types.js";
+export declare const GRID_SCHEMAS: Readonly<Record<string, Schema>>;
+/** Open views (`gridOpen.*`). */
+export declare const GRID_OPEN_SCHEMAS: Readonly<Record<string, Schema>>;
+export type { GridSettings } from "../grid/Grid.schema.js";

package/dist/schema/grid.js

@@ -0,0 +1,12 @@
+// The Grid's option schemas: `Grid.Root`'s props as one form (`GridSettings`) and its open views. The Grid has no
+// metadata registry, so labels are set here. Imports only schema files.
+import { GRID_SCHEMA } from "../grid/Grid.schema.js";
+import { GRID_OPEN_PANEL_SCHEMA, GRID_OPEN_STRIP_SCHEMA, GRID_OPEN_ZOOM_SCHEMA } from "../grid/open.schema.js";
+const keyed = (list) => Object.fromEntries(list.map(([schema, meta]) => [schema.id, { ...schema, meta }]));
+export const GRID_SCHEMAS = keyed([[GRID_SCHEMA, { label: "Grid" }]]);
+/** Open views (`gridOpen.*`). */
+export const GRID_OPEN_SCHEMAS = keyed([
+    [GRID_OPEN_ZOOM_SCHEMA, { label: "Grow where it is" }],
+    [GRID_OPEN_STRIP_SCHEMA, { label: "Big card over a thumbnail strip" }],
+    [GRID_OPEN_PANEL_SCHEMA, { label: "Big card beside a panel" }],
+]);

package/dist/schema/helpers.d.ts

@@ -0,0 +1,34 @@
+import type { Schema, SchemaFamily } from "./types.js";
+/** Every option's default (auto options are left out, as a factory call would). */
+export declare function defaultsOf(schema: Pick<Schema, "fields">): Record<string, unknown>;
+/** Where the factory sits in its entry: `["waterRipple"]`, or `["presence", "contract"]` (imported as `presence`). */
+export declare function factoryPath(schema: Pick<Schema, "factory">): readonly string[];
+/**
+ * What a call to the factory passes: the options object, or with `args` the
+ * options in that order (`pagedBy(3)`), trailing unset ones left off.
+ */
+export declare function factoryArgs(schema: Pick<Schema, "args">, options: Readonly<Record<string, unknown>>): unknown[];
+/** Deep equality for option values (numbers, strings, booleans, arrays, plain objects). */
+export declare function sameValue(a: unknown, b: unknown): boolean;
+/**
+ * Only what differs from the defaults: `undefined` and values equal to a
+ * field's `default` are dropped (an auto option keeps any value it is given),
+ * in the schema's field order. What a config stores and a generator writes.
+ */
+export declare function sparseOptions(schema: Pick<Schema, "fields">, value: Readonly<Record<string, unknown>>): Record<string, unknown>;
+/** A CSS colour as a config may hold one: a theme token, `color-mix()`, a hex or functional colour, a keyword. */
+export declare function isColor(value: unknown): value is string;
+/** Looks up another piece's schema (for `effect` fields). */
+export type SchemaLookup = (family: SchemaFamily, id: string) => Schema | undefined;
+/**
+ * The required options still missing (an image without its `src`). Kept apart
+ * from `validateOptions`: a design may hold a half-configured piece while it
+ * is being edited; a builder warns, an export writes a placeholder.
+ */
+export declare function missingRequired(schema: Pick<Schema, "fields">, value: Readonly<Record<string, unknown>>): string[];
+/**
+ * Readable problems with a set of options, empty when they are fine: unknown
+ * keys (including the code-only ones, which a config can't hold), wrong
+ * types, values out of range or not among the choices, malformed colours.
+ */
+export declare function validateOptions(schema: Pick<Schema, "fields">, value: Readonly<Record<string, unknown>>, lookup?: SchemaLookup): string[];

package/dist/schema/helpers.js

@@ -0,0 +1,183 @@
+/** Every option's default (auto options are left out, as a factory call would). */
+export function defaultsOf(schema) {
+    const out = {};
+    for (const [key, field] of Object.entries(schema.fields)) {
+        if (field.default !== undefined)
+            out[key] = field.default;
+    }
+    return out;
+}
+/** Where the factory sits in its entry: `["waterRipple"]`, or `["presence", "contract"]` (imported as `presence`). */
+export function factoryPath(schema) {
+    return schema.factory.split(".");
+}
+/**
+ * What a call to the factory passes: the options object, or with `args` the
+ * options in that order (`pagedBy(3)`), trailing unset ones left off.
+ */
+export function factoryArgs(schema, options) {
+    if (!schema.args)
+        return [options];
+    const out = schema.args.map((key) => options[key]);
+    while (out.length > 0 && out[out.length - 1] === undefined)
+        out.pop();
+    return out;
+}
+/** Deep equality for option values (numbers, strings, booleans, arrays, plain objects). */
+export function sameValue(a, b) {
+    if (Object.is(a, b))
+        return true;
+    if (Array.isArray(a) && Array.isArray(b))
+        return a.length === b.length && a.every((v, i) => sameValue(v, b[i]));
+    if (a && b && typeof a === "object" && typeof b === "object" && !Array.isArray(a) && !Array.isArray(b)) {
+        const ka = Object.keys(a).filter((k) => a[k] !== undefined);
+        const kb = Object.keys(b).filter((k) => b[k] !== undefined);
+        return ka.length === kb.length && ka.every((k) => sameValue(a[k], b[k]));
+    }
+    return false;
+}
+/**
+ * Only what differs from the defaults: `undefined` and values equal to a
+ * field's `default` are dropped (an auto option keeps any value it is given),
+ * in the schema's field order. What a config stores and a generator writes.
+ */
+export function sparseOptions(schema, value) {
+    const out = {};
+    for (const [key, field] of Object.entries(schema.fields)) {
+        const v = value[key];
+        if (v === undefined)
+            continue;
+        if (field.default !== undefined && sameValue(v, field.default))
+            continue;
+        out[key] = v;
+    }
+    return out;
+}
+const COLOR = /^(#[0-9a-f]{3,4}|#[0-9a-f]{6}|#[0-9a-f]{8}|transparent|currentcolor|[a-z]+|(rgba?|hsla?|hwb|lab|lch|oklab|oklch|color|color-mix|var|light-dark)\(.+\))$/i;
+/** A CSS colour as a config may hold one: a theme token, `color-mix()`, a hex or functional colour, a keyword. */
+export function isColor(value) {
+    return typeof value === "string" && COLOR.test(value.trim());
+}
+const isNumber = (v) => typeof v === "number" && Number.isFinite(v);
+const PERCENT = /^-?\d+(\.\d+)?%$/;
+function fieldErrors(path, field, v, lookup) {
+    const bad = (what) => [`${path}: ${what}`];
+    switch (field.kind) {
+        case "number":
+            if (!isNumber(v))
+                return bad("must be a number");
+            if (v < field.min || v > field.max)
+                return bad(`must be between ${field.min} and ${field.max}`);
+            return [];
+        case "integer":
+        case "seed":
+            if (!isNumber(v) || !Number.isInteger(v))
+                return bad("must be a whole number");
+            if (field.kind === "integer" && (v < field.min || v > field.max))
+                return bad(`must be between ${field.min} and ${field.max}`);
+            return [];
+        case "boolean":
+            return typeof v === "boolean" ? [] : bad("must be true or false");
+        case "choice":
+            return (typeof v === "string" || typeof v === "number") && field.values.includes(v) ? [] : bad(`must be one of ${field.values.join(", ")}`);
+        case "color":
+            return isColor(v) ? [] : bad("must be a CSS colour");
+        case "colors":
+            if (!Array.isArray(v))
+                return bad("must be a list of colours");
+            if (v.length < field.min || v.length > field.max)
+                return bad(`must have ${field.min} to ${field.max} colours`);
+            return v.every(isColor) ? [] : bad("every entry must be a CSS colour");
+        case "range":
+            if (!Array.isArray(v) || v.length !== 2 || !v.every(isNumber))
+                return bad("must be two numbers");
+            const [lo, hi] = v;
+            if (lo > hi)
+                return bad("the first number must not be above the second");
+            if (lo < field.min || hi > field.max)
+                return bad(`must stay between ${field.min} and ${field.max}`);
+            return [];
+        case "text":
+            if (typeof v !== "string")
+                return bad("must be text");
+            if (field.url && v.trim() === "")
+                return bad("must not be empty");
+            return [];
+        case "texts":
+            if (!Array.isArray(v) || !v.every((x) => typeof x === "string"))
+                return bad("must be a list of texts");
+            if (v.length < field.min || v.length > field.max)
+                return bad(`must have ${field.min} to ${field.max} entries`);
+            return [];
+        case "point":
+            if (typeof v === "string")
+                return field.keywords.includes(v) ? [] : bad(`must be one of ${field.keywords.join(", ")}, or [x, y]`);
+            if (!Array.isArray(v) || v.length !== 2 || !v.every(isNumber))
+                return bad(`must be one of ${field.keywords.join(", ")}, or [x, y]`);
+            return v.every((n) => n >= 0 && n <= 1) ? [] : bad("x and y must be between 0 and 1");
+        case "vector": {
+            if (!Array.isArray(v) || v.length !== field.labels.length)
+                return bad(`must be ${field.labels.length} numbers`);
+            for (const n of v) {
+                const num = field.percent && typeof n === "string" && PERCENT.test(n) ? Number.parseFloat(n) : n;
+                if (!isNumber(num))
+                    return bad(field.percent ? "every entry must be a number or a percentage" : "every entry must be a number");
+                if (num < field.min || num > field.max)
+                    return bad(`every entry must be between ${field.min} and ${field.max}`);
+            }
+            return [];
+        }
+        case "group": {
+            if (v === false && field.off)
+                return [];
+            if (!v || typeof v !== "object" || Array.isArray(v))
+                return bad(field.off ? "must be an object, or false" : "must be an object");
+            return objectErrors(path, field.fields, v, lookup);
+        }
+        case "effect": {
+            const e = v;
+            if (!e || typeof e !== "object" || typeof e.id !== "string")
+                return bad("must be { id, options }");
+            const schema = lookup?.(field.family, e.id);
+            if (lookup && !schema)
+                return bad(`"${e.id}" is not a ${field.family}`);
+            if (!schema)
+                return [];
+            if (field.mode && schema.meta?.modes && !schema.meta.modes.includes(field.mode))
+                return bad(`"${e.id}" can't play as a ${field.mode}`);
+            if (field.kinds && !field.kinds.includes(schema.meta?.family ?? ""))
+                return bad(`"${e.id}" must be ${field.kinds.join(" or ")}`);
+            return objectErrors(`${path}.options`, schema.fields, (e.options ?? {}), lookup);
+        }
+    }
+}
+function objectErrors(path, fields, value, lookup) {
+    const errors = [];
+    for (const [key, v] of Object.entries(value)) {
+        const field = fields[key];
+        const at = path ? `${path}.${key}` : key;
+        if (!field)
+            errors.push(`${at}: not an option`);
+        else if (v !== undefined)
+            errors.push(...fieldErrors(at, field, v, lookup));
+    }
+    return errors;
+}
+/**
+ * The required options still missing (an image without its `src`). Kept apart
+ * from `validateOptions`: a design may hold a half-configured piece while it
+ * is being edited; a builder warns, an export writes a placeholder.
+ */
+export function missingRequired(schema, value) {
+    return Object.entries(schema.fields)
+        .filter(([key, field]) => field.required && (value[key] === undefined || value[key] === ""))
+        .map(([key]) => key);
+}
+/**
+ * Readable problems with a set of options, empty when they are fine: unknown
+ * keys (including the code-only ones, which a config can't hold), wrong
+ * types, values out of range or not among the choices, malformed colours.
+ */
+export function validateOptions(schema, value, lookup) {
+    return objectErrors("", schema.fields, value, lookup);
+}

package/dist/schema/index.d.ts

@@ -0,0 +1,42 @@
+import { BACKGROUND_SCHEMAS } from "./backgrounds.js";
+import { REVEAL_SCHEMAS, TRANSITION_SCHEMAS } from "./transitions.js";
+import { CAROUSEL_LAYOUT_SCHEMAS, CAROUSEL_MODIFIER_SCHEMAS, CAROUSEL_OPEN_SCHEMAS, CAROUSEL_PHYSICS_SCHEMAS, CAROUSEL_PRESENCE_SCHEMAS, CAROUSEL_SCHEMAS } from "./carousel.js";
+import { TICKER_SCHEMAS } from "./ticker.js";
+import { GRID_OPEN_SCHEMAS, GRID_SCHEMAS } from "./grid.js";
+import { SCROLL_SCHEMAS } from "./scroll.js";
+import { BUTTON_SCHEMAS } from "./buttons.js";
+import { TEXT_SCHEMAS } from "./text.js";
+import { FORM_SCHEMAS } from "./forms.js";
+import { NUMBER_ROLL_SCHEMAS, TYPEWRITER_SCHEMAS, WORD_CYCLE_SCHEMAS } from "./textParts.js";
+import type { Schema, SchemaFamily } from "./types.js";
+export type { Field, FieldKind, FieldFor, NumberField, IntegerField, SeedField, BooleanField, ChoiceField, ColorField, ColorsField, TextsField, RangeField, TextField, PointField, VectorField, EffectField, GroupField, EffectValue, Schema, SchemaEntry, SchemaFamily, SchemaMeta, } from "./types.js";
+export { SCHEMA_FAMILIES } from "./types.js";
+export { defineSchema } from "./define.js";
+export { layerFields, speedField, seedField, colorsField, shaderFallbackField, buttonFillFields } from "./common.js";
+export { defaultsOf, sparseOptions, validateOptions, missingRequired, sameValue, isColor, factoryPath, factoryArgs } from "./helpers.js";
+export type { SchemaLookup } from "./helpers.js";
+export { BACKGROUND_SCHEMAS, TRANSITION_SCHEMAS, REVEAL_SCHEMAS };
+export { CAROUSEL_LAYOUT_SCHEMAS, CAROUSEL_MODIFIER_SCHEMAS, CAROUSEL_PRESENCE_SCHEMAS, CAROUSEL_OPEN_SCHEMAS, CAROUSEL_PHYSICS_SCHEMAS, CAROUSEL_SCHEMAS, };
+export { CAROUSEL_SECTIONS } from "./carousel.js";
+export type { CarouselSection, CarouselSettings } from "./carousel.js";
+export { TICKER_SCHEMAS, GRID_SCHEMAS, GRID_OPEN_SCHEMAS, SCROLL_SCHEMAS, BUTTON_SCHEMAS, TEXT_SCHEMAS, WORD_CYCLE_SCHEMAS, NUMBER_ROLL_SCHEMAS, TYPEWRITER_SCHEMAS, FORM_SCHEMAS };
+export type { TickerDrive, TickerSettings } from "./ticker.js";
+export type { GridSettings } from "./grid.js";
+/** The carousel's own settings (`<Carousel.Root config>` as one flat form). */
+export declare const CAROUSEL_SETTINGS: Schema;
+/** A Ticker's props as one form (`fade` in px, `drive` in place of `offset`). */
+export declare const TICKER_SETTINGS: Schema;
+/** `Grid.Root`'s props as one form (`columns` unset = `"auto"`). */
+export declare const GRID_SETTINGS: Schema;
+/** `WordCycle`'s props as one form (the Hero's `titleCycle`; the words are content). */
+export declare const WORD_CYCLE_SETTINGS: Schema;
+/** `Typewriter`'s props as one form (the lines come from the page). */
+export declare const TYPEWRITER_SETTINGS: Schema;
+/** `NumberRoll`'s props as one form (About's `statRoll`; the value comes from each figure). */
+export declare const NUMBER_ROLL_SETTINGS: Schema;
+/** Every family's schemas, keyed by piece id. Families without schemas yet are empty. */
+export declare const SCHEMAS: {
+    readonly [F in SchemaFamily]: Readonly<Record<string, Schema>>;
+};
+/** One piece's schema, or `undefined`. */
+export declare function schemaOf(family: SchemaFamily, id: string): Schema | undefined;

package/dist/schema/index.js

@@ -0,0 +1,63 @@
+// ---------------------------------------------------------------------------
+// @sharedex/ui/schema — every configurable piece's options, as data.
+//
+// For tools (the Design System Builder): a form renders a schema, a config
+// stores only what differs from the defaults (`sparseOptions`), and a
+// generator writes `factory(options)` back. No React, no DOM, no effect code.
+// ---------------------------------------------------------------------------
+import { BACKGROUND_SCHEMAS } from "./backgrounds.js";
+import { REVEAL_SCHEMAS, TRANSITION_SCHEMAS } from "./transitions.js";
+import { CAROUSEL_LAYOUT_SCHEMAS, CAROUSEL_MODIFIER_SCHEMAS, CAROUSEL_OPEN_SCHEMAS, CAROUSEL_PHYSICS_SCHEMAS, CAROUSEL_PRESENCE_SCHEMAS, CAROUSEL_SCHEMAS, } from "./carousel.js";
+import { TICKER_SCHEMAS } from "./ticker.js";
+import { GRID_OPEN_SCHEMAS, GRID_SCHEMAS } from "./grid.js";
+import { SCROLL_SCHEMAS } from "./scroll.js";
+import { BUTTON_SCHEMAS } from "./buttons.js";
+import { TEXT_SCHEMAS } from "./text.js";
+import { FORM_SCHEMAS } from "./forms.js";
+import { NUMBER_ROLL_SCHEMAS, TYPEWRITER_SCHEMAS, WORD_CYCLE_SCHEMAS } from "./textParts.js";
+export { SCHEMA_FAMILIES } from "./types.js";
+export { defineSchema } from "./define.js";
+export { layerFields, speedField, seedField, colorsField, shaderFallbackField, buttonFillFields } from "./common.js";
+export { defaultsOf, sparseOptions, validateOptions, missingRequired, sameValue, isColor, factoryPath, factoryArgs } from "./helpers.js";
+export { BACKGROUND_SCHEMAS, TRANSITION_SCHEMAS, REVEAL_SCHEMAS };
+export { CAROUSEL_LAYOUT_SCHEMAS, CAROUSEL_MODIFIER_SCHEMAS, CAROUSEL_PRESENCE_SCHEMAS, CAROUSEL_OPEN_SCHEMAS, CAROUSEL_PHYSICS_SCHEMAS, CAROUSEL_SCHEMAS, };
+export { CAROUSEL_SECTIONS } from "./carousel.js";
+export { TICKER_SCHEMAS, GRID_SCHEMAS, GRID_OPEN_SCHEMAS, SCROLL_SCHEMAS, BUTTON_SCHEMAS, TEXT_SCHEMAS, WORD_CYCLE_SCHEMAS, NUMBER_ROLL_SCHEMAS, TYPEWRITER_SCHEMAS, FORM_SCHEMAS };
+/** The carousel's own settings (`<Carousel.Root config>` as one flat form). */
+export const CAROUSEL_SETTINGS = CAROUSEL_SCHEMAS["carousel"];
+/** A Ticker's props as one form (`fade` in px, `drive` in place of `offset`). */
+export const TICKER_SETTINGS = TICKER_SCHEMAS["ticker"];
+/** `Grid.Root`'s props as one form (`columns` unset = `"auto"`). */
+export const GRID_SETTINGS = GRID_SCHEMAS["grid"];
+/** `WordCycle`'s props as one form (the Hero's `titleCycle`; the words are content). */
+export const WORD_CYCLE_SETTINGS = WORD_CYCLE_SCHEMAS["wordCycle"];
+/** `Typewriter`'s props as one form (the lines come from the page). */
+export const TYPEWRITER_SETTINGS = TYPEWRITER_SCHEMAS["typewriter"];
+/** `NumberRoll`'s props as one form (About's `statRoll`; the value comes from each figure). */
+export const NUMBER_ROLL_SETTINGS = NUMBER_ROLL_SCHEMAS["numberRoll"];
+/** Every family's schemas, keyed by piece id. Families without schemas yet are empty. */
+export const SCHEMAS = {
+    background: BACKGROUND_SCHEMAS,
+    transition: TRANSITION_SCHEMAS,
+    reveal: REVEAL_SCHEMAS,
+    "carousel-layout": CAROUSEL_LAYOUT_SCHEMAS,
+    "carousel-modifier": CAROUSEL_MODIFIER_SCHEMAS,
+    "carousel-presence": CAROUSEL_PRESENCE_SCHEMAS,
+    "carousel-open": CAROUSEL_OPEN_SCHEMAS,
+    "carousel-physics": CAROUSEL_PHYSICS_SCHEMAS,
+    carousel: CAROUSEL_SCHEMAS,
+    ticker: TICKER_SCHEMAS,
+    grid: GRID_SCHEMAS,
+    "grid-open": GRID_OPEN_SCHEMAS,
+    scroll: SCROLL_SCHEMAS,
+    button: BUTTON_SCHEMAS,
+    text: TEXT_SCHEMAS,
+    "word-cycle": WORD_CYCLE_SCHEMAS,
+    typewriter: TYPEWRITER_SCHEMAS,
+    "number-roll": NUMBER_ROLL_SCHEMAS,
+    form: FORM_SCHEMAS,
+};
+/** One piece's schema, or `undefined`. */
+export function schemaOf(family, id) {
+    return SCHEMAS[family][id];
+}

package/dist/schema/scroll.d.ts

@@ -0,0 +1,2 @@
+import type { Schema } from "./types.js";
+export declare const SCROLL_SCHEMAS: Readonly<Record<string, Schema>>;

package/dist/schema/scroll.js

@@ -0,0 +1,16 @@
+// The scroll compositions' option schemas (`transitions/scroll/`): components tied to the page scroll. Their
+// content (sections, cards, a picture, a word, the text) is the page's, so it is listed as code. Imports only
+// schema files.
+import { CURTAIN_SCHEMA } from "../transitions/scroll/Curtain.schema.js";
+import { STACK_CARDS_SCHEMA } from "../transitions/scroll/StackCards.schema.js";
+import { PINNED_EXPAND_SCHEMA } from "../transitions/scroll/PinnedExpand.schema.js";
+import { TEXT_MASK_ZOOM_SCHEMA } from "../transitions/scroll/TextMaskZoom.schema.js";
+import { SPLIT_TEXT_SCHEMA } from "../transitions/scroll/SplitText.schema.js";
+const keyed = (list) => Object.fromEntries(list.map(([schema, meta]) => [schema.id, { ...schema, meta }]));
+export const SCROLL_SCHEMAS = keyed([
+    [CURTAIN_SCHEMA, { label: "Curtain: each section slides off the next" }],
+    [STACK_CARDS_SCHEMA, { label: "Stacked cards" }],
+    [PINNED_EXPAND_SCHEMA, { label: "Picture opening to full screen" }],
+    [TEXT_MASK_ZOOM_SCHEMA, { label: "Picture through growing text" }],
+    [SPLIT_TEXT_SCHEMA, { label: "Text line by line" }],
+]);

package/dist/schema/text.d.ts

@@ -0,0 +1,3 @@
+import type { Schema } from "./types.js";
+/** Every text effect's schema, with its registry metadata, in registry order. Throws if one is missing (caught by the tests). */
+export declare const TEXT_SCHEMAS: Readonly<Record<string, Schema>>;