tosijs-ui 1.16.18 → 1.16.19

package/CHANGELOG.md

@@ -1,5 +1,28 @@
 # Changelog
 
+## 1.16.19
+
+- **`iconSvg()` resolves the built-in icons that rotate or flip another.** 27 built-in
+  names are redirects with a rotation or flip (`chevronDown` is `chevronRight90r`; also
+  `chevronLeft`/`Up`, `arrowDown`/`Left`/`Up`, `cornerDownLeft`, `rotateCcw`, `thumbsDown`
+  and others), and `iconSvg()` returned `undefined` for every one of them, silently. They
+  now return markup with the transform applied about the centre of the viewBox. A rotation
+  or flip written inline (`iconSvg('chevronRight90r')`) and other inline names returned
+  undefined silently too: a rotation or flip now resolves, and anything else throws. A Playwright
+  test draws each one both ways, through `iconSvg` and through `icons.<name>()`, and
+  finds no pixel that differs by more than antialiasing, in all three browsers.
+- **`iconSvg()` throws for a name it cannot turn into one SVG.** A stack
+  (`cloudSync: 'spin120Loader40s_30x$cloud'`, or `tosi$hat` written inline), a rule
+  (`unLock`, `spin90Loader`), a style suffix other than rotation or flip (`check50o`), a
+  redirect to a name that is not an icon, or a redirect cycle all returned `undefined`,
+  the same answer as a name that does not exist, so a build script rendered nothing and
+  said nothing. Each now throws, saying which it is and, where the icon renderer would draw
+  it, that `icons.<name>()` does so where there is a DOM. **Code that relied on `undefined`
+  for those names now gets an exception;** a name nothing would draw still returns
+  `undefined`, as documented. This is the follow-up to #224, for the DOM-free path.
+- `iconSvg()` reads suffixes with the same grammar as the icon renderer, now shared
+  between them: `edit2_90r` is `edit2` turned 90°, not -90°.
+
 ## 1.16.18
 
 - **A `defineIcons` name for a stacked composition draws the stack.** `defineIcons({

package/dist/icon-rules.d.ts

@@ -0,0 +1,20 @@
+import type { ElementPart } from 'tosijs';
+export interface IconRule {
+    prefix: string | RegExp;
+    apply: (baseName: string, match: RegExpMatchArray | string, parts: ElementPart[]) => Element | string | null;
+}
+/** A registered icon, or style suffixes on one (`chevronRight50o`). */
+export declare function canResolve(name: string): boolean;
+/**
+ * `spinN<Icon>` animates, so it is drawn by the DOM renderer, which installs `apply` when
+ * it loads. Its prefix is here so that every module knows the rule exists.
+ */
+export declare const spinRule: IconRule;
+export declare const iconRules: IconRule[];
+/** The icon a rule would apply to in `name`, or null if the rule does not match it. */
+export declare function matchRule(rule: IconRule, name: string): {
+    baseName: string;
+    match: RegExpMatchArray | string;
+} | null;
+/** Whether some rule would draw `name`: it matches, and the icon it applies to exists. */
+export declare const ruleDraws: (name: string) => boolean;

package/dist/icon-rules.js

@@ -0,0 +1,72 @@
+/*
+Composition rules (`spinNLoader`, `unLock`, `checkFile`, …) and how a name is matched to
+one, in ONE place. `icons.ts` (the DOM renderer) draws through them; `icon-svg.ts` (markup
+without a DOM) asks the same question, "would the renderer draw this name?", so it can tell
+a rule it cannot render from a name nothing would draw. It once guessed rules from the shape
+of a name instead, and threw for `redLock`. DOM-free, so `icon-svg.ts` can import it.
+
+Rules an app adds with `iconRules.push()` are seen by both, as long as they are pushed
+before the name is asked for.
+*/
+import iconData from './icon-data.js';
+import { splitSuffixes } from './icon-suffixes.js';
+/** A registered icon, or style suffixes on one (`chevronRight50o`). */
+export function canResolve(name) {
+    const data = iconData;
+    if (data[name])
+        return true;
+    const split = splitSuffixes(name);
+    return split != null && !!data[split.baseName];
+}
+/**
+ * `spinN<Icon>` animates, so it is drawn by the DOM renderer, which installs `apply` when
+ * it loads. Its prefix is here so that every module knows the rule exists.
+ */
+export const spinRule = {
+    prefix: /^spin(_?\d+)/,
+    apply() {
+        throw new Error('spin icons are drawn by the icon renderer (tosijs-ui/icons)');
+    },
+};
+export const iconRules = [
+    spinRule,
+    {
+        prefix: 'un',
+        apply: (baseName) => `slash25o$${baseName}75s75o`,
+    },
+    {
+        prefix: 'check',
+        apply: (baseName) => `check75o_00aa00S$${baseName}75s50o`,
+    },
+    {
+        prefix: 'cancel',
+        apply: (baseName) => `x75o_cc0000S$${baseName}75s50o`,
+    },
+    {
+        prefix: 'search',
+        apply: (baseName) => `search80s30x30y$${baseName}50o`,
+    },
+];
+/** The icon a rule would apply to in `name`, or null if the rule does not match it. */
+export function matchRule(rule, name) {
+    if (rule.prefix instanceof RegExp) {
+        const m = name.match(new RegExp(rule.prefix.source + '(.+)$'));
+        if (!m)
+            return null;
+        const tail = m[m.length - 1];
+        return { baseName: tail[0].toLowerCase() + tail.slice(1), match: m };
+    }
+    if (!name.startsWith(rule.prefix) || name.length <= rule.prefix.length) {
+        return null;
+    }
+    return {
+        baseName: name[rule.prefix.length].toLowerCase() +
+            name.slice(rule.prefix.length + 1),
+        match: rule.prefix,
+    };
+}
+/** Whether some rule would draw `name`: it matches, and the icon it applies to exists. */
+export const ruleDraws = (name) => iconRules.some((rule) => {
+    const matched = matchRule(rule, name);
+    return matched != null && canResolve(matched.baseName);
+});

package/dist/icon-suffixes.d.ts

@@ -0,0 +1,8 @@
+export declare const SUFFIX_RE: RegExp;
+/** A name split into its base and its suffix tokens, in order, or null if it has none. */
+export declare function splitSuffixes(name: string): {
+    baseName: string;
+    tokens: string[];
+} | null;
+/** The signed number in a numeric token: `_45r` is -45. */
+export declare const suffixNumber: (token: string) => number;

package/dist/icon-suffixes.js

@@ -0,0 +1,31 @@
+/*
+The icon style-suffix grammar, in ONE place. `icons.ts` (the DOM renderer) and
+`icon-svg.ts` (markup without a DOM) both read names through it. `icon-svg.ts` kept its own
+copy for one release candidate, and the two disagreed within a day: it read the `_` in
+`edit2_90r` as a minus sign and rotated the wrong way. DOM-free, so `icon-svg.ts` can
+import it.
+
+Suffixes are a value then a letter code:
+  50o (opacity), 75s (scale), 20x (translateX%), _10y (translateY%)
+  90r (rotate 90°), _45r (rotate -45°), 0f (flipH), 1f (flipV)
+  _FF0000F (fill hex), _f00S (stroke hex), 3W (stroke-width)
+  _brandColorF (fill var), _accentS (stroke var)
+Icon names ending in digits need a _ separator: edit2_50o
+*/
+export const SUFFIX_RE = /(?:(?<=[a-zA-Z_])(?:_?\d+[osxyr]|[01]f|\d+W)|_[a-zA-Z0-9]+[FS])+$/;
+const SUFFIX_TOKEN_RE = /_?\d+[osxyr]|[01]f|_[a-zA-Z0-9]+[FS]|\d+W/g;
+/** A name split into its base and its suffix tokens, in order, or null if it has none. */
+export function splitSuffixes(name) {
+    const match = name.match(SUFFIX_RE);
+    if (!match)
+        return null;
+    let baseName = name.slice(0, match.index);
+    // Strip the trailing _ separator (for digit-ending names: edit2_50o)
+    if (baseName.endsWith('_'))
+        baseName = baseName.slice(0, -1);
+    if (!baseName)
+        return null;
+    return { baseName, tokens: match[0].match(SUFFIX_TOKEN_RE) };
+}
+/** The signed number in a numeric token: `_45r` is -45. */
+export const suffixNumber = (token) => parseInt(token.replace('_', '-'));

package/dist/icon-svg.d.ts

@@ -1,3 +1,10 @@
+/**
+ * Raw SVG markup for an icon, or `undefined` when nothing by that name would draw.
+ *
+ * Throws when the name would draw but cannot be one SVG string: a stack (`a$b`), a rule
+ * (`spin…`, `un…`), a style suffix other than rotation or flip, a redirect to a name that
+ * is not an icon, or a redirect cycle. Those need `icons.<name>()` where there is a DOM.
+ */
 export declare function iconSvg(name: string): string | undefined;
 /** Every icon name currently registered, including any added via defineIcons. */
 export declare function iconNames(): string[];

package/dist/icon-svg.js

@@ -5,7 +5,7 @@
 ```js
 import { iconSvg, iconNames } from 'tosijs-ui'
 
