@ax-design/typed-om 0.2.1 → 0.3.0

package/README.md

@@ -54,10 +54,24 @@ binding.get('--my-color'); // [255, 0, 0, 1]
 binding.get('--my-mode'); // 'soft'
 ```
 
-Values in common forms (`12px`, `50%`, `calc(50% + 4px)`, `rgb()`, `#hex`, keywords) are parsed directly. Anything else (`calc(1em + 2px)`, `red`) goes through a hidden probe element, so the browser does the math.
+Values in common forms (`12px`, `50%`, `calc(50% + 4px)`, `rgb()`, `#hex`, `200ms`, `0.2s`, keywords) are parsed directly. Anything else (`calc(1em + 2px)`, `red`) goes through a hidden probe element, so the browser does the math.
 
 `register: true` registers the property with `CSS.registerProperty` where it exists, so your transitions on it interpolate. Where it does not exist, everything still works and transitions jump to the end value.
 
+### Times
+
+A `time` property holds a CSS `<time>` and reads as a number of milliseconds, whichever unit the author wrote:
+
+```javascript
+const schema = new StyleSchema([
+  { name: '--my-delay', syntax: { type: 'time' }, initial: '250ms', inherits: true, register: true },
+]);
+// --my-delay: 0.4s
+binding.get('--my-delay'); // 400
+```
+
+A bare number is not a time, as in CSS: `--my-delay: 400` keeps the initial value. `calc()` and other forms go through the probe like the other types.
+
 ### Watching changes
 
 ```javascript
@@ -80,3 +94,5 @@ A property can be skipped when another property makes it irrelevant, which saves
 ## Browser support
 
 Typed OM works in browsers released since 2016 that support custom properties and Shadow DOM. Keyword values cannot be CSS-wide keywords (`initial`, `inherit` and so on), and changes of a keyword to `none` are not seen by the detector.
+
+The detector sees changes of a `time` property only where `CSS.registerProperty` exists (a time can only transition as a registered property). Elsewhere `read()` still gives the right value: read again when you know it may have changed.

package/dist/detector.d.ts

@@ -6,6 +6,11 @@ export interface KeywordMirror {
     initial: string;
 }
 export declare function keywordMirrors(schema: PropertySpec[]): KeywordMirror[];
+export interface TimeMirror {
+    name: string;
+    property: string;
+}
+export declare function timeMirrors(schema: PropertySpec[]): TimeMirror[];
 export interface DetectorTemplate {
     css: string;
     elementCount: number;

package/dist/detector.js

@@ -4,7 +4,10 @@
 //  - numeric values: folded into up to four weighted calc() hashes, placed in the x and y of
 //    transform-origin and perspective-origin (neither triggers layout), 1ms transitions;
 //  - colors: one real color property each, 1ms transitions;
-//  - keywords: an animation-name list with shadow-scoped empty @keyframes per allowed value.
+//  - keywords: an animation-name list with shadow-scoped empty @keyframes per allowed value;
+//  - times: one registered <time> mirror each, 1ms transitions. A time cannot enter the numeric
+//    hash (calc() multiplies a time by numbers only), and only a registered custom property
+//    interpolates a time, so times are observed where CSS.registerProperty exists.
 // Any transition or animation start marks the host as changed.
 const HASH_SLOTS = 4;
 const COLOR_PROPERTIES = [
@@ -54,10 +57,15 @@ export function keywordMirrors(schema) {
     }
     return out;
 }
+// One registered <time> mirror per time spec, named by its position among the time specs. The
+// definition is the same for every schema (<time>, not inherited, 0s), so schemas share the names.
+export function timeMirrors(schema) {
+    return schema.filter((spec) => spec.syntax.type === 'time').map((spec, i) => ({ name: `--${PREFIX}-t${i}`, property: spec.name }));
+}
 // `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.
