tosijs-ui 1.5.9 → 1.5.11

package/dist/icons.d.ts

@@ -8,9 +8,11 @@ export interface IconRule {
     prefix: string | RegExp;
     apply: (baseName: string, match: RegExpMatchArray | string, parts: ElementPart[]) => Element | string | null;
 }
-/** Returns icon name safe for suffix concatenation (appends _ if name ends in digit) */
-export declare const safeIconSuffix: (name: string) => string;
 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) */
+export declare function resolveIcon(prop: string, parts: ElementPart[]): Element;
 export declare const icons: SVGIconMap;
 export declare class SvgIcon extends WebComponent {
     static preferredTagName: string;

package/dist/icons.js

@@ -428,7 +428,9 @@ viewBox** for best results on non-square base icons.
 `iconRules` is a mutable array. Each rule has a `prefix` (string or
 RegExp) and an `apply` function that returns a **string** (resolved
 through the full pipeline), an **Element** (used directly), or **null**
-(skip to next rule):
+(skip to next rule).
+
+String rewrites are the simplest — just return a composition string:
 
     // String rewrite: addFoo → plus75o_0000ffS$foo75s50o
     iconRules.push({
@@ -436,16 +438,51 @@ through the full pipeline), an **Element** (used directly), or **null**
       apply: (baseName) => `plus75o_0000ffS$${baseName}75s50o`,
     })
 
-    // Function rule with side effects (like spin)
+Function rules can use `resolveIcon()` and `wrapIcon()` (both exported)
+for more control:
+
+    // Function rule: glowNNFoo → foo with brightness filter
     iconRules.push({
       prefix: /^glow(\d+)/,
       apply: (baseName, match, parts) => {
         const icon = resolveIcon(baseName, parts)
         icon.style.filter = `brightness(${match[1]}%)`
-        return icon
+        return wrapIcon(baseName, parts, icon)
       },
     })
 
+- `resolveIcon(name, parts)` — resolve any icon name through the full
+  pipeline (redirects, suffixes, rules, stacking)
+- `wrapIcon(name, parts, ...children)` — wrap elements in a composite
+  container with proper sizing, `pointer-events: none`, and `data-icon`
+
+### Building an icon vocabulary
+
+You don't need to spell out the DSL every time. The real power is in
+defining named patterns that become your application's icon language.
+For example, a `remove` prefix that overlays a trash icon:
+
+    iconRules.push({
+      prefix: 'remove',
+      apply: (baseName) =>
+        `trash75o_actionColorS$${baseName}50o`,
+    })
+
+Now `removeUser`, `removeFile`, `removeProject` all just work — and
+they're consistent. If you redesign the trash icon or change
+`--action-color`, every "remove" icon updates automatically.
+
+You can also use `defineIcons` for one-off named compositions:
+
+    defineIcons({
+      cloudSync: 'spin120Loader40s_30x$cloud',
+      secureShield: 'lock50s75o_10y$shield',
+      newFile: 'plus75o60s25x25y$file',
+    })
+
+Then just use `icons.cloudSync()` or `<tosi-icon icon="cloudSync">` —
+the composition is invisible to consumers of the icon.
+
 ### Composites and `svg2DataUrl`
 
 Composed icons (stacked, overlay rules) are wrapped in a `<span>`, not
@@ -536,8 +573,8 @@ export const svg2DataUrl = (icon, fill, stroke, strokeWidth) => {
     const text = encodeURIComponent(svg.outerHTML);
     return `url(data:image/svg+xml;charset=UTF-8,${text})`;
 };
-/** Returns icon name safe for suffix concatenation (appends _ if name ends in digit) */
-export const safeIconSuffix = (name) => /\d$/.test(name) ? name + '_' : name;
+// Appends _ to names ending in digits to prevent suffix ambiguity
+const safeIconSuffix = (name) => /\d$/.test(name) ? name + '_' : name;
 export const iconRules = [
     {
         prefix: /^spin(_?\d+)/,
@@ -564,19 +601,19 @@ export const iconRules = [
     },
     {
         prefix: 'un',
-        apply: (baseName) => `slash25o$${safeIconSuffix(baseName)}75s75o`,
+        apply: (baseName) => `slash25o$${baseName}75s75o`,
     },
     {
         prefix: 'check',
-        apply: (baseName) => `check75o_00aa00S$${safeIconSuffix(baseName)}75s50o`,
+        apply: (baseName) => `check75o_00aa00S$${baseName}75s50o`,
     },
     {
         prefix: 'cancel',
-        apply: (baseName) => `x75o_cc0000S$${safeIconSuffix(baseName)}75s50o`,
+        apply: (baseName) => `x75o_cc0000S$${baseName}75s50o`,
     },
     {
         prefix: 'search',
-        apply: (baseName) => `search80s30x30y$${safeIconSuffix(baseName)}50o`,
+        apply: (baseName) => `search80s30x30y$${baseName}50o`,
     },
 ];
 function makeIcon(spec, parts) {
@@ -605,7 +642,8 @@ function makeIcon(spec, parts) {
     svg.style.height = varDefault.tosiIconSize('16px');
     return svg;
 }
-function wrapIcon(prop, parts, ...children) {
+/** Wrap icon elements in a composite container (for custom function rules) */
+export function wrapIcon(prop, parts, ...children) {
     const wrapper = elements.span({
         class: 'tosi-icon-composite',
         dataIcon: prop,
@@ -660,7 +698,7 @@ function composeIcon(prop, parts) {
         // Only apply if baseName can actually resolve to an icon
         if (!canResolve(baseName))
             continue;
-        const result = rule.apply(baseName, match, parts);
+        const result = rule.apply(safeIconSuffix(baseName), match, parts);
         if (typeof result === 'string')
             return resolveIcon(result, parts);
         if (result)
@@ -756,7 +794,10 @@ function parseStyleSuffixes(name) {
     }
     return { baseName, style };
 }
-function resolveIcon(prop, parts) {
+/** Resolve an icon name through the full pipeline (redirects, suffixes, rules, stacking) */
+export function resolveIcon(prop, parts) {
+    if (prop.endsWith('_'))
+        prop = prop.slice(0, -1);
     const data = iconData;
     // Direct match or redirect chain
     let name = prop;