-const markup = iconSvg('tosi') // '<svg …>…</svg>' | undefined
+const markup = iconSvg('tosi') // '<svg …>…</svg>', or undefined for an unknown name
 preview.innerHTML =
   `<p>${iconNames().length} icons registered.</p>` +
   `<div style="width:48px">${markup}</div>`
@@ -19,6 +19,14 @@ what the live-example runner can rewrite.)
 is registered. Neither touches the DOM, so both work in a build script, a server-rendered
 template, or an ePub pass.
 
+Redirects are followed, including the built-in ones that rotate or flip another icon
+(`chevronDown` is `chevronRight90r`), and a rotation or flip written inline works too
+(`iconSvg('chevronRight90r')`). A name the icon renderer would draw but that cannot be one
+SVG string **throws**, saying why: a stack (`a$b`), a rule (`spin90Loader`, `unLock`), any
+other style suffix (`check50o`), a redirect to a name that is not an icon, or a redirect
+cycle. Render those with `icons.<name>()` where there is a DOM; the suffixes and rules are
+described on the [[icons]] page. Only a name that nothing would draw returns `undefined`.
+
 Deliberately a separate module from `icons.ts`: that one imports tosijs to build
 elements, so importing it drags in code that needs `HTMLElement` and throws in a build
 script — the exact context that wanted the markup in the first place. This module
