@kupcad/ui 0.0.0-stage → 0.1.1

package/src/ParamField.svelte

@@ -0,0 +1,390 @@
+<!--
+  @component
+  One parameter, in rows: its title (its name where it has none) with a revert while the panel
+  overrides it, its description, its control as its rules say (params.js's controlOf) with its
+  unit, and why its value was refused: by the panel's own check, or by the run (`refused`, the
+  frame's error naming it, and `refusedAt`, where in its value), the control there marked. A
+  tuple's places and a Map's fields are controls side by side, each labelled on top; a list is
+  its elements, each a control (or a block of them) with a remove, and an add, as its
+  `min_items` and `max_items` allow.
+-->
+<script>
+  import {
+    canAdd,
+    canRemove,
+    controlOf,
+    newElement,
+    partAt,
+    partsOf,
+    sameValue,
+    stepOf,
+    validate,
+    withPart,
+  } from './params.js';
+  import { fillOf } from './range.js';
+
+  /** @import { ParamSpec, PathStep, Rule } from '@kupcad/protocol/types' */
+  /** @import { Value } from './params.js' */
+
+  /**
+   * @typedef {object} Props
+   * @property {ParamSpec} spec
+   * @property {Value | null} value what the control shows
+   * @property {boolean} overridden the panel sets it, in place of the script's value
+   * @property {string | null} refused why the run refused its value
+   * @property {PathStep[]} [refusedAt] where in its value the run refused it (all of it: empty)
+   * @property {(value: Value) => void} onset a value the script takes was given
+   * @property {() => void} onrevert
+   */
+
+  /** @type {Props} */
+  let { spec, value, overridden, refused, refusedAt = [], onset, onrevert } = $props();
+
+  const id = $props.id();
+  const errorId = `${id}-error`;
+  const descriptionId = `${id}-description`;
+  const labelId = `${id}-label`;
+  const control = $derived(controlOf(spec));
+  /** A list's elements, as it shows them (none while it has no value). */
+  const items = $derived(control === 'list' && Array.isArray(value) ? value : []);
+  /** A list's element's rule. */
+  const element = $derived(/** @type {Rule} */ (spec.items ?? spec));
+  /** Whether a list's elements are blocks of controls: tuples, or Maps. */
+  const blocks = $derived(
+    control === 'list' && (element.type === 'array' || element.type === 'map'),
+  );
+  /** What the control is labelled by: its title, else its name. */
+  const label = $derived(spec.title || spec.name);
+  /**
+   * Why the value last given isn't one the script takes, where in it, and the value shown then:
+   * another (a revert, the next run's) takes it away.
+   */
+  let refusal = $state(
+    /** @type {{ why: string, path: PathStep[], shown: Value | null } | null} */ (null),
+  );
+  // By what it holds: the array a state keeps is a copy, never the one shown
+  const invalid = $derived(refusal && sameValue(refusal.shown, value) ? refusal : null);
+  const message = $derived(invalid?.why ?? refused);
+  /** Where in the value the message is about: the panel's refusal's place, else the run's. */
+  const wrongAt = $derived(invalid ? invalid.path : refused !== null ? refusedAt : null);
+
+  /**
+   * What ties the control at `path` to the description and the message, and marks it while the
+   * message is about it.
+   * @param {PathStep[]} path
+   */
+  function described(path) {
+    const wrong = wrongAt !== null && sameValue(wrongAt, path);
+    return {
+      'aria-invalid': wrong ? true : undefined,
+      'aria-describedby':
+        [spec.description && descriptionId, message !== null && errorId]
+          .filter(Boolean)
+          .join(' ') || undefined,
+    };
+  }
+
+  /** @param {Value} input the whole value */
+  function commit(input) {
+    const result = validate(spec, input);
+    if ('error' in result) {
+      refusal = { why: result.error, path: result.path, shown: value };
+      return;
+    }
+    refusal = null;
+    onset(result.value);
+  }
+
+  function revert() {
+    refusal = null;
+    onrevert();
+  }
+
+  /** @param {Event} event */
+  const inputOf = (event) => /** @type {HTMLInputElement} */ (event.currentTarget).value;
+
+  /**
+   * Fills a slider's track to its thumb as it is dragged: its value is given only once let go.
+   * @param {Event} event
+   */
+  function dragged(event) {
+    const slider = /** @type {HTMLInputElement} */ (event.currentTarget);
+    slider.style.setProperty('--kc-range-fill', fillOf(slider.value, slider.min, slider.max));
+  }
+</script>
+
+<!--
+  The control of a scalar of `rule` (the parameter, or a part of its value at `path`), showing
+  `shown`; `named` ties it to its label (an id) or names it (an aria-label).
+-->
+{#snippet scalar(
+  /** @type {Rule} */ rule,
+  /** @type {Value | null} */ shown,
+  /** @type {PathStep[]} */ path,
+  /** @type {{ id?: string, 'aria-label'?: string }} */ named,
+)}
+  {@const kind = controlOf(rule)}
+  {@const chosen = (rule.in ?? []).findIndex((choice) => String(choice) === String(shown))}
+  {@const give = (/** @type {Value} */ input) => commit(withPart(value, path, input))}
+  {#if kind === 'slider'}
+    <input
+      class="kc-range"
+      type="range"
+      min={rule.min}
+      max={rule.max}
+      step={stepOf(rule)}
+      value={shown ?? ''}
+      style:--kc-range-fill={fillOf(shown, rule.min, rule.max)}
+      aria-label="{named['aria-label'] ?? label} slider"
+      oninput={dragged}
+      onchange={(event) => give(inputOf(event))}
+      {...described(path)}
+    />
+  {/if}
+  {#if kind === 'slider' || kind === 'number'}
+    <input
+      {...named}
+      class="kc-control"
+      type="number"
+      min={rule.min}
+      max={rule.max}
+      step={stepOf(rule)}
+      value={shown ?? ''}
+      onchange={(event) => give(inputOf(event))}
+      {...described(path)}
+    />
+  {:else if kind === 'select'}
+    <select
+      {...named}
+      class="kc-control"
+      onchange={(event) =>
+        give(/** @type {Value[]} */ (rule.in)[Number(event.currentTarget.value)])}
+      {...described(path)}
+    >
+      <!-- No choice yet (it has no default, or the script computes it, and no run took one) -->
+      {#if chosen === -1}<option value="" selected disabled></option>{/if}
+      {#each rule.in ?? [] as choice, index (index)}
+        <option value={index} selected={index === chosen}>{choice}</option>
+      {/each}
+    </select>
+  {:else if kind === 'toggle'}
+    <input
+      {...named}
+      class="kc-check"
+      type="checkbox"
+      checked={shown === true}
+      onchange={(event) => give(event.currentTarget.checked)}
+      {...described(path)}
+    />
+  {:else}
+    <input
+      {...named}
+      class="kc-control"
+      type="text"
+      value={shown ?? ''}
+      onchange={(event) => give(inputOf(event))}
+      {...described(path)}
+    />
+  {/if}
+  {#if rule.unit}<span class="unit">{rule.unit}</span>{/if}
+{/snippet}
+
+<!-- A tuple's places, or a Map's fields, of the value at `path`: side by side, labelled on top -->
+{#snippet parts(
+  /** @type {Rule} */ rule,
+  /** @type {Value | null} */ shown,
+  /** @type {PathStep[]} */ path,
+)}
+  <div class="parts">
+    {#each partsOf(rule) as part (part.step)}
+      {@const at = [...path, part.step]}
+      <!-- Of a separator the field's own ids don't have: a field may be named `label` -->
+      {@const partId = `${id}/${at.join('/')}`}
+      <div class="part">
+        <label for={partId}>{part.label}</label>
+        <div class="control">
+          {@render scalar(part.rule, partAt(shown, [part.step]), at, { id: partId })}
+        </div>
+      </div>
+    {/each}
+  </div>
+{/snippet}
+
+<div class="field" class:overridden>
+  <div class="head">
+    <!-- The name the script reads it by, where the title hides it -->
+    <label
+      id={labelId}
+      for={control === 'list' || control === 'tuple' || control === 'record' ? undefined : id}
+      title={spec.title ? spec.name : undefined}>{label}</label
+    >
+    {#if overridden}
+      <button type="button" class="revert" aria-label="Revert {label}" onclick={revert}> ↺ </button>
+    {/if}
+  </div>
+  {#if spec.description}
+    <p class="description" id={descriptionId}>{spec.description}</p>
+  {/if}
+  {#if control === 'list'}
+    <ol class="list" aria-labelledby={labelId}>
+      {#each items as item, index (index)}
+        <li class={blocks ? 'block' : 'control'}>
+          {#if blocks}
+            <div class="block-head">
+              <span class="index">[{index}]</span>
+              {@render remove(index)}
+            </div>
+            <div role="group" aria-label="{label} [{index}]">
+              {@render parts(element, item, [index])}
+            </div>
+          {:else}
+            {@render scalar(element, item, [index], { 'aria-label': `${label} [${index}]` })}
+            {@render remove(index)}
+          {/if}
+        </li>
+      {/each}
+    </ol>
+    <button
+      type="button"
+      class="add"
+      aria-label="Add to {label}"
+      disabled={!canAdd(spec, items.length)}
+      onclick={() => commit([...items, newElement(spec, items)])}>+ Add</button
+    >
+  {:else if control === 'tuple' || control === 'record'}
+    <div role="group" aria-labelledby={labelId}>
+      {@render parts(spec, value, [])}
+    </div>
+  {:else}
+    <div class="control">
+      {@render scalar(spec, value, [], { id })}
+    </div>
+  {/if}
+  {#if message !== null}
+    <p class="error" id={errorId} role="alert">{message}</p>
+  {/if}
+</div>
+
+{#snippet remove(/** @type {number} */ index)}
+  <button
+    type="button"
+    class="remove"
+    aria-label="Remove {label} [{index}]"
+    disabled={!canRemove(spec, items.length)}
+    onclick={() => commit(items.filter((_, at) => at !== index))}>−</button
+  >
+{/snippet}
+
+<style>
+  .field {
+    display: flex;
+    flex-direction: column;
+    gap: 4px;
+    padding: 6px 0;
+  }
+  /* A line between one parameter and the next */
+  .field + .field {
+    border-top: 1px solid var(--kc-border);
+  }
+  .head {
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    gap: 4px;
+  }
+  label {
+    color: var(--kc-muted);
+    overflow-wrap: anywhere;
+  }
+  .description {
+    margin: 0;
+    color: var(--kc-muted);
+    font-size: 0.92em;
+  }
+  .overridden label {
+    color: var(--kc-fg);
+    font-weight: 600;
+  }
+  .control {
+    display: flex;
+    align-items: center;
+    gap: 4px;
+    min-width: 0;
+  }
+  /* As wide as the row leaves it: its own width (a browser's 129px) would widen the panel */
+  input[type='range'] {
+    flex: 1;
+    width: 0;
+    min-width: 4em;
+  }
+  .kc-control {
+    min-width: 0;
+    width: 5em;
+    padding: 2px 4px;
+  }
+  input[type='text'] {
+    flex: 1;
+  }
+  .unit {
+    color: var(--kc-muted);
+  }
+  .revert,
+  .remove,
+  .add {
+    font: inherit;
+    color: var(--kc-accent-text);
+    background: none;
+    border: none;
+    cursor: pointer;
+    padding: 0 2px;
+  }
+  .list {
+    display: flex;
+    flex-direction: column;
+    gap: 4px;
+    margin: 0;
+    padding: 0;
+    list-style: none;
+  }
+  .add {
+    align-self: flex-start;
+  }
+  .remove:disabled,
+  .add:disabled {
+    color: var(--kc-muted);
+    cursor: default;
+  }
+  /* A tuple's places, a Map's fields: side by side, wrapping where the panel is narrow */
+  .parts {
+    display: flex;
+    flex-wrap: wrap;
+    gap: 4px 8px;
+  }
+  .part {
+    display: flex;
+    flex-direction: column;
+    gap: 2px;
+    min-width: 0;
+  }
+  /* An element of a list of tuples or Maps */
+  .block {
+    display: flex;
+    flex-direction: column;
+    gap: 4px;
+    padding: 4px 6px;
+    border: 1px solid var(--kc-border);
+    border-radius: 3px;
+  }
+  .block-head {
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+  }
+  .index {
+    color: var(--kc-muted);
+  }
+  .error {
+    margin: 0;
+    color: var(--kc-error);
+  }
+</style>

package/src/ParamsPanel.svelte

@@ -0,0 +1,216 @@
+<!--
+  @component
+  The parameters' controls, from the schema a frame (or `kupcad doc`) gives: grouped by their
+  `group:`, each showing the value set in the panel, else the one the run took. `overrides` is
+  what the panel sets (bindable), each change (and revert) given to `onchange`, which a host
+  sends to the core; a value refused by the run is shown on its control. A bar at the top, held
+  there as the panel scrolls, says how many values are set; while any is, its Reset all reverts
+  them all at once, the panel's refusals with them. The button keeps its place when there is
+  nothing to reset, so nothing under the bar moves as a first value is set or the last reverted.
+  A value set back to the parameter's own (the one it showed before the panel set it: the run's,
+  the script's or a host's preset's) is a revert, not a value set.
+-->
+<script>
+  import ParamField from './ParamField.svelte';
+  import {
+    groupsOf,
+    isOverridden,
+    sameValue,
+    shownValue,
+    withOverride,
+    withoutOverride,
+  } from './params.js';
+
+  /** @import { Failure, ParamSpec, ParamValue, ParamValues, UiSchema } from '@kupcad/protocol/types' */
+
+  /**
+   * @typedef {object} Props
+   * @property {UiSchema} schema
+   * @property {ParamValues} [values] the values the run took
+   * @property {Failure | null} [error] the frame's error: the parameter it refused is marked,
+   *   and the place in its value
+   * @property {ParamValues} [overrides] the values the panel sets; bindable
+   * @property {(overrides: ParamValues) => void} [onchange]
+   */
+
+  /** @type {Props} */
+  let { schema, values = {}, error = null, overrides = $bindable({}), onchange } = $props();
+
+  const groups = $derived(groupsOf(schema.parameters));
+  const set = $derived(Object.keys(overrides).length);
+  /** How many times all were reset: the fields are made again, and their refusals go. */
+  let resets = $state(0);
+
+  /**
+   * Each parameter's own value, which setting it to again reverts it: the one it showed before
+   * the panel first set it. Taken again from a later run, not from `stale`, the run of the
+   * panel's value just reverted, until the next comes.
+   * @type {Map<string, { value: ParamValue | null, stale: ParamValues | null }>}
+   */
+  const own = new Map();
+
+  /** @param {ParamValues} next */
+  function change(next) {
+    overrides = next;
+    onchange?.(next);
+  }
+
+  /**
+   * The panel sets `spec` to `value`; to its own value, it sets it no more.
+   * @param {ParamSpec} spec
+   * @param {ParamValue} value
+   */
+  function setParam(spec, value) {
+    if (!isOverridden(overrides, spec.name) && own.get(spec.name)?.stale !== values) {
+      own.set(spec.name, { value: shownValue(spec, overrides, values), stale: null });
+    }
+    if (sameValue(value, own.get(spec.name)?.value)) revert(spec.name);
+    else change(withOverride(overrides, spec.name, value));
+  }
+
+  /** @param {string} name */
+  function revert(name) {
+    const kept = own.get(name);
+    if (kept) own.set(name, { ...kept, stale: values });
+    change(withoutOverride(overrides, name));
+  }
+
+  function resetAll() {
+    for (const [name, kept] of own) {
+      if (isOverridden(overrides, name)) own.set(name, { ...kept, stale: values });
+    }
+    resets += 1;
+    change({});
+  }
+</script>
+
+<form class="kc-params" onsubmit={(event) => event.preventDefault()}>
+  <div class="bar">
+    <span class="set">{set === 0 ? "The script's values" : `${set} changed`}</span>
+    <!-- Unseen, not gone, while nothing is set: its room kept, out of reach of the keys -->
+    <button
+      type="button"
+      class="kc-control reset"
+      title="Every parameter back to the script's value"
+      style:visibility={set > 0 ? null : 'hidden'}
+      onclick={resetAll}
+    >
+      Reset all
+    </button>
+  </div>
+  {#if schema.meta.title}<h2>{schema.meta.title}</h2>{/if}
+  {#if schema.meta.description}<p class="description">{schema.meta.description}</p>{/if}
+  {#snippet fields(/** @type {import('@kupcad/protocol/types').ParamSpec[]} */ parameters)}
+    <!-- Made again on a reset, not the groups around them: a folded one stays so -->
+    {#key resets}
+      {#each parameters as spec (spec.name)}
+        <ParamField
+          {spec}
+          value={shownValue(spec, overrides, values)}
+          overridden={isOverridden(overrides, spec.name)}
+          refused={error?.param === spec.name ? error.message : null}
+          refusedAt={error?.param === spec.name ? error.path : []}
+          onset={(value) => setParam(spec, value)}
+          onrevert={() => revert(spec.name)}
+        />
+      {/each}
+    {/key}
+  {/snippet}
+  {#each groups as { group, parameters } (group)}
+    {#if group}
+      <!-- A group under its title, folded away with it -->
+      <details class="group" open>
+        <summary>{group}</summary>
+        <div class="fields" role="group" aria-label={group}>{@render fields(parameters)}</div>
+      </details>
+    {:else}
+      <div class="fields">{@render fields(parameters)}</div>
+    {/if}
+  {:else}
+    <p class="empty">This script has no parameters.</p>
+  {/each}
+</form>
+
+<style>
+  .kc-params {
+    display: flex;
+    flex-direction: column;
+    gap: var(--kc-gap);
+    font-family: var(--kc-font);
+    font-size: var(--kc-font-size);
+    color: var(--kc-fg);
+    background: var(--kc-bg);
+  }
+  h2 {
+    margin: 0;
+    font-size: 1.1em;
+  }
+  .description,
+  .empty {
+    margin: 0;
+    color: var(--kc-muted);
+  }
+  /* Always there, a line under it, held at the top of the column as it scrolls: its own space
+     above it, so what scrolls under it shows nowhere above it (a host's column gives none) */
+  .bar {
+    position: sticky;
+    top: 0;
+    z-index: 1;
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    gap: var(--kc-gap);
+    padding: var(--kc-gap) 0 6px;
+    background: var(--kc-bg);
+    border-bottom: 1px solid var(--kc-border);
+  }
+  .set {
+    min-width: 0;
+    overflow: hidden;
+    text-overflow: ellipsis;
+    white-space: nowrap;
+    color: var(--kc-muted);
+  }
+  .reset {
+    flex: none;
+  }
+  /* Parameters, a line between each (ParamField) */
+  .fields {
+    display: flex;
+    flex-direction: column;
+    min-width: 0;
+    padding: 0 var(--kc-gap);
+  }
+  /* A group stands apart from its controls: a section with a header of its own */
+  .group {
+    border: 1px solid var(--kc-border);
+    border-radius: var(--kc-radius);
+    overflow: hidden;
+  }
+  summary {
+    display: flex;
+    align-items: center;
+    gap: 6px;
+    padding: 5px var(--kc-gap);
+    font-size: 0.85em;
+    font-weight: 600;
+    letter-spacing: 0.04em;
+    text-transform: uppercase;
+    color: var(--kc-section-fg);
+    background: var(--kc-section-bg);
+    cursor: pointer;
+    list-style: none;
+  }
+  summary::-webkit-details-marker {
+    display: none;
+  }
+  summary::before {
+    content: '▾';
+  }
+  .group:not([open]) summary::before {
+    content: '▸';
+  }
+  .group[open] summary {
+    border-bottom: 1px solid var(--kc-border);
+  }
+</style>