+// inherit them. Time specs are observed only when their time mirror is in `registered`.
 export function buildDetector(schema, registered = new Set()) {
     const mirrors = [];
     const kwMirrors = [];
@@ -111,6 +119,13 @@ export function buildDetector(schema, registered = new Set()) {
             e.transitions.push(`${COLOR_PROPERTIES[i]} 1ms`);
         });
     });
+    for (const m of timeMirrors(schema)) {
+        if (!registered.has(m.name))
+            continue;
+        const spec = schema.filter((s) => s.name === m.property)[0];
+        elements[0].decls.push(`${m.name}: var(${source(spec)}, ${spec.initial});`);
+        elements[0].transitions.push(`${m.name} 1ms`);
+    }
     const rules = [];
     const keywords = schema.filter((s) => s.syntax.type === 'keyword');
     if (keywords.length) {

package/dist/index.d.ts

@@ -1,8 +1,8 @@
 export { StyleBinding, StyleSchema } from './binding.js';
 export { attachDetector, buildDetector } from './detector.js';
 export type { DetectorHandle, DetectorTemplate } from './detector.js';
-export { parseColor, parseKeyword, parseLength, parseLengthPercentage, parseNumber } from './parse.js';
-export { probeColor, probeLengthPercentage, probeNumber } from './probe.js';
+export { parseColor, parseKeyword, parseLength, parseLengthPercentage, parseNumber, parseTime } from './parse.js';
+export { probeColor, probeLengthPercentage, probeNumber, probeTime } from './probe.js';
 export { StyleReader } from './reader.js';
 export type { ReadStats } from './reader.js';
 export { canRegister, registerProperties } from './register.js';

package/dist/index.js

@@ -1,7 +1,7 @@
 export { StyleBinding, StyleSchema } from './binding.js';
 export { attachDetector, buildDetector } from './detector.js';
-export { parseColor, parseKeyword, parseLength, parseLengthPercentage, parseNumber } from './parse.js';
-export { probeColor, probeLengthPercentage, probeNumber } from './probe.js';
+export { parseColor, parseKeyword, parseLength, parseLengthPercentage, parseNumber, parseTime } from './parse.js';
+export { probeColor, probeLengthPercentage, probeNumber, probeTime } from './probe.js';
 export { StyleReader } from './reader.js';
 export { canRegister, registerProperties } from './register.js';
 export { cssSyntax, validateSchema } from './schema.js';

package/dist/parse.d.ts

@@ -2,5 +2,6 @@ import type { LengthPercentage, Rgba } from './schema.js';
 export declare function parseNumber(text: string): number | null;
 export declare function parseLengthPercentage(text: string): LengthPercentage | null;
 export declare function parseLength(text: string): number | null;
+export declare function parseTime(text: string): number | null;
 export declare function parseKeyword(text: string, values: string[]): string | null;
 export declare function parseColor(text: string): Rgba | null;

package/dist/parse.js

@@ -30,6 +30,16 @@ export function parseLength(text) {
     const m = LENGTH.exec(text);
     return m && m[2] === 'px' ? parseFloat(m[1]) : null;
 }
+const TIME = new RegExp(`^(${NUMBER})(ms|s)$`);
+// A <time> in ms. Engines serialize computed times in seconds ("0.05s"); an unregistered value
+// comes back as written, in either unit. A bare number is not a time, as in CSS.
+export function parseTime(text) {
+    const m = TIME.exec(text);
+    if (!m)
+        return null;
+    const v = parseFloat(m[1]);
+    return m[2] === 's' ? v * 1000 : v;
+}
 export function parseKeyword(text, values) {
     return values.indexOf(text) >= 0 ? text : null;
 }

package/dist/probe.d.ts

@@ -2,3 +2,4 @@ import type { LengthPercentage, Rgba } from './schema.js';
 export declare function probeLengthPercentage(parent: Node, name: string): LengthPercentage;
 export declare function probeNumber(parent: Node, name: string): number;
 export declare function probeColor(parent: Node, name: string): Rgba | null;
+export declare function probeTime(parent: Node, name: string): number | null;

package/dist/probe.js

@@ -1,4 +1,4 @@
-import { parseColor } from './parse.js';
+import { parseColor, parseTime } from './parse.js';
 // Slow path for values the fast parsers cannot read (unregistered `calc(1em + 2px)`, named
 // colors, other units). One probe per document is moved into the shadow root that needs it,
 // so it inherits the host's custom properties, read, and removed again.
@@ -38,6 +38,7 @@ function withProbe(parent, read) {
         probe.narrow.style.marginLeft = '';
         probe.wide.style.marginLeft = '';
         probe.narrow.style.color = '';
+        probe.narrow.style.transitionDelay = '';
     }
 }
 export function probeLengthPercentage(parent, name) {
@@ -64,3 +65,14 @@ export function probeColor(parent, name) {
         return text === sentinel ? null : parseColor(text);
     });
 }
