@alacris/ui 0.2.0 → 0.2.2

package/README.md

@@ -6,7 +6,7 @@ A complete, themeable design system built with **[Alacris](https://github.com/bm
 
 The tags are real custom elements, so they work in plain HTML and inside React, Vue, Svelte, Angular, Rails, Django, and [Alacris-Go](https://github.com/bmartel/alacris-go) — anywhere that renders a tag.
 
-**Docs:** [Getting started](https://bmartel.github.io/alacris/ui/getting-started/)
+**Docs:** [Live catalog](https://bmartel.github.io/alacris/ui/) · [Getting started](https://bmartel.github.io/alacris/ui/getting-started/)
 
 ## Install
 
@@ -46,10 +46,10 @@ The published package is plain ESM. Point an import map at a pinned CDN build of
 <script type="importmap">
 {
   "imports": {
-    "@alacris/core": "https://cdn.jsdelivr.net/npm/@alacris/core@0.11/dist/alacris.js",
-    "@alacris/ui": "https://cdn.jsdelivr.net/npm/@alacris/ui/src/index.js",
-    "@alacris/ui/theme": "https://cdn.jsdelivr.net/npm/@alacris/ui/src/theme/index.js",
-    "@alacris/ui/components/": "https://cdn.jsdelivr.net/npm/@alacris/ui/src/components/"
+    "@alacris/core": "https://cdn.jsdelivr.net/npm/@alacris/core@0.11.0/dist/alacris.js",
+    "@alacris/ui": "https://cdn.jsdelivr.net/npm/@alacris/ui@0.2.2/src/index.js",
+    "@alacris/ui/theme": "https://cdn.jsdelivr.net/npm/@alacris/ui@0.2.2/src/theme/index.js",
+    "@alacris/ui/components/": "https://cdn.jsdelivr.net/npm/@alacris/ui@0.2.2/src/components/"
   }
 }
 </script>
@@ -61,7 +61,7 @@ The published package is plain ESM. Point an import map at a pinned CDN build of
 <ui-button>Hello</ui-button>
 ```
 
-Pin both packages in production.
+Never mix two versions of `@alacris/core` on one page — two copies means two reactive graphs.
 
 ## Theming
 
@@ -135,6 +135,8 @@ ui/
   CONVENTIONS.md rules every component follows
 ```
 
+The live catalog is [bmartel.github.io/alacris/ui](https://bmartel.github.io/alacris/ui/) — every component plus a theme playground, no clone required.
+
 From a clone of the repo:
 
 ```bash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alacris/ui",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "Themeable design system for Alacris — Material defaults, sixty-eight custom elements, ESM-only, no build step.",
   "type": "module",
   "exports": {
@@ -66,7 +66,7 @@
     "url": "git+https://github.com/bmartel/alacris.git",
     "directory": "ui"
   },
-  "homepage": "https://bmartel.github.io/alacris/ui/getting-started/",
+  "homepage": "https://bmartel.github.io/alacris/ui/",
   "bugs": {
     "url": "https://github.com/bmartel/alacris/issues"
   },

package/src/components/ui-autocomplete.js

@@ -28,6 +28,7 @@ import { define, html, css, vars, computed, signal, effect, onCleanup, each } fr
 import { sys } from '../tokens/sys.js';
 import { base } from './base.js';
 import { formBind } from '../util/form.js';
+import { escapeLayer } from '../util/keys.js';
 import { presence } from '../motion/presence.js';
 import { fx } from '../motion/animate.js';
 import { autoUpdate } from '../util/position.js';
@@ -295,9 +296,15 @@ define('ui-autocomplete', {
           if (showPanel() && activeOpt()) { e.preventDefault(); commit(activeOpt().value); }
           else if (freeSolo()) commit(query().trim());
           break;
-        case 'Escape': open.set(false); break;
       }
     };
+    // The panel owns Escape while it is up, so that closing it inside a
+    // dialog does not close the dialog as well.
+    effect(() => {
+      if (!showPanel()) return;
+      return escapeLayer(() => open.set(false));
+    });
+
     const onFocus = () => { focused.set(true); open.set(true); };
     const onBlur = () => {
       focused.set(false);

package/src/components/ui-date-picker.js

@@ -38,6 +38,7 @@ import { formBind } from '../util/form.js';
 import { presence } from '../motion/presence.js';
 import { animate, fx } from '../motion/animate.js';
 import { autoUpdate } from '../util/position.js';
+import { escapeLayer } from '../util/keys.js';
 import { focusTrap, scrollLock } from '../util/focus.js';
 import './ui-icon-button.js';
 import './ui-button.js';
@@ -607,12 +608,14 @@ define('ui-date-picker', {
         if (e.composedPath().includes(host)) return;
         closePanel();
       };
-      const onEsc = (e) => { if (e.key === 'Escape') closePanel(); };
+      // Capture at the document is not early enough: a dialog registers the
+      // same way when it opens, so it is already listening by the time this
+      // panel does and one Escape closes both.
+      const releaseEsc = escapeLayer(closePanel);
       document.addEventListener('pointerdown', onDoc);
-      document.addEventListener('keydown', onEsc, true);
       return () => {
         document.removeEventListener('pointerdown', onDoc);
-        document.removeEventListener('keydown', onEsc, true);
+        releaseEsc();
       };
     });
     effect(() => {

package/src/components/ui-icon.js

@@ -1,6 +1,11 @@
 // <ui-icon> — an icon from the registry, or any slotted SVG.
 //
-// @prop  {string} name=''  — registry name (see util/icons.js); empty renders the slot
+// Names are kebab-case (`arrow-forward`). Underscores are accepted
+// (`arrow_forward`). `iconNames()` lists the built-in set; apps add more
+// with `registerIcons({ name: 'M…' })`. An unknown name logs a warning
+// once and renders a placeholder instead of an empty hole.
+//
+// @prop  {string} name=''  — registry name; empty renders the slot
 // @prop  {string} label='' — accessible name; empty marks the icon decorative
 // @prop  {string} size=''  — CSS length; overrides --ui-icon-size for this element
 // @slot  (default) — a custom <svg> when no name is given
@@ -8,7 +13,10 @@
 
 import { define, html, svg, css, vars, effect } from '@alacris/core';
 import { base } from './base.js';
-import { iconPath, iconsVersion } from '../util/icons.js';
+import { iconPath, iconsVersion, warnUnknownIcon } from '../util/icons.js';
+
+// Hollow square — obviously not a real glyph, so a typo is visible.
+const MISSING = 'M3 3v18h18V3H3zm2 2h14v14H5V5z';
 
 const t = vars('ui-icon', {
   size: '1.5rem',
@@ -52,10 +60,11 @@ define('ui-icon', {
     });
     return html`${() => {
       iconsVersion(); // re-render if icons register late
-      const d = name() && iconPath(name());
-      return d
-        ? svg`<svg viewBox="0 0 24 24" aria-hidden="true"><path d=${d}></path></svg>`
-        : html`<slot></slot>`;
+      const n = name();
+      if (!n) return html`<slot></slot>`;
+      const d = iconPath(n);
+      if (!d) warnUnknownIcon(n);
+      return svg`<svg viewBox="0 0 24 24" aria-hidden="true" data-icon=${d ? n : 'unknown'}><path d=${d || MISSING}></path></svg>`;
     }}`;
   },
 });

package/src/components/ui-select.js

@@ -7,7 +7,8 @@
 //   </ui-select>
 //
 // Keyboard (APG select-only combobox): Enter/Space/ArrowDown/ArrowUp open;
-// arrows move the active option, Enter/Space selects it, Escape closes,
+// arrows move the active option, Enter/Space selects it, Escape closes the
+// panel only — an enclosing dialog keeps its own Escape for a second press,
 // typing jumps to the next option starting with that letter. The panel closes
 // on outside pointerdown and returns focus to the field.
 //
@@ -37,6 +38,7 @@ import { formBind } from '../util/form.js';
 import { presence } from '../motion/presence.js';
 import { fx } from '../motion/animate.js';
 import { autoUpdate } from '../util/position.js';
+import { escapeLayer } from '../util/keys.js';
 import './ui-icon.js';
 import './ui-option.js';
 
@@ -294,6 +296,18 @@ define('ui-select', {
       fieldEl?.focus();
     };
 
+    // Escape belongs to the panel while it is open, not to whatever encloses
+    // it. A dialog listens for the key in the capture phase at the document,
+    // so without claiming it a step earlier one press closes the panel and the
+    // dialog together.
+    effect(() => {
+      if (!open()) return;
+      return escapeLayer(() => {
+        closePanel();
+        fieldEl?.focus();
+      });
+    });
+
     // Outside pointerdown closes (scrim-less popup).
     effect(() => {
       if (!open()) return;
@@ -362,7 +376,6 @@ define('ui-select', {
         }
         case 'Enter':
         case ' ': e.preventDefault(); commit(opts[activeIndex()]); break;
-        case 'Escape': e.preventDefault(); closePanel(); break;
         case 'Tab': closePanel(); break;
         default:
           if (e.key.length === 1 && e.key !== ' ') typeahead(e.key);

package/src/components/ui-slider.js

@@ -1,6 +1,15 @@
 // <ui-slider> — a Material slider on native <input type="range">s for
 // keyboard and screen-reader behavior.
 //
+//   <ui-slider label="Volume" value=${volume}
+//              @input=${(e) => volume.set(e.detail.value)}></ui-slider>
+//
+// Bind `value` (or `.value`) to a signal like any other control. `input` /
+// `change` report a number in `detail.value` (or `detail.start` / `detail.end`
+// when `range`). The host `.value` is a string, matching a native range
+// input, so composed-path helpers that look for `typeof node.value ===
+// 'string'` work the same as they do for text fields.
+//
 // The active track portion is painted with `--ui-slider-fill` (or start/end
 // when `range`) bound from the template into a gradient; the thumb's
 // hover/focus halo is a box-shadow state layer.
@@ -157,6 +166,23 @@ define('ui-slider', {
     });
     formBind(host, { name, value: submitted, disabled });
 
+    // Native <input type="range">.value is a string. Present the same on the
+    // host so composed-path helpers and attribute-based bindings see it, while
+    // the prop signal stays numeric for math and `detail.value`.
+    const toNum = (v) => {
+      const n = typeof v === 'number' ? v : parseFloat(v);
+      return Number.isFinite(n) ? n : min();
+    };
+    Object.defineProperty(host, 'value', {
+      configurable: true,
+      enumerable: true,
+      get() { return String(value()); },
+      set(v) { value.set(toNum(v)); },
+    });
+    effect(() => {
+      host.setAttribute('value', String(value()));
+    });
+
     const active = signal(false);
     const activeThumb = signal('end');
 
@@ -226,7 +252,8 @@ define('ui-slider', {
         ${() => (range()
           ? html`<div class="dual">
               <input part="input" type="range"
-                     min=${min} max=${max} step=${step} .value=${valueStart}
+                     min=${min} max=${max} step=${step}
+                     value=${valueStart} .value=${valueStart}
                      ?disabled=${disabled}
                      aria-label=${() => (label() ? label() + ' start' : 'Start')}
                      @input=${onStartInput} @change=${onStartChange}
@@ -234,7 +261,8 @@ define('ui-slider', {
                      @focus=${() => { active.set(true); activeThumb.set('start'); }}
                      @blur=${() => active.set(false)}>
               <input part="input" type="range"
-                     min=${min} max=${max} step=${step} .value=${valueEnd}
+                     min=${min} max=${max} step=${step}
+                     value=${valueEnd} .value=${valueEnd}
                      ?disabled=${disabled}
                      aria-label=${() => (label() ? label() + ' end' : 'End')}
                      @input=${onEndInput} @change=${onEndChange}
@@ -243,7 +271,8 @@ define('ui-slider', {
                      @blur=${() => active.set(false)}>
             </div>`
           : html`<input part="input" type="range"
-                     min=${min} max=${max} step=${step} .value=${value}
+                     min=${min} max=${max} step=${step}
+                     value=${value} .value=${value}
                      ?disabled=${disabled}
                      aria-label=${() => label() || 'Slider'}
                      @input=${onInput} @change=${onChange}

package/src/util/icons.js

@@ -1,29 +1,45 @@
 // Icon registry.
 //
 // A built-in set of Material Design icon paths (24×24 viewBox, from Google's
-// material-design-icons, Apache-2.0). Components take what they need; the rest
-// is the everyday MD3 filled set so an app can start without a custom registry. Apps add their own with `registerIcons` — any 24×24
-// path data works — or slot a whole `<svg>` into `<ui-icon>` for one-offs.
+// material-design-icons, Apache-2.0). Names are kebab-case; underscores are
+// treated as hyphens so Material Symbols names (`arrow_forward`) resolve.
+// Components take what they need; the rest is the everyday MD3 filled set so
+// an app can start without a custom registry. Apps add their own with
+// `registerIcons` — any 24×24 path data works — or slot a whole `<svg>` into
+// `<ui-icon>` for one-offs.
 
 import { signal } from '@alacris/core';
 
 const registry = new Map();
+const warned = new Set();
 
 // Bumped on registration so already-rendered <ui-icon>s pick up late icons.
 export const iconsVersion = signal(0);
 
-/** registerIcons({ name: 'M…' }) — later registrations win. */
+// Material Symbols use underscores; the registry is kebab-case. Treat them
+// as the same name so `arrow_forward` resolves to `arrow-forward`.
+const canon = (name) => String(name).replace(/_/g, '-');
+
+/** registerIcons({ name: 'M…' }) — later registrations win. Names are stored kebab-case. */
 export function registerIcons(icons) {
-  for (const name in icons) registry.set(name, icons[name]);
+  for (const name in icons) registry.set(canon(name), icons[name]);
   iconsVersion.update((n) => n + 1);
 }
 
-/** Path data for a name, or undefined. */
-export const iconPath = (name) => registry.get(name);
+/** Path data for a name, or undefined. Underscores and hyphens are equivalent. */
+export const iconPath = (name) => (name ? registry.get(canon(name)) : undefined);
 
-/** Registered names (built-ins included) — the demo lists these. */
+/** Registered names (built-ins included, kebab-case) — the demo lists these. */
 export const iconNames = () => [...registry.keys()];
 
+/** Warn once per unknown name so a blank icon is grep-able, not a silent hole. */
+export function warnUnknownIcon(name) {
+  const n = canon(name);
+  if (!n || registry.has(n) || warned.has(n)) return;
+  warned.add(n);
+  console.warn(`ui-icon: "${name}" is not registered. Names are kebab-case (arrow-forward); underscores are accepted. iconNames() lists the set; registerIcons() adds more.`);
+}
+
 registerIcons({
   'add': 'M19 13h-6v6h-2v-6H5v-2h6V5h2v6h6v2z',
   'arrow-back': 'M20 11H7.83l5.59-5.59L12 4l-8 8 8 8 1.41-1.41L7.83 13H20v-2z',
@@ -31,6 +47,7 @@ registerIcons({
   'arrow-drop-down': 'M7 10l5 5 5-5z',
   'arrow-drop-up': 'M7 14l5-5 5 5z',
   'arrow-upward': 'M4 12l1.41 1.41L11 7.83V20h2V7.83l5.58 5.59L20 12l-8-8-8 8z',
+  'arrow-downward': 'M20 12l-1.41-1.41L13 16.17V4h-2v12.17l-5.58-5.59L4 12l8 8 8-8z',
   'calendar': 'M19 3h-1V1h-2v2H8V1H6v2H5c-1.11 0-1.99.9-1.99 2L3 19c0 1.1.89 2 2 2h14c1.1 0 2-.9 2-2V5c0-1.1-.9-2-2-2zm0 16H5V8h14v11zM7 10h5v5H7z',
   'cancel': 'M12 2C6.47 2 2 6.47 2 12s4.47 10 10 10 10-4.47 10-10S17.53 2 12 2zm5 13.59L15.59 17 12 13.41 8.41 17 7 15.59 10.59 12 7 8.41 8.41 7 12 10.59 15.59 7 17 8.41 13.41 12 17 15.59z',
   'check': 'M8.95 19.1 3.65 13.8 6.45 11 8.95 13.5 17.55 4.9 20.35 7.7z',

package/src/util/keys.js

@@ -108,3 +108,34 @@ export function rovingTabindex(container, opts = {}) {
     },
   };
 }
+
+// escapeLayer — claim Escape for the innermost open layer.
+//
+// `ui-dialog` listens for Escape in the capture phase at the document, so that
+// the key works wherever focus happens to be. That is right for a dialog and
+// wrong for anything transient opened inside one: a select's panel, a menu, a
+// date picker. Those handle Escape too, but the dialog has already seen it by
+// then, so one press closes both — and choosing a format in a dialog looks
+// like the dialog is broken rather than like an ordering problem nobody can
+// see.
+//
+// Capture descends window → document → …, so a layer claims the key one step
+// earlier than the dialog and stops it there. Nothing below ever runs.
+
+/**
+ * escapeLayer(onEscape)
+ *
+ * Call while a transient layer is open; call the returned function when it
+ * closes. Only registers a listener while it is held, so a page with nothing
+ * open behaves exactly as before.
+ */
+export function escapeLayer(onEscape) {
+  const onKeydown = (e) => {
+    if (e.key !== 'Escape') return;
+    e.preventDefault();
+    e.stopPropagation();
+    onEscape(e);
+  };
+  window.addEventListener('keydown', onKeydown, true);
+  return () => window.removeEventListener('keydown', onKeydown, true);
+}

package/types/index.d.ts

@@ -147,8 +147,11 @@ export function formBind(
   }
 ): void;
 
+/** Register SVG path data. Names are stored kebab-case; underscores are equivalent. */
 export function registerIcons(icons: Record<string, string>): void;
+/** Path data for a name, or undefined. Underscores and hyphens are equivalent. */
 export function iconPath(name: string): string | undefined;
+/** Registered names (built-ins included, kebab-case). */
 export function iconNames(): string[];
 
 export function processTable(opts: Record<string, unknown>): Record<string, unknown>;