tweakit 0.1.0

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

@@ -0,0 +1,264 @@
+/** An option for a select / radio grid: a bare string, or `{ value, label }`. */
+export type Option = string | {
+    value: string;
+    label?: string;
+};
+/** A colour stop in a gradient. */
+export type GradientStop = {
+    color: string;
+    pos: number;
+};
+/** The CSS `<color-interpolation-method>` a gradient blends through — the space of the
+ *  mode the stops were authored in. Template it as `linear-gradient(in <interpolation> …)`
+ *  so your CSS ramp matches the editor's preview exactly. */
+export type GradientInterpolation = "srgb" | "hsl" | "hwb" | "oklch" | "oklab" | "lch" | "lab" | "display-p3" | "rec2020";
+/** Reader passed to a conditional `render` / `disabled` predicate — `get("siblingKey")`. */
+export type Get = (key: string) => unknown;
+/** Per-control extras that can ride on any object-form value. */
+export interface ControlOptions {
+    /** Show/hide this control based on other values. */
+    render?: (get: Get) => boolean;
+    /** Grey-out + lock this control (static, or derived from other values). */
+    disabled?: boolean | ((get: Get) => boolean);
+    /** A tooltip revealed by an ⓘ marker beside the label. */
+    hint?: string;
+}
+/** The verbose object forms a schema value can take: `{ type: "…", … }`. */
+export type SchemaObject = {
+    type: "slider";
+    value?: number;
+    min?: number;
+    max?: number;
+    step?: number;
+    soft?: boolean;
+} | {
+    type: "number";
+    value?: number;
+    min?: number;
+    max?: number;
+    step?: number;
+    soft?: boolean;
+} | {
+    type: "checkbox";
+    value?: boolean;
+} | {
+    type: "list";
+    options: Option[];
+    value?: string;
+} | {
+    type: "radiogrid" | "segmented";
+    options: Option[];
+    value?: string;
+    cols?: number;
+} | {
+    type: "color";
+    value?: string;
+    label?: string;
+} | {
+    type: "text";
+    value?: string;
+    rows?: number;
+    placeholder?: string;
+} | {
+    type: "interval";
+    value?: [number, number];
+    min?: number;
+    max?: number;
+    step?: number;
+} | {
+    type: "spring";
+    stiffness?: number;
+    damping?: number;
+    mass?: number;
+    value?: {
+        stiffness?: number;
+        damping?: number;
+        mass?: number;
+    };
+} | {
+    type: "cubicbezier";
+    value?: [number, number, number, number];
+} | {
+    type: "point";
+    components: Array<{
+        key: string;
+        label?: string;
+        value?: number;
+        min?: number;
+        max?: number;
+        step?: number;
+    }>;
+    pad?: boolean;
+    invertY?: boolean;
+} | {
+    type: "gradient";
+    value?: {
+        stops: GradientStop[];
+        interpolation?: GradientInterpolation;
+    } | Array<GradientStop | [string, number]>;
+} | {
+    type: "plot";
+    expr?: string;
+    fn?: (x: number) => number;
+    xMin?: number;
+    xMax?: number;
+    yMin?: number;
+    yMax?: number;
+    samples?: number;
+    editable?: boolean;
+} | {
+    type: "fpsgraph";
+    label?: string;
+} | {
+    type: "monitor";
+    get?: () => number | string;
+    value?: number | string;
+    graph?: boolean;
+    view?: "graph" | "text";
+    min?: number;
+    max?: number;
+    interval?: number;
+    rows?: number;
+    decimals?: number;
+} | {
+    type: "image";
+    value?: string;
+} | {
+    type: "button";
+    action: () => void;
+    label?: string;
+} | {
+    type: "buttongroup";
+    buttons: Record<string, () => void> | Array<{
+        label: string;
+        action: () => void;
+    }>;
+} | {
+    type: "separator";
+} | {
+    type: "tabs";
+    pages: Record<string, Schema>;
+};
+/** A schema value — a shorthand, a verbose `{ type }` object, or a nested folder. */
+export type SchemaValue = number | boolean | string | [number] | [number, number] | [number, number, number] | [number, number, number, number] | [[number, number], number, number] | [[number, number], number, number, number] | Option[] | (SchemaObject & ControlOptions) | Schema;
+/** The object you hand to `tweaks(name, schema, opts?)`. */
+export interface Schema {
+    [key: string]: SchemaValue;
+}
+/** 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.
+ *  Use the friendly names here, or any raw `--tw-*` custom property. 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). */
+    accent?: string;
+    /** Text drawn on the accent (active segment / radio label). Auto-derived from the accent's luminance if unset. */
+    onAccent?: string;
+    /** Panel background, reused for recessed wells. */
+    base?: string;
+    /** Popover / dropdown background. */
+    dropdownBg?: string;
+    /** Control surface and its hover / active steps. */
+    surface?: string;
+    surfaceHover?: string;
+    surfaceActive?: string;
+    /** Hairline border and its hover step. */
+    border?: string;
+    borderHover?: string;
+    /** Text-selection highlight wash. */
+    selection?: string;
+    /** Text tones — panel title, section heading, primary value text, control label, and the muted / faint / focus tones. */
+    title?: string;
+    section?: string;
+    text?: string;
+    label?: string;
+    textMuted?: string;
+    textFaint?: string;
+    focus?: string;
+    /** Copy-confirmation accent. */
+    success?: string;
+    /** Invalid-state accent (the plot's bad-expression cue). */
+    danger?: string;
+    /** Popover shadow, the panel's container elevation, and its lifted (floating / dragging) variant. */
+    shadow?: string;
+    shadowPanel?: string;
+    shadowPanelLifted?: string;
+    /** Font stack, and the monospace stack (the plot's expression field). */
+    font?: string;
+    fontMono?: string;
+    /** Control corner radius and row height — a bare number is treated as px. */
+    radius?: number | string;
+    density?: number | string;
+    /** Escape hatch — any raw token, e.g. `"--tw-accent": "#6c8cff"`. */
+    [token: string]: string | number | undefined;
+}
+/** Panel options (third arg to `tweaks()`). */
+export interface TweaksOptions {
+    /** Theme overrides (friendly names or raw `--tw-*`); `null` / omitted = default monochrome. */
+    theme?: Theme | null;
+    /** Persist values to localStorage + enable presets — a key, or `true` to key by name. */
+    persist?: string | boolean;
+    /** Add a filter/search field to the toolbar. */
+    filter?: boolean;
+    /** Start the panel already floated (fixed-positioned): `true` → top-left, or an explicit `{x,y}`. */
+    floating?: boolean | {
+        x: number;
+        y: number;
+    };
+    /** Drag the header to reposition the panel — on by default. An inline panel lifts into a
+     *  floating layer on first drag; set `false` to pin it in place. */
+    draggable?: boolean;
+    /** Set `false` for a bare panel (no copy/reset/presets toolbar). */
+    toolbar?: boolean;
+    /** Enable debounced undo/redo (⌘Z / ⇧⌘Z while the panel is hovered/focused). */
+    undo?: boolean;
+    /** Custom reset handler (e.g. restore real app defaults + rebuild). */
+    onReset?: () => void;
+    /** Fired when a drag/scrub on any control begins. */
+    onEditStart?: () => void;
+    /** Fired when a drag/scrub ends. */
+    onEditEnd?: () => void;
+}
+/** The live values bag — `params[key]` for each control; `_last` is the last-changed key. */
+export type Params = Record<string, any> & {
+    _last?: string;
+};
+/** The panel object `tweaks()` returns. */
+export interface Panel {
+    /** The panel root element — append it to the DOM. */
+    el: HTMLElement;
+    /** Live values, updated in place as controls change. */
+    params: Params;
+    /** Resolves once any lazily-loaded controls have hydrated (resolves immediately when none). */
+    ready: Promise<Panel>;
+    /** Subscribe to changes; returns an unsubscribe fn. */
+    on(fn: (params: Params, last?: string) => void): () => void;
+    /** Set a control's value programmatically. Nested controls take a dotted path
+     *  ("folder.child", "tabs.page.child"); a bare key also reaches a nested control
+     *  when it's unambiguous. A key matching no control is stored on `params` as-is. */
+    set(key: string, value: unknown): void;
+    /** Reset every control to its default (or run `opts.onReset`). */
+    reset(): void;
+    /** Re-theme the panel live; `null` reverts to the default. */
+    setTheme(theme?: Theme | null): void;
+    /** Save the current values as a named preset (needs `opts.persist`). */
+    savePreset(name: string): boolean;
+    /** Load a named preset. */
+    loadPreset(name: string): boolean;
+    /** Delete a named preset. */
+    deletePreset(name: string): void;
+    /** List saved preset names. */
+    presets(): string[];
+    /** 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. */
+    destroy(): void;
+}
+/** A built control's handle (internal-ish, but used across modules). */
+export interface Control {
+    el: HTMLElement;
+    set(value: unknown): void;
+    get(): unknown;
+}

