@kupcad/ui 0.0.0-stage → 0.1.0

package/src/params.js

@@ -0,0 +1,348 @@
+// The parameter panel's logic, apart from its markup: which control a parameter (or a part of its
+// value) gets, how the parameters group, which value a control shows, and whether a value given
+// in the panel is one the script takes (its schema's rules, core/src/core/param_rules.zig's),
+// checked before it leaves the panel; the run is the final check, and a frame names a value it
+// refused, and where in it.
+
+/** @import { ParamSpec, ParamValue, ParamValues, PathStep, Rule } from '@kupcad/protocol/types' */
+
+/**
+ * A slider (with a number beside it) for a number between a min and a max; a number field for
+ * one without; a select for a choice of listed values; a toggle for a boolean; a text field; and
+ * for a value of parts: a list (an element's control or block each, added and removed), a tuple
+ * (a control per place) or a record (a control per field of a Map).
+ * @typedef {'slider' | 'number' | 'select' | 'toggle' | 'text' | 'list' | 'tuple' | 'record'} Control
+ */
+
+/** @typedef {ParamValue} Value */
+
+/**
+ * A value the panel won't give, where in it (`[1, 'depth']`), and why, the place written first
+ * (`[1][:depth] must be at least 0.1`).
+ * @typedef {{ error: string, path: PathStep[] }} Refusal
+ */
+
+/**
+ * @param {Rule} rule
+ * @returns {Control}
+ */
+export function controlOf(rule) {
+  if (rule.type === 'array') return rule.tuple ? 'tuple' : 'list';
+  if (rule.type === 'map') return 'record';
+  if (rule.in) return 'select';
+  if (rule.type === 'boolean') return 'toggle';
+  if (rule.type === 'string') return 'text';
+  return rule.min !== null && rule.max !== null ? 'slider' : 'number';
+}
+
+/**
+ * The places of a value of parts, each with its rule and what labels its control: a tuple's
+ * places (their titles, else their indexes) or a Map's fields (their titles, else their names).
+ * @param {Rule} rule a tuple's or a Map's
+ * @returns {{ step: PathStep, rule: Rule, label: string }[]}
+ */
+export function partsOf(rule) {
+  if (rule.tuple) {
+    return rule.tuple.map((place, index) => ({
+      step: index,
+      rule: place,
+      label: place.title ?? String(index),
+    }));
+  }
+  return (rule.fields ?? []).map((field) => ({
+    step: field.name,
+    rule: field,
+    label: field.title ?? field.name,
+  }));
+}
+
+/**
+ * A number control's increment: the script's `step:`, else 1 for one between a `min` and a
+ * `max` (a slider moved by a hand lands on whole numbers, not on 27.41112), or, for a range
+ * narrower than 1, which a step of 1 couldn't move in, the power of ten that gives it at least
+ * ten positions; any value for a number with no range.
+ * @param {Rule} rule
+ * @returns {number | 'any'}
+ */
+export function stepOf(rule) {
+  if (rule.step !== null) return rule.step;
+  const { min, max } = rule;
+  if (min === null || max === null || !(max > min)) return 'any';
+  const range = max - min;
+  return range >= 1 ? 1 : 10 ** (Math.floor(Math.log10(range)) - 1);
+}
+
+/**
+ * The parameters by their `group:`, the groups in the order the script first names them: those
+ * without one first, under no heading.
+ * @param {ParamSpec[]} parameters
+ * @returns {{ group: string | null, parameters: ParamSpec[] }[]}
+ */
+export function groupsOf(parameters) {
+  /** @type {Map<string | null, ParamSpec[]>} */
+  const groups = new Map([[null, []]]);
+  for (const spec of parameters) {
+    const members = groups.get(spec.group) ?? [];
+    members.push(spec);
+    groups.set(spec.group, members);
+  }
+  return [...groups]
+    .filter(([, members]) => members.length > 0)
+    .map(([group, members]) => ({ group, parameters: members }));
+}
+
+/**
+ * The value a parameter's control shows: the one set in the panel, else the one the run took,
+ * else its default (null when it has none, or the script computes it and no run took one).
+ * @param {ParamSpec} spec
+ * @param {ParamValues} overrides
+ * @param {ParamValues} values
+ * @returns {Value | null}
+ */
+export function shownValue(spec, overrides, values) {
+  return ownValue(overrides, spec.name) ?? ownValue(values, spec.name) ?? spec.default_value;
+}
+
+/**
+ * Whether the panel sets the parameter `name`: by its own key, so a parameter named like an
+ * Object's member (`constructor`) isn't taken for set.
+ * @param {ParamValues} overrides
+ * @param {string} name
+ */
+export const isOverridden = (overrides, name) => Object.hasOwn(overrides, name);
+
+/**
+ * The value `values` holds under `name` itself, not one an Object has (`constructor` read a
+ * function).
+ * @param {ParamValues} values
+ * @param {string} name
+ * @returns {Value | undefined}
+ */
+const ownValue = (values, name) => (Object.hasOwn(values, name) ? values[name] : undefined);
+
+/**
+ * What a new part of `rule` starts as: its first choice, else what is blank for its kind (a
+ * number in its range, each of a tuple's places, each of a Map's fields).
+ * @param {Rule} rule
+ * @returns {Value}
+ */
+export function blankOf(rule) {
+  if (rule.in) return rule.in[0];
+  switch (rule.type) {
+    case 'number': {
+      // Zero, into its range
+      return Math.min(Math.max(0, rule.min ?? -Infinity), rule.max ?? Infinity);
+    }
+    case 'boolean':
+      return false;
+    case 'array':
+      return rule.tuple ? rule.tuple.map(blankOf) : [];
+    case 'map':
+      return Object.fromEntries((rule.fields ?? []).map((field) => [field.name, blankOf(field)]));
+    default:
+      return '';
+  }
+}
+
+/**
+ * What a new element of a list starts as: a copy of the last, else a blank one.
+ * @param {Rule} rule a list's
+ * @param {readonly Value[]} items
+ * @returns {Value}
+ */
+export function newElement(rule, items) {
+  if (items.length > 0) return structuredClone(items[items.length - 1]);
+  return blankOf(/** @type {Rule} */ (rule.items));
+}
+
+/**
+ * Whether a list may have an element added, or removed: its `max_items` and `min_items`.
+ * @param {Rule} rule a list's
+ * @param {number} count its elements now
+ */
+export const canAdd = (rule, count) => rule.max_items === null || count < rule.max_items;
+/** @param {Rule} rule @param {number} count */
+export const canRemove = (rule, count) => rule.min_items === null || count > rule.min_items;
+
+/**
+ * Whether `a` and `b` are one value: arrays and objects by what they hold.
+ * @param {Value | null | undefined} a
+ * @param {Value | null | undefined} b
+ * @returns {boolean}
+ */
+export function sameValue(a, b) {
+  if (Array.isArray(a) || Array.isArray(b)) {
+    return (
+      Array.isArray(a) &&
+      Array.isArray(b) &&
+      a.length === b.length &&
+      a.every((item, index) => sameValue(item, b[index]))
+    );
+  }
+  if (isRecord(a) || isRecord(b)) {
+    if (!isRecord(a) || !isRecord(b)) return false;
+    const keys = Object.keys(a);
+    return (
+      keys.length === Object.keys(b).length &&
+      keys.every((key) => Object.hasOwn(b, key) && sameValue(a[key], b[key]))
+    );
+  }
+  return a === b;
+}
+
+/**
+ * @param {unknown} value
+ * @returns {value is { [field: string]: Value }}
+ */
+const isRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+
+/**
+ * `value` (the whole of it) with the part at `path` given `part`.
+ * @param {Value | null} value
+ * @param {PathStep[]} path
+ * @param {Value} part
+ * @returns {Value}
+ */
+export function withPart(value, path, part) {
+  if (path.length === 0) return part;
+  const [step, ...rest] = path;
+  if (typeof step === 'number') {
+    const items = Array.isArray(value) ? [...value] : [];
+    items[step] = withPart(items[step] ?? null, rest, part);
+    return items;
+  }
+  const fields = isRecord(value) ? { ...value } : {};
+  fields[step] = withPart(Object.hasOwn(fields, step) ? fields[step] : null, rest, part);
+  return fields;
+}
+
+/**
+ * The part of `value` at `path`; null where it has none.
+ * @param {Value | null} value
+ * @param {PathStep[]} path
+ * @returns {Value | null}
+ */
+export function partAt(value, path) {
+  let part = value;
+  for (const step of path) {
+    if (typeof step === 'number') part = Array.isArray(part) ? (part[step] ?? null) : null;
+    else part = isRecord(part) && Object.hasOwn(part, step) ? part[step] : null;
+  }
+  return part;
+}
+
+/**
+ * The place `path` names, as the core writes it: `[1][:depth]`.
+ * @param {PathStep[]} path
+ */
+export const placeOf = (path) =>
+  path.map((step) => (typeof step === 'number' ? `[${step}]` : `[:${step}]`)).join('');
+
+/**
+ * What a control gave, as the parameter's value (a part of it, for a part's rule), or why the
+ * script wouldn't take it and where.
+ * @param {Rule} rule
+ * @param {Value | null} input
+ * @returns {{ value: Value } | Refusal}
+ */
+export function validate(rule, input) {
+  const result = read(rule, input, []);
+  if ('value' in result) return result;
+  const place = placeOf(result.path);
+  return { error: place ? `${place} ${result.error}` : result.error, path: result.path };
+}
+
+/**
+ * @param {Rule} rule
+ * @param {Value | null} input
+ * @param {PathStep[]} path where `input` is in the value
+ * @returns {{ value: Value } | Refusal}
+ */
+function read(rule, input, path) {
+  if (rule.type === 'array') return readArray(rule, input, path);
+  if (rule.type === 'map') return readMap(rule, input, path);
+  const choices = rule.in;
+  if (choices) {
+    const choice = choices.find((listed) => String(listed) === String(input));
+    return choice === undefined
+      ? { error: `must be one of ${choices.join(', ')}`, path }
+      : { value: choice };
+  }
+  if (rule.type === 'boolean') return { value: input === true || input === 'true' };
+  if (rule.type === 'string') return { value: String(input ?? '') };
+  const text = String(input ?? '').trim();
+  const number = Number(text);
+  if (text === '' || !Number.isFinite(number)) return { error: 'must be a number', path };
+  if (rule.min !== null && number < rule.min)
+    return { error: `must be at least ${rule.min}`, path };
+  if (rule.max !== null && number > rule.max) return { error: `must be at most ${rule.max}`, path };
+  return { value: number };
+}
+
+/**
+ * @param {Rule} rule
+ * @param {Value | null} input
+ * @param {PathStep[]} path
+ * @returns {{ value: Value } | Refusal}
+ */
+function readArray(rule, input, path) {
+  if (!Array.isArray(input)) return { error: 'must be a list', path };
+  if (rule.tuple && input.length !== rule.tuple.length) {
+    return { error: `must have ${rule.tuple.length} items`, path };
+  }
+  if (rule.min_items !== null && input.length < rule.min_items) {
+    return { error: `must have at least ${rule.min_items} items`, path };
+  }
+  if (rule.max_items !== null && input.length > rule.max_items) {
+    return { error: `must have at most ${rule.max_items} items`, path };
+  }
+  /** @type {Value[]} */
+  const items = [];
+  for (const [index, item] of input.entries()) {
+    const place = rule.tuple ? rule.tuple[index] : /** @type {Rule} */ (rule.items);
+    const result = read(place, item, [...path, index]);
+    if (!('value' in result)) return result;
+    items.push(result.value);
+  }
+  return { value: items };
+}
+
+/**
+ * @param {Rule} rule
+ * @param {Value | null} input
+ * @param {PathStep[]} path
+ * @returns {{ value: Value } | Refusal}
+ */
+function readMap(rule, input, path) {
+  if (!isRecord(input)) return { error: 'must be a record', path };
+  /** @type {{ [field: string]: Value }} */
+  const fields = {};
+  for (const field of rule.fields ?? []) {
+    const given = Object.hasOwn(input, field.name) ? input[field.name] : null;
+    const result = read(field, given, [...path, field.name]);
+    if (!('value' in result)) return result;
+    fields[field.name] = result.value;
+  }
+  return { value: fields };
+}
+
+/**
+ * `overrides` with `name` set to `value`.
+ * @param {ParamValues} overrides
+ * @param {string} name
+ * @param {Value} value
+ * @returns {ParamValues}
+ */
+export function withOverride(overrides, name, value) {
+  return { ...overrides, [name]: value };
+}
+
+/**
+ * `overrides` without `name`: the parameter takes the script's value again.
+ * @param {ParamValues} overrides
+ * @param {string} name
+ * @returns {ParamValues}
+ */
+export function withoutOverride(overrides, name) {
+  return Object.fromEntries(Object.entries(overrides).filter(([key]) => key !== name));
+}