@@ -32,18 +40,80 @@ resorted to when putting its own logo on a generated page. There is nothing to p
 the map ships in the bundle either way.
 */
 import iconData from './icon-data.js';
+import { splitSuffixes, suffixNumber } from './icon-suffixes.js';
+import { canResolve, ruleDraws } from './icon-rules.js';
+const data = iconData;
+// Rotation and flip, the only suffixes the built-in redirects use (`chevronDown` is
+// `chevronRight90r`). Anything else needs the DOM renderer.
+const isGeometry = (token) => /^(_?\d+r|[01]f)$/.test(token);
+const stripEscape = (name) => name.endsWith('_') ? name.slice(0, -1) : name;
+// Whether the icon renderer would draw something for a name: a registered icon, suffixes on
+// one (`chevronRight50o`), a stack (`a$b`), or a rule applied to one (`spin90Loader`,
+// `unLock`). The rules and suffixes are the renderer's own (icon-rules, icon-suffixes).
+const isComposition = (name) => name.includes('$') || canResolve(name) || ruleDraws(name);
+/**
+ * Raw SVG markup for an icon, or `undefined` when nothing by that name would draw.
+ *
+ * Throws when the name would draw but cannot be one SVG string: a stack (`a$b`), a rule
+ * (`spin…`, `un…`), a style suffix other than rotation or flip, a redirect to a name that
+ * is not an icon, or a redirect cycle. Those need `icons.<name>()` where there is a DOM.
+ */
 export function iconSvg(name) {
-    const data = iconData;
-    let key = name.endsWith('_') ? name.slice(0, -1) : name;
-    for (let i = 0; i < 10; i++) {
-        const value = data[key];
-        if (value === undefined)
-            return undefined;
+    const key = stripEscape(name);
+    if (!isComposition(key))
+        return undefined;
+    return resolve(name, key, new Set());
+}
+function resolve(asked, name, seen) {
+    const key = stripEscape(name);
+    const value = data[key];
+    if (value !== undefined) {
         if (value.startsWith('<'))
             return value;
-        key = value; // a redirect to another icon's name
+        if (seen.has(key)) {
+            throw new Error(`iconSvg("${asked}"): the icon redirects in a cycle`);
+        }
+        seen.add(key);
+        return resolve(asked, value, seen);
+    }
+    // The renderer's order for a name that is not registered: a stack, then a rule, then
+    // suffixes. So `checkCircle90r` is the `check` rule over `circle90r`, not `checkCircle`
+    // turned, and only a name no rule claims gets the transform.
+    const split = key.includes('$') || ruleDraws(key) ? null : splitSuffixes(key);
+    if (split &&
+        data[split.baseName] !== undefined &&
+        split.tokens.every(isGeometry)) {
+        return transformed(asked, resolve(asked, split.baseName, seen), split.tokens);
+    }
+    const what = key === stripEscape(asked) ? `"${key}"` : `it resolves to "${key}", which`;
+    if (isComposition(key)) {
+        throw new Error(`iconSvg("${asked}"): ${what} is not a single SVG (a stack, a rule, or a style ` +
+            `suffix other than rotation or flip). Render it with icons.${stripEscape(asked)}() ` +
+            `where there is a DOM.`);
+    }
+    throw new Error(`iconSvg("${asked}"): it redirects to "${key}", which is not a registered icon`);
+}
+// Apply rotate/flip suffixes about the centre of the viewBox, as the DOM renderer does
+// with `transform-origin: 50% 50%`.
+function transformed(asked, svg, tokens) {
+    const parts = svg.match(/^(\s*<svg\b[^>]*>)([\s\S]*)(<\/svg>\s*)$/);
+    const viewBox = parts?.[1]
+        .match(/viewBox="([^"]+)"/)?.[1]
+        .split(/[\s,]+/)
+        .map(Number);
+    if (!parts || !viewBox || viewBox.length !== 4 || viewBox.some(isNaN)) {
+        throw new Error(`iconSvg("${asked}"): cannot transform an icon without a viewBox`);
     }
-    return undefined; // redirect loop — treat as missing rather than hang
+    const [x, y, width, height] = viewBox;
+    const cx = x + width / 2;
+    const cy = y + height / 2;
+    const ops = tokens.map((token) => token.endsWith('r')
+        ? `rotate(${suffixNumber(token)})`
+        : token === '0f'
+            ? 'scale(-1 1)'
+            : 'scale(1 -1)');
+    const transform = `translate(${cx} ${cy}) ${ops.join(' ')} translate(${-cx} ${-cy})`;
+    return `${parts[1]}<g transform="${transform}">${parts[2]}</g>${parts[3]}`;
 }
 /** Every icon name currently registered, including any added via defineIcons. */
 export function iconNames() {

package/dist/icons.d.ts

@@ -1,16 +1,12 @@
 import { ElementCreator, ElementPart } from 'tosijs';
 import { SVGIconMap } from './icon-types.js';
+export { iconRules, type IconRule } from './icon-rules.js';
 export declare const defineIcons: (newIcons: {
     [key: string]: string;
 }) => void;
 export { iconSvg, iconNames } from './icon-svg.js';
 export type { IconElement, IconName, SVGIconMap } from './icon-types.js';
 export declare const svg2DataUrl: (icon: Element, fill?: string, stroke?: string, strokeWidth?: number) => string;
-export interface IconRule {
-    prefix: string | RegExp;
-    apply: (baseName: string, match: RegExpMatchArray | string, parts: ElementPart[]) => Element | string | null;
-}
-export declare const iconRules: IconRule[];
 /** Wrap icon elements in a composite container (for custom function rules) */
 export declare function wrapIcon(prop: string, parts: ElementPart[], ...children: Element[]): HTMLSpanElement;
 /** Resolve an icon name through the full pipeline (redirects, suffixes, rules, stacking) */

package/dist/icons.js

@@ -564,6 +564,9 @@ copies or substantial portions of the Software.
 */
 import { elements, svgElements, Color, vars, varDefault, withAttributes, } from 'tosijs';
 import iconData from './icon-data.js';
+import { splitSuffixes, suffixNumber } from './icon-suffixes.js';
+import { iconRules, spinRule, matchRule, canResolve } from './icon-rules.js';
+export { iconRules } from './icon-rules.js';
 export const defineIcons = (newIcons) => {
     Object.assign(iconData, newIcons);
 };
@@ -629,47 +632,28 @@ export const svg2DataUrl = (icon, fill, stroke, strokeWidth) => {
 };
 // Appends _ to names ending in digits to prevent suffix ambiguity
 const safeIconSuffix = (name) => /\d$/.test(name) ? name + '_' : name;
-export const iconRules = [
-    {
-        prefix: /^spin(_?\d+)/,
-        apply(baseName, match, parts) {
-            const dps = match[1].replace('_', '-');
-            const duration = 360 / Math.abs(parseFloat(dps));
-            const direction = dps.startsWith('-') ? 'reverse' : 'normal';
-            // Resolve baseName with suffixes intact — they apply to the icon
-            const icon = resolveIcon(baseName, []);
-            const el = icon;
-            if (el.animate) {
-                const base = el.style.transform || '';
-                el.animate([
-                    { transform: `${base} rotate(0deg)` },
-                    { transform: `${base} rotate(360deg)` },
-                ], {
-                    duration: duration * 1000,
-                    iterations: Infinity,
-                    direction,
-                });
-            }
-            return wrapIcon(baseName, parts, icon);
-        },
-    },
-    {
-        prefix: 'un',
-        apply: (baseName) => `slash25o$${baseName}75s75o`,
-    },
-    {
-        prefix: 'check',
-        apply: (baseName) => `check75o_00aa00S$${baseName}75s50o`,
-    },
-    {
-        prefix: 'cancel',
-        apply: (baseName) => `x75o_cc0000S$${baseName}75s50o`,
-    },
-    {
-        prefix: 'search',
-        apply: (baseName) => `search80s30x30y$${baseName}50o`,
-    },
-];
+// The rule list and how names match it live in icon-rules.ts, shared with iconSvg. Spin
+// animates, so its renderer is installed here.
+spinRule.apply = (baseName, match, parts) => {
+    const dps = match[1].replace('_', '-');
+    const duration = 360 / Math.abs(parseFloat(dps));
+    const direction = dps.startsWith('-') ? 'reverse' : 'normal';
+    // Resolve baseName with suffixes intact — they apply to the icon
+    const icon = resolveIcon(baseName, []);
+    const el = icon;
+    if (el.animate) {
+        const base = el.style.transform || '';
+        el.animate([
+            { transform: `${base} rotate(0deg)` },
+            { transform: `${base} rotate(360deg)` },
+        ], {
+            duration: duration * 1000,
+            iterations: Infinity,
+            direction,
+        });
+    }
+    return wrapIcon(baseName, parts, icon);
+};
 let iconIdCounter = 0;
 function makeIcon(spec, parts) {
     const div = elements.div();
@@ -748,38 +732,13 @@ export function wrapIcon(prop, parts, ...children) {
     }
     return wrapper;
 }
-function canResolve(name) {
-    const data = iconData;
-    if (data[name])
-        return true;
-    const parsed = parseStyleSuffixes(name);
-    return parsed != null && !!data[parsed.baseName];
-}
 function composeIcon(prop, parts) {
     for (const rule of iconRules) {
-        let baseName;
-        let match;
-        if (rule.prefix instanceof RegExp) {
-            const re = new RegExp(rule.prefix.source + '(.+)$');
-            const m = prop.match(re);
-            if (!m)
-                continue;
-            baseName = m[m.length - 1];
-            baseName = baseName[0].toLowerCase() + baseName.slice(1);
-            match = m;
-        }
-        else {
-            if (!prop.startsWith(rule.prefix) || prop.length <= rule.prefix.length)
-                continue;
-            baseName =
-                prop[rule.prefix.length].toLowerCase() +
-                    prop.slice(rule.prefix.length + 1);
-            match = rule.prefix;
-        }
+        const matched = matchRule(rule, prop);
         // Only apply if baseName can actually resolve to an icon
-        if (!canResolve(baseName))
+        if (!matched || !canResolve(matched.baseName))
             continue;
-        const result = rule.apply(safeIconSuffix(baseName), match, parts);
+        const result = rule.apply(safeIconSuffix(matched.baseName), matched.match, parts);
         if (typeof result === 'string')
             return resolveIcon(result, parts);
         if (result)
@@ -789,41 +748,20 @@ function composeIcon(prop, parts) {
 }
 // Redirect names being resolved right now, so a redirect cycle ends instead of recursing.
 const expanding = new Set();
-// Style suffixes — value then letter code:
-//   50o (opacity), 75s (scale), 20x (translateX%), _10y (translateY%)
-//   90r (rotate 90°), _45r (rotate -45°), 0f (flipH), 1f (flipV)
-//   _FF0000F (fill hex), _f00S (stroke hex), 3W (stroke-width)
-//   _brandColorF (fill var), _accentS (stroke var)
-// Icon names ending in digits need _ separator: edit2_50o
-const SUFFIX_RE = /(?:(?<=[a-zA-Z_])(?:_?\d+[osxyr]|[01]f|\d+W)|_[a-zA-Z0-9]+[FS])+$/;
+// The suffix grammar lives in icon-suffixes.ts, shared with iconSvg.
 function parseStyleSuffixes(name) {
-    const match = name.match(SUFFIX_RE);
-    if (!match)
-        return null;
-    let baseName = name.slice(0, match.index);
-    if (!baseName)
-        return null;
-    // Strip trailing _ separator (for digit-ending names: edit2_50o)
-    if (baseName.endsWith('_'))
-        baseName = baseName.slice(0, -1);
-    if (!baseName)
+    const split = splitSuffixes(name);
+    if (!split)
         return null;
+    const { baseName } = split;
     const data = iconData;
     // Accept if baseName is in iconData, or matches a composition rule prefix
     if (!data[baseName]) {
-        const matchesRule = iconRules.some((rule) => {
-            if (rule.prefix instanceof RegExp) {
-                return rule.prefix.test(baseName);
-            }
-            return (baseName.startsWith(rule.prefix) && baseName.length > rule.prefix.length);
-        });
-        if (!matchesRule)
+        if (!iconRules.some((rule) => matchRule(rule, baseName)))
             return null;
     }
     const style = {};
-    const suffixes = match[0].match(/_?\d+[osxyr]|[01]f|_[a-zA-Z0-9]+[FS]|\d+W/g);
-    if (!suffixes)
-        return null;
+    const suffixes = split.tokens;
     const transforms = [];
     for (const s of suffixes) {
         const code = s[s.length - 1];
@@ -842,7 +780,7 @@ function parseStyleSuffixes(name) {
             style.strokeWidth = s.slice(0, -1);
         }
         else {
-            const val = parseInt(s.replace('_', '-'));
+            const val = suffixNumber(s);
             switch (code) {
                 case 'o':
                     style.opacity = String(val / 100);