tweakit 0.6.0 → 0.7.0

package/dist/types/tweaks/enhance.d.ts

@@ -1,2 +1,3 @@
-/** Bind every unbound [data-tw] host under `root` (the document by default). */
-export declare function enhance(root?: Document | Element): Promise<void>;
+import type { EnhanceOptions } from "./types.js";
+/** Bind every unbound [data-twk] host under `root` (the document by default). */
+export declare function enhance(root?: Document | Element, opts?: EnhanceOptions): Promise<void>;

package/dist/types/tweaks/types.d.ts

@@ -1,4 +1,5 @@
-/** An option for a select / radio grid: a bare string or number, or `{ value, label }`; the param is the value as written. */
+/** An option for a select / radio grid: a bare string or number, or `{ value, label }`; the param is the value as
+ * written. */
 export type Option = string | number | {
     value: string | number;
     label?: string;
@@ -264,26 +265,30 @@ export type SchemaObject = {
     type: "image";
     value?: string;
     /** Supplied images to pick from, as URLs or `{ value, label }`. The control becomes a row naming the chosen
-     *  image that opens a pane of tiles with the upload below them, and the param is the chosen URL or the upload's data URL. */
+     *  image that opens a pane of tiles with the upload below them, and the param is the chosen URL or the upload's
+     *  data URL. */
     options?: ReadonlyArray<string | {
         value: string;
         label?: string;
     }>;
-    /** Tiles per row in the gallery, 1 to 6 (by default one per option for two or three, 2 for one or four, then 3). */
+    /** Tiles per row in the gallery, 1 to 6 (by default one per option for two or three, 2 for one or four, then
+     * 3). */
     cols?: number;
     /** The largest upload taken, in bytes (10 MB unless set); a bigger file is refused with a note. */
     maxSize?: number;
     /** An upload longer than this on its long side, in px, is drawn down to it before it becomes the param, and one
-     *  heavier than 1.5 MB is redrawn at its size, so a phone photo can't fill storage (2560 unless set; `false` takes
-     *  uploads as they are). A JPEG comes out as a JPEG at
-     *  `quality`; anything else as a PNG when that is 1.5 MB or less (a screenshot, not a photo), else as a JPEG, or a WebP
-     *  when it has transparency. A GIF, an SVG, an animated WebP or APNG, a light picture within `fit`, or one the redraw wouldn't make smaller is kept as it is. */
+     *  heavier than 1.5 MB is redrawn at its size, so a phone photo can't fill storage (2560 unless set; `false`
+     *  takes uploads as they are). A JPEG comes out as a JPEG at
+     *  `quality`; anything else as a PNG when that is 1.5 MB or less (a screenshot, not a photo), else as a JPEG, or
+     *  a WebP when it has transparency. A GIF, an SVG, an animated WebP or APNG, a light picture within `fit`, or one
+     *  the redraw wouldn't make smaller is kept as it is. */
     fit?: number | false;
     /** The JPEG or WebP quality of a shrunk upload, 0 to 1 (0.85 unless set). */
     quality?: number;
     /** `false` leaves the upload button out of a gallery: the options are the whole choice. */
     upload?: boolean;
-    /** `false` leaves Clear out of a gallery, and Delete no longer empties it: for a choice that must keep a value. */
+    /** `false` leaves Clear out of a gallery, and Delete no longer empties it: for a choice that must keep a
+     * value. */
     clear?: boolean;
 } | {
     type: "button";
@@ -359,7 +364,7 @@ type Dashed<S extends string, Acc extends string = "", Run = false> = S extends
 type TrimDash<S extends string> = S extends `-${infer R}` ? TrimDash<R> : S extends `${infer R}-` ? TrimDash<R> : S;
 /** A tab title's key under `params`: lower-case, each run of other characters a `-`, trimmed
  *  (`"Layout & Grid"` → `"layout-grid"`). Two titles that slug alike are told apart at runtime only. */
-export type TabKey<T extends string> = string extends T ? string : TrimDash<Dashed<Lowercase<T>>> extends infer K extends string ? (K extends "" ? "tab" : K) : never;
+export type TabKey<T extends string> = string extends T ? string : TrimDash<Dashed<Lowercase<T>>> extends infer K extends string ? K extends "" ? "tab" : K : never;
 type TabClash<P> = true extends {
     [T in keyof P & string]: TabKey<T> extends {
         [U in Exclude<keyof P & string, T>]: TabKey<U>;
@@ -367,11 +372,11 @@ type TabClash<P> = true extends {
 }[keyof P & string] ? true : false;
 type Valueless = "button" | "buttongroup" | "separator" | "fpsgraph" | "monitor";
 type Hinge = {
-    list: "options";
-    radiogrid: "options";
-    segmented: "options";
+    list: "options" | "value";
+    radiogrid: "options" | "value";
+    segmented: "options" | "value";
     point: "components" | "value";
-    tabs: "pages";
+    tabs: "pages" | "value";
 };
 type TypedValue<V> = V extends {
     readonly type: "slider" | "number";
@@ -379,9 +384,9 @@ type TypedValue<V> = V extends {
     readonly type: "checkbox";
 } ? boolean : V extends {
     readonly type: "list" | "radiogrid" | "segmented";
-} ? (V extends {
+} ? V extends {
     readonly options: readonly unknown[];
-} ? ChoiceValue<V> : never) : V extends {
+} ? ChoiceValue<V> : never : V extends {
     readonly type: "color" | "text" | "image" | "plot";
 } ? string : V extends {
     readonly type: "interval";
@@ -399,7 +404,7 @@ type TypedValue<V> = V extends {
     readonly type: "gradient";
 } ? GradientValue : V extends {
     readonly type: "point";
-} ? (V extends {
+} ? V extends {
     readonly components: readonly [];
 } ? never : V extends {
     readonly components: readonly (infer C)[];
@@ -409,19 +414,19 @@ type TypedValue<V> = V extends {
     } ? Key : never]: number;
 } : V extends {
     readonly value: infer P extends object;
-} ? (keyof P extends never ? never : {
+} ? keyof P extends never ? never : {
     -readonly [K in keyof P & string]: number;
-}) : never) : V extends {
+} : never : V extends {
     readonly type: "tabs";
-} ? (V extends {
+} ? V extends {
     readonly pages: infer P extends object;
-} ? (keyof P extends never ? never : TabClash<P> extends true ? Record<string, Params> : {
+} ? keyof P extends never ? never : TabClash<P> extends true ? Record<string, Params> : {
     [T in keyof P & string as TabKey<T>]: ParamsOf<P[T]>;
-}) : never) : unknown;
+} : never : unknown;
 /** The value a schema entry puts on `params`. */
 export type ValueOf<V> = V extends {
     readonly type: infer T;
-} ? (string extends T ? any : T extends SchemaObject["type"] ? (T extends keyof Hinge ? ([Extract<Hinge[T], keyof V>] extends [never] ? ShorthandValue<V> : VerboseValue<V, T>) : VerboseValue<V, T>) : ShorthandValue<V>) : ShorthandValue<V>;
+} ? string extends T ? any : T extends SchemaObject["type"] ? T extends keyof Hinge ? [Extract<Hinge[T], keyof V>] extends [never] ? ShorthandValue<V> : VerboseValue<V, T> : VerboseValue<V, T> : T extends string ? [Extract<"value" | "options" | "action", keyof V>] extends [never] ? ShorthandValue<V> : never : ShorthandValue<V> : ShorthandValue<V>;
 type VerboseValue<V, T> = T extends Valueless ? never : TypedValue<V>;
 type ShorthandValue<V> = V extends readonly [readonly [number, number], ...unknown[]] ? [number, number] : V extends readonly [number] | readonly [number, number] | readonly [number, number, number] | readonly [number, number, number, number] ? number : V extends readonly [number, ...number[]] ? V[number] : V extends readonly [] ? undefined : V extends readonly number[] ? number : V extends readonly (number | readonly number[])[] ? [number, number] : V extends number ? number : V extends boolean ? boolean : V extends string ? string : V extends readonly (infer O)[] ? OptionValue<O> : V extends {
     readonly action: (...a: any[]) => any;
@@ -429,24 +434,24 @@ type ShorthandValue<V> = V extends readonly [readonly [number, number], ...unkno
     readonly options: readonly unknown[];
 } ? ChoiceValue<V> : V extends object ? Entries<V, true> : unknown;
 type Reserved = "__proto__" | "constructor" | "prototype";
-type FolderChrome<V, K> = K extends "disabled" | "hint" ? true : K extends "render" ? (V extends (...a: any[]) => any ? true : false) : false;
+type FolderChrome<V, K> = K extends "disabled" | "hint" ? true : K extends "render" ? V extends (...a: any[]) => any ? true : false : false;
 type Entries<S, Nested extends boolean> = string extends keyof S ? Params : {
-    -readonly [K in keyof S & string as K extends Reserved ? never : ValueOf<S[K]> extends never ? never : Nested extends true ? (FolderChrome<S[K], K> extends true ? never : K) : K]: ValueOf<S[K]>;
+    -readonly [K in keyof S & string as K extends Reserved ? never : ValueOf<S[K]> extends never ? never : Nested extends true ? FolderChrome<S[K], K> extends true ? never : K : K]: ValueOf<S[K]>;
 };
 /** The live values a schema builds, nested like the schema; a plain `Schema` gives the loose `Params`. */
 export type ParamsOf<S> = Entries<S, false>;
 type CheckValue<V> = V extends {
     readonly type: infer T;
-} ? (string extends T ? V : T extends SchemaObject["type"] ? (V extends {
+} ? string extends T ? V : T extends SchemaObject["type"] ? V extends {
     readonly type: "tabs";
     readonly pages: infer P;
 } ? {
     readonly pages: {
         [K in keyof P]: KnownTypes<P[K]>;
     };
-} : T extends keyof Hinge ? ([Extract<Hinge[T], keyof V>] extends [never] ? unknown : FitsForm<V, T>) : FitsForm<V, T>) : {
+} : T extends keyof Hinge ? [Extract<Hinge[T], keyof V>] extends [never] ? unknown : FitsForm<V, T> : FitsForm<V, T> : {
     readonly type: NotAControlType;
-}) : V extends readonly unknown[] | ((...a: any[]) => any) ? unknown : V extends object ? KnownTypes<V> : unknown;
+} : V extends readonly unknown[] | ((...a: any[]) => any) ? unknown : V extends object ? KnownTypes<V> : unknown;
 type FormOf<O, T> = O extends {
     readonly type: infer N;
 } ? (T extends N ? O & ControlOptions : never) : never;
@@ -462,51 +467,53 @@ export type KnownTypes<S> = {
 export type KnownType<V> = CheckValue<V>;
 /** A theme — token overrides applied over the default monochrome look. Every key is
  *  optional, so a partial theme only moves what it names; unset tokens keep their default.
- *  Keys are the `--tw-*` custom properties themselves. Apply at build via
+ *  Keys are the `--twk-*` custom properties themselves. Apply at build via
  *  `tweaks(name, schema, { theme })`, or live via `panel.setTheme(theme)`. The kit's whole
  *  appearance runs on these custom properties — this is the public theming surface. */
 export interface Theme {
     /** Brand accent — slider fills, focus rings, active highlights (default: neutral, no accent). */
-    "--tw-accent"?: string;
-    /** Text drawn on the accent (active segment / radio label); the primary text tone unless set, so set it with a light accent. */
-    "--tw-on-accent"?: string;
+    "--twk-accent"?: string;
+    /** Text drawn on the accent (active segment / radio label); the primary text tone unless set, so set it with a light
+     * accent. */
+    "--twk-on-accent"?: string;
     /** Panel background, reused for recessed wells. */
-    "--tw-base"?: string;
+    "--twk-base"?: string;
     /** Popover / dropdown background. */
-    "--tw-dropdown-bg"?: string;
+    "--twk-dropdown-bg"?: string;
     /** Control surface and its hover / active steps. */
-    "--tw-surface"?: string;
-    "--tw-surface-hover"?: string;
-    "--tw-surface-active"?: string;
+    "--twk-surface"?: string;
+    "--twk-surface-hover"?: string;
+    "--twk-surface-active"?: string;
     /** Hairline border and its hover step. */
-    "--tw-border"?: string;
-    "--tw-border-hover"?: string;
+    "--twk-border"?: string;
+    "--twk-border-hover"?: string;
     /** Text-selection highlight wash. */
-    "--tw-selection"?: string;
-    /** Text tones — panel title, section heading, primary value text, control label, and the muted / faint / focus tones. */
-    "--tw-text-root"?: string;
-    "--tw-text-section"?: string;
-    "--tw-text-primary"?: string;
-    "--tw-text-label"?: string;
-    "--tw-text-secondary"?: string;
-    "--tw-text-tertiary"?: string;
-    "--tw-text-focus"?: string;
+    "--twk-selection"?: string;
+    /** Text tones — panel title, section heading, primary value text, control label, and the muted / faint / focus
+     * tones. */
+    "--twk-text-root"?: string;
+    "--twk-text-section"?: string;
+    "--twk-text-primary"?: string;
+    "--twk-text-label"?: string;
+    "--twk-text-secondary"?: string;
+    "--twk-text-tertiary"?: string;
+    "--twk-text-focus"?: string;
     /** Copy-confirmation accent, and the invalid-state accent (the plot's bad-expression cue). */
-    "--tw-success"?: string;
-    "--tw-danger"?: string;
+    "--twk-success"?: string;
+    "--twk-danger"?: string;
     /** Popover shadow, the panel's container elevation, and its lifted (floating / dragging) variant. */
-    "--tw-shadow-dropdown"?: string;
-    "--tw-shadow-panel"?: string;
-    "--tw-shadow-panel-lifted"?: string;
+    "--twk-shadow-dropdown"?: string;
+    "--twk-shadow-panel"?: string;
+    "--twk-shadow-panel-lifted"?: string;
     /** Font stack, and the monospace stack (the plot's expression field). */
-    "--tw-font-sans"?: string;
-    "--tw-font-mono"?: string;
+    "--twk-font-sans"?: string;
+    "--twk-font-mono"?: string;
     /** Control corner radius, row height and the panel's width (256px by default), as CSS lengths. */
-    "--tw-radius"?: string;
-    "--tw-row-height"?: string;
-    "--tw-width"?: string;
+    "--twk-radius"?: string;
+    "--twk-row-height"?: string;
+    "--twk-width"?: string;
     /** Any other token. */
-    [token: `--${string}`]: string | undefined;
+    [token: `--twk-${string}`]: string | undefined;
 }
 /** Options for a programmatic write — `set()`, `setMany()`, `fromJSON()`. */
 export interface SetOptions {
@@ -517,14 +524,183 @@ export interface SetOptions {
 }
 /** Where a floating panel starts: `x` / `y` are its insets in px (16 by default) from the
  *  viewport's top-left. The far edge keeps a gap of `y` when the height caps; CSS
- *  `--tw-float-gap` overrides it. */
+ *  `--twk-float-gap` overrides it. */
 export interface FloatingPlacement {
     x?: number;
     y?: number;
 }
+/** The words a panel shows and says, by key, for the `strings` option (each line notes the English default). A key
+ *  with a `{placeholder}` takes a string that uses it, or a function given the values, for a language whose plurals
+ *  need more than one form. Units (px, ms, %), axis letters and color notations stay as they are. */
+export type Word<V = never> = [V] extends [never] ? string : string | ((v: V) => string);
+export interface Strings {
+    /** "Tweaks" — the panel's landmark name when its own is blank */ panel?: string;
+    /** "Presets" — the toolbar button */ presets?: string;
+    /** "Copy values (⇧: changed only)" — the toolbar button */ copy?: string;
+    /** "Reset" — the toolbar button */ reset?: string;
+    /** "Double-click or hold to reset" — a row label's tooltip */ resetHint?: string;
+    /** "Values copied" */ copied?: string;
+    /** "{n} changed values copied" — 1 changed value copied for one */ copiedChanged?: Word<{
+        n: number;
+    }>;
+    /** "Nothing has changed" */ nothingChanged?: string;
+    /** "Copy failed" */ copyFailed?: string;
+    /** "{label} copied" — ⌘C on a row */ rowCopied?: Word<{
+        label: string;
+    }>;
+    /** "Not saved" — a value storage refused */ notSaved?: string;
+    /** "{n} values pasted" — 1 value pasted for one */ pasted?: Word<{
+        n: number;
+    }>;
+    /** "Nothing to paste" */ nothingToPaste?: string;
+    /** "Couldn't read the clipboard" */ clipboardUnread?: string;
+    /** "Preset name…" — the field's placeholder */ presetName?: string;
+    /** "New preset name" — the field's label */ newPreset?: string;
+    /** "Save" */ save?: string;
+    /** "No presets yet" */ noPresets?: string;
+    /** "Loaded preset {name}" */ presetLoaded?: Word<{
+        name: string;
+    }>;
+    /** "Saved preset {name}" */ presetSaved?: Word<{
+        name: string;
+    }>;
+    /** "Preset {name} not saved: storage is full" */ presetFull?: Word<{
+        name: string;
+    }>;
+    /** "Delete preset {name}" — a row's delete button */ presetDelete?: Word<{
+        name: string;
+    }>;
+    /** "Off" — a checkbox */ off?: string;
+    /** "On" — a checkbox */ on?: string;
+    /** "Button" — a group button with no label */ button?: string;
+    /** "Tab" — a tab page whose title is blank */ tab?: string;
+    /** "Folder" — a markup folder with no data-label */ folder?: string;
+    /** "Drag to adjust" — a number field's grip */ dragToAdjust?: string;
+    /** "{label} minimum" */ intervalMin?: Word<{
+        label: string;
+    }>;
+    /** "{label} maximum" */ intervalMax?: Word<{
+        label: string;
+    }>;
+    /** "Monitor" — a monitor with no label */ monitor?: string;
+    /** "FPS" — an fpsgraph with no label */ fps?: string;
+    /** "Plot" — a plot with no label */ plot?: string;
+    /** "{label} — expression in x" — a plot's field */ expression?: Word<{
+        label: string;
+    }>;
+    /** "Point" — a point with no label */ point?: string;
+    /** "{label} pad: {x} and {y}" */ pointPad?: Word<{
+        label: string;
+        x: string | number;
+        y: string | number;
+    }>;
+    /** "Control point {n}" — a cubic bézier handle */ controlPoint?: Word<{
+        n: number;
+    }>;
+    /** "Control point {n}, x {x}, y {y}" */ controlPointAt?: Word<{
+        n: number;
+        x: string | number;
+        y: string | number;
+    }>;
+    /** "Color" — a color row with no label, and the shadow's color row */ color?: string;
+    /** "Color plane: chroma across, lightness up" */ colorPlane?: string;
+    /** "Color mode" */ colorMode?: string;
+    /** "Hex color" */ hex?: string;
+    /** "Hue" */ hue?: string;
+    /** "Alpha" */ alpha?: string;
+    /** "lightness {l}%, chroma {c}" — the color plane's description, said after a run of keys */ colorReadout?: Word<{
+        l: number;
+        c: number;
+    }>;
+    /** "wide" — the gamut badge past P3 (sRGB and P3 are names) */ wide?: string;
+    /** "Gradient" — a gradient with no label */ gradient?: string;
+    /** "{n} stops" — 1 stop for one */ stops?: Word<{
+        n: number;
+    }>;
+    /** "Add a stop after the selected one" — the add button's tooltip */ addStop?: string;
+    /** "Add a color stop after the selected one" — the add button's label */ addStopAria?: string;
+    /** "Color stop at {pos}%" */ stopAt?: Word<{
+        pos: number;
+    }>;
+    /** "Color stop at {pos}%, selected" */ stopAtSelected?: Word<{
+        pos: number;
+    }>;
+    /** "Easing between stops" — the easing menu's label */ stopEasing?: string;
+    /** "How the ramp blends between stops" — its tooltip */ stopEasingHint?: string;
+    /** "Linear" */ easeLinear?: string;
+    /** "Ease" */ ease?: string;
+    /** "Ease in" */ easeIn?: string;
+    /** "Ease out" */ easeOut?: string;
+    /** "Ease in-out" */ easeInOut?: string;
+    /** "Custom" — an easing the menu doesn't list */ custom?: string;
+    /** "Upload image" — the gallery's upload button */ upload?: string;
+    /** "{label}: upload an image" */ uploadImage?: Word<{
+        label: string;
+    }>;
+    /** "{label}: choose an image" */ chooseImage?: Word<{
+        label: string;
+    }>;
+    /** "Clear" */ clear?: string;
+    /** "{label}: clear the image" */ clearImage?: Word<{
+        label: string;
+    }>;
+    /** "Replace" */ replace?: string;
+    /** "Drop or choose" */ dropOrChoose?: string;
+    /** "None" — no image chosen */ none?: string;
+    /** "Image {n}" — a gallery option with no label */ imageN?: Word<{
+        n: number;
+    }>;
+    /** "Uploaded image" */ uploadedImage?: string;
+    /** "Custom image" — a value off the gallery's list */ customImage?: string;
+    /** "Not an image" */ notAnImage?: string;
+    /** "Couldn't read the file" */ unreadable?: string;
+    /** "{size}, max {max}" — a file over maxSize */ tooLarge?: Word<{
+        size: string;
+        max: string;
+    }>;
+    /** "Motion" — a motion row with no label */ motion?: string;
+    /** "Motion type" */ motionType?: string;
+    /** "Type" — the motion pane's row label beside that switch */ type?: string;
+    /** "Easing" */ easing?: string;
+    /** "Spring" */ spring?: string;
+    /** "Duration" */ duration?: string;
+    /** "Replay the motion" */ replay?: string;
+    /** "Easing · {ms} ms" */ easingSummary?: Word<{
+        ms: number;
+    }>;
+    /** "Spring · {ms} ms" */ springSummary?: Word<{
+        ms: number;
+    }>;
+    /** "Spring mode" */ springMode?: string;
+    /** "Mode" */ mode?: string;
+    /** "Time" */ time?: string;
+    /** "Physics" */ physics?: string;
+    /** "Stiffness" */ stiffness?: string;
+    /** "Damping" */ damping?: string;
+    /** "Mass" */ mass?: string;
+    /** "Bounce" */ bounce?: string;
+    /** "Shadow" — a shadow with no label */ shadow?: string;
+    /** "Shadow position" */ shadowPosition?: string;
+    /** "in" — an inset shadow's summary, before its numbers */ inset?: string;
+    /** "Position" */ position?: string;
+    /** "Outer" */ outer?: string;
+    /** "Inner" */ inner?: string;
+    /** "Blur" */ blur?: string;
+    /** "Spread" */ spread?: string;
+    /** "Top" */ top?: string;
+    /** "Right" */ right?: string;
+    /** "Bottom" */ bottom?: string;
+    /** "Left" */ left?: string;
+    /** "Top-left" */ topLeft?: string;
+    /** "Top-right" */ topRight?: string;
+    /** "Bottom-right" */ bottomRight?: string;
+    /** "Bottom-left" */ bottomLeft?: string;
+    /** "Independent sides" */ splitSides?: string;
+    /** "Independent corners" */ splitCorners?: string;
+}
 /** Panel options (third arg to `tweaks()`). */
 export interface TweaksOptions {
-    /** Theme overrides as `--tw-*` tokens; `null` / omitted = default monochrome. */
+    /** Theme overrides as `--twk-*` tokens; `null` / omitted = default monochrome. */
     theme?: Theme | null;
     /** Persist values to localStorage + enable presets — a key, or `true` to key by name. Uploaded images go to
      *  IndexedDB under the same key, and come back by `ready`. */
@@ -544,14 +720,28 @@ export interface TweaksOptions {
     undo?: boolean;
     /** Custom reset handler (e.g. restore real app defaults + rebuild). */
     onReset?: () => void;
+    /** Mount the panel in a shadow root, so page CSS can't restyle it (`#app button { … }`, a `.prose` wrapper). `el` is
+     *  then its host, a `<twk-host>`: theme it with `--twk-*` on the host itself (`.twk-host { … }`), or with `theme`.
+     *  The styles come from the page's `tweakit/css` when that's loaded, else from `href` (by default `tweaks.css` beside
+     *  the module). */
+    shadow?: boolean | {
+        href?: string;
+    };
+    /** The words the panel and its controls show and say, over the English defaults: translate them, or rename the chrome
+     *  (`{ presets: "Looks" }`). A key left out keeps its default. */
+    strings?: Strings;
+}
+/** Options for `enhance()`: the words its markup controls show and say. */
+export interface EnhanceOptions {
+    strings?: Strings;
 }
 /** The live values bag, loosely typed — `params[key]` for each control. A schema literal passed
  *  to `tweaks()` gets its exact shape instead (`ParamsOf`). */
 export type Params = Record<string, any>;
 /** The keys `set()` and `setMany()` take: a typed panel's controls by dotted path (`size`, `card.size`), so a typo is a
  *  compile error; any string for a panel built from a plain `Schema`. An object-valued control's own fields read as
- *  paths too (`drop.blur`): the types can't tell its value from a folder, so they allow what the runtime refuses. Past ten
- *  folders deep the rest of a path is any string, since spelling every one out overran tsc's depth limit. */
+ *  paths too (`drop.blur`): the types can't tell its value from a folder, so they allow what the runtime refuses. Past
+ *  ten folders deep the rest of a path is any string, since spelling every one out overran tsc's depth limit. */
 export type PanelPath<P> = PathsOf<P, []>;
 type PathsOf<P, D extends unknown[]> = string extends keyof P ? string : D["length"] extends 10 ? string : {
     [K in keyof P & string]: K | (P[K] extends readonly unknown[] ? never : P[K] extends object ? `${K}.${PathsOf<P[K], [...D, 0]>}` : never);
@@ -580,14 +770,15 @@ export interface PanelState {
 /** The panel object `tweaks()` returns; `P` is its values' shape. A bare `Panel` takes any panel, typed or not (its
  *  default is `any`, not `Params`: `set()`'s typed paths would make a typed panel unassignable to `Panel<Params>`). */
 export interface Panel<P = any> {
-    /** The panel root element — append it to the DOM. */
+    /** The panel root element — append it to the DOM. With `shadow`, the host the panel lives in. */
     el: HTMLElement;
     /** Live values, updated in place as controls change. */
     params: P;
     /** Resolves once any lazily-loaded controls have hydrated and, for a panel that persists an image control, its
      *  stored images have loaded (resolves immediately when there's neither). */
     ready: Promise<Panel<P>>;
-    /** Subscribe to changes; `last` is the changed control's dotted path (`size`, `card.size`), as `set()` and `changes()`
+    /** Subscribe to changes; `last` is the changed control's dotted path (`size`, `card.size`), as `set()` and
+     * `changes()`
      *  name it, or undefined when many changed at once (a restore, `reset()`, `fromJSON`, `setMany`). */
     on(fn: (params: P, last?: string) => void): () => void;
     /** Set a control's value programmatically. Nested controls take a dotted path
@@ -627,7 +818,8 @@ export interface Panel<P = any> {
      *  with stays its storage key (`persist: true`), so saved values and presets keep their
      *  home across a rename. */
     setName(name: string): void;
-    /** Save the current values as a named preset (needs `opts.persist`). False when there is nowhere to save it, or storage refused it. */
+    /** Save the current values as a named preset (needs `opts.persist`). False when there is nowhere to save it, or
+     * storage refused it. */
     savePreset(name: string): boolean;
     /** Load a named preset. */
     loadPreset(name: string): boolean;
@@ -638,7 +830,8 @@ export interface Panel<P = any> {
     /** Undo / redo (need `opts.undo`). */
     undo(): void;
     redo(): void;
-    /** Tear the panel down — remove it from the DOM, release every global listener, close any open popover; the API goes inert. */
+    /** Tear the panel down — remove it from the DOM, release every global listener, close any open popover; the API goes
+     * inert. */
     destroy(): void;
 }
 /** A built control's handle (internal-ish, but used across modules). */
@@ -665,12 +858,19 @@ export interface MountOptions {
     label?: string;
     /** Fired with the new value whenever the control changes — by hand or through `set()`. */
     onChange?: (value: unknown, key: string) => void;
+    /** Mount it in a shadow root, as `tweaks()`'s `shadow` does a panel; `el` is then the host. */
+    shadow?: boolean | {
+        href?: string;
+    };
+    /** Its words, as `tweaks()`'s `strings`. */
+    strings?: Strings;
 }
 /** The handle `mountControl()` returns. */
 export interface MountedControl {
-    /** The wrapper (`.tw-control`) the control lives in, already appended to the host and
+    /** The wrapper (`.twk-control`) the control lives in, already appended to the host and
      *  stable from creation — it carries the kit's tokens, so the control renders outside a
-     *  panel. On the code-split build a lazily-loaded control fills it in once `ready` resolves. */
+     *  panel. On the code-split build a lazily-loaded control fills it in once `ready` resolves. With `shadow`, the host
+     *  the wrapper lives in. */
     el: HTMLElement;
     /** Apply a value — the control updates AND `onChange` fires (when the value actually
      *  changed). Before `ready`, the value is queued and applied once the control builds. */
@@ -694,13 +894,19 @@ export interface ColorPickerOptions {
     mode?: ColorMode;
     /** Fired with the new color string whenever it changes — by hand or through `set()`. */
     onChange?: (value: string) => void;
+    /** Build it in a shadow root, as `tweaks()`'s `shadow` does a panel; `el` is then the host. */
+    shadow?: boolean | {
+        href?: string;
+    };
+    /** Its words, as `tweaks()`'s `strings`. */
+    strings?: Strings;
 }
 /** The handle `createColorPicker()` returns. Bring your own trigger: append `el` to a popover
  *  or a panel of your own; the kit owns the editor surface and the gamut math. */
 export interface ColorPicker {
-    /** The picker's root (`.tw-color-picker`), stable from creation; it carries the kit's tokens,
+    /** The picker's root (`.twk-color-picker`), stable from creation; it carries the kit's tokens,
      *  so the picker renders anywhere. On the code-split build the editor fills it in once the
-     *  color chunk has loaded. */
+     *  color chunk has loaded. With `shadow`, the host the root lives in. */
     el: HTMLElement;
     /** Apply a color — the picker updates AND `onChange` fires (when the color actually changed). */
     set(value: string): void;
@@ -718,7 +924,7 @@ export interface ColorPicker {
     /** Resolves with this handle once the editor has built — immediately on the single-file build. */
     ready: Promise<ColorPicker>;
 }
-/** `detail` of the `tw:change` event a `[data-tw]` host dispatches (bubbling) whenever its
+/** `detail` of the `twk:change` event a `[data-twk]` host dispatches (bubbling) whenever its
  *  control changes — `key` is the host's `data-key` (or its label), `value` the new value,
  *  also written to the host's `data-value`. */
 export interface TwChangeDetail {
@@ -727,7 +933,7 @@ export interface TwChangeDetail {
 }
 declare global {
     interface HTMLElementEventMap {
-        "tw:change": CustomEvent<TwChangeDetail>;
+        "twk:change": CustomEvent<TwChangeDetail>;
     }
 }
 export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tweakit",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "type": "module",
   "main": "./dist/tweaks/core.js",
   "types": "./dist/types/tweaks/core.d.ts",
@@ -32,7 +32,9 @@
     "prepublishOnly": "npm test",
     "prepack": "node build.mjs",
     "serve": "node build.mjs && python3 -m http.server 4330 --directory dist",
-    "test:browser": "node build.mjs && node --test \"test/browser/*.test.mjs\""
+    "test:browser": "node build.mjs && node --test \"test/browser/*.test.mjs\"",
+    "format": "prettier --write .",
+    "format:check": "prettier --check ."
   },
   "exports": {
     ".": {
@@ -83,6 +85,7 @@
     "fake-indexeddb": "^6.2.6",
     "jsdom": "^30.1.2",
     "playwright": "^1.64.1",
+    "prettier": "3.9.10",
     "typescript": "^7.0.2"
   }
 }

package/src/tweaks/auto.ts

@@ -1,12 +1,16 @@
-/* tweakit/auto: the code-split API, plus enhance(document) once the page has parsed. The bare import binds nothing, so a
- * page of [data-tw] markup with no script of its own imports this entry instead. Built on its own, unbundled, so it stays a
- * few lines over ./core.js rather than reshaping the split build's chunks. */
+/* tweakit/auto: the code-split API, plus enhance(document) once the page has parsed. The bare import binds nothing, so
+ * a
+ * page of [data-twk] markup with no script of its own imports this entry instead. Built on its own, unbundled, so it
+ * stays a few lines over ./core.js rather than reshaping the split build's chunks. */
 import { enhance } from "./core.js";
 export * from "./core.js";
 
-// A page with nothing to bind doesn't fetch the markup chunk: no [data-tw] host, and no static showcase panel (enhance() wraps one).
+// A page with nothing to bind doesn't fetch the markup chunk: no [data-twk] host, and no static showcase panel
+// (enhance() wraps one).
 if (typeof document !== "undefined") {
-  const run = () => { if (document.querySelector('[data-tw], .tw-panel[data-mode="inline"] > .tw-controls')) enhance(document); };
+  const run = () => {
+    if (document.querySelector('[data-twk], .twk-panel[data-mode="inline"] > .twk-controls')) enhance(document);
+  };
   if (document.readyState === "loading") document.addEventListener("DOMContentLoaded", run);
   else run();
 }