@alacris/ui 0.1.1 → 0.2.1

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
 
@@ -123,10 +123,10 @@ Component modules have side effects (they call `define()`). Theme, motion and to
 
 ## In this repository
 
-This package lives in `starter/` of the [Alacris repo](https://github.com/bmartel/alacris) so the library and the design system can be developed together. They **publish separately**: `@alacris/ui` has its own version, changelog, and npm release. A commit that only changes this folder does not cut an Alacris library release.
+This package lives in `ui/` of the [Alacris repo](https://github.com/bmartel/alacris) so the library and the design system can be developed together. They **publish separately**: `@alacris/ui` has its own version, changelog, and npm release. A commit that only changes this folder does not cut an Alacris library release. `starter/` in the same repo is a usage example and install guide, not this package.
 
 ```
-starter/
+ui/
   src/           the published modules
   types/         hand-written .d.ts
   demo/          kitchen-sink app (not published)
@@ -135,12 +135,15 @@ starter/
   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
 npm install
-npm run demo        # http://localhost:5173/starter/
-cd starter && npm test
+npm run demo        # kitchen sink: http://localhost:5173/ui/
+                    # starter app:  http://localhost:5173/starter/
+cd ui && npm test
 ```
 
 ## License

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alacris/ui",
-  "version": "0.1.1",
+  "version": "0.2.1",
   "description": "Themeable design system for Alacris — Material defaults, sixty-eight custom elements, ESM-only, no build step.",
   "type": "module",
   "exports": {
@@ -64,9 +64,9 @@
   "repository": {
     "type": "git",
     "url": "git+https://github.com/bmartel/alacris.git",
-    "directory": "starter"
+    "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-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-nav-item.js

@@ -90,6 +90,7 @@ const styles = css`
     font: ${t.font};
     letter-spacing: ${t.tracking};
     color: ${t.labelFg};
+    white-space: nowrap;
     transition: color ${sys.duration.short4} ${sys.easing.standard};
   }
   .selected .label { color: ${t.labelFgActive}; }

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/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>;