@stanko/ctrls 0.1.9 → 0.3.1

package/README.md

@@ -332,6 +332,40 @@ Example:
 
 </div>
 
+### Group
+
+Collapsible group of controls. All values are going to be nested in an object using the group's name.
+
+```ts
+{
+  // Mandatory
+  controls: ConfigItem[]
+}
+```
+
+Example:
+
+<div class="example">
+
+```json
+{
+  "type": "group",
+  "name": "color",
+  "controls": [
+    {
+      "type": "boolean",
+      "name": "monochrome"
+    },
+    {
+      "type": "easing",
+      "name": "distribution"
+    }
+  ]
+}
+```
+
+</div>
+
 ## Theming
 
 Ctrls uses CSS variables for theming. There are many you can adjust, but I recommend starting with these four:
@@ -389,7 +423,7 @@ Thank you for stopping by! If you end up using Ctrls, please let me know, I woul
 * [x] On input event / handler
 * [x] Revisit naming `controls` vs `options` vs `values`
 * [x] Remove lucide as a dependency, swap with local SVGs
-* [x] Add Aleas PRNG instead of seedrandom
+* [x] Add Alea PRNG instead of seedrandom
 * [x] Storage options - none
 * [x] Fix get random value float point error in dual range (modulo with floats)
 * [x] Easing - fix handles jumping to previous positions after selecting preset (no storage)

package/dist/ctrls/ctrl-boolean.d.ts

@@ -1,15 +1,17 @@
 import type { Ctrl, CtrlType, CtrlChangeHandler, CtrlConfig } from ".";
 export declare class BooleanCtrl implements Ctrl<boolean> {
     type: CtrlType;
+    id: string;
+    group?: string;
     name: string;
     label: string;
     value: boolean;
     isRandomizationDisabled: boolean;
-    onChange: CtrlChangeHandler<boolean>;
-    onInput: CtrlChangeHandler<boolean>;
+    onChange: CtrlChangeHandler;
+    onInput: CtrlChangeHandler;
     element: HTMLElement;
     input: HTMLInputElement;
-    constructor(config: CtrlConfig<boolean>, onChange: CtrlChangeHandler<boolean>, onInput: CtrlChangeHandler<boolean>);
+    constructor(config: CtrlConfig<boolean>, onChange: CtrlChangeHandler, onInput: CtrlChangeHandler);
     parse: (string: string) => string is "true";
     getRandomValue: () => boolean;
     getDefaultValue: () => boolean;

package/dist/ctrls/ctrl-boolean.js

@@ -25,11 +25,11 @@ export class BooleanCtrl {
             input.checked = this.value;
             input.addEventListener("change", () => {
                 this.value = input.checked;
-                this.onChange(this.name, this.value);
+                this.onChange(this);
             });
             input.addEventListener("input", () => {
                 this.value = input.checked;
-                this.onInput(this.name, this.value);
+                this.onInput(this);
             });
             const checkmark = document.createElement("span");
             checkmark.classList.add("ctrls__boolean-checkmark");
@@ -56,6 +56,8 @@ export class BooleanCtrl {
         };
         this.type = "boolean";
         this.name = config.name;
+        this.id = config.id || config.name;
+        this.group = config.group || "";
         this.label = config.label || config.name;
         this.value =
             config.defaultValue === undefined

package/dist/ctrls/ctrl-dual-range.d.ts

@@ -11,12 +11,14 @@ export type DualRangeValue = {
 };
 export declare class DualRangeCtrl implements Ctrl<DualRangeValue> {
     type: CtrlType;
+    id: string;
+    group?: string;
     name: string;
     label: string;
     value: DualRangeValue;
     isRandomizationDisabled: boolean;
-    onChange: CtrlChangeHandler<DualRangeValue>;
-    onInput: CtrlChangeHandler<DualRangeValue>;
+    onChange: CtrlChangeHandler;
+    onInput: CtrlChangeHandler;
     min: number;
     max: number;
     step: number;
@@ -25,7 +27,7 @@ export declare class DualRangeCtrl implements Ctrl<DualRangeValue> {
     maxInput: HTMLInputElement;
     dualRange: DualRangeInput;
     valueSpan: HTMLSpanElement;
-    constructor(config: ConfigFor<"dual-range">, onChange: CtrlChangeHandler<DualRangeValue>, onInput: CtrlChangeHandler<DualRangeValue>);
+    constructor(config: ConfigFor<"dual-range">, onChange: CtrlChangeHandler, onInput: CtrlChangeHandler);
     parse: (string: string) => {
         min: number;
         max: number;

package/dist/ctrls/ctrl-dual-range.js

@@ -36,7 +36,7 @@ export class DualRangeCtrl {
                     max: parseFloat(maxInput.value),
                 };
                 this.update(this.value);
-                this.onChange(this.name, this.value);
+                this.onChange(this);
             };
             const inputHandler = () => {
                 this.value = {
@@ -44,7 +44,7 @@ export class DualRangeCtrl {
                     max: parseFloat(maxInput.value),
                 };
                 this.update(this.value);
-                this.onInput(this.name, this.value);
+                this.onInput(this);
             };
             const minInput = document.createElement("input");
             minInput.setAttribute("type", "range");
@@ -101,6 +101,8 @@ export class DualRangeCtrl {
             this.dualRange.update();
         };
         this.name = config.name;
+        this.id = config.id || config.name;
+        this.group = config.group || "";
         this.label = config.label || config.name;
         this.min = config.min;
         this.max = config.max;

package/dist/ctrls/ctrl-easing.d.ts

@@ -2,12 +2,14 @@ import type { Ctrl, CtrlChangeHandler, CtrlType, ConfigFor } from ".";
 export type Easing = [number, number, number, number];
 export declare class EasingCtrl implements Ctrl<Easing> {
     type: CtrlType;
+    id: string;
+    group?: string;
     name: string;
     label: string;
     value: Easing;
     isRandomizationDisabled: boolean;
-    onChange: CtrlChangeHandler<Easing>;
-    onInput: CtrlChangeHandler<Easing>;
+    onChange: CtrlChangeHandler;
+    onInput: CtrlChangeHandler;
     element: HTMLElement;
     ticks: SVGLineElement[];
     control: HTMLDivElement;
@@ -15,7 +17,7 @@ export declare class EasingCtrl implements Ctrl<Easing> {
     lines: SVGLineElement[];
     path: SVGPathElement;
     presets: Record<string, Easing>;
-    constructor(config: ConfigFor<"easing">, onChange: CtrlChangeHandler<Easing>, onInput: CtrlChangeHandler<Easing>);
+    constructor(config: ConfigFor<"easing">, onChange: CtrlChangeHandler, onInput: CtrlChangeHandler);
     parse: (string: string) => Easing;
     getRandomValue: () => Easing;
     getDefaultValue: () => Easing;

package/dist/ctrls/ctrl-easing.js

@@ -117,14 +117,14 @@ export class EasingCtrl {
                         dragging = false;
                         const newValue = getNewValue(e.clientX, e.clientY);
                         this.value = newValue;
-                        this.onChange(this.name, this.value);
+                        this.onChange(this);
                         this.update();
                     }
                 });
                 document.addEventListener("mousemove", (e) => {
                     if (dragging) {
                         const newValue = getNewValue(e.clientX, e.clientY);
-                        this.onInput(this.name, this.value);
+                        this.onInput(this);
                         this.updateUI(newValue);
                     }
                 });
@@ -145,7 +145,7 @@ export class EasingCtrl {
                     if (dragging) {
                         e.preventDefault();
                         const newValue = getNewValue(e.touches[0].clientX, e.touches[0].clientY);
-                        this.onInput(this.name, this.value);
+                        this.onInput(this);
                         this.updateUI(newValue);
                     }
                 });
@@ -155,7 +155,7 @@ export class EasingCtrl {
                         dragging = false;
                         const newValue = getNewValue(e.changedTouches[0].clientX, e.changedTouches[0].clientY);
                         this.value = newValue;
-                        this.onChange(this.name, this.value);
+                        this.onChange(this);
                         this.update();
                     }
                 });
@@ -175,7 +175,7 @@ export class EasingCtrl {
                         // Cap x values
                         newValue[index] = Math.max(Math.min(newValue[index], 1), 0);
                         this.value = newValue;
-                        this.onChange(this.name, this.value);
+                        this.onChange(this);
                         this.update();
                     }
                 });
