@ponchia/ui 0.3.5 → 0.4.0

package/glyphs/glyphs.js

@@ -0,0 +1,1063 @@
+/**
+ * @ponchia/ui — display glyphs.
+ *
+ * Small, frozen bitmap registry rendered on the existing `.ui-dotmatrix`
+ * primitive (see css/dots.css). CSS-first to the core: a glyph is just a
+ * grid of dot cells, three tones — `.` off (the dim panel dot), `#` hot,
+ * `*` accent — so it re-skins with the same `--field-dot*` tokens as every
+ * other dot surface.
+ *
+ * Framework-agnostic, dependency-free, side-effect-free on import, SSR-safe
+ * (`renderGlyph` returns a string; nothing touches the DOM here — the
+ * optional `initDotGlyph` behavior lives in behaviors/index.js).
+ *
+ *   import { renderGlyph } from '@ponchia/ui/glyphs';
+ *   el.innerHTML = renderGlyph('check', { label: 'Done' });
+ *
+ * The `GlyphName` union, helper signatures, and drift gate are generated +
+ * checked from this file — see scripts/gen-glyphs.mjs / check-glyphs.mjs.
+ */
+
+/** The grid edge length: every glyph is GLYPH_SIZE rows of GLYPH_SIZE chars. */
+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; the gate in check-glyphs.mjs enforces the shape.
+const RAW = {
+  circle: [
+    '................',
+    '.....######.....',
+    '....########....',
+    '...###....###...',
+    '..##........##..',
+    '.###........###.',
+    '.##..........##.',
+    '.##..........##.',
+    '.##..........##.',
+    '.##..........##.',
+    '.###........###.',
+    '..##........##..',
+    '...###....###...',
+    '....########....',
+    '.....######.....',
+    '................',
+  ],
+  'check-circle': [
+    '................',
+    '.....######.....',
+    '....########....',
+    '...###....###...',
+    '..##........##..',
+    '.###........###.',
+    '.##........####.',
+    '.##..##...##.##.',
+    '.##...##.##..##.',
+    '.##....###...##.',
+    '.###...##...###.',
+    '..##........##..',
+    '...###....###...',
+    '....########....',
+    '.....######.....',
+    '................',
+  ],
+  'x-circle': [
+    '................',
+    '.....######.....',
+    '....########....',
+    '...###....###...',
+    '..##........##..',
+    '.###.##..##.###.',
+    '.##...####...##.',
+    '.##....##....##.',
+    '.##...####...##.',
+    '.##..##..##..##.',
+    '.#####....#####.',
+    '..##........##..',
+    '...###....###...',
+    '....########....',
+    '.....######.....',
+    '................',
+  ],
+  'plus-circle': [
+    '................',
+    '.....######.....',
+    '....########....',
+    '...###....###...',
+    '..##........##..',
+    '.###...##...###.',
+    '.##....##....##.',
+    '.##..######..##.',
+    '.##..######..##.',
+    '.##....##....##.',
+    '.###...##...###.',
+    '..##........##..',
+    '...###....###...',
+    '....########....',
+    '.....######.....',
+    '................',
+  ],
+  'minus-circle': [
+    '................',
+    '.....######.....',
+    '....########....',
+    '...###....###...',
+    '..##........##..',
+    '.###........###.',
+    '.##..........##.',
+    '.##..######..##.',
+    '.##..######..##.',
+    '.##..........##.',
+    '.###........###.',
+    '..##........##..',
+    '...###....###...',
+    '....########....',
+    '.....######.....',
+    '................',
+  ],
+  'arrow-down': [
+    '................',
+    '......####......',
+    '......####......',
+    '......####......',
+    '......####......',
+    '......####......',
+    '......####......',
+    '.##############.',
+    '..############..',
+    '...##########...',
+    '....########....',
+    '.....######.....',
+    '......####......',
+    '.......##.......',
+    '.......##.......',
+    '................',
+  ],
+  'arrow-left': [
+    '................',
+    '........#.......',
+    '.......##.......',
+    '......###.......',
+    '.....####.......',
+    '....#####.......',
+    '...############.',
+    '.##############.',
+    '.##############.',
+    '...############.',
+    '....#####.......',
+    '.....####.......',
+    '......###.......',
+    '.......##.......',
+    '........#.......',
+    '................',
+  ],
+  'arrow-right': [
+    '................',
+    '.......#........',
+    '.......##.......',
+    '.......###......',
+    '.......####.....',
+    '.......#####....',
+    '.############...',
+    '.##############.',
+    '.##############.',
+    '.############...',
+    '.......#####....',
+    '.......####.....',
+    '.......###......',
+    '.......##.......',
+    '.......#........',
+    '................',
+  ],
+  'arrow-up': [
+    '................',
+    '.......##.......',
+    '.......##.......',
+    '......####......',
+    '.....######.....',
+    '....########....',
+    '...##########...',
+    '..############..',
+    '.##############.',
+    '......####......',
+    '......####......',
+    '......####......',
+    '......####......',
+    '......####......',
+    '......####......',
+    '................',
+  ],
+  bell: [
+    '................',
+    '.......##.......',
+    '......####......',
+    '.....######.....',
+    '....########....',
+    '....########....',
+    '....########....',
+    '...##########...',
+    '...##########...',
+    '..############..',
+    '.##############.',
+    '################',
+    '................',
+    '......####......',
+    '......####......',
+    '................',
+  ],
+  check: [
+    '................',
+    '................',
+    '.............###',
+    '............###.',
+    '...........###..',
+    '..........###...',
+    '.........###....',
+    '.##.....###.....',
+    '.##....###......',
+    '.###..###.......',
+    '..######........',
+    '...####.........',
+    '...###..........',
+    '................',
+    '................',
+    '................',
+  ],
+  'chevron-down': [
+    '................',
+    '................',
+    '................',
+    '................',
+    '.##..........##.',
+    '.###........###.',
+    '..###......###..',
+    '...###....###...',
+    '....###..###....',
+    '.....######.....',
+    '......####......',
+    '.......##.......',
+    '................',
+    '................',
+    '................',
+    '................',
+  ],
+  'chevron-left': [
+    '................',
+    '..........##....',
+    '.........###....',
+    '........###.....',
+    '.......###......',
+    '......###.......',
+    '.....###........',
+    '....###.........',
+    '....###.........',
+    '.....###........',
+    '......###.......',
+    '.......###......',
+    '........###.....',
+    '.........###....',
+    '..........##....',
+    '................',
+  ],
+  'chevron-right': [
+    '................',
+    '....##..........',
+    '....###.........',
+    '.....###........',
+    '......###.......',
+    '.......###......',
+    '........###.....',
+    '.........###....',
+    '.........###....',
+    '........###.....',
+    '.......###......',
+    '......###.......',
+    '.....###........',
+    '....###.........',
+    '....##..........',
+    '................',
+  ],
+  'chevron-up': [
+    '................',
+    '................',
+    '................',
+    '................',
+    '.......##.......',
+    '......####......',
+    '.....######.....',
+    '....###..###....',
+    '...###....###...',
+    '..###......###..',
+    '.###........###.',
+    '.##..........##.',
+    '................',
+    '................',
+    '................',
+    '................',
+  ],
+  clock: [
+    '................',
+    '.......##.......',
+    '....########....',
+    '...##......##...',
+    '..##...##...##..',
+    '..#....##....#..',
+    '..#....##....#..',
+    '.##....####..##.',
+    '.##....####..##.',
+    '..#..........#..',
+    '..#..........#..',
+    '..##........##..',
+    '...##......##...',
+    '....########....',
+    '.......##.......',
+    '................',
+  ],
+  close: [
+    '................',
+    '................',
+    '.###........###.',
+    '..###......###..',
+    '...###....###...',
+    '....###..###....',
+    '.....######.....',
+    '......####......',
+    '......####......',
+    '.....######.....',
+    '....###..###....',
+    '...###....###...',
+    '..###......###..',
+    '.###........###.',
+    '................',
+    '................',
+  ],
+  download: [
+    '................',
+    '.......##.......',
+    '.......##.......',
+    '.......##.......',
+    '.......##.......',
+    '.......##.......',
+    '...#########....',
+    '....#######.....',
+    '.....#####......',
+    '......###.......',
+    '.......#........',
+    '................',
+    '.##############.',
+    '.##############.',
+    '................',
+    '................',
+  ],
+  edit: [
+    '................',
+    '...........####.',
+    '..........#####.',
+    '.........#####..',
+    '........#####...',
+    '.......#####....',
+    '......#####.....',
+    '.....#####......',
+    '....#####.......',
+    '...#####........',
+    '..#####.........',
+    '.#####..........',
+    '.####...........',
+    '.###............',
+    '.#..............',
+    '................',
+  ],
+  eye: [
+    '................',
+    '................',
+    '................',
+    '....########....',
+    '..####....####..',
+    '.###..####..###.',
+    '.##..######..##.',
+    '##..########..##',
+    '.##..######..##.',
+    '.###..####..###.',
+    '..####....####..',
+    '....########....',
+    '................',
+    '................',
+    '................',
+    '................',
+  ],
+  'eye-off': [
+    '................',
+    '................',
+    '#...............',
+    '.#..########....',
+    '..####....####..',
+    '.###.#####..###.',
+    '.##..###.##..##.',
+    '##..####.###..##',
+    '.##..######.#.#.',
+    '.###..####..###.',
+    '..####....####.#',
+    '....########.#..',
+    '............#...',
+    '...........#....',
+    '................',
+    '................',
+  ],
+  file: [
+    '................',
+    '..##########....',
+    '..##......###...',
+    '..##......####..',
+    '..##......#.##..',
+    '..##......####..',
+    '..##........##..',
+    '..##........##..',
+    '..##........##..',
+    '..##........##..',
+    '..##........##..',
+    '..##........##..',
+    '..############..',
+    '................',
+    '................',
+    '................',
+  ],
+  folder: [
+    '................',
+    '................',
+    '..#####.........',
+    '.#######........',
+    '.##############.',
+    '.##############.',
+    '.##..........##.',
+    '.##..........##.',
+    '.##..........##.',
+    '.##..........##.',
+    '.##..........##.',
+    '.##############.',
+    '................',
+    '................',
+    '................',
+    '................',
+  ],
+  gear: [
+    '.......##.......',
+    '.......##.......',
+    '......####......',
+    '....########....',
+    '...##########...',
+    '...###....###...',
+    '..###......###..',
+    '#####......#####',
+    '#####......#####',
+    '..###......###..',
+    '...###....###...',
+    '...##########...',
+    '....########....',
+    '......####......',
+    '.......##.......',
+    '.......##.......',
+  ],
+  grid: [
+    '................',
+    '..#####..#####..',
+    '..#####..#####..',
+    '..#####..#####..',
+    '..#####..#####..',
+    '..#####..#####..',
+    '................',
+    '................',
+    '..#####..#####..',
+    '..#####..#####..',
+    '..#####..#####..',
+    '..#####..#####..',
+    '..#####..#####..',
+    '................',
+    '................',
+    '................',
+  ],
+  heart: [
+    '................',
+    '...###....###...',
+    '..#####..#####..',
+    '.######..######.',
+    '.##############.',
+    '.##############.',
+    '..############..',
+    '..############..',
+    '...##########...',
+    '....########....',
+    '.....######.....',
+    '......####......',
+    '.......##.......',
+    '................',
+    '................',
+    '................',
+  ],
+  home: [
+    '................',
+    '.......##.......',
+    '......####......',
+    '.....######.....',
+    '....########....',
+    '...##########...',
+    '..############..',
+    '.##############.',
+    '..############..',
+    '..##........##..',
+    '..##..####..##..',
+    '..##..####..##..',
+    '..##..####..##..',
+    '..############..',
+    '................',
+    '................',
+  ],
+  info: [
+    '................',
+    '......####......',
+    '.....######.....',
+    '.....######.....',
+    '......####......',
+    '................',
+    '....######......',
+    '......####......',
+    '......####......',
+    '......####......',
+    '......####......',
+    '....##########..',
+    '....##########..',
+    '................',
+    '................',
+    '................',
+  ],
+  link: [
+    '................',
+    '................',
+    '.....######.....',
+    '....########....',
+    '...###....###...',
+    '..###......###..',
+    '..##........##..',
+    '....######......',
+    '......######....',
+    '..##........##..',
+    '..###......###..',
+    '...###....###...',
+    '....########....',
+    '.....######.....',
+    '................',
+    '................',
+  ],
+  lock: [
+    '................',
+    '.....######.....',
+    '....##....##....',
+    '....##....##....',
+    '...##......##...',
+    '...##......##...',
+    '..############..',
+    '..############..',
+    '..####....####..',
+    '..###......###..',
+    '..###......###..',
+    '..####....####..',
+    '..############..',
+    '..############..',
+    '................',
+    '................',
+  ],
+  mail: [
+    '................',
+    '................',
+    '.##############.',
+    '.##..........##.',
+    '.#.##......##.#.',
+    '.#..##....##..#.',
+    '.#...##..##...#.',
+    '.#....####....#.',
+    '.#.....##.....#.',
+    '.#............#.',
+    '.#............#.',
+    '.##############.',
+    '................',
+    '................',
+    '................',
+    '................',
+  ],
+  menu: [
+    '................',
+    '................',
+    '.##############.',
+    '.##############.',
+    '................',
+    '................',
+    '.##############.',
+    '.##############.',
+    '................',
+    '................',
+    '.##############.',
+    '.##############.',
+    '................',
+    '................',
+    '................',
+    '................',
+  ],
+  minus: [
+    '................',
+    '................',
+    '................',
+    '................',
+    '................',
+    '................',
+    '..############..',
+    '..############..',
+    '..############..',
+    '..############..',
+    '................',
+    '................',
+    '................',
+    '................',
+    '................',
+    '................',
+  ],
+  moon: [
+    '................',
+    '......##........',
+    '....###.........',
+    '...###..........',
+    '..####..........',
+    '..####..........',
+    '.#####..........',
+    '.#####..........',
+    '.#####..........',
+    '.######.........',
+    '..######........',
+    '..#######.......',
+    '...##########...',
+    '....########....',
+    '......####......',
+    '................',
+  ],
+  'more-horizontal': [
+    '................',
+    '................',
+    '................',
+    '................',
+    '................',
+    '................',
+    '................',
+    '.##...##...##...',
+    '.##...##...##...',
+    '................',
+    '................',
+    '................',
+    '................',
+    '................',
+    '................',
+    '................',
+  ],
+  'more-vertical': [
+    '................',
+    '.......##.......',
+    '.......##.......',
+    '................',
+    '................',
+    '.......##.......',
+    '.......##.......',
+    '................',
+    '................',
+    '.......##.......',
+    '.......##.......',
+    '................',
+    '................',
+    '................',
+    '................',
+    '................',
+  ],
+  pause: [
+    '................',
+    '...###....###...',
+    '...###....###...',
+    '...###....###...',
+    '...###....###...',
+    '...###....###...',
+    '...###....###...',
+    '...###....###...',
+    '...###....###...',
+    '...###....###...',
+    '...###....###...',
+    '...###....###...',
+    '...###....###...',
+    '...###....###...',
+    '................',
+    '................',
+  ],
+  play: [
+    '................',
+    '....#...........',
+    '....##..........',
+    '....###.........',
+    '....####........',
+    '....#####.......',
+    '....######......',
+    '....#######.....',
+    '....#######.....',
+    '....######......',
+    '....#####.......',
+    '....####........',
+    '....###.........',
+    '....##..........',
+    '....#...........',
+    '................',
+  ],
+  plus: [
+    '................',
+    '................',
+    '.......##.......',
+    '.......##.......',
+    '.......##.......',
+    '.......##.......',
+    '..############..',
+    '..############..',
+    '..############..',
+    '..############..',
+    '.......##.......',
+    '.......##.......',
+    '.......##.......',
+    '.......##.......',
+    '................',
+    '................',
+  ],
+  refresh: [
+    '.....##.........',
+    '.....####.......',
+    '.....###........',
+    '.....##.........',
+    '.....#....#.....',
+    '....##....##....',
+    '...##......##...',
+    '...#........#...',
+    '...#........#...',
+    '...#........#...',
+    '...##......##...',
+    '....##....##....',
+    '.....######.....',
+    '......####......',
+    '................',
+    '................',
+  ],
+  search: [
+    '................',
+    '...######.......',
+    '..########......',
+    '.###....###.....',
+    '.##......##.....',
+    '.##......##.....',
+    '.##......##.....',
+    '.###....###.....',
+    '..########......',
+    '...#######......',
+    '......#####.....',
+    '.......#####....',
+    '........#####...',
+    '.........###....',
+    '................',
+    '................',
+  ],
+  spark: [
+    '................',
+    '.......**.......',
+    '.......**.......',
+    '.......**.......',
+    '.......**.......',
+    '.......**.......',
+    '......****......',
+    '.******##******.',
+    '.******##******.',
+    '......****......',
+    '.......**.......',
+    '.......**.......',
+    '.......**.......',
+    '.......**.......',
+    '.......**.......',
+    '................',
+  ],
+  star: [
+    '................',
+    '.......##.......',
+    '.......##.......',
+    '......####......',
+    '......####......',
+    '.##############.',
+    '..############..',
+    '...##########...',
+    '....########....',
+    '....########....',
+    '...####..####...',
+    '..####....####..',
+    '..###......###..',
+    '................',
+    '................',
+    '................',
+  ],
+  sun: [
+    '.......##.......',
+    '.......##.......',
+    '..#..........#..',
+    '...#........#...',
+    '................',
+    '......####......',
+    '.....######.....',
+    '##...######...##',
+    '##...######...##',
+    '.....######.....',
+    '......####......',
+    '................',
+    '...#........#...',
+    '..#..........#..',
+    '.......##.......',
+    '.......##.......',
+  ],
+  trash: [
+    '................',
+    '......####......',
+    '....########....',
+    '.##############.',
+    '................',
+    '..############..',
+    '..###.##.##.##..',
+    '..###.##.##.##..',
+    '..###.##.##.##..',
+    '..###.##.##.##..',
+    '..###.##.##.##..',
+    '..###.##.##.##..',
+    '..###.##.##.##..',
+    '..############..',
+    '................',
+    '................',
+  ],
+  upload: [
+    '................',
+    '.......#........',
+    '......###.......',
+    '.....#####......',
+    '....#######.....',
+    '...#########....',
+    '.......##.......',
+    '.......##.......',
+    '.......##.......',
+    '.......##.......',
+    '.......##.......',
+    '................',
+    '.##############.',
+    '.##############.',
+    '................',
+    '................',
+  ],
+  user: [
+    '................',
+    '.....######.....',
+    '....########....',
+    '....########....',
+    '....########....',
+    '.....######.....',
+    '................',
+    '..############..',
+    '.##############.',
+    '###..........###',
+    '###..........###',
+    '###..........###',
+    '##............##',
+    '................',
+    '................',
+    '................',
+  ],
+  warning: [
+    '................',
+    '.......##.......',
+    '.......##.......',
+    '......####......',
+    '......####......',
+    '.....##..##.....',
+    '.....##..##.....',
+    '....###..###....',
+    '....##....##....',
+    '...###....###...',
+    '...##.####.##...',
+    '..###.####.###..',
+    '..##........##..',
+    '.###############',
+    '.###############',
+    '................',
+  ],
+};
+
+/** The frozen name→bitmap registry (keys sorted, every row frozen). */
+export const GLYPHS = Object.freeze(
+  Object.fromEntries(
+    Object.keys(RAW)
+      .sort()
+      .map((name) => [name, Object.freeze(RAW[name])]),
+  ),
+);
+
+/** Every glyph name, frozen and sorted (mirrors GLYPHS keys). */
+export const GLYPH_NAMES = Object.freeze(Object.keys(GLYPHS));
+
+const TONE = { '#': 'hot', '*': 'accent' };
+
+/** The raw bitmap rows for a glyph, or `undefined` if the name is unknown. */
+export function glyph(name) {
+  return GLYPHS[name];
+}
+
+/** GLYPH_SIZE² cell descriptors (row-major), or `[]` if the name is unknown. */
+export function glyphCells(name) {
+  const rows = GLYPHS[name];
+  if (!rows) return [];
+  const cells = [];
+  for (const row of rows) {
+    for (const ch of row) {
+      if (ch === '.') cells.push({ on: false });
+      else cells.push({ on: true, tone: TONE[ch] });
+    }
+  }
+  return cells;
+}
+
+const CELL = 'ui-dotmatrix__cell';
+
+function cellClass(cell) {
+  if (!cell.on) return CELL;
+  if (cell.tone === 'hot') return `${CELL} ${CELL}--hot`;
+  if (cell.tone === 'accent') return `${CELL} ${CELL}--accent`;
+  return CELL;
+}
+
+function esc(s) {
+  return String(s)
+    .replace(/&/g, '&')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;');
+}
+
+// `dot`/`gap` land in an inline-CSS context (`style="--dotmatrix-dot:VALUE"`),
+// where HTML-escaping a `"` stops attribute breakout but a `;` would still open
+// a second CSS declaration (overlay/clickjacking, selector exfil). So restrict
+// them to length/calc syntax — digits, units, %, whitespace and `()+-*/.,` for
+// calc()/clamp()/var() — and drop anything else rather than emit it.
+function cssLen(v) {
+  return /^[\w.%+\-*/()\s,]+$/.test(v) ? v : '';
+}
+
+/**
+ * Build a CSS `mask-image` `url()` of an inline SVG for a glyph's lit cells —
+ * the basis of the one-node `render: 'mask'` path. Horizontal runs are merged
+ * into single `<rect>`s (fewer nodes, no seams). The SVG is alpha-masked, so
+ * the element's `currentColor` background shows through only the lit cells —
+ * one DOM node instead of GLYPH_SIZE² (256), for an icon at any size/colour.
+ */
+function maskUrl(rows) {
+  let rects = '';
+  rows.forEach((row, y) => {
+    let run = 0;
+    for (let x = 0; x <= GLYPH_SIZE; x++) {
+      const on = x < GLYPH_SIZE && row[x] !== '.';
+      if (on) run++;
+      else if (run) {
+        rects += `<rect x='${x - run}' y='${y}' width='${run}' height='1'/>`;
+        run = 0;
+      }
+    }
+  });
+  // The url() lands unquoted inside an HTML `style="…"` attribute, so it must
+  // carry no spaces or quotes of its own — encode them (and `<>#`) so it stays
+  // a single CSS url-token and can't break out of the attribute.
+  const svg = `<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 ${GLYPH_SIZE} ${GLYPH_SIZE}'>${rects}</svg>`;
+  const enc = svg
+    .replace(/%/g, '%25')
+    .replace(/</g, '%3C')
+    .replace(/>/g, '%3E')
+    .replace(/#/g, '%23')
+    .replace(/'/g, '%27')
+    .replace(/ /g, '%20');
+  return `url(data:image/svg+xml,${enc})`;
+}
+
+/**
+ * A full `.ui-dotmatrix` HTML string for a glyph (`''` if the name is
+ * unknown). Decorative by default (`aria-hidden`); pass `label` to expose it
+ * as `role="img"`. Pins `--dotmatrix-cols` to GLYPH_SIZE so the square layout
+ * holds regardless of the 12-col default; `dot`/`gap` set `--dotmatrix-dot` /
+ * `--dotmatrix-gap` (sanitized to a CSS length/calc allowlist; a malformed
+ * value is dropped). `grid: false` drops the unlit panel dots (glyph-only).
+ *
+ * `solid: true` renders the lit cells as square, gapless pixels (a filled
+ * silhouette) instead of separated dots — the legible mode at small/inline
+ * sizes (~16–24px) where the dot look fragments. It implies glyph-only.
+ *
+ * `anim` opts into a decorative animation (disabled under reduced-motion;
+ * the static frame + `label` still carry the meaning): `'reveal'` powers the
+ * cells on in a scan, `'pulse'` makes the glyph breathe.
+ *
+ * `render: 'mask'` returns a single `.ui-icon` element masked by the glyph
+ * bitmap (one DOM node, not GLYPH_SIZE²) — the icon-at-scale path: it sizes to
+ * `size` (or `--icon-size` / `1em`) and inherits `currentColor`. The
+ * cell-mode options (grid/solid/anim/dot/gap) don't apply; `label` does.
+ * Needs `@ponchia/ui/css` (the `.ui-icon` rule).
+ */
+export function renderGlyph(name, options = {}) {
+  const rows = GLYPHS[name];
+  if (!rows) return '';
+  const { grid = true, solid = false, anim, label, dot, gap, render, size } = options;
+
+  // One-node icon: a single `.ui-icon` span masked by the glyph's bitmap, so
+  // it scales to any font-size and inherits `currentColor` — for icon-at-scale
+  // (e.g. one in every table row) where the GLYPH_SIZE²-cell path is too heavy.
+  if (render === 'mask') {
+    const a11yM = label ? `role="img" aria-label="${esc(label)}"` : 'aria-hidden="true"';
+    const sz = size && cssLen(size) ? `--icon-size:${cssLen(size)};` : '';
+    return `<span class="ui-icon" style="${sz}--icon-mask:${maskUrl(rows)}" ${a11yM}></span>`;
+  }
+
+  const cells = glyphCells(name);
+
+  const style = [`--dotmatrix-cols:${GLYPH_SIZE}`];
+  const dotLen = dot && cssLen(dot);
+  const gapLen = gap && cssLen(gap);
+  if (dotLen) style.push(`--dotmatrix-dot:${dotLen}`);
+  // 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}`);
+
+  const cls =
+    anim === 'reveal'
+      ? 'ui-dotmatrix ui-dotmatrix--reveal'
+      : anim === 'pulse'
+        ? 'ui-dotmatrix ui-dotmatrix--pulse'
+        : 'ui-dotmatrix';
+  // `reveal` staggers each cell by its row-major index via `--i`.
+  const stagger = anim === 'reveal';
+
+  const a11y = label ? `role="img" aria-label="${esc(label)}"` : 'aria-hidden="true"';
+
+  // Off cells keep the cell class (so they hold their grid track and 1:1
+  // aspect-ratio); `grid: false` (implied by `solid`) only drops their lit
+  // background, for the glyph-only look, without collapsing all-off rows.
+  const showPanel = grid && !solid;
+  const inner = cells
+    .map((c, i) => {
+      const cl = c.on ? cellClass(c) : 'ui-dotmatrix__cell';
+      const cellStyle = [];
+      if (!c.on && !showPanel) cellStyle.push('background:transparent');
+      if (stagger) cellStyle.push(`--i:${i}`);
+      const s = cellStyle.length ? ` style="${cellStyle.join(';')}"` : '';
+      return `<span class="${cl}"${s}></span>`;
+    })
+    .join('');
+
+  // A `<span>` (not `<div>`): it's phrasing content, so the glyph is valid
+  // inline and inside a `<button>` (its content model is phrasing-only) — the
+  // inline-icon use. `.ui-dotmatrix`'s `display: grid` works on a span.
+  return `<span class="${cls}" style="${style.join(';')}" ${a11y}>${inner}</span>`;
+}