@sharedex/ui 0.0.0-stage → 0.9.0

package/dist/schema/buttons.js

@@ -0,0 +1,158 @@
+// The button effects' option schemas, keyed by id, in the order of BUTTON_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 { BUTTON_EFFECTS } from "../buttons/registry.js";
+import { FILL_FADE_SCHEMA } from "../buttons/effects/fill/fillFade.schema.js";
+import { FILL_SWEEP_SCHEMA } from "../buttons/effects/fill/fillSweep.schema.js";
+import { FILL_RADIAL_SCHEMA } from "../buttons/effects/fill/fillRadial.schema.js";
+import { FILL_SHUTTER_SCHEMA } from "../buttons/effects/fill/fillShutter.schema.js";
+import { FILL_SLASH_SCHEMA } from "../buttons/effects/fill/fillSlash.schema.js";
+import { FILL_DIRECTIONAL_SCHEMA } from "../buttons/effects/fill/fillDirectional.schema.js";
+import { FILL_SPOTLIGHT_SCHEMA } from "../buttons/effects/fill/fillSpotlight.schema.js";
+import { DEPTH_TILT_SCHEMA } from "../buttons/effects/depth/depthTilt.schema.js";
+import { CURSOR_MAGNET_SCHEMA } from "../buttons/effects/cursor/cursorMagnet.schema.js";
+import { CURSOR_BLOB_SCHEMA } from "../buttons/effects/cursor/cursorBlob.schema.js";
+import { FILL_GRADIENT_SCHEMA } from "../buttons/effects/fill/fillGradient.schema.js";
+import { FILL_WAVE_SCHEMA } from "../buttons/effects/fill/fillWave.schema.js";
+import { BORDER_UNDERLINE_SCHEMA } from "../buttons/effects/border/borderUnderline.schema.js";
+import { BORDER_DRAW_SCHEMA } from "../buttons/effects/border/borderDraw.schema.js";
+import { BORDER_OUTLINE_SCHEMA } from "../buttons/effects/border/borderOutline.schema.js";
+import { BORDER_ROUND_SCHEMA } from "../buttons/effects/border/borderRound.schema.js";
+import { BORDER_CONIC_SCHEMA } from "../buttons/effects/border/borderConic.schema.js";
+import { BORDER_RUNNER_SCHEMA } from "../buttons/effects/border/borderRunner.schema.js";
+import { BORDER_SPREAD_SCHEMA } from "../buttons/effects/border/borderSpread.schema.js";
+import { BORDER_BEAM_SCHEMA } from "../buttons/effects/border/borderBeam.schema.js";
+import { BORDER_STAR_SCHEMA } from "../buttons/effects/border/borderStar.schema.js";
+import { BORDER_ANTS_SCHEMA } from "../buttons/effects/border/borderAnts.schema.js";
+import { GLOW_HOVER_SCHEMA } from "../buttons/effects/glow/glowHover.schema.js";
+import { GLOW_LIFT_SCHEMA } from "../buttons/effects/glow/glowLift.schema.js";
+import { GLOW_SHINE_SCHEMA } from "../buttons/effects/glow/glowShine.schema.js";
+import { GLOW_SHIMMER_SCHEMA } from "../buttons/effects/glow/glowShimmer.schema.js";
+import { GLOW_RAINBOW_SCHEMA } from "../buttons/effects/glow/glowRainbow.schema.js";
+import { GLOW_SHINY_SCHEMA } from "../buttons/effects/glow/glowShiny.schema.js";
+import { GLOW_GLARE_SCHEMA } from "../buttons/effects/glow/glowGlare.schema.js";
+import { GLOW_NEON_SCHEMA } from "../buttons/effects/glow/glowNeon.schema.js";
+import { GLOW_AURA_SCHEMA } from "../buttons/effects/glow/glowAura.schema.js";
+import { DEPTH_PUSHABLE_SCHEMA } from "../buttons/effects/depth/depthPushable.schema.js";
+import { PRESS_SCALE_SCHEMA } from "../buttons/effects/press/pressScale.schema.js";
+import { DEPTH_GROW_SCHEMA } from "../buttons/effects/depth/depthGrow.schema.js";
+import { DEPTH_FLOAT_SCHEMA } from "../buttons/effects/depth/depthFloat.schema.js";
+import { DEPTH_JIGGLE_SCHEMA } from "../buttons/effects/depth/depthJiggle.schema.js";
+import { DEPTH_FLIP_SCHEMA } from "../buttons/effects/depth/depthFlip.schema.js";
+import { DEPTH_CUBE_SCHEMA } from "../buttons/effects/depth/depthCube.schema.js";
+import { DEPTH_NEUMORPH_SCHEMA } from "../buttons/effects/depth/depthNeumorph.schema.js";
+import { LABEL_ROLL_SCHEMA } from "../buttons/effects/label/labelRoll.schema.js";
+import { LABEL_SWAP_SCHEMA } from "../buttons/effects/label/labelSwap.schema.js";
+import { LABEL_FALL_SCHEMA } from "../buttons/effects/label/labelFall.schema.js";
+import { LABEL_SCRAMBLE_SCHEMA } from "../buttons/effects/label/labelScramble.schema.js";
+import { LABEL_SHINY_SCHEMA } from "../buttons/effects/label/labelShiny.schema.js";
+import { ICON_NUDGE_SCHEMA } from "../buttons/effects/icon/iconNudge.schema.js";
+import { ICON_REVEAL_SCHEMA } from "../buttons/effects/icon/iconReveal.schema.js";
+import { ICON_EXPAND_SCHEMA } from "../buttons/effects/icon/iconExpand.schema.js";
+import { ICON_MORPH_SCHEMA } from "../buttons/effects/icon/iconMorph.schema.js";
+import { PRESS_RIPPLE_SCHEMA } from "../buttons/effects/press/pressRipple.schema.js";
+import { PRESS_SPARK_SCHEMA } from "../buttons/effects/press/pressSpark.schema.js";
+import { PRESS_BURST_SCHEMA } from "../buttons/effects/press/pressBurst.schema.js";
+import { PRESS_CONFETTI_SCHEMA } from "../buttons/effects/press/pressConfetti.schema.js";
+import { PRESS_SPRAY_SCHEMA } from "../buttons/effects/press/pressSpray.schema.js";
+import { PRESS_JELLY_SCHEMA } from "../buttons/effects/press/pressJelly.schema.js";
+import { STATE_SHAKE_SCHEMA } from "../buttons/effects/press/stateShake.schema.js";
+import { STATE_SPINNER_SCHEMA } from "../buttons/effects/state/stateSpinner.schema.js";
+import { STATE_SWAP_SCHEMA } from "../buttons/effects/state/stateSwap.schema.js";
+import { STATE_MORPH_SCHEMA } from "../buttons/effects/state/stateMorph.schema.js";
+import { STATE_PROGRESS_SCHEMA } from "../buttons/effects/state/stateProgress.schema.js";
+import { STATE_RING_SCHEMA } from "../buttons/effects/state/stateRing.schema.js";
+import { STATE_HOLD_SCHEMA } from "../buttons/effects/state/stateHold.schema.js";
+import { STATE_COPY_SCHEMA } from "../buttons/effects/state/stateCopy.schema.js";
+import { FILL_GOO_SCHEMA } from "../buttons/effects/fill/fillGoo.schema.js";
+import { BORDER_ELECTRIC_SCHEMA } from "../buttons/effects/border/borderElectric.schema.js";
+import { IDLE_PING_SCHEMA } from "../buttons/effects/idle/idlePing.schema.js";
+import { IDLE_BREATHE_SCHEMA } from "../buttons/effects/idle/idleBreathe.schema.js";
+import { IDLE_WIGGLE_SCHEMA } from "../buttons/effects/idle/idleWiggle.schema.js";
+import { IDLE_GRAIN_SCHEMA } from "../buttons/effects/idle/idleGrain.schema.js";
+import { GLASS_BLUR_SCHEMA } from "../buttons/effects/glass/glassBlur.schema.js";
+import { GLASS_LIQUID_SCHEMA } from "../buttons/effects/glass/glassLiquid.schema.js";
+import { GLASS_NATIVE_SCHEMA } from "../buttons/effects/glass/glassNative.schema.js";
+import { GLASS_REFRACT_SCHEMA } from "../buttons/effects/glass/glassRefract.schema.js";
+import { GLASS_DISTORT_SCHEMA } from "../buttons/effects/glass/glassDistort.schema.js";
+const BY_ID = {
+    fillFade: FILL_FADE_SCHEMA,
+    fillSweep: FILL_SWEEP_SCHEMA,
+    fillRadial: FILL_RADIAL_SCHEMA,
+    fillShutter: FILL_SHUTTER_SCHEMA,
+    fillSlash: FILL_SLASH_SCHEMA,
+    fillDirectional: FILL_DIRECTIONAL_SCHEMA,
+    fillSpotlight: FILL_SPOTLIGHT_SCHEMA,
+    depthTilt: DEPTH_TILT_SCHEMA,
+    cursorMagnet: CURSOR_MAGNET_SCHEMA,
+    cursorBlob: CURSOR_BLOB_SCHEMA,
+    fillGradient: FILL_GRADIENT_SCHEMA,
+    fillWave: FILL_WAVE_SCHEMA,
+    borderUnderline: BORDER_UNDERLINE_SCHEMA,
+    borderDraw: BORDER_DRAW_SCHEMA,
+    borderOutline: BORDER_OUTLINE_SCHEMA,
+    borderRound: BORDER_ROUND_SCHEMA,
+    borderConic: BORDER_CONIC_SCHEMA,
+    borderRunner: BORDER_RUNNER_SCHEMA,
+    borderSpread: BORDER_SPREAD_SCHEMA,
+    borderBeam: BORDER_BEAM_SCHEMA,
+    borderStar: BORDER_STAR_SCHEMA,
+    borderAnts: BORDER_ANTS_SCHEMA,
+    glowHover: GLOW_HOVER_SCHEMA,
+    glowLift: GLOW_LIFT_SCHEMA,
+    glowShine: GLOW_SHINE_SCHEMA,
+    glowShimmer: GLOW_SHIMMER_SCHEMA,
+    glowRainbow: GLOW_RAINBOW_SCHEMA,
+    glowShiny: GLOW_SHINY_SCHEMA,
+    glowGlare: GLOW_GLARE_SCHEMA,
+    glowNeon: GLOW_NEON_SCHEMA,
+    glowAura: GLOW_AURA_SCHEMA,
+    depthPushable: DEPTH_PUSHABLE_SCHEMA,
+    pressScale: PRESS_SCALE_SCHEMA,
+    depthGrow: DEPTH_GROW_SCHEMA,
+    depthFloat: DEPTH_FLOAT_SCHEMA,
+    depthJiggle: DEPTH_JIGGLE_SCHEMA,
+    depthFlip: DEPTH_FLIP_SCHEMA,
+    depthCube: DEPTH_CUBE_SCHEMA,
+    depthNeumorph: DEPTH_NEUMORPH_SCHEMA,
+    labelRoll: LABEL_ROLL_SCHEMA,
+    labelSwap: LABEL_SWAP_SCHEMA,
+    labelFall: LABEL_FALL_SCHEMA,
+    labelScramble: LABEL_SCRAMBLE_SCHEMA,
+    labelShiny: LABEL_SHINY_SCHEMA,
+    iconNudge: ICON_NUDGE_SCHEMA,
+    iconReveal: ICON_REVEAL_SCHEMA,
+    iconExpand: ICON_EXPAND_SCHEMA,
+    iconMorph: ICON_MORPH_SCHEMA,
+    pressRipple: PRESS_RIPPLE_SCHEMA,
+    pressSpark: PRESS_SPARK_SCHEMA,
+    pressBurst: PRESS_BURST_SCHEMA,
+    pressConfetti: PRESS_CONFETTI_SCHEMA,
+    pressSpray: PRESS_SPRAY_SCHEMA,
+    pressJelly: PRESS_JELLY_SCHEMA,
+    stateShake: STATE_SHAKE_SCHEMA,
+    stateSpinner: STATE_SPINNER_SCHEMA,
+    stateSwap: STATE_SWAP_SCHEMA,
+    stateMorph: STATE_MORPH_SCHEMA,
+    stateProgress: STATE_PROGRESS_SCHEMA,
+    stateRing: STATE_RING_SCHEMA,
+    stateHold: STATE_HOLD_SCHEMA,
+    stateCopy: STATE_COPY_SCHEMA,
+    fillGoo: FILL_GOO_SCHEMA,
+    borderElectric: BORDER_ELECTRIC_SCHEMA,
+    idlePing: IDLE_PING_SCHEMA,
+    idleBreathe: IDLE_BREATHE_SCHEMA,
+    idleWiggle: IDLE_WIGGLE_SCHEMA,
+    idleGrain: IDLE_GRAIN_SCHEMA,
+    glassBlur: GLASS_BLUR_SCHEMA,
+    glassLiquid: GLASS_LIQUID_SCHEMA,
+    glassNative: GLASS_NATIVE_SCHEMA,
+    glassRefract: GLASS_REFRACT_SCHEMA,
+    glassDistort: GLASS_DISTORT_SCHEMA,
+};
+/** Every button effect's schema, with its registry metadata, in registry order. Throws if one is missing (caught by the tests). */
+export const BUTTON_SCHEMAS = Object.fromEntries(BUTTON_EFFECTS.map((m) => {
+    const schema = BY_ID[m.id];
+    if (!schema)
+        throw new Error(`[@sharedex/ui] no schema for button effect "${m.id}"`);
+    return [m.id, { ...schema, meta: { label: m.label, category: m.group, family: m.tech, tier: m.tier } }];
+}));