package/dist/types/wide-gamut.d.ts

@@ -0,0 +1,121 @@
+export declare const num: (x: any) => any;
+export declare function convert(coords: any, from: any, to: any): any[];
+/** Map OKLCH into an RGB gamut (CSS Color 4 chroma reduction + local clip). */
+export declare function toGamut(oklch: any, dest: any): any;
+/** Fast in-gamut probe at a fixed hue — `(L,C)=>inside?` (his chroma-boundary loop). */
+export declare function oklchGamutProbe(hue: any, gamut: any): (L: any, C: any) => boolean;
+/** OKLCH→RGB at a fixed hue, folded for per-pixel rasterising: hoists cos/sin(hue) and
+ * collapses LMS→XYZ→RGB into one matrix once, then `(L, C, out)` writes the RGB straight
+ * into `out` (no per-pixel array alloc, no per-pixel trig). Algebraically identical to
+ * `convert([L,C,hue], "oklch", gamut)` — OKLAB_TO_LMS[i][0] is 1, so p_i = L + C·d_i, the
+ * same fold `oklchGamutProbe` ships. The picker's plane raster calls it once per repaint. */
+export declare function oklchToRgbFn(hue: any, gamut: any): (L: any, C: any, out: any) => void;
+/** Bisect the chroma ceiling at lightness L for an `oklchGamutProbe` — the highest
+ * in-gamut C. The picker traces its plane gamut, boundary lines, and hue strip with it. */
+export declare function chromaCeil(probe: any, L: any, hi?: number): number;
+/** One 0–1 channel → a 2-digit hex byte (also the alpha suffix for #RRGGBBAA). */
+export declare const hexByte: (n: any) => string;
+export declare const oklchToHex: (L: any, C: any, H: any) => string;
+export declare function hexToOklch(hex: any): any[];
+export declare const EDIT_MODES: string[];
+export declare const MODE_LABELS: {
+    hex: string;
+    srgb: string;
+    css: string;
+    hsl: string;
+    hwb: string;
+    oklch: string;
+    oklab: string;
+    lch: string;
+    lab: string;
+    p3: string;
+    rec2020: string;
+};
+export declare const showsGamutBoundary: (mode: any) => boolean;
+export declare const modeInterpolation: (mode: any) => any;
+export declare const interpolationMode: (interp: any) => any;
+export declare const MODE_CHANNELS: {
+    oklch: {
+        k: string;
+        min: number;
+        max: number;
+        step: number;
+        scale: number;
+    }[];
+    oklab: {
+        k: string;
+        min: number;
+        max: number;
+        step: number;
+        scale: number;
+    }[];
+    lch: {
+        k: string;
+        min: number;
+        max: number;
+        step: number;
+        scale: number;
+    }[];
+    lab: {
+        k: string;
+        min: number;
+        max: number;
+        step: number;
+        scale: number;
+    }[];
+    srgb: {
+        k: string;
+        min: number;
+        max: number;
+        step: number;
+        scale: number;
+    }[];
+    css: {
+        k: string;
+        min: number;
+        max: number;
+        step: number;
+        scale: number;
+    }[];
+    hsl: {
+        k: string;
+        min: number;
+        max: number;
+        step: number;
+        scale: number;
+    }[];
+    hwb: {
+        k: string;
+        min: number;
+        max: number;
+        step: number;
+        scale: number;
+    }[];
+    p3: {
+        k: string;
+        min: number;
+        max: number;
+        step: number;
+        scale: number;
+    }[];
+    rec2020: {
+        k: string;
+        min: number;
+        max: number;
+        step: number;
+        scale: number;
+    }[];
+};
+/** Display-unit channel values for `mode` from canonical OKLCH. */
+export declare function channelValues(oklch: any, mode: any): any;
+/** New OKLCH with channel `index` of `mode` set to `displayValue`. */
+export declare function withChannel(oklch: any, mode: any, index: any, displayValue: any): any[];
+/** Plain-text gamut label: sRGB / P3 / wide. */
+export declare function gamutLabel(oklch: any, mode: any): "P3" | "sRGB" | "wide";
+/** The collapsed-row value string for `mode` (bare channels w/ units, or hex). */
+export declare function readout(oklch: any, mode: any): string;
+/** The colour control's emitted CSS value — `mode`-faithful at the mode's display
+ * precision, alpha appended in that mode's own syntax. One form for opaque and
+ * translucent: a translucent rgb stays `rgb(… / a)` (it used to jump to `oklch()` at
+ * a different precision), and an opaque value reads back identically through parse. */
+export declare function serialize(oklch: any, mode: any, alpha: any): any;

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "tweakit",
+  "version": "0.1.0",
+  "type": "module",
+  "description": "A dependency-free, code-split real-time parameter panel — sliders, toggles, a wide-gamut OKLCH colour picker, curve editors and more, from a plain schema.",
+  "license": "MIT",
+  "author": "Ryan Kiley",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ryankiley/tweakit.git"
+  },
+  "homepage": "https://ryankiley.github.io/tweakit/",
+  "bugs": "https://github.com/ryankiley/tweakit/issues",
+  "keywords": [
+    "gui",
+    "panel",
+    "controls",
+    "parameters",
+    "debug",
+    "tweakpane",
+    "dat.gui",
+    "leva",
+    "oklch",
+    "color-picker",
+    "wide-gamut"
+  ],
+  "scripts": {
+    "build": "node build.mjs",
+    "test": "node build.mjs && node --test \"test/*.test.mjs\"",
+    "prepublishOnly": "node build.mjs && node --test \"test/*.test.mjs\"",
+    "serve": "node build.mjs && python3 -m http.server 4330 --directory dist"
+  },
+  "types": "./dist/types/tweaks/single.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/types/tweaks/single.d.ts",
+      "import": "./dist/tweaks.js"
+    },
+    "./core": {
+      "types": "./dist/types/tweaks/core.d.ts",
+      "import": "./dist/tweaks/core.js"
+    },
+    "./css": "./dist/tweaks.css"
+  },
+  "files": [
+    "dist/tweaks",
+    "dist/tweaks.js",
+    "dist/tweaks.css",
+    "dist/types",
+    "THIRD-PARTY-NOTICES.md"
+  ],
+  "devDependencies": {
+    "esbuild": "^0.28.0",
+    "jsdom": "^29.1.1",
+    "typescript": "^6.0.3"
+  }
+}