+// A time in ms, or null when the value is not a valid time. transition-delay is not inherited,
+// so an invalid value would read as its initial 0s, the same as a real 0s. The second entry of
+// the list tells them apart: an invalid var() invalidates the whole declaration, which leaves
+// one entry instead of two. Negative delays are valid, so negative times read back too.
+export function probeTime(parent, name) {
+    return withProbe(parent, (p) => {
+        p.narrow.style.transitionDelay = `var(${name}), 0s`;
+        const list = getComputedStyle(p.narrow).transitionDelay.split(',');
+        return list.length === 2 ? parseTime(list[0].trim()) : null;
+    });
+}

package/dist/reader.js

@@ -1,5 +1,5 @@
-import { parseColor, parseKeyword, parseLength, parseLengthPercentage, parseNumber } from './parse.js';
-import { probeColor, probeLengthPercentage, probeNumber } from './probe.js';
+import { parseColor, parseKeyword, parseLength, parseLengthPercentage, parseNumber, parseTime } from './parse.js';
+import { probeColor, probeLengthPercentage, probeNumber, probeTime } from './probe.js';
 // Reads the computed values of a schema from one element. Fast path: literal parsing of
 // getComputedStyle strings. Slow path: the shared probe, inserted into `probeParent`, which
 // must be inside the element's shadow root (or otherwise inherit its custom properties).