package/dist/schema/carousel.d.ts

@@ -0,0 +1,14 @@
+import type { Schema } from "./types.js";
+/** The 16 layout presets: flat rows, stacks, then 3D shapes. `axis: "x"` in `modes` = horizontal only. */
+export declare const CAROUSEL_LAYOUT_SCHEMAS: Readonly<Record<string, Schema>>;
+/** Speed effects, added to any layout with `modify()`. */
+export declare const CAROUSEL_MODIFIER_SCHEMAS: Readonly<Record<string, Schema>>;
+/** Enter / exit presets (`presence.*`). */
+export declare const CAROUSEL_PRESENCE_SCHEMAS: Readonly<Record<string, Schema>>;
+/** Open views (`openView.*`). */
+export declare const CAROUSEL_OPEN_SCHEMAS: Readonly<Record<string, Schema>>;
+/** How a drag lands (`physics.settle`). */
+export declare const CAROUSEL_PHYSICS_SCHEMAS: Readonly<Record<string, Schema>>;
+/** `<Carousel.Root config>` as one form. */
+export declare const CAROUSEL_SCHEMAS: Readonly<Record<string, Schema>>;
+export { CAROUSEL_SECTIONS, type CarouselSection, type CarouselSettings } from "../carousel/config.schema.js";

