muigui 0.0.10 → 0.0.13

package/README.md

@@ -1,15 +1,11 @@
-# muigui
-
-# NOT READY for USE
-
-<!---
-
-<img src="./images/muigui.png" style="max-width: 640px">
+# muigui (⍺)
 
 A simple Web UI library.
 
+[See docs here](https://muigui.org)
+
 muigui is a simple UI library in the spirit of
-[dat.gui](https://github.com/dataarts/dat.gui) and/or [lil-gui](https://github.com/georgealways/).
+[dat.gui](https://github.com/dataarts/dat.gui) and/or [lil-gui](https://github.com/georgealways/) and [tweakpane](https://cocopon.github.io/tweakpane/)
 
 ## Usage
 
@@ -28,66 +24,377 @@ Then
 ```js
 const s = {
   someNumber: 123,
-  someString: "hello",
-  someOption: "dog",
+  someString: 'hello',
+  someOption: 'dog',
   someColor: '#ED3281',
   someFunction: () => console.log('called')
 };
 
 const gui = new GUI();
 gui.add(s, 'someNumber', 0, 200);  // range 0 to 200
-gui.add(s, 'someString);
-gui.add(s, 'someOption, ['cat', 'bird', 'dog']);
+gui.add(s, 'someString');
+gui.add(s, 'someOption', ['cat', 'bird', 'dog']);
 gui.addColor(s, 'someColor');
 gui.add(s, 'someFunction');
 ```
 
 produces
 
-<img src="./images/muigui-screenshot.png" style="max-width: 275px">
+<img src="./images/muigui-screenshot.png" style="max-width: 250px">
 
-or a shorter version
+## Why
 
-```js
-const s = {
-  someNumber: 123,
-  someString: "hello",
-  someOption: "dog",
-  someColor: '#ED3281',
-  someFunction: () => console.log('called')
-};
+So, to be honest, I like [tweakpane](https://cocopon.github.io/tweakpane/) and
+I didn't know about it when I started this library. That said, I've looked
+into using tweakpane and it doesn't meet my needs as of v4.0.0. Examples below
+
+* ## Simpler
+  
+  I wanted certain things to be simpler. For example, in dat.gui/lil.gui/tweakpane, if I wanted
+  to store radians in code but show degrees in the UI I had to jump through
+  hoops. I could either, store degrees and convert 😢
+
+  ```js
+  const settings = {
+    angle: 45,
+  };
+  gui.add(settings, 'angle', -360, 360);
+
+  ...
+     const rotation = settings.angle * Math.PI / 180
+  ```
+
+  That's bad IMO. I shouldn't have to refactor my code to fit the GUI.
+
+  I can make some proxy class that presents degrees to the GUI
+  and stores them in radians like this
+
+  ```js
+  class DegRadHelper {
+    constructor( obj, prop ) {
+      this.obj = obj;
+      this.prop = prop;
+    }
+    get value() {
+      return this.obj[this.prop] * 180 / Math.PI;
+    }
+    set value(v) {
+      this.obj[this.prop] = v * Math.PI / 180;
+    }
+  }
+  const settings = {
+    angle: Math.PI * 0.5,
+  };
+  gui.add(new DegRadHelper(settings, 'angle'), 'value', -360, 360);
+  ```
+
+  But that looks poor to use. What is `'value'`?? 😭
+
+  So, muigui handles that slightly nicer in the form of converters.
+
+  ```js
+  const settings = {
+    angle: Math.PI * 0.5,
+  };
+  const degToRad = d => d * Math.PI / 180;
+  const radToDeg = r => r * 180 / Math.PI;
+  gui.add(s, 'angleRad', {
+    min: -360, max: 360,
+    converters: {
+      to: radToDeg,
+      from: v => [true, degToRad(v)],
+    }});
+  ```
+
+  Typically I'll pull out the settings like this
+
+  ```js
+  const degToRad = d => d * Math.PI / 180;
+  const radToDeg = r => r * 180 / Math.PI;
+  const radToDegSettings {
+    min: -360, max: 360,
+    converters: {
+      to: radToDeg,
+      from: v => [true, degToRad(v)],
+    }});
+  ```
+
+  And then I can use it like this
+
+  ```js
+  const settings = {
+    angle: Math.PI * 0.5,
+    rotation: Math.PI * 0.25,
+  };
+  gui.add(s, 'angleRad', radToDegSettings);
+  gui.add(s, 'rotation', radToDegSettings);
+  ```
+
+  You provide converters where `to` converts to the form the UI wants
+  and `from` converts back. The reason `from` returns a tuple is that
+  it's used to convert the text and gives you a chance to say the text
+  does not match the required format in which case you return `[false]`
+
+  Other examples of simpler: Want a drop-down for numbers?
+
+  ```js
+  const settings = { speed: 1 }
+
+  // tweakpane
+  pane.addBinding(settings, speed, {
+    options: {
+      slow: 0,
+      medium: 1,
+      fast: 2,
+    }
+  })
+
+  // muigui
+  gui.add(settings, 'speed', ['slow', 'medium', 'fast']);
+  ```
+
+  Want a drop-down for strings
+
+  ```js
+  const settings = { alphaMode: 'opaque' }
+
+  // tweakpane
+  pane.addBindng(settings, 'alphaMode', {
+    options: {
+      'opaque': 'opaque',
+      'premultiplied': 'premultiplied',
+    }
+  });
+
+  // muigui
+  gui.add(settings, 'alphaMode', ['opaque', 'premultiplied']);
+  ```
+
+  Of course you can also pass in key/value settings like tweakpane.
+
+* ## Color formats and storage
+
+  I often work with WebGL and WebGPU. The most common colors are in an array or a typedArray
+  
+  ```js
+  const uniforms = {
+    color1: [1, 0.5, 0.25],                   // orange
+    color2: new Float32Array([0, 1, 1]);      // cyan
+    color3: new Uint8Array([0, 128, 0, 128]); // transparent green
+  }
+  ```
+
+  Neither dat.gui, lil.gui, nor tweakpane can edit these AFAICT. (2023)
+  You'd have to jump
+  through the hoops like the `DegRadHelper` example above but it's not
+  that easy because, if you're showing the value textually
+  then you want that value to be the one you want to show the user,
+  not the value the editor wants.
+
+  This is still an issue in muigui where it uses the browser's built
+  in color editor in parts. That editor might show 0-255 values but if it's
+  editing 0 to 1 values it'd be nice if the editor showed 0 to 1 values.
+
+  muigui does handle this in the text part of it's color display. If you
+  ask it to edit 0 to 1 values it shows 0 to 1 values in the text part.
+  The reason you need the text part is so you can copy and paste colors
 
-const options = {
-  someNumber: [1, 200],   // range 0 to 200
-  someOption: ['cat', 'bird', 'dog'],
-}
+  muigui also edits hsl colors. By that I don't mean the editor can
+  switch to an HSL editor, I mean the actual value that comes out
+  is `hsl(hue, sat, luminance)` and not some RGB value. Like the number
+  conversions, it would be easy to add `hsv`, `hsb`, maybe `labch` etc...
+
+* ## More Use Cases
+
+  In some projects, I'd end up writing a small
+  app with an HTML form and then have to write all the code to parse
+  the form and I'd be thinking "It would be so nice if I could use
+  the same API as dat.gui 🙁
+
+  So, I thought I'd try to write a library that handled that case.
+
+I also wanted to explore various things though many of them
+have not made it into muigui yet.
+
+* ## PropertyGrid
+
+  I'm sure the first app to do this was something from the 60s or 70s
+  in Smalltalk or something but my first experience was C#. In C#
+  the UI library had a `PropertyGrid` which you could pass any class
+  and with would auto-magically make UI to edit the public fields
+  of that class. If you've ever used Unity, it's the same. You declare
+  a class and it immediately shows a UI for all of its public properties.
+
+  That's easier in a typed language than a more loose language like
+  JavaScript.
+
+  I'm still experimenting with ideas but it sure would be nice to
+  get that for JS. Just give it an object and get a UI. You can
+  then customize later.
+
+  To be more concrete. Here's some code to setup a GUI
+  
+  ```js
+  const s = {
+    someNumber: 123,
+    someString: 'hello',
+    someOption: 'dog',
+    someColor: '#ED3281',
+    someFunction: () => console.log('called')
+  };
+
+  const gui = new GUI();
+  gui.add(s, 'someNumber', 0, 200);  // range 0 to 200
+  gui.add(s, 'someString');
+  gui.add(s, 'someOption', ['cat', 'bird', 'dog']);
+  gui.addColor(s, 'someColor');
+  gui.add(s, 'someFunction');
+  ```
+
+  I'd really like it to be this
+
+  ```js
+  const s = {
+    someNumber: 123,
+    someString: 'hello',
+    someOption: 'dog',
+    someColor: '#ED3281',
+    someFunction: () => console.log('called')
+  };
+
+  const gui = new GUI();
+  gui.add(s);
+  ```
+
+  At the moment that won't work. `someNumber` could only become
+  a `TextNumber` because there's no range. `someOption` would
+  only become a `Text` because there's no info that it's an enum.
+  `someColor` would become a `Text` because there's no info that
+  it's a color. So in the end only 2 of the 5 would work without
+  having to provide more info.
+
+  It's not clear in JS that adding that info would be a win
+  for keeping it simple but it sure would be nice.
+
+* ## Modularity
+
+  Ideally I'd like it to be easy to make UIs based on collections
+  of parts. A simple example might be a 3 component vector
+  editor that is the combination of 3 number editors.
+
+  I'm still experimenting. While muigui has components that
+  do this I'm not happy with the API ergonomics yet.
+
+  Similarly I'd like to more easily split layout so it's trivial
+  to layout sub components. Again, still experimenting.
+
+* ## Don't over specialize
+
+  This might be ranty, but I find libraries that try to do too much,
+  frustrating. In this case, it would
+  be a library that graphs data for you. The problem
+  with this functionality is that there is no end to
+  the number of features that will be requested.
+
+  You start with "graph an array of numbers".
+  Then you'll be asked to be able to supply a range.
+  Then you'll be asked to allow more than one array
+  for the graph.
+  You'll next be asked to let you specify a different
+  color for each array. Next you'll be asked to draw
+  axes, in different colors, with different units,
+  and labels. Then you'll be asked to have an option
+  to fill under the graph. Etc, etc, etc... forever.
+
+  In this case, It's arguably better to provide
+  a canvas and let the developer write their
+  own graphing code. Maybe provide an example or
+  a simple helper for the simplest case.
+
+  They can even choose when to update vs having to
+  choose an interval.
+
+  Let's compare
+
+  ```js
+  // tweakpane
+  const pane = new Pane();
+  pane.addBinding(PARAMS, 'wave', {
+    readonly: true,
+    view: 'graph',
+    min: -1,
+    max: +1,
+  });
+
+  // muigui
+  const gui = new GUI();
+  helpers.graph(gui.addCanvas('wave'), waveData, {
+    min: -1,
+    max: +1,
+  });
+  ```
+
+  It wasn't any harder to use, but the fact that we
+  just returned a canvas and left the rest outside
+  the library made it way more flexible.
+
+  This problem of providing too specialized a solution
+  is endemic throughout the library ecosystem of pretty much
+  every language.
+
+  There's a balance, but in general, if you need
+  to add more and more options then it was probably the
+  wrong solution. It's better to provide the
+  building blocks.
+
+## No Save/Restore
+
+The problem with save/restore in lil.gui etc is it assumes the data
+I want to edit can be serialized to JSON
+
+Just as the simplest example I can think of
+
+```js
+const material = new THREE.MeshBasicMaterial();
 
 const gui = new GUI();
-gui.add(s, options);
+gui.addColor(material, 'color');
 ```
 
-## What
+It makes no sense to save/restore here. I'm editing a three.js material.
+If I wanted to serialize anything I'd serialize the material.
 
-It is not a general purpose library for every type of GUI.
-Rather, it is a small, easy to use library for small apps.
-Basically I liked how simple it was to use dat.gui to add
-a few sliders and options to a demo.
+Otherwise I can just save the stuff I passed to the GUI.
 
-I thought I'd try to make a CSS/DOM based UI standard elements
-only and then require CSS to style it and see how far I got.
+```js
+  const s = {
+    someNumber: 123,
+    someString: 'hello',
+    someOption: 'dog',
+    someColor: '#ED3281',
+  };
 
-### Not invented here syndrome
+  // save
+  const str = JSON.stringify(s);
 
-It's possible this already exists but if so I couldn't find it.
-Most UI libraries seem to be giant and require a build step.
-I wanted something hopefully not too big and something I could
-easily add to any example with 1 file (or 2 if you add CSS).
+  // restore
+  Object.assign(s, JSON.parse(str));
+  gui.updateDisplay(); 
+```
 
-## muigui - wat?
+In other words, the serialization is too specialized. It's trivial
+to call `JSON.stringify` on data that serializable. No need to put
+serialization in the GUI. Note: I get that you might want to save
+some hidden gui state like whether or not a folder is expanded.
+You still run into the issue though that the data being edited
+might not be easily serializable so you'd have to find another solution.
 
-https://user-images.githubusercontent.com/234804/177000460-3449c2dd-da94-4119-903f-cc7460b46e7b.mp4
+## Future
 
--->
+I'm under sure how much time I'll continue to put into this.
+I get the feeling other people are far more motivated to make
+UIs. Maybe if I'm lucky they'll take some inspiration from
+the thoughts above and I'll find they've covered it all.
 
 ## License
 

package/package.json

@@ -1,17 +1,22 @@
 {
   "name": "muigui",
-  "version": "0.0.10",
+  "version": "0.0.13",
   "description": "A Simple GUI",
   "main": "muigui.js",
   "module": "src/muigui.js",
   "type": "module",
   "scripts": {
     "build": "npm run build-normal",
+    "build-ci": "npm run build && node build/prep-for-deploy.js",
     "build-normal": "rollup -c",
     "build-min": "rollup -c",
+    "check-ci": "npm run pre-push",
     "eslint": "eslint \"**/*.js\"",
-    "pre-push": "npm run eslint",
-    "test": "echo \"Error: no test specified\" && exit 1"
+    "fix": "eslint --fix",
+    "pre-push": "npm run eslint && npm run build && npm run test",
+    "start": "node build/serve.js",
+    "test": "node test/puppeteer.js",
+    "watch": "npm run start"
   },
   "repository": {
     "type": "git",
@@ -35,10 +40,20 @@
   "devDependencies": {
     "@rollup/plugin-node-resolve": "^15.0.1",
     "@rollup/plugin-terser": "^0.4.0",
-    "eslint": "^8.20.0",
+    "@rollup/plugin-typescript": "^11.1.5",
+    "@tsconfig/recommended": "^1.0.3",
+    "@typescript-eslint/eslint-plugin": "^6.12.0",
+    "@typescript-eslint/parser": "^6.12.0",
+    "chokidar": "^3.5.3",
+    "eslint": "^8.54.0",
     "eslint-plugin-html": "^7.1.0",
+    "eslint-plugin-one-variable-per-var": "^0.0.3",
     "eslint-plugin-optional-comma-spacing": "0.0.4",
     "eslint-plugin-require-trailing-comma": "0.0.1",
-    "rollup": "^3.20.2"
+    "puppeteer": "^21.5.2",
+    "rollup": "^3.20.2",
+    "servez": "^2.1.2",
+    "tslib": "^2.6.2",
+    "typescript": "5.2"
   }
 }

package/src/controllers/Button.js

@@ -26,6 +26,9 @@ export default class Button extends Controller {
         }));
     this.setOptions({name: property, ...options});
   }
+  name(name) {
+    this.#buttonElem.textContent = name;
+  }
   setOptions(options) {
     copyExistingProperties(this.#options, options);
     const {name} = this.#options;

package/src/controllers/Canvas.js

@@ -5,8 +5,8 @@ import LabelController from './LabelController.js';
 export default class Canvas extends LabelController {
   #canvasElem;
 
-  constructor() {
-    super('muigui-canvas');
+  constructor(name) {
+    super('muigui-canvas', name);
     this.#canvasElem = this.add(
       new ElementView('canvas', 'muigui-canvas'),
     ).domElement;

package/src/controllers/ColorChooser.js

@@ -1,12 +1,53 @@
+/* eslint-disable no-underscore-dangle */
+import {
+  colorFormatConverters,
+  guessFormat,
+  hasAlpha,
+  hexToUint8RGB,
+  hslToRgbUint8,
+  rgbUint8ToHsl,
+  uint8RGBToHex,
+} from '../libs/color-utils.js';
 import ColorChooserView from '../views/ColorChooserView.js';
 import TextView from '../views/TextView.js';
 import PopDownController from './PopDownController.js';
 
 export default class ColorChooser extends PopDownController {
-  constructor(object, property) {
+  #colorView;
+  #textView;
+  #to;
+
+  constructor(object, property, options = {}) {
     super(object, property, 'muigui-color-chooser');
-    this.addTop(new TextView(this));
-    this.addBottom(new ColorChooserView(this));
+    const format = options.format || guessFormat(this.getValue());
+    const {color, text} = colorFormatConverters[format];
+    this.#to = color.to;
+    this.#textView = new TextView(this, {converters: text, alpha: hasAlpha(format)});
+    this.#colorView = new ColorChooserView(this, {converters: color, alpha: hasAlpha(format)});
+    this.addTop(this.#textView);
+    this.addBottom(this.#colorView);
+    // WTF! FIX!
+    this.___setKnobHelper = true;
     this.updateDisplay();
   }
+  #setKnobHelper() {
+    if (this.#to) {
+      const hex6Or8 = this.#to(this.getValue());
+      const alpha = hex6Or8.length === 9 ? hex6Or8.substring(7, 9) : 'FF';
+      const hsl = rgbUint8ToHsl(hexToUint8RGB(hex6Or8));
+      hsl[2] = (hsl[2] + 50) % 100;
+      const hex = uint8RGBToHex(hslToRgbUint8(hsl));
+      this.setKnobColor(`${hex6Or8.substring(0, 7)}${alpha}`, hex);
+    }
+  }
+  updateDisplay() {
+    super.updateDisplay();
+    if (this.___setKnobHelper) {
+      this.#setKnobHelper();
+    }
+  }
+  setOptions(options) {
+    super.setOptions(options);
+    return this;
+  }
 }

package/src/controllers/Container.js

@@ -43,14 +43,14 @@ export default class Container extends Controller {
     }
     return this;
   }
-  _addControllerImpl(controller) {
+  #addControllerImpl(controller) {
     this.domElement.appendChild(controller.domElement);
     this.#controllers.push(controller);
     controller.setParent(this);
     return controller;
   }
   addController(controller) {
-    return this.#childDestController._addControllerImpl(controller);
+    return this.#childDestController.#addControllerImpl(controller);
   }
   pushContainer(container) {
     this.addController(container);

package/src/controllers/Folder.js

@@ -11,6 +11,7 @@ export default class Folder extends Container {
       type: 'button',
       onClick: () => this.toggleOpen(),
     }, [this.#labelElem]));
+    this.pushContainer(new Container('muigui-open-container'));
     this.pushContainer(new Container());
     this.name(name);
     this.open();

package/src/controllers/PopDownController.js

@@ -29,8 +29,11 @@ pc.addBottom
 export default class PopDownController extends ValueController {
   #top;
   #valuesView;
+  #checkboxElem;
   #bottom;
-  #options = {open: false};
+  #options = {
+    open: false,
+  };
 
   constructor(object, property, options = {}) {
     super(object, property, 'muigui-pop-down-controller');
@@ -46,12 +49,25 @@ export default class PopDownController extends ValueController {
       type: 'checkbox',
       onChange: () => {
         this.#options.open = checkboxElem.checked;
+        this.updateDisplay();
       },
     }));
+    this.#checkboxElem = checkboxElem;
     this.#valuesView = this.#top.add(new ElementView('div', 'muigui-pop-down-values'));
-    this.#bottom = this.add(new ElementView('div', 'muigui-pop-down-bottom'));
+    const container = new ElementView('div', 'muigui-pop-down-bottom muigui-open-container');
+    this.#bottom = new ElementView('div');
+    container.add(this.#bottom);
+    this.add(container);
     this.setOptions(options);
   }
+  setKnobColor(bgCssColor/*, fgCssColor*/) {
+    if (this.#checkboxElem) {
+      this.#checkboxElem.style = `
+        --range-color: ${bgCssColor};
+        --value-bg-color: ${bgCssColor};
+      `;
+    }
+  }
   updateDisplay() {
     super.updateDisplay();
     const {open} = this.#options;

package/src/controllers/Text.js

@@ -3,7 +3,7 @@ import ValueController from './ValueController.js';
 
 export default class Text extends ValueController {
   constructor(object, property) {
-    super(object, property, 'muigui-checkbox');
+    super(object, property, 'muigui-text');
     this.add(new TextView(this));
     this.updateDisplay();
   }

package/src/controllers/TextNumber.js

@@ -11,7 +11,7 @@ export default class TextNumber extends ValueController {
   #step;
 
   constructor(object, property, options = {}) {
-    super(object, property, 'muigui-checkbox');
+    super(object, property, 'muigui-text-number');
     this.#textView = this.add(new NumberView(this, options));
     this.updateDisplay();
   }

package/src/controllers/create-controller.js

@@ -24,6 +24,9 @@ export function createController(object, property, ...args) {
   if (Array.isArray(arg1)) {
     return new Select(object, property, {keyValues: arg1});
   }
+  if (arg1 && arg1.keyValues) {
+    return new Select(object, property, {keyValues: arg1.keyValues});
+  }
 
   const t = typeof object[property];
   switch (t) {

package/src/{esm.js → esm.ts}

@@ -9,4 +9,12 @@ export { default as Slider } from './controllers/Slider.js';
 export { default as TextNumber } from './controllers/TextNumber.js';
 export { default as Vec2 } from './controllers/Vec2.js';
 
+import {graph} from './libs/graph.js';
+import {monitor} from './libs/monitor.js';
+
+export const helpers = {
+  graph,
+  monitor,
+};
+
 export default GUI;