@stanko/ctrls 0.3.4 → 0.4.1

package/dist/ctrls/index.js

@@ -6,8 +6,10 @@ import { EasingCtrl } from "./ctrl-easing";
 import { RadioCtrl } from "./ctrl-radio";
 import { RangeCtrl } from "./ctrl-range";
 import { SeedCtrl } from "./ctrl-seed";
+import { FileCtrl } from "./ctrl-file";
 import Alea from "../utils/alea";
-import { diceIcon } from "../utils/icons";
+import { chevronUpIcon, diceIcon } from "../utils/icons";
+import { getHTMLControlElement } from "./ctrl-html";
 const controlMap = {
     boolean: BooleanCtrl,
     range: RangeCtrl,
@@ -15,84 +17,82 @@ const controlMap = {
     seed: SeedCtrl,
     easing: EasingCtrl,
     "dual-range": DualRangeCtrl,
+    file: FileCtrl,
 };
 export class Ctrls {
     constructor(configs, options) {
         this.controls = [];
         this.controlsMap = {};
+        this.processControls = (configs) => {
+            const elements = [];
+            // Handlers shared by all controls
+            const onChangeControlHandler = (control) => {
+                const updatedValues = this.updateValuesObject({}, control);
+                this.onChange?.(updatedValues);
+                if (this.options.storage === "hash") {
+                    this.setHash();
+                }
+            };
+            const onInputControlHandler = (control) => {
+                const updatedValues = this.updateValuesObject({}, control);
+                this.onInput?.(updatedValues);
+            };
+            // Processing configs and creating component instances and HTML elements
+            configs.map((config) => {
+                if (config.type === "group") {
+                    // Create group element
+                    const groupElement = document.createElement("div");
+                    groupElement.classList.add("ctrls__group");
+                    if (config.isCollapsed) {
+                        groupElement.classList.add("ctrls__group--hidden");
+                    }
+                    const groupTitle = document.createElement("button");
+                    groupTitle.classList.add("ctrls__group-title");
+                    groupTitle.innerHTML =
+                        (config.label || toSpaceCase(config.name)) + chevronUpIcon;
+                    groupTitle.addEventListener("click", () => {
+                        groupTitle.parentElement?.classList.toggle("ctrls__group--hidden");
+                    });
+                    // Add title
+                    groupElement.append(groupTitle);
+                    config.controls.forEach((itemConfig) => {
+                        const control = this.registerControl(itemConfig, onChangeControlHandler, onInputControlHandler, toCamelCase(config.name));
+                        // Add the control elements to the group element
+                        groupElement.append(control?.element);
+                    });
+                    // Add the group element
+                    elements.push(groupElement);
+                }
+                else if (config.type === "html") {
+                    // HTML controls are just rendered on their own
+                    elements.push(getHTMLControlElement(config));
+                }
+                else {
+                    const control = this.registerControl(config, onChangeControlHandler, onInputControlHandler);
+                    // Add the control element
+                    elements.push(control.element);
+                }
+            });
+            return elements;
+        };
         this.registerControl = (config, onChangeControlHandler, onInputControlHandler, group = "") => {
-            // To make typescript happy
-            if (config.type === "group") {
-                return;
-            }
-            // TODO
-            // Again, document as it is my personal preference
+            // It is my personal preference is to use space case for labels
             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
+            // Another personal preference of mine is to have properties named in camel case when using them in code
             config.name = toCamelCase(config.name);
+            // Add group properties to the control config
             if (group) {
                 config.group = group;
                 config.id = toCamelCase(`${group}-${config.name}`);
             }
+            // Instantiate the control component
             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) => {
-                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");
-                randomizeButton.classList.add("ctrls__randomize", "ctrls__btn", "ctrls__btn--lg");
-                randomizeButton.innerHTML = `Randomize ${diceIcon}`;
-                randomizeButton.addEventListener("click", this.randomize);
-                controlsContainer.appendChild(randomizeButton);
-            }
-            if (this.options.title) {
-                const titleButton = document.createElement("button");
-                titleButton.classList.add("ctrls__title");
-                titleButton.innerText = this.options.title;
-                titleButton.addEventListener("click", this.toggleVisibility);
-                element.appendChild(titleButton);
-            }
-            element.appendChild(controlsContainer);
-            return element;
+            return control;
         };
         this.toggleVisibility = () => {
             this.element.classList.toggle("ctrls--hidden");
@@ -107,6 +107,7 @@ export class Ctrls {
         };
         this.getHash = () => {
             const values = this.controls
+                .filter((control) => control.type !== "file")
                 .map((control) => {
                 return `${toKebabCase(control.id)}:${control.valueToString()}`;
             })
@@ -170,34 +171,41 @@ export class Ctrls {
             theme: "system",
             ...options,
         };
-        const onChangeControlHandler = (control) => {
-            const updatedValues = this.updateValuesObject({}, control);
-            this.onChange?.(updatedValues);
-            if (this.options.storage === "hash") {
-                this.setHash();
-            }
-        };
-        const onInputControlHandler = (control) => {
-            const updatedValues = this.updateValuesObject({}, control);
-            this.onInput?.(updatedValues);
-        };
-        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);
-            }
-        });
-        this.element = this.buildUI();
-        if (this.options.storage === "hash") {
-            this.addHashListeners();
+        // Main element
+        this.element = document.createElement("div");
+        this.element.classList.add("ctrls");
+        this.element.classList.add(`ctrls--${this.options.theme}-theme`);
+        // Title
+        if (this.options.title) {
+            const titleButton = document.createElement("button");
+            titleButton.classList.add("ctrls__title");
+            titleButton.innerHTML = this.options.title + chevronUpIcon;
+            titleButton.addEventListener("click", this.toggleVisibility);
+            this.element.appendChild(titleButton);
         }
+        // Controls wrapper
+        const controlsContainer = document.createElement("div");
+        controlsContainer.classList.add("ctrls__controls");
+        this.element.appendChild(controlsContainer);
+        // Controls
+        const controlElements = this.processControls(configs);
+        controlsContainer.append(...controlElements);
+        // Randomize button
+        if (this.options.showRandomizeButton) {
+            const randomizeButton = document.createElement("button");
+            randomizeButton.classList.add("ctrls__randomize", "ctrls__btn", "ctrls__btn--lg");
+            randomizeButton.innerHTML = `Randomize ${diceIcon}`;
+            randomizeButton.addEventListener("click", this.randomize);
+            controlsContainer.appendChild(randomizeButton);
+        }
+        // Append the Ctrls element to the provided parent element
         if (this.options.parent) {
             this.options.parent.appendChild(this.element);
         }
+        // Hash storage
+        if (this.options.storage === "hash") {
+            this.addHashListeners();
+        }
     }
     updateValuesObject(values, control) {
         let objectToUpdate = values;

package/dist/ctrls/types.d.ts

@@ -0,0 +1,146 @@
+import type BezierEasing from "bezier-easing";
+import type { BooleanCtrl } from "./ctrl-boolean";
+import type { DualRangeValue, DualRangeCtrl } from "./ctrl-dual-range";
+import type { Easing, EasingCtrl } from "./ctrl-easing";
+import type { RadioCtrl } from "./ctrl-radio";
+import type { RangeCtrl } from "./ctrl-range";
+import type { SeedCtrl } from "./ctrl-seed";
+import type { FileCtrl } from "./ctrl-file";
+export interface PRNG {
+    (): number;
+}
+export type HashItem = {
+    id: string;
+    value: unknown;
+};
+export type CtrlControlType = "boolean" | "range" | "radio" | "seed" | "easing" | "dual-range" | "file";
+export type CtrlItemType = CtrlControlType | "group" | "html";
+export type CtrlChangeHandler = (control: CtrlComponent) => void;
+export type CtrlConfig<T = unknown> = {
+    type: CtrlItemType;
+    id?: string;
+    name: string;
+    accept?: string;
+    group?: string;
+    label?: string;
+    defaultValue?: T;
+    isRandomizationDisabled?: boolean;
+};
+export interface Ctrl<T> {
+    id: string;
+    group?: string;
+    name: string;
+    label?: string;
+    type: CtrlItemType;
+    isRandomizationDisabled: boolean;
+    onChange: CtrlChangeHandler;
+    parse: (value: string) => T;
+    getRandomValue: () => T;
+    getDefaultValue: () => T;
+    buildUI: () => unknown;
+    valueToString: (value?: T) => string;
+    update: (value: T) => void;
+    element: HTMLElement;
+}
+export interface CtrlTypeMap {
+    boolean: {
+        value: boolean;
+    };
+    range: {
+        value: number;
+        min: number;
+        max: number;
+        step?: number;
+    };
+    radio: {
+        value: string;
+        items: Record<string, string>;
+        columns?: 1 | 2 | 3 | 4 | 5;
+    };
+    seed: {
+        value: string;
+    };
+    easing: {
+        value: Easing;
+        presets?: Record<string, Easing>;
+    };
+    "dual-range": {
+        value: DualRangeValue;
+        min: number;
+        max: number;
+        step?: number;
+    };
+    group: {
+        value: Record<string, unknown>;
+        controls: readonly TypedControlConfig[];
+        isRandomizationDisabled?: boolean;
+    };
+    html: {
+        html: HTMLElement;
+    };
+    file: {
+        value: File | null;
+        accept?: string;
+    };
+}
+export type TypedControlConfig = {
+    [K in CtrlControlType]: {
+        type: K;
+        id?: string;
+        name: string;
+        group?: string;
+        label?: string;
+        defaultValue?: CtrlTypeMap[K]["value"];
+        isRandomizationDisabled?: boolean;
+    } & Omit<CtrlTypeMap[K], "value">;
+}[CtrlControlType];
+export type GroupConfig = {
+    type: "group";
+    name: string;
+    label?: string;
+    controls: readonly TypedControlConfig[];
+    isCollapsed?: boolean;
+};
+export type HTMLConfig = {
+    type: "html";
+    name: string;
+    label?: string;
+    html: HTMLElement;
+};
+export type ConfigItem = TypedControlConfig | GroupConfig | HTMLConfig;
+export type ConfigFor<T extends CtrlItemType> = Extract<TypedControlConfig, {
+    type: T;
+}>;
+type ExtractValues<Configs extends readonly ConfigItem[]> = {
+    [C in Extract<Configs[number], {
+        type: CtrlControlType;
+    }> 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 ConfigItem[]> = {
+    [C in Extract<Configs[number], {
+        type: "easing";
+    }> as `${C["name"]}Easing`]: ReturnType<typeof BezierEasing>;
+} & {
+    [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"]>;
+};
+export type OptionsMap<Configs extends readonly ConfigItem[]> = ExtractValues<Configs> & DerivedProps<Configs>;
+export type ControlsOptions = {
+    showRandomizeButton?: boolean;
+    storage?: "hash" | "none";
+    theme?: "system" | "light" | "dark";
+    parent?: Element;
+    title?: string;
+};
+export type CtrlComponent = BooleanCtrl | RangeCtrl | RadioCtrl | SeedCtrl | EasingCtrl | DualRangeCtrl | FileCtrl;
+export type ControlConstructor<T> = new (...args: any[]) => T;
+export {};

package/dist/ctrls/types.js

@@ -0,0 +1 @@
+export {};