package/src/range.js

@@ -0,0 +1,19 @@
+// How far along a range input's thumb is, for controls.css's .kc-range: WebKit and Blink fill
+// no track of their own, so the panel sets this as --kc-range-fill as the value changes.
+
+/**
+ * `value`'s place between `min` and `max` as a CSS percentage, held to 0% and 100%. A range
+ * input with no value puts its thumb half way, and so does this; a span that is none, at 0%.
+ * @param {unknown} value
+ * @param {number | string | null} [min] the input's (none: a browser's default, 0)
+ * @param {number | string | null} [max] the input's (none: a browser's default, 100)
+ * @returns {string}
+ */
+export function fillOf(value, min, max) {
+  const low = Number(min ?? 0);
+  const high = Number(max ?? 100);
+  if (!Number.isFinite(low) || !Number.isFinite(high) || high <= low) return '0%';
+  const at = value === null || value === undefined || value === '' ? NaN : Number(value);
+  if (!Number.isFinite(at)) return '50%';
+  return `${Math.min(100, Math.max(0, ((at - low) / (high - low)) * 100))}%`;
+}

package/src/recent.js

@@ -0,0 +1,44 @@
+// What a pane keeps of each thing it showed, for the next time it shows it: the most recently
+// shown kept, as many as it keeps, the least recently shown let go past them. Only for as long
+// as the pane is there: nothing is written anywhere.
+
+/** @template T */
+export class Recent {
+  /** @type {Map<string, T>} */
+  #kept = new Map();
+  #most;
+
+  /** @param {number} most how many it keeps */
+  constructor(most) {
+    this.#most = most;
+  }
+
+  /**
+   * Keeps `value` for `key`, the most recent; the least recent goes past the most kept.
+   * @param {string} key
+   * @param {T} value
+   */
+  keep(key, value) {
+    this.#kept.delete(key);
+    this.#kept.set(key, value);
+    for (const oldest of this.#kept.keys()) {
+      if (this.#kept.size <= this.#most) break;
+      this.#kept.delete(oldest);
+    }
+  }
+
+  /**
+   * What is kept for `key`, the most recent now; none for a key not kept, or let go.
+   * @param {string} key
+   * @returns {T | undefined}
+   */
+  get(key) {
+    const value = this.#kept.get(key);
+    if (value !== undefined) this.keep(key, value);
+    return value;
+  }
+
+  get size() {
+    return this.#kept.size;
+  }
+}

package/src/run-status.js

@@ -0,0 +1,78 @@
+// How the run a viewer shows went, for its status line, and what it said went wrong: from the
+// preview frame's header, the same for every host.
+
+/** @import { FrameHeader } from '@kupcad/protocol/types' */
+
+/**
+ * The run of the script shown: running, done, or failed; how long it took (ms), and how many
+ * warnings it gave.
+ * @typedef {object} RunStatus
+ * @property {'running' | 'ready' | 'failed'} state
+ * @property {number} [runMs]
+ * @property {number} [warnings]
+ */
+
+/**
+ * Something the run said went wrong: why it failed, or a warning, and where in the script it
+ * was (a 1-based line and column, in UTF-8 bytes), null where it wasn't running.
+ * @typedef {object} Problem
+ * @property {'error' | 'warning'} severity
+ * @property {string} message
+ * @property {number | null} line
+ * @property {number | null} column
+ */
+
+/** @type {Record<RunStatus['state'], string>} */
+const STATES = { running: 'Running…', ready: 'Ready', failed: 'Failed' };
+
+/**
+ * The run whose frame is `header`: running while none came (null).
+ * @param {FrameHeader | null} header
+ * @returns {RunStatus}
+ */
+export function runStatusOf(header) {
+  if (!header) return { state: 'running' };
+  return {
+    state: header.error ? 'failed' : 'ready',
+    runMs: header.timing.runMs,
+    warnings: header.warnings.length,
+  };
+}
+
+/**
+ * What the status line says of `run`: its state, then its time and its warnings.
+ * @param {RunStatus} run
+ */
+export function describeRun(run) {
+  const said = [STATES[run.state]];
+  if (run.runMs !== undefined) said.push(`${Math.round(run.runMs)} ms`);
+  if (run.warnings) said.push(`${run.warnings} warning${run.warnings === 1 ? '' : 's'}`);
+  return said.join(' · ');
+}
+
+/**
+ * What the run whose frame is `header` said went wrong: why it failed first, then its warnings;
+ * nothing while none came (null).
+ * @param {FrameHeader | null} header
+ * @returns {Problem[]}
+ */
+export function problemsOf(header) {
+  if (!header) return [];
+  /** @type {Problem[]} */
+  const problems = header.warnings.map(({ message, line, column }) => ({
+    severity: 'warning',
+    message,
+    line,
+    column,
+  }));
+  const { error } = header;
+  if (error) {
+    problems.unshift({
+      severity: 'error',
+      message: error.message,
+      line: error.line,
+      column: error.column,
+    });
+  }
+  return problems;
+}

package/src/settings.js

@@ -0,0 +1,82 @@
+// What a person set in a host's panels (the panes' sizes, whether they show), kept where the
+// host keeps such things. The playground keeps it in the page's localStorage (localSettings),
+// the VS Code extension and the desktop app their own way, each on memorySettings; a host that
+// keeps nothing gives memorySettings alone.
+//
+// Settings are reactive: a pane reads its value in a $derived, and follows it as it is set,
+// wherever from. A size dragged is the pane's own until the drag is done, and set then, once.
+// A key not kept yet is followed as the map is (a SvelteMap's reader of a key it doesn't hold
+// reads again as any key is added): a size never kept, mid-drag as another key is kept for the
+// first time, goes back to its own. Svelte doesn't let a reaction follow state it made itself,
+// so a cell of a key's own, made as the key is first read, would never be followed.
+
+import { SvelteMap } from 'svelte/reactivity';
+
+/**
+ * A host's settings, by key: what `get` reads in a reaction (a $derived, an effect, the markup)
+ * it reads again when `set` changes it. A host's own are built on `memorySettings`.
+ * @typedef {object} Settings
+ * @property {(key: string) => unknown} get the value kept for `key`; undefined for none
+ * @property {(key: string, value: unknown) => void} set keeps `value` for `key`
+ */
+
+/**
+ * Settings kept in memory alone, from `values`: gone with the page.
+ * @param {Record<string, unknown>} [values]
+ * @returns {Settings}
+ */
+export function memorySettings(values = {}) {
+  const kept = new SvelteMap(Object.entries(values));
+  return { get: (key) => kept.get(key), set: (key, value) => void kept.set(key, value) };
+}
+
+/**
+ * Settings kept in `storage` (the page's localStorage) as one JSON object under `name`. A page
+ * that may not keep anything there (a private window's quota, a policy), or finds no JSON
+ * object under the name, keeps them in memory for the page's life.
+ * @param {string} [name]
+ * @param {Pick<Storage, 'getItem' | 'setItem'> | undefined} [storage]
+ * @returns {Settings}
+ */
+export function localSettings(name = 'kupcad.settings', storage = globalThis.localStorage) {
+  const settings = memorySettings(read(storage, name));
+  return {
+    get: settings.get,
+    set(key, value) {
+      settings.set(key, value);
+      try {
+        const all = { ...read(storage, name), [key]: value };
+        storage?.setItem(name, JSON.stringify(all));
+      } catch {
+        // Kept in memory: the page may not store anything
+      }
+    },
+  };
+}
+
+/**
+ * The JSON object `storage` keeps under `name`; an empty one for none, or for what isn't one.
+ * @param {Pick<Storage, 'getItem'> | undefined} storage
+ * @param {string} name
+ * @returns {Record<string, unknown>}
+ */
+function read(storage, name) {
+  try {
+    const parsed = JSON.parse(storage?.getItem(name) ?? '{}');
+    return typeof parsed === 'object' && parsed !== null && !Array.isArray(parsed) ? parsed : {};
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * A pane's size kept under `key`: a finite number of pixels, else `fallback` (none kept, or
+ * what was kept is no size).
+ * @param {Settings} settings
+ * @param {string} key
+ * @param {number} fallback
+ */
+export function sizeSetting(settings, key, fallback) {
+  const kept = settings.get(key);
+  return typeof kept === 'number' && Number.isFinite(kept) && kept > 0 ? kept : fallback;
+}

package/src/shortcuts.js

@@ -0,0 +1,59 @@
+// The keys and the pointer's moves a person can't see on the screen, listed in ShortcutsDialog:
+// the viewer's (VIEWER_SHORTCUTS), and a host's own groups before them. Named as the system
+// names its keys: ⌘ and ⌥ on a Mac, Ctrl and Alt elsewhere.
+
+/**
+ * A group of shortcuts under its title: each a key, or keys pressed together, and what it does.
+ * @typedef {object} ShortcutGroup
+ * @property {string} title
+ * @property {readonly (readonly [keys: string, what: string])[]} keys
+ * @property {string} [note] what a person needs to know first (where the keys work)
+ */
+
+/** @typedef {'mac' | 'windows' | 'other'} KeyboardSystem */
+
+/**
+ * The system the page runs on, as its keys are named.
+ * @param {string} [agent] the browser's user agent
+ * @returns {KeyboardSystem}
+ */
+export function keyboardSystem(agent = globalThis.navigator?.userAgent ?? '') {
+  if (/Mac|iPhone|iPad/.test(agent)) return 'mac';
+  return agent.includes('Windows') ? 'windows' : 'other';
+}
+
+/**
+ * The viewer's shortcuts, its keys named as `system` names them. Cmd is the Meta key, which
+ * Windows calls Win and Linux Super.
+ * @param {KeyboardSystem} system
+ * @returns {ShortcutGroup}
+ */
+export function viewerShortcuts(system) {
+  const alt = system === 'mac' ? '⌥' : 'Alt';
+  const meta = system === 'mac' ? '⌘' : system === 'windows' ? 'Win' : 'Super';
+  return {
+    title: 'Viewer',
+    note: 'Keys once the model has the focus: a click on it gives it.',
+    keys: [
+      ['0', 'Iso view'],
+      ['1', 'Top view'],
+      ['2', 'Bottom view'],
+      ['3', 'Front view'],
+      ['4', 'Back view'],
+      ['5', 'Left view'],
+      ['6', 'Right view'],
+      ['F', 'Fit the model'],
+      ['I', 'Zoom in'],
+      ['O', 'Zoom out'],
+      ['Drag', 'Turn the view'],
+      ['Right or middle drag', 'Pan'],
+      ['Wheel, pinch', 'Zoom'],
+      ['Shift + wheel', 'Pan'],
+      [`${alt} + wheel`, 'Move the section'],
+      [`${meta} + wheel`, 'Turn the view'],
+    ],
+  };
+}
+
+/** The viewer's shortcuts on the system the page runs on. */
+export const VIEWER_SHORTCUTS = viewerShortcuts(keyboardSystem());