@ax-design/typed-om 0.1.0 → 0.2.1

package/README.md

@@ -1,7 +1,12 @@
-<h1 align="center">Typed OM</h1>
+<h1 align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/ax-design/typed-om/master/docs/logo-r.png">
+    <img src="https://raw.githubusercontent.com/ax-design/typed-om/master/docs/logo.png" alt="Ax Typed OM">
+  </picture>
+</h1>
 
 <p align="center">
-  Typed reads and change detection of CSS custom properties for Axiom Design System, with or without CSS Typed OM.
+  Typed reads and monitors CSS custom properties for Axiom Design System.
 </p>
 
 <p align="center">

package/dist/detector.d.ts

@@ -1,4 +1,11 @@
 import type { PropertySpec } from './schema.js';
+export interface KeywordMirror {
+    name: string;
+    property: string;
+    syntax: string;
+    initial: string;
+}
+export declare function keywordMirrors(schema: PropertySpec[]): KeywordMirror[];
 export interface DetectorTemplate {
     css: string;
     elementCount: number;

package/dist/detector.js

@@ -30,13 +30,45 @@ function chunk(items, size) {
 function weight(i) {
     return (1 + i * 0.0173).toFixed(4);
 }
+// Numeric specs that may hold a keyword (e.g. "<length> | auto") would poison the numeric
+// calc() hash when the computed value is that keyword: calc(auto * 1.0000) is invalid and
+// invalidates the whole transform-origin / perspective-origin declaration. Give each such spec
+// a registered mirror with a pure numeric syntax: "auto" is rejected at computed-value time,
+// so the mirror falls back to its zero initial and the hash stays legal. Value<->keyword jumps
+// still move the hash (number -> 0), so changes keep firing.
+export function keywordMirrors(schema) {
+    const out = [];
+    let i = 0;
+    for (const spec of schema) {
+        const t = spec.syntax.type;
+        if (t !== 'length' && t !== 'length-percentage' && t !== 'number')
+            continue;
+        if (!spec.syntax.keywords || !spec.syntax.keywords.length)
+            continue;
+        out.push({
+            name: `--${PREFIX}-kw-m${i++}`,
+            property: spec.name,
+            syntax: t === 'number' ? '<number>' : t === 'length' ? '<length>' : '<length-percentage>',
+            initial: t === 'number' ? '0' : '0px',
+        });
+    }
+    return out;
+}
 // `registered` lists the properties registered by name. A registered non-inherited property
 // does not reach the detector element inside the shadow root, so the host mirrors it into an
 // unregistered (inherited) property. The slot resets the mirrors so author content does not
 // inherit them.
 export function buildDetector(schema, registered = new Set()) {
     const mirrors = [];
+    const kwMirrors = [];
+    const kwName = {};
+    for (const m of keywordMirrors(schema)) {
+        kwName[m.property] = m.name;
+        kwMirrors.push(`${m.name}: var(${m.property});`);
+    }
     const source = (spec) => {
+        if (kwName[spec.name])
+            return kwName[spec.name];
         if (!registered.has(spec.name) || spec.inherits)
             return spec.name;
         const mirror = `--${PREFIX}-m${mirrors.length}`;
@@ -52,7 +84,11 @@ export function buildDetector(schema, registered = new Set()) {
         const groups = chunk(numeric, Math.ceil(numeric.length / HASH_SLOTS));
         const hashes = groups.map((group) => `calc(${group
             .map((spec, i) => {
-            const v = `var(${source(spec)}, ${spec.initial})`;
+            const src = source(spec);
+            // The registered mirror always resolves to a number (keyword -> zero), so a
+            // keyword-capable spec's fallback is zero rather than its (keyword) initial.
+            const fallback = kwName[spec.name] ? (spec.syntax.type === 'number' ? '0' : '0px') : spec.initial;
+            const v = `var(${src}, ${fallback})`;
             return spec.syntax.type === 'number' ? `${v} * ${weight(i)}px` : `${v} * ${weight(i)}`;
         })
             .join(' + ')})`);
@@ -94,9 +130,10 @@ export function buildDetector(schema, registered = new Set()) {
         const transition = e.transitions.length ? ` transition: ${e.transitions.join(', ')};` : '';
         rules.push(`.${PREFIX}-d${i} { ${e.decls.join(' ')}${transition} }`);
     });
-    if (mirrors.length) {
-        rules.push(`:host { ${mirrors.join(' ')} }`);
-        rules.push(`slot { ${mirrors.map((m) => `${m.slice(0, m.indexOf(':'))}: initial;`).join(' ')} }`);
+    if (mirrors.length || kwMirrors.length) {
+        const all = [...mirrors, ...kwMirrors];
+        rules.push(`:host { ${all.join(' ')} }`);
+        rules.push(`slot { ${all.map((m) => `${m.slice(0, m.indexOf(':'))}: initial;`).join(' ')} }`);
     }
     rules.push(`.${PREFIX}-c { position: absolute; left: 0; top: 0; width: 1px; height: 1px; overflow: hidden; visibility: hidden; pointer-events: none; contain: strict; }`, `.${PREFIX}-c > div { position: absolute; left: 0; top: 0; width: 1px; height: 1px; }`);
     return { css: rules.join('\n'), elementCount: elements.length };

package/dist/reader.js

@@ -41,10 +41,16 @@ export class StyleReader {
 function parseFast(spec, text) {
     switch (spec.syntax.type) {
         case 'length':
+            if (spec.syntax.keywords && spec.syntax.keywords.indexOf(text) >= 0)
+                return text;
             return parseLength(text);
         case 'length-percentage':
+            if (spec.syntax.keywords && spec.syntax.keywords.indexOf(text) >= 0)
+                return text;
             return parseLengthPercentage(text);
         case 'number':
+            if (spec.syntax.keywords && spec.syntax.keywords.indexOf(text) >= 0)
+                return text;
             return parseNumber(text);
         case 'color':
             if (spec.syntax.keywords && spec.syntax.keywords.indexOf(text) >= 0)

package/dist/register.js

@@ -1,3 +1,4 @@
+import { keywordMirrors } from './detector.js';
 import { cssSyntax } from './schema.js';
 export function canRegister() {
     return typeof CSS !== 'undefined' && typeof CSS.registerProperty === 'function';
@@ -25,5 +26,19 @@ export function registerProperties(schema) {
                 throw error;
         }
     }
+    // Numeric specs that may hold a keyword get a registered mirror with a pure numeric syntax,
+    // so the keyword is rejected at computed-value time and the numeric hash stays legal. The
+    // mirror is internal (never read by the reader) and its definition is derived from the
+    // permanent schema contract, so a re-registration by another copy is the same definition.
+    for (const m of keywordMirrors(schema)) {
+        try {
+            css.registerProperty({ name: m.name, syntax: m.syntax, inherits: true, initialValue: m.initial });
+        }
+        catch (error) {
+            // Already registered by an earlier copy with the identical definition.
+            if (!error || error.name !== 'InvalidModificationError')
+                throw error;
+        }
+    }
     return registered;
 }

package/dist/schema.d.ts

@@ -1,9 +1,12 @@
 export type PropertySyntax = {
     type: 'length';
+    keywords?: string[];
 } | {
     type: 'length-percentage';
+    keywords?: string[];
 } | {
     type: 'number';
+    keywords?: string[];
 } | {
     type: 'color';
     keywords?: string[];

package/dist/schema.js

@@ -1,4 +1,12 @@
 const RESERVED = ['initial', 'inherit', 'unset', 'revert', 'revert-layer', 'default'];
+function checkKeywords(name, keywords) {
+    for (const value of keywords) {
+        if (RESERVED.indexOf(value) >= 0)
+            throw new Error(`${name}: keyword "${value}" cannot be observed`);
+        if (!/^-?[_a-zA-Z][_a-zA-Z0-9-]*$/.test(value))
+            throw new Error(`${name}: "${value}" is not an identifier`);
+    }
+}
 export function validateSchema(schema) {
     const seen = [];
     for (const spec of schema) {
@@ -8,24 +16,25 @@ export function validateSchema(schema) {
         seen.push(spec.name);
         if (spec.name.indexOf('--') !== 0)
             throw new Error(`${spec.name} is not a custom property name`);
-        if (spec.syntax.type !== 'keyword')
-            continue;
-        for (const value of spec.syntax.values) {
-            if (RESERVED.indexOf(value) >= 0)
-                throw new Error(`${spec.name}: keyword "${value}" cannot be observed`);
-            if (!/^-?[_a-zA-Z][_a-zA-Z0-9-]*$/.test(value))
-                throw new Error(`${spec.name}: "${value}" is not an identifier`);
+        const syntax = spec.syntax;
+        if (syntax.type === 'keyword') {
+            checkKeywords(spec.name, syntax.values);
+        }
+        else if (syntax.type !== 'color' && syntax.keywords) {
+            // Numeric types may hold a keyword instead of a value ("<length> | auto");
+            // validate them the same way as the keyword type. Color keywords stay unvalidated.
+            checkKeywords(spec.name, syntax.keywords);
         }
     }
 }
 export function cssSyntax(syntax) {
     switch (syntax.type) {
         case 'length':
-            return '<length>';
+            return syntax.keywords && syntax.keywords.length ? `<length> | ${syntax.keywords.join(' | ')}` : '<length>';
         case 'length-percentage':
-            return '<length-percentage>';
+            return syntax.keywords && syntax.keywords.length ? `<length-percentage> | ${syntax.keywords.join(' | ')}` : '<length-percentage>';
         case 'number':
-            return '<number>';
+            return syntax.keywords && syntax.keywords.length ? `<number> | ${syntax.keywords.join(' | ')}` : '<number>';
         case 'color':
             return syntax.keywords && syntax.keywords.length ? `<color> | ${syntax.keywords.join(' | ')}` : '<color>';
         case 'keyword':

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ax-design/typed-om",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "description": "Typed reads and change detection for CSS custom properties, for browsers with or without CSS Typed OM and @property.",
   "keywords": [
     "css",

package/src/detector.ts

@@ -35,6 +35,40 @@ function weight(i: number): string {
     return (1 + i * 0.0173).toFixed(4);
 }
 
+export interface KeywordMirror {
+    // Name of the registered mirror property, e.g. "--ax-typed-om-kw-m0".
+    name: string;
+    // The source custom property the mirror reflects.
+    property: string;
+    // Pure numeric syntax (no keywords) the mirror is registered with.
+    syntax: string;
+    // Zero initial value for that syntax.
+    initial: string;
+}
+
+// Numeric specs that may hold a keyword (e.g. "<length> | auto") would poison the numeric
+// calc() hash when the computed value is that keyword: calc(auto * 1.0000) is invalid and
+// invalidates the whole transform-origin / perspective-origin declaration. Give each such spec
+// a registered mirror with a pure numeric syntax: "auto" is rejected at computed-value time,
+// so the mirror falls back to its zero initial and the hash stays legal. Value<->keyword jumps
+// still move the hash (number -> 0), so changes keep firing.
+export function keywordMirrors(schema: PropertySpec[]): KeywordMirror[] {
+    const out: KeywordMirror[] = [];
+    let i = 0;
+    for (const spec of schema) {
+        const t = spec.syntax.type;
+        if (t !== 'length' && t !== 'length-percentage' && t !== 'number') continue;
+        if (!spec.syntax.keywords || !spec.syntax.keywords.length) continue;
+        out.push({
+            name: `--${PREFIX}-kw-m${i++}`,
+            property: spec.name,
+            syntax: t === 'number' ? '<number>' : t === 'length' ? '<length>' : '<length-percentage>',
+            initial: t === 'number' ? '0' : '0px',
+        });
+    }
+    return out;
+}
+
 export interface DetectorTemplate {
     css: string;
     elementCount: number;
@@ -46,7 +80,14 @@ export interface DetectorTemplate {
 // inherit them.
 export function buildDetector(schema: PropertySpec[], registered: Set<string> = new Set()): DetectorTemplate {
     const mirrors: string[] = [];
+    const kwMirrors: string[] = [];
+    const kwName: { [name: string]: string } = {};
+    for (const m of keywordMirrors(schema)) {
+        kwName[m.property] = m.name;
+        kwMirrors.push(`${m.name}: var(${m.property});`);
+    }
     const source = (spec: PropertySpec) => {
+        if (kwName[spec.name]) return kwName[spec.name];
         if (!registered.has(spec.name) || spec.inherits) return spec.name;
         const mirror = `--${PREFIX}-m${mirrors.length}`;
         mirrors.push(`${mirror}: var(${spec.name});`);
@@ -64,7 +105,11 @@ export function buildDetector(schema: PropertySpec[], registered: Set<string> =
         const hashes = groups.map((group) =>
             `calc(${group
                 .map((spec, i) => {
-                    const v = `var(${source(spec)}, ${spec.initial})`;
+                    const src = source(spec);
+                    // The registered mirror always resolves to a number (keyword -> zero), so a
+                    // keyword-capable spec's fallback is zero rather than its (keyword) initial.
+                    const fallback = kwName[spec.name] ? (spec.syntax.type === 'number' ? '0' : '0px') : spec.initial;
+                    const v = `var(${src}, ${fallback})`;
                     return spec.syntax.type === 'number' ? `${v} * ${weight(i)}px` : `${v} * ${weight(i)}`;
                 })
                 .join(' + ')})`
@@ -106,9 +151,10 @@ export function buildDetector(schema: PropertySpec[], registered: Set<string> =
         const transition = e.transitions.length ? ` transition: ${e.transitions.join(', ')};` : '';
         rules.push(`.${PREFIX}-d${i} { ${e.decls.join(' ')}${transition} }`);
     });
-    if (mirrors.length) {
-        rules.push(`:host { ${mirrors.join(' ')} }`);
-        rules.push(`slot { ${mirrors.map((m) => `${m.slice(0, m.indexOf(':'))}: initial;`).join(' ')} }`);
+    if (mirrors.length || kwMirrors.length) {
+        const all = [...mirrors, ...kwMirrors];
+        rules.push(`:host { ${all.join(' ')} }`);
+        rules.push(`slot { ${all.map((m) => `${m.slice(0, m.indexOf(':'))}: initial;`).join(' ')} }`);
     }
     rules.push(
         `.${PREFIX}-c { position: absolute; left: 0; top: 0; width: 1px; height: 1px; overflow: hidden; visibility: hidden; pointer-events: none; contain: strict; }`,

package/src/reader.ts

@@ -54,10 +54,13 @@ export class StyleReader {
 function parseFast(spec: PropertySpec, text: string): PropertyValue {
     switch (spec.syntax.type) {
         case 'length':
+            if (spec.syntax.keywords && spec.syntax.keywords.indexOf(text) >= 0) return text;
             return parseLength(text);
         case 'length-percentage':
+            if (spec.syntax.keywords && spec.syntax.keywords.indexOf(text) >= 0) return text;
             return parseLengthPercentage(text);
         case 'number':
+            if (spec.syntax.keywords && spec.syntax.keywords.indexOf(text) >= 0) return text;
             return parseNumber(text);
         case 'color':
             if (spec.syntax.keywords && spec.syntax.keywords.indexOf(text) >= 0) return text;

package/src/register.ts

@@ -1,3 +1,4 @@
+import { keywordMirrors } from './detector.js';
 import { cssSyntax } from './schema.js';
 import type { PropertySpec } from './schema.js';
 
@@ -32,5 +33,17 @@ export function registerProperties(schema: PropertySpec[]): Set<string> {
             else throw error;
         }
     }
+    // Numeric specs that may hold a keyword get a registered mirror with a pure numeric syntax,
+    // so the keyword is rejected at computed-value time and the numeric hash stays legal. The
+    // mirror is internal (never read by the reader) and its definition is derived from the
+    // permanent schema contract, so a re-registration by another copy is the same definition.
+    for (const m of keywordMirrors(schema)) {
+        try {
+            css.registerProperty!({ name: m.name, syntax: m.syntax, inherits: true, initialValue: m.initial });
+        } catch (error) {
+            // Already registered by an earlier copy with the identical definition.
+            if (!error || (error as Error).name !== 'InvalidModificationError') throw error;
+        }
+    }
     return registered;
 }

package/src/schema.ts

@@ -1,8 +1,8 @@
 // Description of one custom property the caller wants to read and observe.
 export type PropertySyntax =
-    | { type: 'length' }
-    | { type: 'length-percentage' }
-    | { type: 'number' }
+    | { type: 'length'; keywords?: string[] }
+    | { type: 'length-percentage'; keywords?: string[] }
+    | { type: 'number'; keywords?: string[] }
     // `keywords`: extra identifiers the property may hold instead of a color (returned as strings).
     | { type: 'color'; keywords?: string[] }
     // Allowed values. CSS-wide keywords are rejected. `none` is allowed for existing APIs, but
@@ -37,6 +37,13 @@ export type PropertyValue = LengthPercentage | number | string | Rgba | null;
 
 const RESERVED = ['initial', 'inherit', 'unset', 'revert', 'revert-layer', 'default'];
 
+function checkKeywords(name: string, keywords: string[]): void {
+    for (const value of keywords) {
+        if (RESERVED.indexOf(value) >= 0) throw new Error(`${name}: keyword "${value}" cannot be observed`);
+        if (!/^-?[_a-zA-Z][_a-zA-Z0-9-]*$/.test(value)) throw new Error(`${name}: "${value}" is not an identifier`);
+    }
+}
+
 export function validateSchema(schema: PropertySpec[]): void {
     const seen: string[] = [];
     for (const spec of schema) {
@@ -45,10 +52,13 @@ export function validateSchema(schema: PropertySpec[]): void {
         }
         seen.push(spec.name);
         if (spec.name.indexOf('--') !== 0) throw new Error(`${spec.name} is not a custom property name`);
-        if (spec.syntax.type !== 'keyword') continue;
-        for (const value of spec.syntax.values) {
-            if (RESERVED.indexOf(value) >= 0) throw new Error(`${spec.name}: keyword "${value}" cannot be observed`);
-            if (!/^-?[_a-zA-Z][_a-zA-Z0-9-]*$/.test(value)) throw new Error(`${spec.name}: "${value}" is not an identifier`);
+        const syntax = spec.syntax;
+        if (syntax.type === 'keyword') {
+            checkKeywords(spec.name, syntax.values);
+        } else if (syntax.type !== 'color' && syntax.keywords) {
+            // Numeric types may hold a keyword instead of a value ("<length> | auto");
+            // validate them the same way as the keyword type. Color keywords stay unvalidated.
+            checkKeywords(spec.name, syntax.keywords);
         }
     }
 }
@@ -56,11 +66,11 @@ export function validateSchema(schema: PropertySpec[]): void {
 export function cssSyntax(syntax: PropertySyntax): string {
     switch (syntax.type) {
         case 'length':
-            return '<length>';
+            return syntax.keywords && syntax.keywords.length ? `<length> | ${syntax.keywords.join(' | ')}` : '<length>';
         case 'length-percentage':
-            return '<length-percentage>';
+            return syntax.keywords && syntax.keywords.length ? `<length-percentage> | ${syntax.keywords.join(' | ')}` : '<length-percentage>';
         case 'number':
-            return '<number>';
+            return syntax.keywords && syntax.keywords.length ? `<number> | ${syntax.keywords.join(' | ')}` : '<number>';
         case 'color':
             return syntax.keywords && syntax.keywords.length ? `<color> | ${syntax.keywords.join(' | ')}` : '<color>';
         case 'keyword':