package/dist/schema/carousel.js

@@ -0,0 +1,73 @@
+// The carousel's option schemas: its layouts, speed effects, enter / exit presets, open views, settle policies and
+// its own settings. The carousel has no metadata registry like TRANSITION_EFFECTS, so labels and categories are
+// set here. Imports only schema files, which import only types: this entry carries no carousel code.
+import { WAVE_SCHEMA } from "../carousel/layout/presets/wave.schema.js";
+import { SCALE_SCHEMA } from "../carousel/layout/presets/scale.schema.js";
+import { SPOTLIGHT_SCHEMA } from "../carousel/layout/presets/spotlight.schema.js";
+import { SUPER_FLOW_SCHEMA } from "../carousel/layout/presets/superFlow.schema.js";
+import { EXPO_SCHEMA } from "../carousel/layout/presets/expo.schema.js";
+import { MATERIAL_SCHEMA } from "../carousel/layout/presets/material.schema.js";
+import { FALL_AWAY_SCHEMA } from "../carousel/layout/presets/fallAway.schema.js";
+import { FAN_SCHEMA } from "../carousel/layout/presets/fan.schema.js";
+import { DECK_SCHEMA } from "../carousel/layout/presets/deck.schema.js";
+import { COVERFLOW_SCHEMA } from "../carousel/layout/presets/coverflow.schema.js";
+import { PANORAMA_SCHEMA } from "../carousel/layout/presets/panorama.schema.js";
+import { STAIRCASE_SCHEMA } from "../carousel/layout/presets/staircase.schema.js";
+import { BARREL_SCHEMA } from "../carousel/layout/presets/barrel.schema.js";
+import { RING_SCHEMA } from "../carousel/layout/presets/ring.schema.js";
+import { HELIX_SCHEMA } from "../carousel/layout/presets/helix.schema.js";
+import { SPHERE_SCHEMA } from "../carousel/layout/presets/sphere.schema.js";
+import { SPEED_TILT_SCHEMA, SPEED_WAVE_SCHEMA } from "../carousel/layout/modifiers/speed.schema.js";
+import { PRESENCE_CONTRACT_SCHEMA, PRESENCE_EXPAND_SCHEMA, PRESENCE_FADE_SCHEMA, PRESENCE_SCATTER_SCHEMA, PRESENCE_SLIDE_ALONG_SCHEMA, } from "../carousel/layout/presence.schema.js";
+import { OPEN_DETAIL_SCHEMA, OPEN_INLINE_SCHEMA, OPEN_PANEL_SCHEMA } from "../carousel/layout/open.schema.js";
+import { FREE_SCROLL_SCHEMA, MOMENTUM_SNAP_SCHEMA, PAGED_BY_SCHEMA, SNAP_TO_NEAREST_SCHEMA } from "../carousel/physics/policies.schema.js";
+import { CAROUSEL_SCHEMA } from "../carousel/config.schema.js";
+const keyed = (list) => Object.fromEntries(list.map(([schema, meta]) => [schema.id, { ...schema, meta }]));
+/** The 16 layout presets: flat rows, stacks, then 3D shapes. `axis: "x"` in `modes` = horizontal only. */
+export const CAROUSEL_LAYOUT_SCHEMAS = keyed([
+    [WAVE_SCHEMA, { label: "Wave", category: "row" }],
+    [SCALE_SCHEMA, { label: "Scale", category: "row" }],
+    [SPOTLIGHT_SCHEMA, { label: "Spotlight", category: "row" }],
+    [SUPER_FLOW_SCHEMA, { label: "Super flow", category: "row" }],
+    [EXPO_SCHEMA, { label: "Expo", category: "row" }],
+    [MATERIAL_SCHEMA, { label: "Material", category: "row", modes: ["x"] }],
+    [FALL_AWAY_SCHEMA, { label: "Fall away", category: "row" }],
+    [FAN_SCHEMA, { label: "Fan", category: "stack" }],
+    [DECK_SCHEMA, { label: "Deck", category: "stack" }],
+    [COVERFLOW_SCHEMA, { label: "Coverflow", category: "shape" }],
+    [PANORAMA_SCHEMA, { label: "Panorama", category: "shape", modes: ["x"] }],
+    [STAIRCASE_SCHEMA, { label: "Staircase", category: "shape" }],
+    [BARREL_SCHEMA, { label: "Barrel", category: "shape" }],
+    [RING_SCHEMA, { label: "Ring", category: "shape" }],
+    [HELIX_SCHEMA, { label: "Helix", category: "shape" }],
+    [SPHERE_SCHEMA, { label: "Sphere", category: "shape" }],
+]);
+/** Speed effects, added to any layout with `modify()`. */
+export const CAROUSEL_MODIFIER_SCHEMAS = keyed([
+    [SPEED_WAVE_SCHEMA, { label: "Wave while moving" }],
+    [SPEED_TILT_SCHEMA, { label: "Lean while moving" }],
+]);
+/** Enter / exit presets (`presence.*`). */
+export const CAROUSEL_PRESENCE_SCHEMAS = keyed([
+    [PRESENCE_FADE_SCHEMA, { label: "Fade" }],
+    [PRESENCE_CONTRACT_SCHEMA, { label: "Contract into the focus" }],
+    [PRESENCE_EXPAND_SCHEMA, { label: "Expand past the viewer" }],
+    [PRESENCE_SCATTER_SCHEMA, { label: "Scatter" }],
+    [PRESENCE_SLIDE_ALONG_SCHEMA, { label: "Slide along the track" }],
+]);
+/** Open views (`openView.*`). */
+export const CAROUSEL_OPEN_SCHEMAS = keyed([
+    [OPEN_INLINE_SCHEMA, { label: "Grow in place" }],
+    [OPEN_DETAIL_SCHEMA, { label: "Big card over a thumbnail strip" }],
+    [OPEN_PANEL_SCHEMA, { label: "Big card beside a panel" }],
+]);
+/** How a drag lands (`physics.settle`). */
+export const CAROUSEL_PHYSICS_SCHEMAS = keyed([
+    [MOMENTUM_SNAP_SCHEMA, { label: "Glide, then land on a card" }],
+    [SNAP_TO_NEAREST_SCHEMA, { label: "Spring to the nearest card" }],
+    [FREE_SCROLL_SCHEMA, { label: "Glide and stop anywhere" }],
+    [PAGED_BY_SCHEMA, { label: "Move a page of cards at a time" }],
+]);
+/** `<Carousel.Root config>` as one form. */
+export const CAROUSEL_SCHEMAS = keyed([[CAROUSEL_SCHEMA, { label: "Carousel" }]]);
+export { CAROUSEL_SECTIONS } from "../carousel/config.schema.js";

