@ponchia/ui 0.6.0 → 0.6.4

package/glyphs/glyphs.js

@@ -22,8 +22,12 @@
 export const GLYPH_SIZE = 16;
 
 // Raw bitmaps. Each is GLYPH_SIZE rows of GLYPH_SIZE chars over [.#*]:
-// `.` off · `#` hot · `*` accent. Only `spark` uses accent dots — it is the
-// canonical two-tone demo; test/glyphs.test.mjs asserts the spark-only-* rule.
+// `.` off · `#` hot · `*` accent. The curated two-tone glyphs (`spark`,
+// `warning`, `info`) lift one feature onto the accent colour; every other
+// glyph is monotone. test/glyphs.test.mjs pins that exact set.
+//
+// `digit-0`..`digit-9` + `colon`/`comma`/`period`/`percent` are the readout
+// face — composed into multi-digit numerics by renderReadout().
 const RAW = {
   circle: [
     '................',
@@ -387,21 +391,21 @@ const RAW = {
   ],
   'eye-off': [
     '................',
-    '................',
-    '#...............',
-    '.#..########....',
-    '..####....####..',
-    '.###.#####..###.',
-    '.##..###.##..##.',
-    '##..####.###..##',
-    '.##..######.#.#.',
-    '.###..####..###.',
-    '..####....####.#',
-    '....########.#..',
-    '............#...',
-    '...........#....',
-    '................',
-    '................',
+    '.#..............',
+    '.##.............',
+    '..##....###.....',
+    '...##.##...##...',
+    '..#.###.....##..',
+    '.##...##.##..##.',
+    '##.....####...#.',
+    '.##...##.##..##.',
+    '..##.##....###..',
+    '...##...###.##..',
+    '....##.....##...',
+    '.....##...##....',
+    '......##.##.....',
+    '.......###......',
+    '........##......',
   ],
   file: [
     '................',
@@ -513,10 +517,10 @@ const RAW = {
   ],
   info: [
     '................',
-    '......####......',
-    '.....######.....',
-    '.....######.....',
-    '......####......',
+    '......****......',
+    '.....******.....',
+    '.....******.....',
+    '......****......',
     '................',
     '....######......',
     '......####......',
@@ -874,19 +878,433 @@ const RAW = {
   warning: [
     '................',
     '.......##.......',
-    '.......##.......',
     '......####......',
     '......####......',
+    '.....##**##.....',
+    '.....##**##.....',
+    '....###**###....',
+    '....###**###....',
+    '...####**####...',
+    '...####**####...',
+    '..#####**#####..',
+    '..#####..#####..',
+    '.######**######.',
+    '.##############.',
+    '.##############.',
+    '................',
+  ],
+  'bar-chart': [
+    '................',
+    '................',
+    '............##..',
+    '............##..',
+    '.......##...##..',
+    '.......##...##..',
+    '.......##...##..',
+    '..##...##...##..',
+    '..##...##...##..',
+    '..##...##...##..',
+    '..##...##...##..',
+    '..##...##...##..',
+    '..############..',
+    '..############..',
+    '................',
+    '................',
+  ],
+  calendar: [
+    '................',
+    '...#......#.....',
+    '...#......#.....',
+    '..############..',
+    '..############..',
+    '..#..........#..',
+    '..#.##.##.##.#..',
+    '..#..........#..',
+    '..#.##.##.##.#..',
+    '..#..........#..',
+    '..#.##.##....#..',
+    '..############..',
+    '................',
+    '................',
+    '................',
+    '................',
+  ],
+  colon: [
+    '................',
+    '................',
+    '................',
+    '................',
+    '......####......',
+    '......####......',
+    '......####......',
+    '................',
+    '................',
+    '......####......',
+    '......####......',
+    '......####......',
+    '................',
+    '................',
+    '................',
+    '................',
+  ],
+  comma: [
+    '................',
+    '................',
+    '................',
+    '................',
+    '................',
+    '................',
+    '................',
+    '................',
+    '................',
+    '................',
+    '......####......',
+    '......####......',
+    '......####......',
+    '.......###......',
+    '......###.......',
+    '.....##.........',
+  ],
+  copy: [
+    '................',
+    '......#######...',
+    '......#.....#...',
+    '...#######..#...',
+    '...#.....#..#...',
+    '...#.....#..#...',
+    '...#.....####...',
+    '...#.....#......',
+    '...#.....#......',
+    '...#######......',
+    '................',
+    '................',
+    '................',
+    '................',
+    '................',
+    '................',
+  ],
+  database: [
+    '................',
+    '...########.....',
+    '..##########....',
+    '..#........#....',
+    '..##########....',
+    '...########.....',
+    '..#........#....',
+    '..##########....',
+    '...########.....',
+    '..#........#....',
+    '..##########....',
+    '...########.....',
+    '................',
+    '................',
+    '................',
+    '................',
+  ],
+  'digit-0': [
+    '................',
+    '.....######.....',
+    '.....######.....',
+    '...##......##...',
+    '...##......##...',
+    '...##....####...',
+    '...##....####...',
+    '...##..##..##...',
+    '...##..##..##...',
+    '...####....##...',
+    '...####....##...',
+    '...##......##...',
+    '...##......##...',
+    '.....######.....',
+    '.....######.....',
+    '................',
+  ],
+  'digit-1': [
+    '................',
+    '.......##.......',
+    '.......##.......',
+    '.....####.......',
+    '.....####.......',
+    '.......##.......',
+    '.......##.......',
+    '.......##.......',
+    '.......##.......',
+    '.......##.......',
+    '.......##.......',
+    '.......##.......',
+    '.......##.......',
+    '.....######.....',
+    '.....######.....',
+    '................',
+  ],
+  'digit-2': [
+    '................',
+    '.....######.....',
+    '.....######.....',
+    '...##......##...',
+    '...##......##...',
+    '...........##...',
+    '...........##...',
+    '.........##.....',
+    '.........##.....',
+    '.......##.......',
+    '.......##.......',
+    '.....##.........',
+    '.....##.........',
+    '...##########...',
+    '...##########...',
+    '................',
+  ],
+  'digit-3': [
+    '................',
+    '...##########...',
+    '...##########...',
+    '.........##.....',
+    '.........##.....',
+    '.......##.......',
+    '.......##.......',
+    '.........##.....',
+    '.........##.....',
+    '...........##...',
+    '...........##...',
+    '...##......##...',
+    '...##......##...',
+    '.....######.....',
+    '.....######.....',
+    '................',
+  ],
+  'digit-4': [
+    '................',
+    '.........##.....',
+    '.........##.....',
+    '.......####.....',
+    '.......####.....',
     '.....##..##.....',
     '.....##..##.....',
-    '....###..###....',
-    '....##....##....',
-    '...###....###...',
-    '...##.####.##...',
-    '..###.####.###..',
-    '..##........##..',
-    '.###############',
-    '.###############',
+    '...##....##.....',
+    '...##....##.....',
+    '...##########...',
+    '...##########...',
+    '.........##.....',
+    '.........##.....',
+    '.........##.....',
+    '.........##.....',
+    '................',
+  ],
+  'digit-5': [
+    '................',
+    '...##########...',
+    '...##########...',
+    '...##...........',
+    '...##...........',
+    '...########.....',
+    '...########.....',
+    '...........##...',
+    '...........##...',
+    '...........##...',
+    '...........##...',
+    '...##......##...',
+    '...##......##...',
+    '.....######.....',
+    '.....######.....',
+    '................',
+  ],
+  'digit-6': [
+    '................',
+    '.......####.....',
+    '.......####.....',
+    '.....##.........',
+    '.....##.........',
+    '...##...........',
+    '...##...........',
+    '...########.....',
+    '...########.....',
+    '...##......##...',
+    '...##......##...',
+    '...##......##...',
+    '...##......##...',
+    '.....######.....',
+    '.....######.....',
+    '................',
+  ],
+  'digit-7': [
+    '................',
+    '...##########...',
+    '...##########...',
+    '...........##...',
+    '...........##...',
+    '.........##.....',
+    '.........##.....',
+    '.......##.......',
+    '.......##.......',
+    '.....##.........',
+    '.....##.........',
+    '.....##.........',
+    '.....##.........',
+    '.....##.........',
+    '.....##.........',
+    '................',
+  ],
+  'digit-8': [
+    '................',
+    '.....######.....',
+    '.....######.....',
+    '...##......##...',
+    '...##......##...',
+    '...##......##...',
+    '...##......##...',
+    '.....######.....',
+    '.....######.....',
+    '...##......##...',
+    '...##......##...',
+    '...##......##...',
+    '...##......##...',
+    '.....######.....',
+    '.....######.....',
+    '................',
+  ],
+  'digit-9': [
+    '................',
+    '.....######.....',
+    '.....######.....',
+    '...##......##...',
+    '...##......##...',
+    '...##......##...',
+    '...##......##...',
+    '.....########...',
+    '.....########...',
+    '...........##...',
+    '...........##...',
+    '.........##.....',
+    '.........##.....',
+    '.....####.......',
+    '.....####.......',
+    '................',
+  ],
+  filter: [
+    '................',
+    '..############..',
+    '..############..',
+    '...##########...',
+    '....########....',
+    '.....######.....',
+    '......####......',
+    '......####......',
+    '......####......',
+    '......####......',
+    '......####......',
+    '......####......',
+    '................',
+    '................',
+    '................',
+    '................',
+  ],
+  hash: [
+    '................',
+    '................',
+    '....#...#.......',
+    '....#...#.......',
+    '..#########.....',
+    '..#########.....',
+    '....#...#.......',
+    '....#...#.......',
+    '..#########.....',
+    '..#########.....',
+    '....#...#.......',
+    '....#...#.......',
+    '................',
+    '................',
+    '................',
+    '................',
+  ],
+  percent: [
+    '................',
+    '...###......#...',
+    '..#...#....#....',
+    '..#...#...#.....',
+    '..#...#..#......',
+    '...###..#.......',
+    '.......#........',
+    '......#.........',
+    '.....#..###.....',
+    '....#..#...#....',
+    '...#...#...#....',
+    '..#....#...#....',
+    '.#......###.....',
+    '................',
+    '................',
+    '................',
+  ],
+  period: [
+    '................',
+    '................',
+    '................',
+    '................',
+    '................',
+    '................',
+    '................',
+    '................',
+    '................',
+    '................',
+    '................',
+    '......####......',
+    '......####......',
+    '......####......',
+    '................',
+    '................',
+  ],
+  share: [
+    '................',
+    '...........###..',
+    '..........#####.',
+    '...........###..',
+    '.........#.#....',
+    '.......##.......',
+    '...###.#........',
+    '..#####.........',
+    '...###.#........',
+    '.......##.......',
+    '.........#.#....',
+    '...........###..',
+    '..........#####.',
+    '...........###..',
+    '................',
+    '................',
+  ],
+  sliders: [
+    '................',
+    '................',
+    '....#...........',
+    '...###..........',
+    '..#####.########',
+    '...###..........',
+    '....#...........',
+    '................',
+    '...........#....',
+    '..........###...',
+    '########.#####..',
+    '..........###...',
+    '...........#....',
+    '................',
+    '................',
+    '................',
+  ],
+  sort: [
+    '................',
+    '......#.........',
+    '.....###........',
+    '....#####.......',
+    '...#######......',
+    '......#.........',
+    '......#.........',
+    '......#.........',
+    '......#.........',
+    '......#.........',
+    '...#######......',
+    '....#####.......',
+    '.....###........',
+    '......#.........',
+    '................',
     '................',
   ],
 };
@@ -903,6 +1321,79 @@ export const GLYPHS = Object.freeze(
 /** Every glyph name, frozen and sorted (mirrors GLYPHS keys). */
 export const GLYPH_NAMES = Object.freeze(Object.keys(GLYPHS));
 
+/**
+ * Intent → glyph search aliases. A small hand-curated set so a name search can
+ * resolve the *word a consumer thinks of* to the glyph that depicts it (the
+ * "depict, don't name the purpose" convention: `delete` → `trash`, `settings`
+ * → `gear`). Keys are real glyph names (gated by check-glyphs.mjs); values are
+ * extra search terms beyond the name itself. Not every glyph needs an entry —
+ * findGlyphs() always also matches the name substring.
+ */
+export const GLYPH_TAGS = Object.freeze({
+  trash: ['delete', 'remove', 'bin'],
+  gear: ['settings', 'config', 'options', 'cog', 'preferences'],
+  search: ['find', 'magnify', 'zoom', 'lookup'],
+  'bar-chart': ['analytics', 'graph', 'stats', 'report', 'metrics'],
+  database: ['db', 'storage', 'data', 'server', 'table'],
+  sliders: ['filter', 'settings', 'controls', 'adjust', 'tune'],
+  filter: ['funnel', 'refine', 'facet'],
+  sort: ['order', 'arrange', 'rank'],
+  mail: ['email', 'envelope', 'message', 'inbox'],
+  bell: ['notification', 'alert', 'remind'],
+  user: ['person', 'account', 'profile', 'member'],
+  home: ['house', 'dashboard', 'start'],
+  file: ['document', 'page', 'doc'],
+  folder: ['directory', 'group'],
+  lock: ['secure', 'private', 'password', 'locked'],
+  eye: ['view', 'show', 'visible', 'preview'],
+  'eye-off': ['hide', 'hidden', 'invisible', 'mask'],
+  star: ['favorite', 'bookmark', 'rate'],
+  heart: ['like', 'love', 'favorite'],
+  refresh: ['reload', 'sync', 'update', 'retry'],
+  close: ['cancel', 'dismiss', 'remove'],
+  'x-circle': ['cancel', 'error', 'fail', 'dismiss'],
+  check: ['done', 'ok', 'complete', 'confirm', 'tick'],
+  'check-circle': ['done', 'success', 'ok', 'verified'],
+  warning: ['caution', 'alert', 'attention'],
+  info: ['about', 'help', 'note', 'details'],
+  plus: ['add', 'new', 'create'],
+  'plus-circle': ['add', 'new', 'create'],
+  minus: ['subtract', 'collapse'],
+  link: ['url', 'hyperlink', 'external', 'chain'],
+  download: ['save', 'export', 'fetch'],
+  upload: ['import', 'send'],
+  grid: ['layout', 'apps', 'dashboard', 'tiles'],
+  menu: ['hamburger', 'nav', 'list'],
+  clock: ['time', 'schedule', 'history', 'recent'],
+  calendar: ['date', 'schedule', 'event', 'day'],
+  copy: ['duplicate', 'clipboard', 'clone'],
+  share: ['send', 'export', 'network', 'distribute'],
+  hash: ['number', 'tag', 'pound', 'count'],
+  moon: ['dark', 'night', 'theme'],
+  sun: ['light', 'day', 'theme', 'bright'],
+  edit: ['pencil', 'write', 'modify', 'rename'],
+});
+
+/**
+ * Glyph names whose name OR a search alias contains `query` (case-insensitive),
+ * sorted. `findGlyphs('')` returns every name. For discovery — a CMS field, an
+ * icon picker, an LLM resolving an intent word to a real glyph.
+ *
+ * @param {string} query
+ * @returns {GlyphName[]}
+ */
+export function findGlyphs(query) {
+  const q = String(query ?? '')
+    .trim()
+    .toLowerCase();
+  if (!q) return [...GLYPH_NAMES];
+  return GLYPH_NAMES.filter(
+    (name) =>
+      name.toLowerCase().includes(q) ||
+      (GLYPH_TAGS[name] ?? []).some((t) => t.toLowerCase().includes(q)),
+  );
+}
+
 const TONE = { '#': 'hot', '*': 'accent' };
 
 /** The raw bitmap rows for a glyph, or `undefined` if the name is unknown. */
@@ -924,6 +1415,20 @@ export function glyphCells(name) {
   return cells;
 }
 
+/**
+ * The CSS `mask-image` `url()` for a glyph's lit cells — the value of
+ * `--icon-mask` on a `.ui-icon` element (the one-node, currentColor,
+ * scales-with-text icon path). `''` if the name is unknown. Single-tone:
+ * accent `*` cells become opaque mask regions, like hot `#`.
+ *
+ * @param {GlyphNameInput} name
+ * @returns {string}
+ */
+export function glyphMask(name) {
+  const rows = GLYPHS[name];
+  return rows ? maskUrl(rows) : '';
+}
+
 const CELL = 'ui-dotmatrix__cell';
 
 function cellClass(cell) {
@@ -1027,7 +1532,13 @@ export function renderGlyph(name, options = {}) {
   const style = [`--dotmatrix-cols:${GLYPH_SIZE}`];
   const dotLen = dot && cssLen(dot);
   const gapLen = gap && cssLen(gap);
-  if (dotLen) style.push(`--dotmatrix-dot:${dotLen}`);
+  // Default the dot track to an intrinsic icon scale when the author set no
+  // (valid) `--dotmatrix-dot`. Without it the CSS grid falls back to
+  // `minmax(0, 1fr)` and the 16×16 matrix balloons to fill its container
+  // (full-bleed, ~1250px) — the string API would then render an icon-intent call
+  // very differently from the DOM `initDotGlyph` path, which already defaults to
+  // 0.08em. Mirror that default here so both paths render the same icon. (C7.)
+  style.push(`--dotmatrix-dot:${dotLen || '0.08em'}`);
   // Solid mode fuses the dots into a crisp pixel glyph: square cells, no gap.
   if (solid) style.push('--dotmatrix-dot-radius:0', '--dotmatrix-gap:0');
   else if (gapLen) style.push(`--dotmatrix-gap:${gapLen}`);
@@ -1063,3 +1574,61 @@ export function renderGlyph(name, options = {}) {
   // inline-icon use. `.ui-dotmatrix`'s `display: grid` works on a span.
   return `<span class="${cls}" style="${style.join(';')}" ${a11y}>${inner}</span>`;
 }
+
+// Character → glyph name for renderReadout. Punctuation reuses the readout face
+// (digit-0..9 + colon/comma/period/percent) plus the existing minus/plus.
+const READOUT_CHARS = {
+  0: 'digit-0',
+  1: 'digit-1',
+  2: 'digit-2',
+  3: 'digit-3',
+  4: 'digit-4',
+  5: 'digit-5',
+  6: 'digit-6',
+  7: 'digit-7',
+  8: 'digit-8',
+  9: 'digit-9',
+  ':': 'colon',
+  ',': 'comma',
+  '.': 'period',
+  '%': 'percent',
+  '-': 'minus',
+  '+': 'plus',
+};
+
+/**
+ * Compose a string of digits/punctuation into a row of dot-matrix glyphs — the
+ * Nothing-style big numeric readout for a hero KPI, clock, countdown, or
+ * percentage. Every character is a decorative glyph; the readout's *value* is
+ * carried by the accessible name, so a `label` is STRONGLY recommended (it
+ * defaults to the raw `text` when omitted — fine for "12:48", but pass a
+ * fuller label like "Revenue: 12,480 USD" when the digits alone are ambiguous).
+ *
+ * Recognised characters: `0-9 : , . % - +` and space (a blank advance).
+ * Anything else is skipped. The per-glyph options (`solid`, `render: 'mask'`,
+ * `dot`, `gap`, `anim`) pass straight through to renderGlyph for each character,
+ * so a mask-mode readout is one node per glyph (lightest) and a cell-mode one is
+ * the full dot-display look. Returns `''` for empty input. Needs
+ * `@ponchia/ui/css` (the `.ui-readout` + `.ui-dotmatrix`/`.ui-icon` rules).
+ *
+ * @param {string} text
+ * @param {RenderReadoutOptions} [options]
+ * @returns {string}
+ */
+export function renderReadout(text, options = {}) {
+  const str = String(text ?? '');
+  if (!str) return '';
+  const { label, gap, ...glyphOpts } = options;
+  const a11y = `role="img" aria-label="${esc(label ?? str)}"`;
+  // The glyphs inside are always decorative — the wrapper carries the name.
+  const inner = [...str]
+    .map((ch) => {
+      if (ch === ' ') return '<span class="ui-readout__spacer" aria-hidden="true"></span>';
+      const name = READOUT_CHARS[ch];
+      if (!name) return '';
+      return renderGlyph(name, glyphOpts);
+    })
+    .join('');
+  const style = gap && cssLen(gap) ? ` style="--readout-gap:${cssLen(gap)}"` : '';
+  return `<span class="ui-readout"${style} ${a11y}>${inner}</span>`;
+}