@stanko/ctrls 0.1.0

package/README.md

@@ -0,0 +1,359 @@
+# Ctrls
+
+## Made for algorithmic art
+
+I made Ctrls for my [algorithmic art projects](https://muffinman.io/art/). By default, the state is saved in the URL, which lets you navigate history and easily share links. Besides standard components like checkboxes and ranges, it also includes two that are especially useful for generative projects: RNG seed and easing. These not only let you adjust parameters but also provide functions (`rng` and `easing`) that you can call directly.
+
+You can play with the live example above or check the older version on my [Space Invaders generator](https://muffinman.io/invaders/).
+
+## Features
+
+- Minimal API
+- Six components (RNG seed, easing, boolean, radio, range and dual range)
+- Fully typed, including the dynamic typings for properties it controls
+- Light and dark themes included
+- Easy to theme through CSS variables
+
+## Quick start
+
+Install the library:
+
+```bash
+npm install @stanko/ctrls
+````
+
+Define your controls as an array and instantiate a `Ctrls` class:
+
+```ts
+import { Ctrls } from "@stanko/ctrls";
+import type { TypedControlConfig } from "@stanko/ctrls";
+
+// Import CSS
+import "@stanko/ctrls/dist/ctrls.css";
+
+// Define configuration for controls
+const config = [
+  {
+    type: "boolean",
+    name: "animate",
+    defaultValue: true,
+    isRandomizationDisabled: true,
+  },
+  {
+    type: "seed",
+    name: "opacitySeed",
+  },
+  {
+    type: "range",
+    name: "hue",
+    defaultValue: 220,
+    min: 0,
+    max: 360,
+    step: 1,
+  },
+  // in the demo above there are three more components:
+  // - speed, shape and size
+
+  // Casting the config to enable editor's code completion
+] as const satisfies readonly TypedControlConfig[];
+
+// Create the instance of Ctrls
+export const options = new Ctrls(config, {
+  showRandomizeButton: true,
+});
+
+export type Options = ReturnValue<options.getValues()>;
+```
+
+Add your handlers. Ctrls provides `onChange` and `onInput` methods.
+
+To get the current values, use `.getValues()`.
+
+```ts
+options.onChange = (updatedValues: Partial<Options>) => {
+  // Example: re-render your drawing
+  render(options.getValues()); // Get all values and pass it to the render method
+};
+
+options.onInput = (updatedValues: Partial<Options>) => {
+  // Example: update a CSS variable
+  if (updatedValues.hue) {
+    document.body.style.setProperty("--hue", updatedValues.hue);
+  }
+};
+```
+
+## API
+
+To instantiate:
+
+```ts
+type ControlsOptions = {
+  showRandomizeButton?: boolean;
+  storage?: "hash" | null;
+  theme?: "system" | "light" | "dark";
+};
+```
+
+Public API:
+
+* `element`
+* `onChange`
+* `onInput`
+* `getValues`
+* `randomize`
+
+But technically all of the methods are public. I've done this on purpose to let you experiment.
+
+## Controls
+
+All controls share the following properties:
+
+```ts
+{
+  // --- Mandatory --- //
+  type: CtrlType; // "seed" | "easing" | "boolean" | "range" | "dual-range" | "radio"
+  name: string;
+
+  // --- Optional --- //
+  // If passed it will be used instead of the name
+  label?: string;
+  // Depends on the control type, if it is not passed it will be randomly generated
+  defaultValue?: T;
+  // Should the value be randomized when randomize button is clicked
+  isRandomizationDisabled?: boolean; // default: false
+}
+```
+
+Some controls will have a few more properties explained below.
+
+### Boolean
+
+A checkbox control for boolean parameter.
+
+<div class="example">
+
+```json
+{
+  "type": "boolean",
+  "name": "debug"
+}
+```
+
+</div>
+
+### Seed
+
+A text input which generates a random text seed and creates a random number generator using the seed.
+
+<div class="example">
+
+```json
+{
+  "type": "seed",
+  "name": "mainSeed"
+}
+```
+
+</div>
+
+A seeded RNG will be created and it will be included in the values. For the example above the return value of `.getValues()` would look like this:
+
+```ts
+{
+  mainSeed: "a-random-seed-value",
+  mainSeedRng: () => number;
+}
+```
+
+### Easing
+
+Cubic-bezier easing control which also creates easing function you can use directly. It includes five presets, which can be changed through the `presets` property. To disable presets pass an empty array.
+
+```ts
+{
+  // Optional
+  presets?: Record<string, [number, number, number, number]>; // default: 1
+}
+```
+
+Example:
+
+<div class="example">
+
+```json
+{
+  "type": "easing",
+  "name": "distribution",
+  "defaultValue": [0.8, 0.1, 0.2, 0.9],
+  "presets": {
+    "ease_in": [0.42, 0, 1, 1],
+    "ease_out": [0, 0, 0.58, 1],
+    "ease_in_out": [0.42, 0, 0.58, 1]
+  }
+}
+```
+
+</div>
+
+Please note that the string `ease_` will be removed from the preset labels.
+
+An easing function will be created and it will be included in the values. For the example above the return value of `.getValues()` would look like this:
+
+```ts
+{
+  distribution: [0.8, 0.1, 0.2, 0.9],
+  distributionEasing: (t: number) => number;
+}
+```
+
+### Range
+
+A range slider that controls a number parameter. Accepts minimum, maximum and step values. It includes a few additional properties:
+
+```ts
+{
+  // Mandatory
+  min: number;
+  max: number;
+
+  // Optional
+  step?: number; // default: 1
+}
+```
+
+Example:
+
+<div class="example">
+
+```json
+{
+  "type": "range",
+  "name": "width",
+  "defaultValue": 5,
+  "min": 0,
+  "max": 10,
+  "step": 1
+}
+```
+
+</div>
+
+### Dual range
+
+A range input with two handles that control minimum and maximum values. Includes the same additional properties as the range input.
+
+```ts
+{
+  // Mandatory
+  min: number;
+  max: number;
+
+  // Optional
+  step?: number; // default: 1
+}
+```
+
+Example:
+
+<div class="example">
+
+```json
+{
+  "type": "dual-range",
+  "name": "size",
+  "defaultValue": { "min": 3, "max": 7 },
+  "min": 0,
+  "max": 10,
+  "step": 1
+}
+```
+
+</div>
+
+### Radio
+
+A grid of radio buttons. Can be set to have between one and five columns.
+
+```ts
+{
+  // Mandatory
+  items: Record<string, string>; // Map of radio items (key, value)
+
+  // Optional
+  columns?: number; // default: 3
+}
+```
+
+Example:
+
+<div class="example">
+
+```json
+{
+  "type": "radio",
+  "name": "main shape",
+  "items": {
+    "triangle": "3",
+    "rectangle": "4",
+    "hexagon": "6",
+    "octagon": "8",
+    "circle": "32"
+  },
+  "columns": 2
+}
+```
+
+</div>
+
+## Theming
+
+Ctrls relies on CSS variables for theming. There is a lot of variables you can tweak, but I suggest starting with these four:
+
+```css
+--ctrls-c: 0.7;
+--ctrls-h: 220;
+--ctrls-radius: 4px;
+--ctrls-range-thumb-radius: 4px;
+```
+
+<div class="theme-controls">
+</div>
+
+## Why?
+
+You might ask why I made another library when [dat.GUI](https://github.com/dataarts/dat.gui) and [TweakPane](https://tweakpane.github.io/docs/) already exist. They both solve a general use case, with extensive options and elaborate APIs, while I wanted something smaller and easier to adapt for [my algorithmic drawings](https://muffinman.io/art/).
+
+I originally built a crude library with no plans to release it. Over time I polished it, ported it to TypeScript, and realized it might actually be useful to others. The code is solid, though I would love to add a few more features.
+
+Ctrls is a very opinionated library tailored to my likings. I'm open to suggestions, but they need to fit algorithmic art workflows and align with my vision. It's not meant to be a general-purpose library - others already cover that space well.
+
+I also want to mention that I really like TweakPane, and Ctrls' homepage is heavily influenced by it.
+
+## Cheers!
+
+Thank you for stopping by! If you end up using Ctrls, please let me know, I would love to see it.
+
+## TODO
+
+* [ ] Demo - favicon and metadata
+* [ ] Readme - screenshots
+* [ ] Prefix input names' with `ctrl_${id}_${name}` to avoid collisions
+* [ ] Allow users to pass a custom PRNG lib
+* [ ] Hash storage - check if there is an instance using hash storage already
+* [ ] Demo - stop animation when not in viewport
+* [ ] Add title which collapses the controls
+* [ ] Storage - local storage
+* [x] Use web safe / system fonts by default
+* [x] Experiment with chroma for light and dark shades of the main color
+* [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] 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)
+* [x] Scope the CSS
+* [x] Controls -> Ctrls
+* [x] Easing - option to pass custom presets (or an empty array to disable them)
+* [x] onChange - maybe add current options (?) - decided not to do

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

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

package/dist/ctrls/ctrl-boolean.js

@@ -0,0 +1,67 @@
+import { checkIcon } from "../utils/icons";
+export class BooleanCtrl {
+    constructor(config, onChange, onInput) {
+        this.type = "boolean";
+        this.parse = (string) => {
+            return string === "true";
+        };
+        this.getRandomValue = () => {
+            return Math.random() > 0.5;
+        };
+        this.getDefaultValue = () => {
+            return true;
+        };
+        this.valueToString = (value = this.value) => {
+            return value.toString();
+        };
+        this.buildUI = () => {
+            const input = document.createElement("input");
+            input.classList.add("ctrls__boolean-input");
+            input.setAttribute("type", "checkbox");
+            input.checked = this.value;
+            input.addEventListener("change", () => {
+                this.value = input.checked;
+                this.onChange(this.name, this.value);
+            });
+            input.addEventListener("input", () => {
+                this.value = input.checked;
+                this.onInput(this.name, this.value);
+            });
+            const checkmark = document.createElement("span");
+            checkmark.classList.add("ctrls__boolean-checkmark");
+            checkmark.innerHTML = checkIcon;
+            const right = document.createElement("div");
+            right.classList.add("ctrls__control-right");
+            right.appendChild(input);
+            right.appendChild(checkmark);
+            const label = document.createElement("span");
+            label.textContent = this.label;
+            label.classList.add("ctrls__control-label");
+            const element = document.createElement("label");
+            element.classList.add("ctrls__control", "ctrls__control--boolean");
+            element.appendChild(label);
+            element.appendChild(right);
+            return {
+                element,
+                input,
+            };
+        };
+        this.update = (value) => {
+            this.value = value;
+            this.input.checked = this.value;
+        };
+        this.type = "boolean";
+        this.name = config.name;
+        this.label = config.label || config.name;
+        this.value =
+            config.defaultValue === undefined
+                ? this.getDefaultValue()
+                : config.defaultValue;
+        this.isRandomizationDisabled = config.isRandomizationDisabled || false;
+        this.onChange = onChange;
+        this.onInput = onInput;
+        const { input, element } = this.buildUI();
+        this.input = input;
+        this.element = element;
+    }
+}

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

@@ -0,0 +1,47 @@
+import DualRangeInput from "@stanko/dual-range-input";
+import type { Ctrl, CtrlChangeHandler, CtrlType, CtrlTypeRegistry } from ".";
+export type DualRangeControlOptions = {
+    min: number;
+    max: number;
+    step?: number;
+};
+export type DualRangeValue = {
+    min: number;
+    max: number;
+};
+export declare class DualRangeCtrl implements Ctrl<DualRangeValue> {
+    type: CtrlType;
+    name: string;
+    label: string;
+    value: DualRangeValue;
+    isRandomizationDisabled: boolean;
+    onChange: CtrlChangeHandler<DualRangeValue>;
+    onInput: CtrlChangeHandler<DualRangeValue>;
+    min: number;
+    max: number;
+    step: number;
+    element: HTMLElement;
+    minInput: HTMLInputElement;
+    maxInput: HTMLInputElement;
+    dualRange: DualRangeInput;
+    constructor(config: CtrlTypeRegistry["dual-range"]["config"], onChange: CtrlChangeHandler<DualRangeValue>, onInput: CtrlChangeHandler<DualRangeValue>);
+    parse: (string: string) => {
+        min: number;
+        max: number;
+    };
+    getRandomValue: () => {
+        min: number;
+        max: number;
+    };
+    getDefaultValue: () => {
+        min: number;
+        max: number;
+    };
+    valueToString: (value?: DualRangeValue) => string;
+    buildUI: () => {
+        element: HTMLDivElement;
+        minInput: HTMLInputElement;
+        maxInput: HTMLInputElement;
+    };
+    update: (value: DualRangeValue) => void;
+}

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

@@ -0,0 +1,113 @@
+import random from "../utils/random";
+import DualRangeInput from "@stanko/dual-range-input";
+import { roundToStep } from "../utils/round-to-step";
+// TODO
+// Add a span with the current value
+export class DualRangeCtrl {
+    constructor(config, onChange, onInput) {
+        this.type = "dual-range";
+        this.parse = (string) => {
+            const [min, max] = string.split(",").map(parseFloat);
+            return { min, max };
+        };
+        this.getRandomValue = () => {
+            const { step } = this;
+            const min = random(this.min, this.max - step);
+            const max = random(min + step, this.max);
+            return {
+                min: roundToStep(min, step),
+                max: roundToStep(max, step),
+            };
+        };
+        this.getDefaultValue = () => {
+            return {
+                min: this.min,
+                max: this.max,
+            };
+        };
+        this.valueToString = (value = this.value) => {
+            return `${value.min},${value.max}`;
+        };
+        this.buildUI = () => {
+            const { min, max, step, value } = this;
+            const minInput = document.createElement("input");
+            minInput.setAttribute("type", "range");
+            minInput.setAttribute("min", min.toString());
+            minInput.setAttribute("max", max.toString());
+            minInput.setAttribute("step", step.toString());
+            minInput.setAttribute("value", value.min.toString());
+            minInput.addEventListener("input", () => {
+                this.value = {
+                    min: parseFloat(minInput.value),
+                    max: parseFloat(maxInput.value),
+                };
+                this.onInput(this.name, this.value);
+            });
+            minInput.addEventListener("change", () => {
+                this.value = {
+                    min: parseFloat(minInput.value),
+                    max: parseFloat(maxInput.value),
+                };
+                this.onChange(this.name, this.value);
+            });
+            const maxInput = document.createElement("input");
+            maxInput.setAttribute("type", "range");
+            maxInput.setAttribute("min", min.toString());
+            maxInput.setAttribute("max", max.toString());
+            maxInput.setAttribute("step", step.toString());
+            maxInput.setAttribute("value", value.max.toString());
+            maxInput.addEventListener("change", () => {
+                this.value = {
+                    min: parseFloat(minInput.value),
+                    max: parseFloat(maxInput.value),
+                };
+                this.onChange(this.name, this.value);
+            });
+            const inputWrapper = document.createElement("div");
+            inputWrapper.classList.add("dual-range-input");
+            inputWrapper.appendChild(minInput);
+            inputWrapper.appendChild(maxInput);
+            const right = document.createElement("div");
+            right.classList.add("ctrls__control-right");
+            right.appendChild(inputWrapper);
+            const label = document.createElement("span");
+            label.textContent = this.label;
+            label.classList.add("ctrls__control-label");
+            const element = document.createElement("div");
+            element.classList.add("ctrls__control", "ctrls__control--dual-range");
+            element.appendChild(label);
+            element.appendChild(right);
+            return {
+                element,
+                minInput,
+                maxInput,
+            };
+        };
+        this.update = (value) => {
+            const { min, max } = value;
+            this.value = value;
+            this.minInput.setAttribute("max", max.toString());
+            this.maxInput.setAttribute("min", min.toString());
+            this.minInput.value = value.min.toString();
+            this.maxInput.value = value.max.toString();
+            this.dualRange.update();
+        };
+        this.name = config.name;
+        this.label = config.label || config.name;
+        this.min = config.min;
+        this.max = config.max;
+        this.step = config.step || 1;
+        this.value =
+            config.defaultValue === undefined
+                ? this.getDefaultValue()
+                : config.defaultValue;
+        this.isRandomizationDisabled = config.isRandomizationDisabled || false;
+        this.onChange = onChange;
+        this.onInput = onInput;
+        const { minInput, maxInput, element } = this.buildUI();
+        this.minInput = minInput;
+        this.maxInput = maxInput;
+        this.element = element;
+        this.dualRange = new DualRangeInput(this.minInput, this.maxInput);
+    }
+}

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

@@ -0,0 +1,37 @@
+import type { Ctrl, CtrlChangeHandler, CtrlType, CtrlTypeRegistry } from ".";
+export type Easing = [number, number, number, number];
+export declare class EasingCtrl implements Ctrl<Easing> {
+    type: CtrlType;
+    name: string;
+    label: string;
+    value: Easing;
+    isRandomizationDisabled: boolean;
+    onChange: CtrlChangeHandler<Easing>;
+    onInput: CtrlChangeHandler<Easing>;
+    element: HTMLElement;
+    ticks: SVGLineElement[];
+    control: HTMLDivElement;
+    handles: HTMLButtonElement[];
+    lines: SVGLineElement[];
+    path: SVGPathElement;
+    presets: Record<string, Easing>;
+    constructor(config: CtrlTypeRegistry["easing"]["config"], onChange: CtrlChangeHandler<Easing>, onInput: CtrlChangeHandler<Easing>);
+    parse: (string: string) => Easing;
+    getRandomValue: () => Easing;
+    getDefaultValue: () => Easing;
+    valueToString: (value?: Easing) => string;
+    getRelativeValues: (value?: Easing) => {
+        px: Easing;
+        percentage: Easing;
+    };
+    buildUI: () => {
+        element: HTMLDivElement;
+        ticks: SVGLineElement[];
+        control: HTMLDivElement;
+        handles: HTMLButtonElement[];
+        lines: SVGLineElement[];
+        path: SVGPathElement;
+    };
+    updateUI: (value?: Easing) => void;
+    update: (value?: Easing) => void;
+}