package/dist/schema/common.d.ts

@@ -0,0 +1,41 @@
+import type { BlendMode } from "../backgrounds/types.js";
+import type { ChoiceField, ColorField, ColorsField, EffectField, NumberField, SeedField } from "./types.js";
+/**
+ * A background layer's `opacity`, `blend` and `mask` (`LayerOptions`). Auto
+ * unless a piece sets its own default: left out, the layer is fully opaque,
+ * blends normally and is not masked.
+ */
+export declare function layerFields(defaults?: {
+    readonly opacity?: number;
+}): {
+    opacity: NumberField;
+    blend: ChoiceField<BlendMode>;
+    mask: ChoiceField<string>;
+};
+/** A pace multiplier: 1 = the piece's own pace. Auto (left out, the piece runs at 1). */
+export declare function speedField(max?: number): NumberField;
+/** A seed with a known default, or auto when leaving it out means something no value reproduces. */
+export declare function seedField(defaultSeed?: number): SeedField;
+/** A colour list; `fallback` is what the piece uses when the list is left out. */
+export declare function colorsField(fallback: readonly string[], min?: number, max?: number, label?: string): ColorsField;
+/** A button fill's colour, the label's colour on it, and how long it takes (`FillOptions`). */
+export declare function buttonFillFields(duration?: number): {
+    color: ColorField;
+    textColor: ColorField;
+    duration: NumberField;
+};
+/** A shader transition's `fallback`: any CSS transition, played without WebGL or on a weaker device. */
+export declare function shaderFallbackField(note?: string): EffectField;
+/** An entrance's timing (`EnterTiming` without `from`). `stagger` is auto unless the effect fixes its own: left out, it follows what moves. */
+export declare function textEnterFields(defaults: {
+    readonly duration: number;
+    readonly stagger?: number;
+}): {
+    duration: NumberField;
+    stagger: NumberField;
+    delay: NumberField;
+};
+/** What an entrance moves (`EnterOptions.by`). */
+export declare function textByField(by: "chars" | "words" | "lines"): ChoiceField<"chars" | "words" | "lines">;
+/** Which piece of an entrance goes first (`EnterTiming.from`). */
+export declare function textFromField(): ChoiceField<"start" | "end" | "centre" | "edges">;

