tosijs-ui 1.16.22 → 1.16.23

package/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## 1.16.23
+
+- **`rule:icon` applies an icon composition rule explicitly.** A `:` marks the boundary
+  between a rule's prefix and the icon it applies to. `checkSquare` is a registered icon, so
+  it draws that icon; `check:square` is the `check` rule over `square`. The explicit form
+  always applies the rule, needs no capital after the prefix (`check:Square` is the same), and
+  takes suffixes and stacking as usual (`spin90:loader40s`, `un:lock$shield`). A `:` is not
+  valid in an identifier, so write `icons['check:square']()` or
+  `<tosi-icon icon="check:square">`, and it works in the `caption:icon` option strings of
+  `<tosi-select>` and `<tosi-segmented>` (`done=Done:check:square`), whose caption now ends at
+  the first colon. Names without a `:` resolve exactly as before. `defineIcons` warns when
+  it defines a `rule:icon` name, since the definition then wins over the rule.
+- **The kitchen-sink style testbed is no longer bound into the ePub or print.** It stays on
+  the site; it is a component showcase, not reading. Docs-only: no API or rendering moved.
+
 ## 1.16.22
 
 Three site options asked for by adopters, and a review pass over the documentation.

package/dist/caption-icon.d.ts

@@ -0,0 +1,2 @@
+/** `caption:icon` split at the first colon, both trimmed; the icon is '' when absent. */
+export declare function splitCaptionIcon(text: string): [string, string];

package/dist/caption-icon.js

@@ -0,0 +1,12 @@
+/*
+`caption:icon` in the option strings of `<tosi-select>` and `<tosi-segmented>`, split in ONE
+place. The caption ends at the FIRST colon, because an icon name may hold one itself: an
+explicit composition rule (`check:square`) is still an icon name.
+*/
+/** `caption:icon` split at the first colon, both trimmed; the icon is '' when absent. */
+export function splitCaptionIcon(text) {
+    const colon = text.indexOf(':');
+    return colon === -1
+        ? [text.trim(), '']
+        : [text.slice(0, colon).trim(), text.slice(colon + 1).trim()];
+}

package/dist/icon-rules.d.ts

@@ -21,7 +21,13 @@ export declare function canResolve(name: string): boolean;
  */
 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. */
+/**
+ * The icon a rule would apply to in `name`, or null if the rule does not match it.
+ *
+ * A `:` makes the boundary explicit: `check:box` is the `check` rule applied to `box`, with
+ * no camelCase guess, so it never reads as an icon called `checkBox`. Everything before the
+ * first `:` must be the whole prefix (`spin90:loader`, `un:lock`).
+ */
 export declare function matchRule(rule: IconRule, name: string): {
     baseName: string;
     match: RegExpMatchArray | string;

package/dist/icon-rules.js

@@ -55,8 +55,27 @@ export const iconRules = [
         apply: (baseName) => `search80s30x30y$${baseName}50o`,
     },
 ];
-/** The icon a rule would apply to in `name`, or null if the rule does not match it. */
+/**
+ * The icon a rule would apply to in `name`, or null if the rule does not match it.
+ *
+ * A `:` makes the boundary explicit: `check:box` is the `check` rule applied to `box`, with
+ * no camelCase guess, so it never reads as an icon called `checkBox`. Everything before the
+ * first `:` must be the whole prefix (`spin90:loader`, `un:lock`).
+ */
 export function matchRule(rule, name) {
+    const colon = name.indexOf(':');
+    if (colon !== -1) {
+        const head = name.slice(0, colon);
+        const tail = name.slice(colon + 1);
+        if (!tail)
+            return null;
+        const baseName = tail[0].toLowerCase() + tail.slice(1);
+        if (rule.prefix instanceof RegExp) {
+            const m = head.match(new RegExp(rule.prefix.source + '$'));
+            return m && m.index === 0 ? { baseName, match: m } : null;
+        }
+        return head === rule.prefix ? { baseName, match: rule.prefix } : null;
+    }
     if (rule.prefix instanceof RegExp) {
         const m = name.match(new RegExp(rule.prefix.source + '(.+)$'));
         if (!m)

package/dist/icon-svg.js

@@ -60,6 +60,9 @@ export function iconSvg(name) {
         return undefined;
     return resolve(name, key, new Set());
 }
+// How to call the creator for a name: `icons.lock()`, or `icons['check:box']()` for a name
+// that is not an identifier.
+const creatorCall = (name) => /^[A-Za-z_$][\w$]*$/.test(name) ? `icons.${name}()` : `icons['${name}']()`;
 function resolve(asked, name, seen) {
     const key = stripEscape(name);
     const value = data[key];
@@ -81,7 +84,7 @@ function resolve(asked, name, seen) {
     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)}() ` +
+            `suffix other than rotation or flip). Render it with ${creatorCall(stripEscape(asked))} ` +
             `where there is a DOM.`);
     }
     throw new Error(`iconSvg("${asked}"): it redirects to "${key}", which is not a registered icon`);

package/dist/icons.js

@@ -442,6 +442,24 @@ The overlay rules are just string rewrites — for example, `unFoo`
 becomes `slash25o$foo75s75o`. **Overlay icons should have a square
 viewBox** for best results on non-square base icons.
 
+#### Explicit rules: `rule:icon`
+
+`checkSquare` is ambiguous: it is a registered icon, and it also reads as
+the `check` rule over `square`. A registered icon wins, so it draws the
+icon. Put a `:` at the boundary to ask for the rule: `check:square`,
+`un:lock`, `spin90:loader`. The explicit form applies the rule (unless
+you `defineIcons` that exact name, which warns), needs no capital letter
+after the prefix, and takes suffixes and stacking
+as usual (`spin90:loader40s`, `un:lock$shield`). A `:` is not valid in a
+JavaScript identifier, so write `icons['check:square']()`, or
+`<tosi-icon icon="check:square">`.
+
+```html
+<tosi-icon icon="checkSquare" size="48"></tosi-icon>
+<tosi-icon icon="check:square" size="48"></tosi-icon>
+<tosi-icon icon="un:lock" size="48"></tosi-icon>
+```
+
 ### Custom rules
 
 `iconRules` is a mutable array. Each rule has a `prefix` (string or
@@ -593,6 +611,7 @@ export const defineIcons = (newIcons) => {
             if (matched == null || !canResolve(matched.baseName))
                 return false;
             return (typeof rule.prefix !== 'string' ||
+                name.includes(':') ||
                 /[A-Z]/.test(name[rule.prefix.length]));
         });
         if (readsAsRule) {