@ng-native/fabric 0.1.2 → 0.1.3

package/README.md

@@ -49,7 +49,7 @@ const platform = nativePlatform(); // 'ios' | 'android'
   [what CSS reaches a device](https://ng-native.com/packages/fabric/supported-css) and
   [animation](https://ng-native.com/packages/fabric/animation)
 - [Root README](https://github.com/ng-native/ng-native/blob/main/README.md) and
-  [ARCHITECTURE.md](https://github.com/ng-native/ng-native/blob/main/ARCHITECTURE.md)
+  [ARCHITECTURE.md](https://github.com/ng-native/ng-native/blob/main/docs/ARCHITECTURE.md)
 
 ## License
 

package/dist/css.d.ts

@@ -125,15 +125,24 @@ export interface TokenValue {
     readonly transform?: readonly unknown[];
     /** One font variant, as the one-entry list `fontVariant` takes: a numeric variant's slot. */
     readonly fontVariant?: readonly string[];
-    /** Bare colour channels, `13, 110, 253`, for an `rgba(var(--x), <alpha>)` to finish. */
+    /** Bare colour channels as `rgb()` reads them, 0 to 255: `13, 110, 253` or `100% 0% 0%`. */
     readonly channels?: readonly number[];
+    /** The same as `hsl()` reads them: degrees, then saturation and lightness as fractions. */
+    readonly hslChannels?: readonly number[];
+    /** A transition's curve, as the cubic-bezier control points a timing keyword stands for. */
+    readonly easing?: readonly number[];
+    /** A whole animation, as the spec the engine plays: `--animate-spin`. */
+    readonly animation?: Readonly<Record<string, unknown>>;
     /**
-     * Defined as `rgba(var(--channels), <alpha>)`: a colour made of a channels token and an alpha
-     * written or tokened. Settled on the node that defines it, as an `hsl` one is.
+     * Defined as a colour made of other tokens: `rgba(var(--channels), <alpha>)`, or a `color-mix()`
+     * of one. Settled on the node that defines it, as an `hsl` one is.
      */
-    readonly deferredColour?: Extract<ColourExpression, {
-        channels: unknown;
-    }>;
+    readonly deferredColour?: ColourExpression;
+    /**
+     * Defined as arithmetic of other tokens, `calc(var(--spacing) * 4)`, read as a length and as a
+     * number. Settled on the node that defines it, as an `hsl` one is.
+     */
+    readonly deferredCalc?: readonly CalcMarker[];
     /**
      * Defined as another token, `var(--name)`. Resolved on the node that defines it, against the
      * tokens in scope there, and passed down resolved - which is what a browser does.
@@ -159,7 +168,7 @@ export type HslChannel = number | {
     readonly fallback?: number;
 };
 /** The forms a token can be read in: one per kind of value a use site can need. */
-export type TokenKind = 'length' | 'color' | 'keyword' | 'number' | 'weight' | 'family' | 'lineHeight' | 'shadow' | 'filter' | 'transform' | 'fontVariant' | 'channels';
+export type TokenKind = 'length' | 'color' | 'keyword' | 'number' | 'weight' | 'family' | 'lineHeight' | 'shadow' | 'filter' | 'transform' | 'fontVariant' | 'channels' | 'hslChannels' | 'easing' | 'time' | 'animation';
 export interface DeferredDeclaration {
     /**
      * The React Native style properties this lands in. Usually one, but a four-sided shorthand is
@@ -194,6 +203,8 @@ export interface DeferredDeclaration {
         readonly reference: string;
         readonly fallback?: number;
     };
+    /** For a colour built from `channels`, read through `hsl()` rather than `rgb()`. */
+    readonly space?: ChannelSpace;
     /**
      * A gradient whose stops are custom properties, filled in once a node's tokens are known. What
      * a utility framework's `from-*` and `to-*` classes compile to, since the class that paints the
@@ -247,6 +258,7 @@ export type ColourExpression = {
     readonly channels: {
         readonly reference: string;
         readonly fallback?: readonly number[];
+        readonly space?: ChannelSpace;
     };
     readonly alpha?: number | {
         readonly reference: string;
@@ -314,12 +326,18 @@ export interface StyleSheet {
      * has to re-resolve a whole child list when it changes. It only does that where a sheet asks.
      */
     readonly structural?: true;
+    /**
+     * The `@font-face` rules the sheet declares, each `source` the bundler's `require` of the file.
+     * The engine does not read them: `loadFonts()` in `@ng-native/expo/fonts` registers them with
+     * the platform before mount.
+     */
+    readonly fonts?: readonly {
+        readonly family: string;
+        readonly source: unknown;
+        readonly weight?: number;
+        readonly style?: string;
+    }[];
 }
-/**
- * What one node resolved to. `style` is what it renders with; `inherited` is what its children
- * start from, which is the parent's own `inherited` plus whatever inheritable values this node
- * set. Keeping the two apart is what lets resolution go downwards.
- */
 export interface StyleCache {
     epoch: number;
     /**
@@ -560,7 +578,26 @@ export declare class StyleResolver {
      * survives and a later sheet wins equal weight.
      */
     private merge;
-    /** The declarations that apply to a node. The list is sorted, so later simply wins. */
+    /**
+     * A node's style from the rules it matched, shared with every other node that matched the same
+     * rules under the same inherited values and tokens: a list's rows, and what is inside each.
+     *
+     * Everything past matching depends on those alone, and it is most of the work where a sheet
+     * leaves values to the device: settling each `var()`, mixing colours, filling a shadow's slots.
+     * A node that sets custom properties of its own is worked out alone. What is shared is never
+     * written to after, so sharing it is safe; each node still has a cache and a context of its own.
+     */
+    private styled;
+    private readonly shared;
+    private sharedGeneration;
+    private readonly ruleIds;
+    private nextRuleId;
+    private ruleId;
+    /** A node's style from the rules it matched, worked out. */
+    private style;
+    /** The rules that apply to a node, weakest first. */
+    private matched;
+    /** The declarations of the rules a node matched. The list is sorted, so later simply wins. */
     private cascade;
     /**
      * Whether a rule's media query holds, memoised per rule.
@@ -601,6 +638,20 @@ export declare class StyleResolver {
     /** A length relative to the viewport or to the font size in scope. */
     private computed;
 }
+/** `hsl()` reads a channels token as hue, saturation and lightness; `rgb()` as sRGB. */
+type ChannelSpace = 'rgb' | 'hsl';
+/**
+ * Arithmetic with tokens in it, as the compiler leaves it: numbers, token references and
+ * `[op, a, b]`, in points, degrees or plain numbers as the slot it fills counts.
+ */
+type CalcExpression = number | {
+    readonly reference: string;
+    readonly fallback?: number;
+} | readonly ['+' | '-' | '*' | '/' | 'max' | 'min', CalcExpression, CalcExpression];
+interface CalcMarker {
+    readonly expression: CalcExpression;
+    readonly kind: 'length' | 'angle' | 'time' | 'number';
+}
 /**
  * Where a component's compiled sheet lives: a static on the component class, written by the
  * Metro transformer at build time.

package/dist/css.js

@@ -594,25 +594,15 @@ export class StyleResolver {
             return this.unstyled(node, epoch, parent, parentContext, parentInherited);
         }
         styleStats.nodesResolved++;
-        const result = this.cascade(node, this.rulesFor(node));
-        // Tokens are in scope for this node's own declarations as well as its descendants', so they
-        // are merged before any `var()` here is resolved.
+        const matched = this.matched(node, this.rulesFor(node));
         const parentTokens = parent ? parent.tokens : this.tokensOnRoot;
-        const tokens = tokensInScope(parentTokens, result.tokens, node.customProperties);
-        const own = result.declarations;
-        if (result.deferred) {
-            this.applyDeferred(result.deferred, own, tokens, parentInherited, result.important);
-        }
-        if (own['borderStyle'] === 'none')
-            drawNoBorder(own);
+        const styled = this.styled(node, matched, parentTokens, parentInherited);
         const cache = {
             epoch,
             generation: this.generation,
             context: {},
             parentContext,
-            style: { ...parentInherited, ...own },
-            inherited: inheritFrom(parentInherited, own),
-            tokens,
+            ...styled,
         };
         node.styleCache = cache;
         node.styleDirty = false;
@@ -713,16 +703,81 @@ export class StyleResolver {
         add(sheet, COMPONENT_SPECIFICITY_BUMP);
         return entries.sort((a, b) => a.weight - b.weight);
     }
-    /** The declarations that apply to a node. The list is sorted, so later simply wins. */
-    cascade(node, entries) {
+    /**
+     * A node's style from the rules it matched, shared with every other node that matched the same
+     * rules under the same inherited values and tokens: a list's rows, and what is inside each.
+     *
+     * Everything past matching depends on those alone, and it is most of the work where a sheet
+     * leaves values to the device: settling each `var()`, mixing colours, filling a shadow's slots.
+     * A node that sets custom properties of its own is worked out alone. What is shared is never
+     * written to after, so sharing it is safe; each node still has a cache and a context of its own.
+     */
+    styled(node, matched, parentTokens, parentInherited) {
+        if (node.customProperties)
+            return this.style(node, matched, parentTokens, parentInherited);
+        if (this.sharedGeneration !== this.generation) {
+            this.shared.clear();
+            this.sharedGeneration = this.generation;
+        }
+        const key = matched.map((rule) => this.ruleId(rule)).join(',');
+        let byTokens = this.shared.get(key);
+        if (!byTokens)
+            this.shared.set(key, (byTokens = new WeakMap()));
+        let byInherited = byTokens.get(parentTokens);
+        if (!byInherited)
+            byTokens.set(parentTokens, (byInherited = new WeakMap()));
+        let styled = byInherited.get(parentInherited);
+        if (!styled) {
+            styled = this.style(node, matched, parentTokens, parentInherited);
+            byInherited.set(parentInherited, styled);
+        }
+        return styled;
+    }
+    shared = new Map();
+    sharedGeneration = 0;
+    ruleIds = new WeakMap();
+    nextRuleId = 0;
+    ruleId(rule) {
+        let id = this.ruleIds.get(rule);
+        if (id === undefined)
+            this.ruleIds.set(rule, (id = this.nextRuleId++));
+        return id;
+    }
+    /** A node's style from the rules it matched, worked out. */
+    style(node, matched, parentTokens, parentInherited) {
+        const result = this.cascade(matched);
+        // Tokens are in scope for this node's own declarations as well as its descendants', so they
+        // are merged before any `var()` here is resolved.
+        const tokens = tokensInScope(parentTokens, result.tokens, node.customProperties);
+        const own = result.declarations;
+        if (result.deferred) {
+            this.applyDeferred(result.deferred, own, tokens, parentInherited, result.important);
+        }
+        if (own['borderStyle'] === 'none')
+            drawNoBorder(own);
+        return {
+            style: { ...parentInherited, ...own },
+            inherited: inheritFrom(parentInherited, own),
+            tokens,
+        };
+    }
+    /** The rules that apply to a node, weakest first. */
+    matched(node, entries) {
+        const out = [];
+        for (const { rule, sheet } of entries) {
+            if (this.conditionHolds(rule) && matches(node, rule, sheet))
+                out.push(rule);
+        }
+        return out;
+    }
+    /** The declarations of the rules a node matched. The list is sorted, so later simply wins. */
+    cascade(matched) {
         const normal = {};
         const important = {};
         let hasImportant = false;
         let tokens = null;
         let deferred = null;
-        for (const { rule, sheet } of entries) {
-            if (!this.conditionHolds(rule) || !matches(node, rule, sheet))
-                continue;
+        for (const rule of matched) {
             Object.assign(normal, rule.declarations);
             if (rule.important) {
                 Object.assign(important, rule.important);
@@ -917,7 +972,10 @@ export class StyleResolver {
         const base = declaration.props.includes('fontSize')
             ? parentInherited['fontSize']
             : (own['fontSize'] ?? parentInherited['fontSize']);
-        return factor * (typeof base === 'number' ? base : DEFAULT_FONT_SIZE) + offset;
+        // To a thousandth of a point: a factor rounded at build time, times a font size, is otherwise
+        // 19.99998 where the web draws 20.
+        const points = factor * (typeof base === 'number' ? base : DEFAULT_FONT_SIZE) + offset;
+        return Math.round(points * 1000) / 1000;
     }
 }
 /**
@@ -957,26 +1015,57 @@ function tokensInScope(parentTokens, ruleTokens, custom) {
 }
 function resolveAliases(own, merged) {
     const names = Object.keys(own);
-    for (const name of names) {
-        if (own[name].alias)
-            settle(merged, name, followAlias(name, merged, new Set()));
-    }
-    for (const name of names) {
-        const { hsl, deferredColour } = own[name];
-        if (hsl)
-            settle(merged, name, colourToken(resolveHsl(hsl, merged)));
-        if (deferredColour)
-            settle(merged, name, colourToken(channelsColour(deferredColour, merged)));
+    const aliases = names.filter((name) => own[name].alias);
+    followAliases(aliases, merged);
+    // Until a pass settles nothing more: one made of another defined after it, or of one not yet
+    // settled, cannot be worked out until that one is. What is left then is a cycle, or reads a
+    // token that is not there, and is unset.
+    const derivedNames = names.filter((name) => isDerived(own[name]));
+    let pending = derivedNames;
+    for (let settled = true; settled && pending.length;) {
+        settled = false;
+        pending = pending.filter((name) => {
+            const value = derived(own[name], merged);
+            if (!value)
+                return true;
+            merged[name] = value;
+            settled = true;
+            return false;
+        });
     }
-    // An alias to one of those copied it unsettled above: follow it again, now it is a colour.
-    for (const name of names) {
-        const target = own[name].alias;
-        if (!target || !(own[target]?.hsl || own[target]?.deferredColour))
-            continue;
-        settle(merged, name, followAlias(name, { ...merged, [name]: own[name] }, new Set()));
+    for (const name of pending)
+        delete merged[name];
+    // A chain that ends at one of those, by a link or a fallback, copied it unsettled above into
+    // every alias on the way: follow them all again, from what they were defined as, now it is.
+    if (derivedNames.length && aliases.length) {
+        for (const name of aliases)
+            merged[name] = own[name];
+        followAliases(aliases, merged);
     }
     return merged;
 }
+/** Whether a token is made of others, and so worked out where it is defined. */
+function isDerived(token) {
+    return Boolean(token?.hsl || token?.deferredColour || token?.deferredCalc);
+}
+/** A token made of others, worked out from the tokens in scope. */
+function derived(token, tokens) {
+    if (token.hsl)
+        return colourToken(resolveHsl(token.hsl, tokens));
+    if (token.deferredColour)
+        return colourToken(resolveColour(token.deferredColour, tokens));
+    return calcToken(token.deferredCalc, tokens);
+}
+/**
+ * Each alias settled to what it names. `follow` writes back every one that resolves; one in a
+ * cycle is removed only once all are followed, as removed any sooner, the next one round the
+ * cycle would find it unset and take its own fallback.
+ */
+function followAliases(aliases, merged) {
+    const cyclic = aliases.filter((name) => typeof follow(name, merged, []) === 'number');
+    for (const name of cyclic)
+        delete merged[name];
+}
 /** A token set to what it resolved to, or removed when it resolved to nothing, as CSS unsets it. */
 function settle(merged, name, value) {
     if (value)
@@ -985,6 +1074,20 @@ function settle(merged, name, value) {
         delete merged[name];
 }
 const colourToken = (color) => color === undefined ? undefined : { color };
+/** A `calc()` token's forms, from the tokens in scope: undefined when it makes neither. */
+function calcToken(markers, tokens) {
+    let token;
+    for (const marker of markers) {
+        const value = resolveCalc(marker, tokens);
+        if (value === undefined)
+            continue;
+        if (marker.kind === 'length')
+            token = { ...token, length: value };
+        else if (typeof value === 'number')
+            token = { ...token, number: value };
+    }
+    return token;
+}
 /** An `hsl()` token's channels, read from the tokens in scope, as the colour they make. */
 function resolveHsl(hsl, tokens) {
     const h = hslChannel(hsl.h, tokens);
@@ -1031,14 +1134,36 @@ function hslToRgb(h, s, l, alpha) {
         ? `rgb(${r}, ${g}, ${b})`
         : `rgba(${r}, ${g}, ${b}, ${Math.round(alpha * 1000) / 1000})`;
 }
-function followAlias(name, tokens, seen) {
+/**
+ * A token with its `var()` substituted, through as many aliases and fallbacks as it takes.
+ *
+ * `path` is the aliases being followed on the way here. A number is a cycle, and the index in
+ * `path` where it starts: every property from there on is in it and invalid at computed-value
+ * time, so none of them takes its fallback, while one before it names an invalid property and
+ * does. Anything else is final wherever the chain started, so it is written back to `tokens`, and
+ * no alias is followed twice.
+ */
+function follow(name, tokens, path) {
     const value = tokens[name];
     if (!value?.alias)
         return value;
-    if (seen.has(name))
-        return undefined;
-    seen.add(name);
-    return followAlias(value.alias, tokens, seen) ?? value.fallback;
+    const start = path.indexOf(name);
+    if (start >= 0)
+        return start;
+    const depth = path.push(name) - 1;
+    const result = substituted(value, tokens, path, depth);
+    path.pop();
+    if (typeof result !== 'number')
+        settle(tokens, name, result);
+    return result;
+}
+/** An alias's target, or its fallback, which may be another `var()`, when the target is unset. */
+function substituted(value, tokens, path, depth) {
+    const target = follow(value.alias, tokens, path);
+    if (typeof target === 'object' || (typeof target === 'number' && target <= depth))
+        return target;
+    const { fallback } = value;
+    return fallback?.alias ? substituted(fallback, tokens, path, depth) : fallback;
 }
 /** What a `var()` resolves to: a gradient's stops, or one value with its arithmetic applied. */
 function referenced(declaration, tokens) {
@@ -1056,17 +1181,25 @@ function referenced(declaration, tokens) {
         value = formOf(tokens[alternative], declaration.kind);
     }
     value ??= declaration.fallback;
-    const base = declaration.kind === 'channels' ? fromChannels(value, declaration.alpha, tokens) : value;
+    const base = CHANNEL_KINDS.has(declaration.kind)
+        ? fromChannels(value, declaration.alpha, tokens, declaration.space)
+        : value;
     return declaration.adjust ? adjusted(base, declaration.adjust) : base;
 }
-/** `13, 110, 253` as the colour it is, at the alpha the token beside it says, if one does. */
-function fromChannels(value, alpha, tokens) {
+const CHANNEL_KINDS = new Set(['channels', 'hslChannels']);
+/**
+ * `13, 110, 253` as the colour it is, at the alpha the token beside it says, if one does: the
+ * channels form for `rgb()`, the hslChannels form for `hsl()`.
+ */
+function fromChannels(value, alpha, tokens, space) {
     if (!Array.isArray(value) || value.length !== 3)
         return undefined;
     // An alpha naming a token nothing set, with no fallback, is no colour: CSS drops it.
     const opacity = alpha ? (tokens[alpha.reference]?.number ?? alpha.fallback) : 1;
     if (opacity === undefined)
         return undefined;
+    if (space === 'hsl')
+        return hslToRgb(value[0], value[1], value[2], opacity);
     const [r, g, b] = value;
     return opacity >= 1
         ? `rgb(${r}, ${g}, ${b})`
@@ -1236,6 +1369,10 @@ function calculated(expression, kind, tokens) {
         return left - right;
     if (op === '*')
         return left * right;
+    if (op === 'max')
+        return Math.max(left, right);
+    if (op === 'min')
+        return Math.min(left, right);
     return left / right;
 }
 /** Where each kind of slot reads a token from, before its bare number. */
@@ -1328,17 +1465,34 @@ function settledMarker(value, tokens) {
     const sum = value.__calc;
     if (sum)
         return resolveCalc(sum, tokens);
+    const shadow = value.__dropShadow;
+    if (shadow)
+        return dropShadowOf(tokens[shadow.reference]?.shadow);
     return NOT_A_MARKER;
 }
+/**
+ * A shadow token as the drop shadow a filter draws: `drop-shadow(var(--drop-shadow-xs))`. One
+ * shadow, never inset and with no spread, which is all a drop shadow can be; nothing otherwise.
+ */
+function dropShadowOf(shadow) {
+    if (!Array.isArray(shadow) || shadow.length !== 1)
+        return undefined;
+    const [{ offsetX, offsetY, blurRadius, spreadDistance, color, inset }] = shadow;
+    if (spreadDistance !== 0 || inset || typeof color !== 'string')
+        return undefined;
+    return { offsetX, offsetY, standardDeviation: blurRadius, color };
+}
 /** What a colour that cannot be settled makes of the whole value it is in. */
 const UNSETTLED = Symbol('unsettled');
 /** `rgba(var(--channels), <alpha>)`: the token's channels, at the alpha written or tokened. */
 function channelsColour(expression, tokens) {
-    const value = formOf(tokens[expression.channels.reference], 'channels') ?? expression.channels.fallback;
+    const { space } = expression.channels;
+    const kind = space === 'hsl' ? 'hslChannels' : 'channels';
+    const value = formOf(tokens[expression.channels.reference], kind) ?? expression.channels.fallback;
     const { alpha } = expression;
     if (typeof alpha !== 'number')
-        return fromChannels(value, alpha, tokens);
-    const opaque = fromChannels(value, undefined, tokens);
+        return fromChannels(value, alpha, tokens, space);
+    const opaque = fromChannels(value, undefined, tokens, space);
     return opaque === undefined ? undefined : faded(opaque, alpha);
 }
 /** A token's colour, or the first of its alternatives that is defined, or its fallback. */
@@ -1364,11 +1518,20 @@ function colourMarker(value) {
 function adjusted(value, adjust) {
     if (adjust.alpha !== undefined)
         return faded(value, adjust.alpha);
+    const em = value?.__defer;
+    if (em && adjust.floor === undefined)
+        return adjustedEm(em, adjust);
     if (typeof value !== 'number')
         return value;
     const scaled = value * (adjust.scale ?? 1) + (adjust.offset ?? 0);
     return adjust.floor === undefined ? scaled : Math.max(scaled, adjust.floor);
 }
+/** A length in em, worked out against the font size later, with the arithmetic moved inside it. */
+function adjustedEm(em, adjust) {
+    const scale = adjust.scale ?? 1;
+    const offset = (em.offset ?? 0) * scale + (adjust.offset ?? 0);
+    return { __defer: { ...em, factor: em.factor * scale, ...(offset ? { offset } : {}) } };
+}
 /** `rgb(r, g, b)` and `rgba(r, g, b, a)`, which is every colour the compiler emits. */
 const RGB = /^rgba?\(\s*([\d.]+)\s*,\s*([\d.]+)\s*,\s*([\d.]+)\s*(?:,\s*([\d.]+)\s*)?\)$/;
 /**