package/dist/schema/common.js

@@ -0,0 +1,109 @@
+const BLEND_MODES = [
+    "normal", "multiply", "screen", "overlay", "darken", "lighten", "color-dodge", "color-burn",
+    "hard-light", "soft-light", "difference", "exclusion", "hue", "saturation", "color", "luminosity",
+];
+/**
+ * A background layer's `opacity`, `blend` and `mask` (`LayerOptions`). Auto
+ * unless a piece sets its own default: left out, the layer is fully opaque,
+ * blends normally and is not masked.
+ */
+export function layerFields(defaults = {}) {
+    const opacity = {
+        kind: "number",
+        label: "Opacity",
+        min: 0,
+        max: 1,
+        step: 0.01,
+        ...(defaults.opacity !== undefined ? { default: defaults.opacity } : { autoValue: 1, autoNote: "1 (fully opaque)" }),
+    };
+    const blend = {
+        kind: "choice",
+        label: "Blend",
+        values: BLEND_MODES,
+        advanced: true,
+        autoValue: "normal",
+        autoNote: "normal",
+    };
+    const mask = {
+        kind: "choice",
+        label: "Mask",
+        values: ["radial", "fade-top", "fade-bottom", "fade-edges"],
+        labels: { radial: "Radial", "fade-top": "Fade at the top", "fade-bottom": "Fade at the bottom", "fade-edges": "Fade at the edges" },
+        advanced: true,
+        autoNote: "none",
+    };
+    return { opacity, blend, mask };
+}
+/** A pace multiplier: 1 = the piece's own pace. Auto (left out, the piece runs at 1). */
+export function speedField(max = 4) {
+    return { kind: "number", label: "Speed", min: 0, max, step: 0.05, autoValue: 1, autoNote: "1 (its own pace)" };
+}
+/** A seed with a known default, or auto when leaving it out means something no value reproduces. */
+export function seedField(defaultSeed) {
+    return {
+        kind: "seed",
+        label: "Seed",
+        advanced: true,
+        help: "Change it for a different arrangement of the same effect.",
+        ...(defaultSeed !== undefined ? { default: defaultSeed } : { autoNote: "the effect's own" }),
+    };
+}
+/** A colour list; `fallback` is what the piece uses when the list is left out. */
+export function colorsField(fallback, min = 1, max = 6, label = "Colours") {
+    return { kind: "colors", label, min, max, default: fallback };
+}
+/** A button fill's colour, the label's colour on it, and how long it takes (`FillOptions`). */
+export function buttonFillFields(duration = 0.35) {
+    const color = { kind: "color", label: "Fill colour", default: "var(--color-sx-accent)" };
+    const textColor = { kind: "color", label: "Label colour", help: "The label's colour while filled.", default: "var(--color-sx-ink)" };
+    const time = { kind: "number", label: "Duration", min: 0.1, max: 1.5, step: 0.05, unit: "s", default: duration };
+    return { color, textColor, duration: time };
+}
+/** A shader transition's `fallback`: any CSS transition, played without WebGL or on a weaker device. */
+export function shaderFallbackField(note = "a fade") {
+    return {
+        kind: "effect",
+        label: "Fallback",
+        family: "transition",
+        kinds: ["css"],
+        autoNote: note,
+        help: "Plays instead without WebGL or on a weaker device.",
+        advanced: true,
+    };
+}
+/** An entrance's timing (`EnterTiming` without `from`). `stagger` is auto unless the effect fixes its own: left out, it follows what moves. */
+export function textEnterFields(defaults) {
+    const duration = { kind: "number", label: "Duration", min: 0.1, max: 3, step: 0.05, unit: "s", default: defaults.duration };
+    const stagger = {
+        kind: "number",
+        label: "Between pieces",
+        min: 0,
+        max: 0.5,
+        step: 0.005,
+        unit: "s",
+        ...(defaults.stagger !== undefined ? { default: defaults.stagger } : { autoValue: 0.07, autoNote: "0.03 s for letters, 0.07 s for words, 0.12 s for lines" }),
+    };
+    const delay = { kind: "number", label: "Delay", min: 0, max: 3, step: 0.05, unit: "s", default: 0 };
+    return { duration, stagger, delay };
+}
+/** What an entrance moves (`EnterOptions.by`). */
+export function textByField(by) {
+    return {
+        kind: "choice",
+        label: "Moves",
+        values: ["chars", "words", "lines"],
+        labels: { chars: "Letters", words: "Words", lines: "Lines" },
+        help: "Letters only in short text; Arabic and other joined scripts move by the word.",
+        default: by,
+    };
+}
+/** Which piece of an entrance goes first (`EnterTiming.from`). */
+export function textFromField() {
+    return {
+        kind: "choice",
+        label: "First",
+        values: ["start", "end", "centre", "edges"],
+        labels: { start: "Reading start", end: "Reading end", centre: "Middle out", edges: "Edges in" },
+        default: "start",
+    };
+}

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/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[];