@@ -192,7 +192,7 @@ export class EasingCtrl {
                     button.textContent = key.toLowerCase().replace("ease_", "");
                     button.addEventListener("click", () => {
                         this.value = this.presets[key];
-                        this.onChange(this.name, this.value);
+                        this.onChange(this);
                         this.update();
                     });
                     presetButtons.appendChild(button);
@@ -270,6 +270,8 @@ export class EasingCtrl {
             this.element.setAttribute("data-value", value.join(","));
         };
         this.name = config.name;
+        this.id = config.id || config.name;
+        this.group = config.group || "";
         this.label = config.label || config.name;
         this.value =
             config.defaultValue === undefined

package/dist/ctrls/ctrl-radio.d.ts

@@ -8,17 +8,19 @@ export type RadioControlOptions = {
 };
 export declare class RadioCtrl implements Ctrl<string> {
     type: CtrlType;
+    htmlId: string;
+    id: string;
+    group?: string;
     name: string;
     label: string;
     value: string;
     isRandomizationDisabled: boolean;
-    onChange: CtrlChangeHandler<string>;
-    onInput: CtrlChangeHandler<string>;
+    onChange: CtrlChangeHandler;
+    onInput: CtrlChangeHandler;
     items: Option[];
     element: HTMLElement;
     columns: 1 | 2 | 3 | 4 | 5;
-    id: string;
-    constructor(config: ConfigFor<"radio">, onChange: CtrlChangeHandler<string>, onInput: CtrlChangeHandler<string>);
+    constructor(config: ConfigFor<"radio">, onChange: CtrlChangeHandler, onInput: CtrlChangeHandler);
     parse: (string: string) => string;
     getRandomValue: () => string;
     getDefaultValue: () => string;

package/dist/ctrls/ctrl-radio.js

@@ -23,17 +23,17 @@ export class RadioCtrl {
             const inputs = items.map((item) => {
                 const input = document.createElement("input");
                 input.setAttribute("type", "radio");
-                input.setAttribute("name", this.id);
-                input.setAttribute("id", `${this.id}-${toKebabCase(item.value)}`);
+                input.setAttribute("name", this.htmlId);
+                input.setAttribute("id", `${this.htmlId}-${toKebabCase(item.value)}`);
                 input.setAttribute("value", item.value);
                 input.checked = item.value === value;
                 input.addEventListener("change", () => {
                     this.value = this.parse(input.value);
-                    this.onChange(this.name, this.value);
+                    this.onChange(this);
                 });
                 input.addEventListener("input", () => {
                     this.value = this.parse(input.value);
-                    this.onInput(this.name, this.value);
+                    this.onInput(this);
                 });
                 const label = document.createElement("span");
                 label.textContent = item.label;
@@ -77,8 +77,10 @@ export class RadioCtrl {
         });
         this.columns = config.columns || 3;
         this.name = config.name;
+        this.id = config.id || config.name;
+        this.group = config.group || "";
         this.label = config.label || config.name;
-        this.id = `ctrls__${toKebabCase(config.name)}-${getRandomString()}`;
+        this.htmlId = `ctrls__${toKebabCase(config.name)}-${getRandomString()}`;
         const defaultValue = this.items.find((item) => item.value === config.defaultValue);
         this.value = defaultValue?.value || this.getDefaultValue();
         this.isRandomizationDisabled = config.isRandomizationDisabled || false;

package/dist/ctrls/ctrl-range.d.ts

@@ -1,19 +1,21 @@
 import type { Ctrl, CtrlChangeHandler, CtrlType, ConfigFor } from ".";
 export declare class RangeCtrl implements Ctrl<number> {
     type: CtrlType;
+    id: string;
+    group?: string;
     name: string;
     label: string;
     value: number;
     isRandomizationDisabled: boolean;
-    onChange: CtrlChangeHandler<number>;
-    onInput: CtrlChangeHandler<number>;
+    onChange: CtrlChangeHandler;
+    onInput: CtrlChangeHandler;
     min: number;
     max: number;
     step: number;
     element: HTMLElement;
     input: HTMLInputElement;
     valueSpan: HTMLSpanElement;
-    constructor(config: ConfigFor<"range">, onChange: CtrlChangeHandler<number>, onInput: CtrlChangeHandler<number>);
+    constructor(config: ConfigFor<"range">, onChange: CtrlChangeHandler, onInput: CtrlChangeHandler);
     parse: (string: string) => number;
     getRandomValue: () => number;
     getDefaultValue: () => number;

package/dist/ctrls/ctrl-range.js

@@ -33,12 +33,12 @@ export class RangeCtrl {
             input.addEventListener("input", () => {
                 this.value = this.parse(input.value);
                 this.update(this.value);
-                this.onInput(this.name, this.value);
+                this.onInput(this);
             });
             input.addEventListener("change", () => {
                 this.value = this.parse(input.value);
                 this.update(this.value);
-                this.onChange(this.name, this.value);
+                this.onChange(this);
             });
             input.addEventListener("input", () => {
                 const value = this.parse(input.value);
@@ -73,6 +73,8 @@ export class RangeCtrl {
             this.element.style.setProperty("--gradient-position", `${percentage.toFixed(2)}%`);
         };
         this.name = config.name;
+        this.id = config.id || config.name;
+        this.group = config.group || "";
         this.label = config.label || config.name;
         this.isRandomizationDisabled = config.isRandomizationDisabled || false;
         this.onChange = onChange;

package/dist/ctrls/ctrl-seed.d.ts

@@ -1,15 +1,17 @@
 import type { Ctrl, CtrlChangeHandler, CtrlConfig, CtrlType } from ".";
 export declare class SeedCtrl implements Ctrl<string> {
     type: CtrlType;
+    id: string;
+    group?: string;
     name: string;
     label: string;
     value: string;
     isRandomizationDisabled: boolean;
-    onChange: CtrlChangeHandler<string>;
-    onInput: CtrlChangeHandler<string>;
+    onChange: CtrlChangeHandler;
+    onInput: CtrlChangeHandler;
     element: HTMLElement;
     input: HTMLInputElement;
-    constructor(config: CtrlConfig<string>, onChange: CtrlChangeHandler<string>, onInput: CtrlChangeHandler<string>);
+    constructor(config: CtrlConfig<string>, onChange: CtrlChangeHandler, onInput: CtrlChangeHandler);
     parse: (string: string) => string;
     getRandomValue: () => string;
     getDefaultValue: () => string;

package/dist/ctrls/ctrl-seed.js

@@ -30,11 +30,11 @@ export class SeedCtrl {
             input.setAttribute("name", id);
             input.addEventListener("change", () => {
                 this.value = this.parse(input.value);
-                this.onChange(this.name, this.value);
+                this.onChange(this);
             });
             input.addEventListener("input", () => {
                 this.value = this.parse(input.value);
-                this.onInput(this.name, this.value);
+                this.onInput(this);
             });
             const reload = document.createElement("button");
             reload.innerHTML = refreshIcon;
@@ -42,7 +42,7 @@ export class SeedCtrl {
             reload.addEventListener("click", () => {
                 this.value = this.getRandomValue();
                 this.update();
-                this.onChange(this.name, this.getRandomValue());
+                this.onChange(this);
             });
             const right = document.createElement("div");
             right.classList.add("ctrls__control-right");
@@ -66,6 +66,8 @@ export class SeedCtrl {
             this.input.value = value;
         };
         this.name = config.name;
+        this.id = config.id || config.name;
+        this.group = config.group || "";
         this.label = config.label || config.name;
         this.value =
             config.defaultValue === undefined

package/dist/ctrls/index.d.ts

@@ -8,21 +8,25 @@ import { SeedCtrl } from "./ctrl-seed";
 export interface PRNG {
     (): number;
 }
-export type CtrlType = "boolean" | "range" | "radio" | "seed" | "easing" | "dual-range";
-export type CtrlChangeHandler<T> = (name: string, value: T) => void;
+export type CtrlType = "boolean" | "range" | "radio" | "seed" | "easing" | "dual-range" | "group";
+export type CtrlChangeHandler = (control: CtrlComponent) => void;
 export type CtrlConfig<T = unknown> = {
     type: CtrlType;
+    id?: string;
     name: string;
+    group?: string;
     label?: string;
     defaultValue?: T;
     isRandomizationDisabled?: boolean;
 };
 export interface Ctrl<T> {
+    id: string;
+    group?: string;
     name: string;
     label: string;
     type: CtrlType;
     isRandomizationDisabled: boolean;
-    onChange: CtrlChangeHandler<T>;
+    onChange: CtrlChangeHandler;
     parse: (value: string) => T;
     getRandomValue: () => T;
     getDefaultValue: () => T;
@@ -59,23 +63,44 @@ export interface CtrlTypeMap {
         max: number;
         step?: number;
     };
+    group: {
+        value: Record<string, unknown>;
+        controls: readonly ConfigItem[];
+        isRandomizationDisabled?: boolean;
+    };
 }
 export type TypedControlConfig = {
     [K in CtrlType]: {
         type: K;
+        id?: string;
         name: string;
+        group?: string;
         label?: string;
         defaultValue?: CtrlTypeMap[K]["value"];
         isRandomizationDisabled?: boolean;
     } & Omit<CtrlTypeMap[K], "value">;
 }[CtrlType];
+export type GroupConfig = {
+    type: "group";
+    name: string;
+    label?: string;
+    controls: readonly TypedControlConfig[];
+    isRandomizationDisabled?: boolean;
+};
+export type ConfigItem = TypedControlConfig | GroupConfig;
 export type ConfigFor<T extends CtrlType> = Extract<TypedControlConfig, {
     type: T;
 }>;
-type ExtractValues<Configs extends readonly TypedControlConfig[]> = {
-    [C in Configs[number] as C["name"]]: CtrlTypeMap[C["type"]]["value"];
+type ExtractValues<Configs extends readonly ConfigItem[]> = {
+    [C in Extract<Configs[number], {
+        type: Exclude<CtrlType, "group">;
+    }> as C["name"]]: CtrlTypeMap[C["type"]]["value"];
+} & {
+    [C in Extract<Configs[number], {
+        type: "group";
+    }> as C["name"]]: OptionsMap<C["controls"]>;
 };
-type DerivedProps<Configs extends readonly TypedControlConfig[]> = {
+type DerivedProps<Configs extends readonly ConfigItem[]> = {
     [C in Extract<Configs[number], {
         type: "easing";
     }> as `${C["name"]}Easing`]: ReturnType<typeof BezierEasing>;
@@ -83,8 +108,12 @@ type DerivedProps<Configs extends readonly TypedControlConfig[]> = {
     [C in Extract<Configs[number], {
         type: "seed";
     }> as `${C["name"]}Rng`]: PRNG;
+} & {
+    [C in Extract<Configs[number], {
+        type: "group";
+    }> as C["name"]]: DerivedProps<C["controls"]>;
 };
-type OptionsMap<Configs extends readonly TypedControlConfig[]> = ExtractValues<Configs> & DerivedProps<Configs>;
+type OptionsMap<Configs extends readonly ConfigItem[]> = ExtractValues<Configs> & DerivedProps<Configs>;
 type ControlsOptions = {
     showRandomizeButton?: boolean;
     storage?: "hash" | "none";
@@ -93,20 +122,22 @@ type ControlsOptions = {
     title?: string;
 };
 type CtrlComponent = BooleanCtrl | RangeCtrl | RadioCtrl | SeedCtrl | EasingCtrl | DualRangeCtrl;
-export declare class Ctrls<Configs extends readonly TypedControlConfig[]> {
+export declare class Ctrls<Configs extends readonly ConfigItem[]> {
     options: ControlsOptions;
     controls: CtrlComponent[];
     controlsMap: Record<string, CtrlComponent>;
     element: HTMLDivElement;
     onChange?: (updatedValues: Partial<ReturnType<typeof this.getValues>>) => void;
     onInput?: (updatedValues: Partial<ReturnType<typeof this.getValues>>) => void;
-    constructor(controls: Configs, options?: ControlsOptions);
+    constructor(configs: Configs, options?: ControlsOptions);
+    registerControl: (config: TypedControlConfig, onChangeControlHandler: (control: CtrlComponent) => void, onInputControlHandler: (control: CtrlComponent) => void, group?: string) => void;
     buildUI: () => HTMLDivElement;
     toggleVisibility: () => void;
     addHashListeners: () => void;
     getHash: () => string;
     setHash: () => void;
     updateFromHash: () => void;
+    updateValuesObject(values: any, control: CtrlComponent): void;
     getValues(): OptionsMap<Configs>;
     randomize: () => void;
 }

package/dist/ctrls/index.js

@@ -17,16 +17,65 @@ const controlMap = {
     "dual-range": DualRangeCtrl,
 };
 export class Ctrls {
-    constructor(controls, options) {
+    constructor(configs, options) {
+        this.controls = [];
         this.controlsMap = {};
+        this.registerControl = (config, onChangeControlHandler, onInputControlHandler, group = "") => {
+            // To make typescript happy
+            if (config.type === "group") {
+                return;
+            }
+            // TODO
+            // Again, document as it is my personal preference
+            if (!config.label) {
+                config.label = toSpaceCase(config.name);
+            }
+            // TODO
+            // Document this behaviour
+            // This might counter-intuitive for some people,
+            // but it is my personal preference to have properties named in camel case
+            // when using them in code
+            //
+            // However, they are going to be converted to kebab case when used in the hash,
+            // because it is nicer that URL be all lowercase
+            config.name = toCamelCase(config.name);
+            if (group) {
+                config.group = group;
+                config.id = toCamelCase(`${group}-${config.name}`);
+            }
+            const ControlComponent = controlMap[config.type];
+            const control = new ControlComponent(config, onChangeControlHandler, onInputControlHandler);
+            this.controlsMap[control.id] = control;
+            this.controls.push(control);
+        };
         this.buildUI = () => {
             const element = document.createElement("div");
             element.classList.add("ctrls");
             element.classList.add(`ctrls--${this.options.theme}-theme`);
             const controlsContainer = document.createElement("div");
             controlsContainer.classList.add("ctrls__controls");
+            let group = "";
+            let groupElement;
             this.controls.forEach((control) => {
-                controlsContainer.appendChild(control.element);
+                if (control.group) {
+                    if (control.group !== group) {
+                        group = control.group;
+                        groupElement = document.createElement("div");
+                        groupElement.classList.add("ctrls__group");
+                        const groupTitle = document.createElement("button");
+                        groupTitle.classList.add("ctrls__group-title");
+                        groupTitle.innerText = control.group;
+                        groupTitle.addEventListener("click", () => {
+                            groupTitle.parentElement?.classList.toggle("ctrls__group--hidden");
+                        });
+                        groupElement.append(groupTitle);
+                        controlsContainer.appendChild(groupElement);
+                    }
+                    groupElement.append(control.element);
+                }
+                else {
+                    controlsContainer.appendChild(control.element);
+                }
             });
             if (this.options.showRandomizeButton) {
                 const randomizeButton = document.createElement("button");
@@ -59,7 +108,7 @@ export class Ctrls {
         this.getHash = () => {
             const values = this.controls
                 .map((control) => {
-                return `${toKebabCase(control.name)}:${control.valueToString()}`;
+                return `${toKebabCase(control.id)}:${control.valueToString()}`;
             })
                 .join("/");
             return `#/${values}`;
@@ -73,22 +122,22 @@ export class Ctrls {
             const items = [];
             pairs.forEach((pair) => {
                 const [kebabCaseName, value] = pair.split(":");
-                const name = toCamelCase(kebabCaseName);
-                const control = this.controlsMap[name];
+                const id = toCamelCase(kebabCaseName);
+                const control = this.controlsMap[id];
                 if (control) {
                     const parsed = control.parse(value);
                     items.push({
-                        name,
+                        id,
                         value: parsed,
                     });
                 }
             });
             const updatedValues = {};
             items.forEach((item) => {
-                const { name, value } = item;
-                const control = this.controlsMap[name];
+                const { id, value } = item;
+                const control = this.controlsMap[id];
                 if (control && JSON.stringify(value) !== JSON.stringify(control.value)) {
-                    updatedValues[name] = value;
+                    this.updateValuesObject(updatedValues, control);
                     control.update(value);
                 }
             });
@@ -105,7 +154,7 @@ export class Ctrls {
                 }
                 control.value = control.getRandomValue();
                 control.update(control.value);
-                updatedValues[control.name] = control.value;
+                this.updateValuesObject(updatedValues, control);
             });
             if (Object.keys(updatedValues).length > 0) {
                 this.onChange?.(updatedValues);
@@ -121,34 +170,28 @@ export class Ctrls {
             theme: "system",
             ...options,
         };
-        const onChangeControlHandler = (name, value) => {
-            this.onChange?.({ [name]: value });
+        const onChangeControlHandler = (control) => {
+            const updatedValues = {};
+            this.updateValuesObject(updatedValues, control);
+            this.onChange?.(updatedValues);
             if (this.options.storage === "hash") {
                 this.setHash();
             }
         };
-        const onInputControlHandler = (name, value) => {
-            this.onInput?.({ [name]: value });
+        const onInputControlHandler = (control) => {
+            const updatedValues = {};
+            this.updateValuesObject(updatedValues, control);
+            this.onInput?.(updatedValues);
         };
-        this.controls = controls.map((config) => {
-            // TODO
-            // Document this behaviour
-            // This might counter-intuitive for some people,
-            // but it is my personal preference to have properties named in camel case
-            // when using them in code
-            //
-            // However, they are going to be converted to kebab case when used in the hash,
-            // because it is nicer that URL be all lowercase
-            config.name = toCamelCase(config.name);
-            // TODO
-            // Again, document as it is my personal preference
-            if (!config.label) {
-                config.label = toSpaceCase(config.name);
+        configs.map((config) => {
+            if (config.type === "group") {
+                config.controls.forEach((groupConfig) => {
+                    this.registerControl(groupConfig, onChangeControlHandler, onInputControlHandler, toCamelCase(config.name));
+                });
+            }
+            else {
+                this.registerControl(config, onChangeControlHandler, onInputControlHandler);
             }
-            const ControlComponent = controlMap[config.type];
-            const control = new ControlComponent(config, onChangeControlHandler, onInputControlHandler);
-            this.controlsMap[control.name] = control;
-            return control;
         });
         this.element = this.buildUI();
         if (this.options.storage === "hash") {
@@ -158,17 +201,27 @@ export class Ctrls {
             this.options.parent.appendChild(this.element);
         }
     }
+    updateValuesObject(values, control) {
+        let objectToUpdate = values;
+        if (control.group) {
+            if (!values[control.group]) {
+                values[control.group] = {};
+            }
+            objectToUpdate = values[control.group];
+        }
+        objectToUpdate[control.name] = control.value;
+        if (control.type === "easing") {
+            objectToUpdate[control.name + "Easing"] = BezierEasing(...control.value);
+        }
+        else if (control.type === "seed") {
+            objectToUpdate[control.name + "Rng"] = Alea(...control.value.split("-"));
+        }
+    }
     getValues() {
-        const options = {};
+        const values = {};
         this.controls.forEach((control) => {
-            options[control.name] = control.value;
-            if (control.type === "easing") {
-                options[control.name + "Easing"] = BezierEasing(...control.value);
-            }
-            else if (control.type === "seed") {
-                options[control.name + "Rng"] = Alea(control.value);
-            }
+            this.updateValuesObject(values, control);
         });
-        return options;
+        return values;
     }
 }

package/dist/ctrls.css

@@ -170,8 +170,8 @@
     ui-monospace, "Cascadia Code", "Source Code Pro", Menlo, Consolas,
     "DejaVu Sans Mono", monospace;
   --ctrls-radius: 4px;
-  --ctrls-label-width: 5rem;
-  --ctrls-width: 22rem;
+  --ctrls-label-width: 7rem;
+  --ctrls-width: 24rem;
   --ctrls-font-size: 0.75rem;
   --ctrls-value-font-size: 0.6875rem;
   --ctrls-c: 0.25;
@@ -301,6 +301,7 @@
   overflow: visible;
 }
 
+.ctrls__group-title,
 .ctrls__title {
   background: none;
   border: none;
@@ -312,15 +313,17 @@
   cursor: pointer;
   transition: color 300ms, background-color 300ms;
 }
-.ctrls__title:focus-visible, .ctrls__title:hover {
+.ctrls__group-title:focus-visible, .ctrls__group-title:hover,
+.ctrls__title:focus-visible,
+.ctrls__title:hover {
   color: var(--ctrls-theme);
   background: var(--ctrls-btn-hover-bg);
 }
 
 .ctrls__controls {
   display: grid;
+  padding-block: 0.5rem;
   gap: 0.5rem;
-  padding: 0.5rem;
   overflow: auto;
   scrollbar-width: thin;
   scrollbar-color: var(--ctrls-scrollbar-thumb-bg) transparent;
@@ -330,6 +333,10 @@
   display: none;
 }
 
+.ctrls--hidden .ctrls__title {
+  border-block-end: none;
+}
+
 /* ----- Buttons ----- */
 .ctrls__btn {
   background: none;
@@ -355,7 +362,8 @@
 }
 
 .ctrls__btn--lg {
-  margin-left: var(--ctrls-label-width);
+  margin-inline-start: calc(var(--ctrls-label-width) + 0.5rem);
+  margin-inline-end: 0.5rem;
   padding: 0.5rem 1rem;
   background: var(--ctrls-btn-bg);
   border: 1px solid var(--ctrls-input-border);
@@ -375,8 +383,40 @@
   opacity: 0;
 }
 
-/* ----- General ----- */
+/* ----- Groups ----- */
+.ctrls__group {
+  margin: 0 0.5rem;
+  display: grid;
+  gap: 0.5rem;
+  padding-block-end: 0.5rem;
+  border: 1px solid var(--ctrls-border);
+  border-radius: var(--ctrls-radius);
+}
+
+.ctrls__group .ctrls__control {
+  grid-template-columns: calc(var(--ctrls-label-width) - 0.5rem) minmax(0, 1fr);
+}
+
+.ctrls__group:has(+ .ctrls__group) {
+  border-block-end: none;
+  margin-block-end: 0;
+}
+
+.ctrls__group-title {
+  text-align: left;
+}
+
+.ctrls__group--hidden {
+  padding-block-end: 0;
+}
+
+.ctrls__group--hidden .ctrls__control {
+  display: none;
+}
+
+/* ----- Controls ----- */
 .ctrls__control {
+  padding-inline: 0.5rem;
   display: grid;
   grid-template-columns: var(--ctrls-label-width) minmax(0, 1fr);
   align-items: center;

package/dist/ctrls.css.map

@@ -1 +1 @@
-{"version":3,"sourceRoot":"","sources":["../node_modules/@stanko/dual-range-input/dist/index.css","../src/scss/_ctrls.scss"],"names":[],"mappings":"AAAA;EACE;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;;;AAEF;EACE;EACA;EACA;;;AAEF;EACE;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;;;AAEF;EACE;EACA;EACA;EACA;;;AAEF;EACE;EACA;EACA;;;AAEF;EACE;;;AAEF;EACE;EACA;EACA;;;AAEF;EACE;;;AAEF;EACE;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;;;AAEF;EACE;;;AAEF;EACE;EACA;;;AAEF;EACE;EACA;;;AAEF;EACE;EACA;;;AAEF;EACE;EACA;EACA;EACA;;;AAEF;EACE;EACA;EACA;;;AAEF;EACE;;;AAEF;EACE;EACA;EACA;;;AAEF;EACE;;;AAEF;EACE;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;;;AAEF;EACE;;;AAEF;EACE;EACA;;;AAEF;EACE;EACA;;;AAEF;EACE;EACA;;;;AC3IF;EACE;AAAA;AAAA;EAGA;EACA;EACA;EACA;EACA;EAGA;EACA;EAEA;EACA;EAGA;EACA;EACA;EACA;EACA;EACA;EAGA;EAGA;EACA;EACA;EAGA;EACA;EAGA;EAGA;EAEA;EACA;EAEA;EACA;EAGA;EAGA;EACA;EAEA;EACA;EAEA;EACA;EACA;EACA;EAGA;EACA;EAEA;EAEA;EACA;EAEA;EAGA;EAEA;EACA;;;AA+CF;EACE;IA3CA;IAEA;IACA;IAGA;IACA;IACA;IACA;IACA;IACA;IAGA;IAGA;IACA;IACA;IAGA;IACA;IAGA;IAGA;IAEA;IAGA;IAGA;AAAA;AAAA;;;AAWF;EAhDE;EAEA;EACA;EAGA;EACA;EACA;EACA;EACA;EACA;EAGA;EAGA;EACA;EACA;EAGA;EACA;EAGA;EAGA;EAEA;EAGA;EAGA;AAAA;AAAA;;;AAiBF;EACE;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;;AAEA;AAAA;AAAA;EAGE;EACA;EACA;;AAGF;AAAA;EAEE;EACA;EACA;;AAGF;EACE;EACA;;;AAIJ;EACE;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA,YACE;;AAGF;EAEE;EACA;;;AAIJ;EACE;EACA;EACA;EACA;EACA;EACA;;;AAGF;EACE;;;AAGF;AAGA;EACE;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA,YACE;;AAGF;EAEE;;AAGF;EACE;EACA;EACA,YACE;;AAIJ;EACE;;;AAKJ;EACE;EACA;EACA;EACA;EACA;;AAEA;EAEE;EACA;;;AAOA;EACE;;AAGF;AAAA;AAAA;EAEE;;;AAKN;AAEA;EACE;EACA;EACA;EACA;;;AAGF;EACE;EACA;EACA;EACA;;;AAGF;EACE;EACA;;;AAGF;EACE;EACA;;;AAKA;AAAA;EACE;EACA;EACA;;;AAIJ;AAEA;EACE;EACA;EACA;EACA;;;AAGF;EACE;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;;AAEA;EACE;EACA;EACA;;;AAKJ;EACE;EACA;EACA;;;AAIF;EACE;;;AAIF;EACE;;;AAIF;EACE;EACA;;;AAGF;AAEA;EACE;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;;AAEA;EACE;EACA;;;AAmCJ;EA5BE;EACA;EACA;EACA;EACA;EAEA;;;AA0BF;EAhCE;EACA;EACA;EACA;EACA;EAEA;;;AA8BF;EAtBE;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EAkBA;;;AAGF;EACE;EACA;;;AAGF;EACE;EACA;;;AAKF;EAvDE;EACA;EACA;EACA;EACA;EAEA;;;AAqDF;EA7CE;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EAwCA;EACA;;;AAGF;EACE;EACA;;;AAGF;AAEA;EAGE;;AAEA;EACE;;AANJ;EASE;EACA;EAEA;EACA;EACA;EAEA;EACA;EACA;EACA;EAEA;EACA;EACA;;AAEA;EACE;;;AAIJ;AAEA;EACE;EACA;EACA;;;AAGF;EACE;EACA;EACA;EACA;EACA;EACA;EACA;EACA,YACE;EAEF;EACA;EACA;;AAEA;EAEE;EACA;;;AAIJ;EACE;EACA;EACA;EACA;;;AAGF;EACE;EACA;EACA;;;AAGF;EACE;EACA;;;AAGF;AAEA;EACE;EACA;;;AAGF;EACE;EACA;EACA;EACA;EACA;EACA;EACA;;AAEA;EACE;EACA;;;AAIJ;EACE;EACA;;AAIE;EACE;;;AAKN;AAEA;EACE;EACA;EACA;EACA;EACA;;;AAGF;EACE;EACA;;AAEA;AAAA;EAEE;EACA;EACA;;;AAIJ;EACE;EACA;;;AAGF;EACE;EACA;EACA;;;AAGF;EACE;EACA;;;AAGF;EACE;EACA;;;AAGF;EACE;EACA;;;AAGF;EACE;EACA;EACA;;;AAGF;EACE;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA,YACE;;AAGF;EAEE;EACA;;;AAIJ;EACE;EACA;EACA;;;AAGF;EACE;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;;AAEA;EACE;EACA;EACA;EACA;EACA;EACA;EACA;;AAGF;EAEE;;AAEA;EACE;EACA","file":"ctrls.css"}
+{"version":3,"sourceRoot":"","sources":["../node_modules/@stanko/dual-range-input/dist/index.css","../src/scss/_ctrls.scss"],"names":[],"mappings":"AAAA;EACE;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;;;AAEF;EACE;EACA;EACA;;;AAEF;EACE;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;;;AAEF;EACE;EACA;EACA;EACA;;;AAEF;EACE;EACA;EACA;;;AAEF;EACE;;;AAEF;EACE;EACA;EACA;;;AAEF;EACE;;;AAEF;EACE;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;;;AAEF;EACE;;;AAEF;EACE;EACA;;;AAEF;EACE;EACA;;;AAEF;EACE;EACA;;;AAEF;EACE;EACA;EACA;EACA;;;AAEF;EACE;EACA;EACA;;;AAEF;EACE;;;AAEF;EACE;EACA;EACA;;;AAEF;EACE;;;AAEF;EACE;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;;;AAEF;EACE;;;AAEF;EACE;EACA;;;AAEF;EACE;EACA;;;AAEF;EACE;EACA;;;;AC3IF;EACE;AAAA;AAAA;EAGA;EACA;EACA;EACA;EACA;EAGA;EACA;EAEA;EACA;EAGA;EACA;EACA;EACA;EACA;EACA;EAGA;EAGA;EACA;EACA;EAGA;EACA;EAGA;EAGA;EAEA;EACA;EAEA;EACA;EAGA;EAGA;EACA;EAEA;EACA;EAEA;EACA;EACA;EACA;EAGA;EACA;EAEA;EAEA;EACA;EAEA;EAGA;EAEA;EACA;;;AA+CF;EACE;IA3CA;IAEA;IACA;IAGA;IACA;IACA;IACA;IACA;IACA;IAGA;IAGA;IACA;IACA;IAGA;IACA;IAGA;IAGA;IAEA;IAGA;IAGA;AAAA;AAAA;;;AAWF;EAhDE;EAEA;EACA;EAGA;EACA;EACA;EACA;EACA;EACA;EAGA;EAGA;EACA;EACA;EAGA;EACA;EAGA;EAGA;EAEA;EAGA;EAGA;AAAA;AAAA;;;AAiBF;EACE;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;;AAEA;AAAA;AAAA;EAGE;EACA;EACA;;AAGF;AAAA;EAEE;EACA;EACA;;AAGF;EACE;EACA;;;AAIJ;AAAA;EAEE;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA,YACE;;AAGF;AAAA;AAAA;EAEE;EACA;;;AAOJ;EACE;EACA;EACA;EACA;EACA;EACA;;;AAGF;EACE;;;AAGF;EACE;;;AAGF;AAGA;EACE;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA,YACE;;AAGF;EAEE;;AAGF;EACE;EACA;EACA,YACE;;AAIJ;EACE;;;AAKJ;EACE;EACA;EACA;EACA;EACA;EACA;;AAEA;EAEE;EACA;;;AAOA;EACE;;AAGF;AAAA;AAAA;EAEE;;;AAKN;AAEA;EACE;EACA;EACA;EACA;EACA;EACA;;;AAGF;EACE;;;AAGF;EACE;EACA;;;AAGF;EACE;;;AAGF;EACE;;;AAGF;EACE;;;AAGF;AAEA;EACE;EACA;EACA;EACA;EACA;;;AAGF;EACE;EACA;EACA;EACA;;;AAGF;EACE;EACA;;;AAGF;EACE;EACA;;;AAKA;AAAA;EACE;EACA;EACA;;;AAIJ;AAEA;EACE;EACA;EACA;EACA;;;AAGF;EACE;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;;AAEA;EACE;EACA;EACA;;;AAKJ;EACE;EACA;EACA;;;AAIF;EACE;;;AAIF;EACE;;;AAIF;EACE;EACA;;;AAGF;AAEA;EACE;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;;AAEA;EACE;EACA;;;AAmCJ;EA5BE;EACA;EACA;EACA;EACA;EAEA;;;AA0BF;EAhCE;EACA;EACA;EACA;EACA;EAEA;;;AA8BF;EAtBE;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EAkBA;;;AAGF;EACE;EACA;;;AAGF;EACE;EACA;;;AAKF;EAvDE;EACA;EACA;EACA;EACA;EAEA;;;AAqDF;EA7CE;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EAwCA;EACA;;;AAGF;EACE;EACA;;;AAGF;AAEA;EAGE;;AAEA;EACE;;AANJ;EASE;EACA;EAEA;EACA;EACA;EAEA;EACA;EACA;EACA;EAEA;EACA;EACA;;AAEA;EACE;;;AAIJ;AAEA;EACE;EACA;EACA;;;AAGF;EACE;EACA;EACA;EACA;EACA;EACA;EACA;EACA,YACE;EAEF;EACA;EACA;;AAEA;EAEE;EACA;;;AAIJ;EACE;EACA;EACA;EACA;;;AAGF;EACE;EACA;EACA;;;AAGF;EACE;EACA;;;AAGF;AAEA;EACE;EACA;;;AAGF;EACE;EACA;EACA;EACA;EACA;EACA;EACA;;AAEA;EACE;EACA;;;AAIJ;EACE;EACA;;AAIE;EACE;;;AAKN;AAEA;EACE;EACA;EACA;EACA;EACA;;;AAGF;EACE;EACA;;AAEA;AAAA;EAEE;EACA;EACA;;;AAIJ;EACE;EACA;;;AAGF;EACE;EACA;EACA;;;AAGF;EACE;EACA;;;AAGF;EACE;EACA;;;AAGF;EACE;EACA;;;AAGF;EACE;EACA;EACA;;;AAGF;EACE;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA,YACE;;AAGF;EAEE;EACA;;;AAIJ;EACE;EACA;EACA;;;AAGF;EACE;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;EACA;;AAEA;EACE;EACA;EACA;EACA;EACA;EACA;EACA;;AAGF;EAEE;;AAEA;EACE;EACA","file":"ctrls.css"}

package/dist/utils/alea.d.ts

@@ -1,2 +1,2 @@
-declare const Alea: (seed?: string) => (() => number);
+declare const Alea: (...seeds: string[]) => (() => number);
 export default Alea;

package/dist/utils/alea.js

@@ -1,36 +1,45 @@
 // Algorithm by Johannes Baagøe
 // Slim TypeScript version of this implementation:
 // https://github.com/coverslide/node-alea
-const getMash = () => {
-    let n = 0xefc8249d;
-    const mash = (seed) => {
-        for (let i = 0; i < seed.length; i++) {
-            n += seed.charCodeAt(i);
-            let h = 0.02519603282416938 * n;
-            n = h >>> 0;
-            h -= n;
-            h *= n;
-            n = h >>> 0;
-            h -= n;
-            n += h * 0x100000000; // 2^32
-        }
-        return (n >>> 0) * 2.3283064365386963e-10; // 2^-32
+const Alea = (...seeds) => {
+    const getMash = () => {
+        let n = 0xefc8249d;
+        const mash = (seed) => {
+            for (let i = 0; i < seed.length; i++) {
+                n += seed.charCodeAt(i);
+                let h = 0.02519603282416938 * n;
+                n = h >>> 0;
+                h -= n;
+                h *= n;
+                n = h >>> 0;
+                h -= n;
+                n += h * 0x100000000; // 2^32
+            }
+            return (n >>> 0) * 2.3283064365386963e-10; // 2^-32
+        };
+        return mash;
     };
-    return mash;
-};
-const Alea = (seed = Date.now().toString()) => {
-    let s = [0, 0, 0];
+    const getRandomSeeds = () => {
+        return [
+            Math.random().toString(36).slice(2),
+            Math.random().toString(36).slice(2),
+            Math.random().toString(36).slice(2),
+        ];
+    };
+    const mash = getMash();
+    const s = [mash(" "), mash(" "), mash(" ")];
     let c = 1;
-    let mash = getMash();
-    s.forEach((_, i) => {
-        s[i] = mash(" ") - mash(seed);
-        if (s[i] < 0) {
-            s[i] += 1;
-        }
+    (seeds || getRandomSeeds()).forEach((seed) => {
+        s.forEach((_, i) => {
+            s[i] -= mash(seed);
+            if (s[i] < 0) {
+                s[i] += 1;
+            }
+        });
     });
     const random = () => {
         const t = 2091639 * s[0] + c * 2.3283064365386963e-10; // 2^-32
-        c = t | 0;
+        c = t | 0; // quicker floor
         s[0] = s[1];
         s[1] = s[2];
         s[2] = t - c;

package/package.json

@@ -1,8 +1,9 @@
 {
   "name": "@stanko/ctrls",
-  "version": "0.1.9",
+  "version": "0.3.1",
   "type": "module",
   "scripts": {
+    "test": "vitest",
     "start": "npm run parse-markdown && vite",
     "build": "npm run parse-markdown && tsc && rm -rf ./docs && vite build && touch ./docs/.nojekyll",
     "build-css": "sass ./src/scss/index.scss ./dist/ctrls.css",
@@ -19,12 +20,13 @@
   ],
   "devDependencies": {
     "highlight.js": "^11.11.1",
-    "marked": "^16.2.1",
-    "marked-highlight": "^2.2.2",
-    "sass": "^1.92.1",
+    "marked": "^17.0.0",
+    "marked-highlight": "^2.2.3",
+    "sass": "^1.94.0",
     "simplex-noise": "^4.0.3",
-    "typescript": "~5.9.2",
-    "vite": "^7.1.5"
+    "typescript": "~5.9.3",
+    "vite": "^7.2.2",
+    "vitest": "^4.0.10"
   },
   "dependencies": {
     "@stanko/dual-range-input": "^1.0.1",