@@ -52,6 +52,8 @@ function parseFast(spec, text) {
             if (spec.syntax.keywords && spec.syntax.keywords.indexOf(text) >= 0)
                 return text;
             return parseNumber(text);
+        case 'time':
+            return parseTime(text);
         case 'color':
             if (spec.syntax.keywords && spec.syntax.keywords.indexOf(text) >= 0)
                 return text;
@@ -68,6 +70,8 @@ function parseSlow(spec, parent) {
             return probeLengthPercentage(parent, spec.name);
         case 'number':
             return probeNumber(parent, spec.name);
+        case 'time':
+            return probeTime(parent, spec.name);
         case 'color':
             return probeColor(parent, spec.name);
         case 'keyword':

package/dist/register.js

@@ -1,11 +1,12 @@
-import { keywordMirrors } from './detector.js';
+import { keywordMirrors, timeMirrors } from './detector.js';
 import { cssSyntax } from './schema.js';
 export function canRegister() {
     return typeof CSS !== 'undefined' && typeof CSS.registerProperty === 'function';
 }
 // Registers the properties that ask for it. Returns the names that are registered after the
 // call, including ones another copy of the package registered before (first registration
-// wins, so definitions must never change between versions).
+// wins, so definitions must never change between versions), and the time mirrors of the
+// detector (see timeMirrors).
 export function registerProperties(schema) {
     const registered = new Set();
     if (!canRegister())
@@ -40,5 +41,19 @@ export function registerProperties(schema) {
                 throw error;
         }
     }
+    // Time specs get a registered <time> mirror on the detector element, the only way to make a
+    // time transition (and so be observed). Same definition for every schema, like the above.
+    for (const m of timeMirrors(schema)) {
+        try {
+            css.registerProperty({ name: m.name, syntax: '<time>', inherits: false, initialValue: '0s' });
+            registered.add(m.name);
+        }
+        catch (error) {
+            if (error && error.name === 'InvalidModificationError')
+                registered.add(m.name);
+            else
+                throw error;
+        }
+    }
     return registered;
 }

package/dist/schema.d.ts

@@ -7,6 +7,8 @@ export type PropertySyntax = {
 } | {
     type: 'number';
     keywords?: string[];
+} | {
+    type: 'time';
 } | {
     type: 'color';
     keywords?: string[];

package/dist/schema.js

@@ -20,7 +20,7 @@ export function validateSchema(schema) {
         if (syntax.type === 'keyword') {
             checkKeywords(spec.name, syntax.values);
         }
-        else if (syntax.type !== 'color' && syntax.keywords) {
+        else if (syntax.type !== 'color' && syntax.type !== 'time' && 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);
@@ -35,6 +35,8 @@ export function cssSyntax(syntax) {
             return syntax.keywords && syntax.keywords.length ? `<length-percentage> | ${syntax.keywords.join(' | ')}` : '<length-percentage>';
         case 'number':
             return syntax.keywords && syntax.keywords.length ? `<number> | ${syntax.keywords.join(' | ')}` : '<number>';
+        case 'time':
+            return '<time>';
         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.2.1",
+  "version": "0.3.0",
   "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

@@ -6,7 +6,10 @@ import type { PropertySpec } from './schema.js';
 //  - numeric values: folded into up to four weighted calc() hashes, placed in the x and y of
 //    transform-origin and perspective-origin (neither triggers layout), 1ms transitions;
 //  - colors: one real color property each, 1ms transitions;
-//  - keywords: an animation-name list with shadow-scoped empty @keyframes per allowed value.
+//  - keywords: an animation-name list with shadow-scoped empty @keyframes per allowed value;
+//  - times: one registered <time> mirror each, 1ms transitions. A time cannot enter the numeric
+//    hash (calc() multiplies a time by numbers only), and only a registered custom property
+//    interpolates a time, so times are observed where CSS.registerProperty exists.
 // Any transition or animation start marks the host as changed.
 
 const HASH_SLOTS = 4;
@@ -69,6 +72,19 @@ export function keywordMirrors(schema: PropertySpec[]): KeywordMirror[] {
     return out;
 }
 
+export interface TimeMirror {
+    // Name of the registered <time> mirror on the detector element, e.g. "--ax-typed-om-t0".
+    name: string;
+    // The source custom property the mirror reflects.
+    property: string;
+}
+
+// One registered <time> mirror per time spec, named by its position among the time specs. The
+// definition is the same for every schema (<time>, not inherited, 0s), so schemas share the names.
+export function timeMirrors(schema: PropertySpec[]): TimeMirror[] {
+    return schema.filter((spec) => spec.syntax.type === 'time').map((spec, i) => ({ name: `--${PREFIX}-t${i}`, property: spec.name }));
+}
+
 export interface DetectorTemplate {
     css: string;
     elementCount: number;
@@ -77,7 +93,7 @@ export interface DetectorTemplate {
 // `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.
+// inherit them. Time specs are observed only when their time mirror is in `registered`.
 export function buildDetector(schema: PropertySpec[], registered: Set<string> = new Set()): DetectorTemplate {
     const mirrors: string[] = [];
     const kwMirrors: string[] = [];
@@ -134,6 +150,13 @@ export function buildDetector(schema: PropertySpec[], registered: Set<string> =
         });
     });
 
+    for (const m of timeMirrors(schema)) {
+        if (!registered.has(m.name)) continue;
+        const spec = schema.filter((s) => s.name === m.property)[0];
+        elements[0].decls.push(`${m.name}: var(${source(spec)}, ${spec.initial});`);
+        elements[0].transitions.push(`${m.name} 1ms`);
+    }
+
     const rules: string[] = [];
     const keywords = schema.filter((s) => s.syntax.type === 'keyword');
     if (keywords.length) {

package/src/index.ts

@@ -1,8 +1,8 @@
 export { StyleBinding, StyleSchema } from './binding.js';
 export { attachDetector, buildDetector } from './detector.js';
 export type { DetectorHandle, DetectorTemplate } from './detector.js';
-export { parseColor, parseKeyword, parseLength, parseLengthPercentage, parseNumber } from './parse.js';
-export { probeColor, probeLengthPercentage, probeNumber } from './probe.js';
+export { parseColor, parseKeyword, parseLength, parseLengthPercentage, parseNumber, parseTime } from './parse.js';
+export { probeColor, probeLengthPercentage, probeNumber, probeTime } from './probe.js';
 export { StyleReader } from './reader.js';
 export type { ReadStats } from './reader.js';
 export { canRegister, registerProperties } from './register.js';

package/src/parse.ts

@@ -35,6 +35,17 @@ export function parseLength(text: string): number | null {
     return m && m[2] === 'px' ? parseFloat(m[1]) : null;
 }
 
+const TIME = new RegExp(`^(${NUMBER})(ms|s)$`);
+
+// A <time> in ms. Engines serialize computed times in seconds ("0.05s"); an unregistered value
+// comes back as written, in either unit. A bare number is not a time, as in CSS.
+export function parseTime(text: string): number | null {
+    const m = TIME.exec(text);
+    if (!m) return null;
+    const v = parseFloat(m[1]);
+    return m[2] === 's' ? v * 1000 : v;
+}
+
 export function parseKeyword(text: string, values: string[]): string | null {
     return values.indexOf(text) >= 0 ? text : null;
 }

package/src/probe.ts

@@ -1,4 +1,4 @@
-import { parseColor } from './parse.js';
+import { parseColor, parseTime } from './parse.js';
 import type { LengthPercentage, Rgba } from './schema.js';
 
 // Slow path for values the fast parsers cannot read (unregistered `calc(1em + 2px)`, named
@@ -48,6 +48,7 @@ function withProbe<T>(parent: Node, read: (p: Probe) => T): T {
         probe.narrow.style.marginLeft = '';
         probe.wide.style.marginLeft = '';
         probe.narrow.style.color = '';
+        probe.narrow.style.transitionDelay = '';
     }
 }
 
@@ -77,3 +78,15 @@ export function probeColor(parent: Node, name: string): Rgba | null {
         return text === sentinel ? null : parseColor(text);
     });
 }
+
+// A time in ms, or null when the value is not a valid time. transition-delay is not inherited,
+// so an invalid value would read as its initial 0s, the same as a real 0s. The second entry of
+// the list tells them apart: an invalid var() invalidates the whole declaration, which leaves
+// one entry instead of two. Negative delays are valid, so negative times read back too.
+export function probeTime(parent: Node, name: string): number | null {
+    return withProbe(parent, (p) => {
+        p.narrow.style.transitionDelay = `var(${name}), 0s`;
+        const list = getComputedStyle(p.narrow).transitionDelay.split(',');
+        return list.length === 2 ? parseTime(list[0].trim()) : null;
+    });
+}

package/src/reader.ts

@@ -1,5 +1,5 @@
-import { parseColor, parseKeyword, parseLength, parseLengthPercentage, parseNumber } from './parse.js';
-import { probeColor, probeLengthPercentage, probeNumber } from './probe.js';
+import { parseColor, parseKeyword, parseLength, parseLengthPercentage, parseNumber, parseTime } from './parse.js';
+import { probeColor, probeLengthPercentage, probeNumber, probeTime } from './probe.js';
 import type { PropertySpec, PropertyValue } from './schema.js';
 
 export interface ReadStats {
@@ -62,6 +62,8 @@ function parseFast(spec: PropertySpec, text: string): PropertyValue {
         case 'number':
             if (spec.syntax.keywords && spec.syntax.keywords.indexOf(text) >= 0) return text;
             return parseNumber(text);
+        case 'time':
+            return parseTime(text);
         case 'color':
             if (spec.syntax.keywords && spec.syntax.keywords.indexOf(text) >= 0) return text;
             return parseColor(text);
@@ -78,6 +80,8 @@ function parseSlow(spec: PropertySpec, parent: Node): PropertyValue {
             return probeLengthPercentage(parent, spec.name);
         case 'number':
             return probeNumber(parent, spec.name);
+        case 'time':
+            return probeTime(parent, spec.name);
         case 'color':
             return probeColor(parent, spec.name);
         case 'keyword':

package/src/register.ts

@@ -1,4 +1,4 @@
-import { keywordMirrors } from './detector.js';
+import { keywordMirrors, timeMirrors } from './detector.js';
 import { cssSyntax } from './schema.js';
 import type { PropertySpec } from './schema.js';
 
@@ -17,7 +17,8 @@ export function canRegister(): boolean {
 
 // Registers the properties that ask for it. Returns the names that are registered after the
 // call, including ones another copy of the package registered before (first registration
-// wins, so definitions must never change between versions).
+// wins, so definitions must never change between versions), and the time mirrors of the
+// detector (see timeMirrors).
 export function registerProperties(schema: PropertySpec[]): Set<string> {
     const registered = new Set<string>();
     if (!canRegister()) return registered;
@@ -45,5 +46,16 @@ export function registerProperties(schema: PropertySpec[]): Set<string> {
             if (!error || (error as Error).name !== 'InvalidModificationError') throw error;
         }
     }
+    // Time specs get a registered <time> mirror on the detector element, the only way to make a
+    // time transition (and so be observed). Same definition for every schema, like the above.
+    for (const m of timeMirrors(schema)) {
+        try {
+            css.registerProperty!({ name: m.name, syntax: '<time>', inherits: false, initialValue: '0s' });
+            registered.add(m.name);
+        } catch (error) {
+            if (error && (error as Error).name === 'InvalidModificationError') registered.add(m.name);
+            else throw error;
+        }
+    }
     return registered;
 }

package/src/schema.ts

@@ -3,6 +3,8 @@ export type PropertySyntax =
     | { type: 'length'; keywords?: string[] }
     | { type: 'length-percentage'; keywords?: string[] }
     | { type: 'number'; keywords?: string[] }
+    // A CSS <time>, read as a number of milliseconds ("0.2s" and "200ms" are both 200).
+    | { type: 'time' }
     // `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
@@ -55,7 +57,7 @@ export function validateSchema(schema: PropertySpec[]): void {
         const syntax = spec.syntax;
         if (syntax.type === 'keyword') {
             checkKeywords(spec.name, syntax.values);
-        } else if (syntax.type !== 'color' && syntax.keywords) {
+        } else if (syntax.type !== 'color' && syntax.type !== 'time' && 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);
@@ -71,6 +73,8 @@ export function cssSyntax(syntax: PropertySyntax): string {
             return syntax.keywords && syntax.keywords.length ? `<length-percentage> | ${syntax.keywords.join(' | ')}` : '<length-percentage>';
         case 'number':
             return syntax.keywords && syntax.keywords.length ? `<number> | ${syntax.keywords.join(' | ')}` : '<number>';
+        case 'time':
+            return '<time>';
         case 'color':
             return syntax.keywords && syntax.keywords.length ? `<color> | ${syntax.keywords.join(' | ')}` : '<color>';
         case 'keyword':