@ng-native/fabric 0.1.1 → 0.1.3

package/dist/engine.d.ts

@@ -1,6 +1,6 @@
 /**
  * Framework-agnostic retained tree + incremental Fabric commit.
- * Nothing Angular-specific may enter this file; lint bans the import (see ARCHITECTURE.md).
+ * Nothing Angular-specific may enter this file; lint bans the import (see docs/ARCHITECTURE.md).
  *
  * Angular mutates; Fabric is persistent. A committed node is never mutated, it is cloned with
  * new props and/or a new child set. Cloning a leaf therefore forces every ancestor to re-clone,
@@ -284,6 +284,14 @@ export interface PlatformViewName {
     readonly ios: string;
     readonly android: string;
 }
+/** Hear about faces registering with the platform, until the returned function is called. */
+export declare function onFontsRegistered(listener: (families: ReadonlySet<string>) => void): () => void;
+/**
+ * Faces just registered with the platform, by the family names text asks for them by. Every
+ * mounted app lays out again the paragraphs and text inputs that name one: see
+ * `Engine.fontsRegistered`.
+ */
+export declare function fontsRegistered(families: Iterable<string>): void;
 /**
  * Commit every `elementName` as a direct child of its nearest `ancestorName`, wherever the
  * template put it, e.g. `registerHoist('native-header', 'screen')`.
@@ -503,6 +511,29 @@ export declare class Engine implements HostEngine {
      * which is what makes Fabric dirty a measured node and measure it at the size now in effect.
      */
     remeasureText(): void;
+    /** Whether any text has been laid out again for a face. See `fontsRegistered`. */
+    private fontsRefreshed;
+    /** How many times each paragraph or text input has been laid out again for a face. */
+    private readonly fontRefreshes;
+    /** The text inputs whose `fontFamily` the next commit sends again. See `fontsRegistered`. */
+    private readonly fontResends;
+    /**
+     * Faces registered after text naming them was laid out: lay that text out again, and commit.
+     *
+     * Native keeps a paragraph's text layout, face included, keyed by what the paragraph asks for.
+     * iOS caches the attributed string it built and the size it measured, so text laid out before
+     * its face registered stays in the fallback face, and committing it again unchanged hits the
+     * same cache. What it asks for has to change, and nothing visible can: each paragraph naming
+     * one of the families is committed with its text size cap raised by a step too small to see, or
+     * set far above any size the platform offers where it had none. Its view, and everything native
+     * holds for it, stays where it is. Android keys its text layout the same way and applies the
+     * cap the same way, so the same change works there.
+     *
+     * A text input takes its font another way. iOS sets it on the field again only when the input's
+     * text attributes change, which the same cap does. Android sets it only when `fontFamily` is in
+     * the props it is sent, and the engine sends only what changed, so it is sent again once.
+     */
+    fontsRegistered(families: ReadonlySet<string>): void;
     /**
      * Put the cursor in a text input; bring anything else on screen, in the scroll view it is in.
      * A form sends the user to the first field that needs fixing this way, and a toggle or a picker
@@ -661,6 +692,13 @@ export declare class Engine implements HostEngine {
      * unrelated change.
      */
     private mergeProps;
+    /**
+     * The text size cap that lays a paragraph or text input out again once a face it names has
+     * registered: a step per face above the app's own cap where it set one (below 1 is none, on
+     * both platforms), or above any text size there is. Counted per view, so an app's cap moves by
+     * a step for each face its text names and no further. See `fontsRegistered`.
+     */
+    private capForFonts;
     /** Set once any node has had a `direction` in its inline style. See `directionOf`. */
     private inlineDirection;
     /**
@@ -681,8 +719,21 @@ export declare class Engine implements HostEngine {
      * A property seen for the first time is recorded and left alone. That is CSS's own rule, and
      * without it every element would fade in from whatever the previous value happened to be.
      */
-    /** Take a sheet's `@keyframes` into the registry. Cheap and idempotent; sheets are few. */
-    private registerKeyframes;
+    /**
+     * Take a sheet's `@keyframes` and `@font-face` rules into the registries. Cheap and idempotent;
+     * sheets are few.
+     */
+    private registerSheet;
+    /** Every `@font-face` seen, global as on the web: a face declared in one sheet serves all. */
+    private readonly fontFaces;
+    /** Whether a sheet first used in this commit declared a face. See `rematchFonts`. */
+    private facesAdded;
+    /**
+     * Faces a sheet declared partway through a commit: text resolved before it, in this commit or
+     * an earlier one, matched without them. Resolve every text naming a family again, and commit.
+     * Once per sheet that declares faces, so walking the tree costs nothing that matters.
+     */
+    private rematchFonts;
     private readonly knownSheets;
     /**
      * Start, advance or stop the `@keyframes` animation a node's style asks for.
@@ -769,6 +820,8 @@ export declare class Engine implements HostEngine {
     private processGradients;
     private clearFlags;
     private reconcile;
+    /** What a clone sends: the props that changed, and a text input's font once it registered. */
+    private propsPayload;
     /**
      * Whether a node has to be committed with its children again.
      *

package/dist/engine.js

@@ -1,6 +1,6 @@
 /**
  * Framework-agnostic retained tree + incremental Fabric commit.
- * Nothing Angular-specific may enter this file; lint bans the import (see ARCHITECTURE.md).
+ * Nothing Angular-specific may enter this file; lint bans the import (see docs/ARCHITECTURE.md).
  *
  * Angular mutates; Fabric is persistent. A committed node is never mutated, it is cloned with
  * new props and/or a new child set. Cloning a leaf therefore forces every ancestor to re-clone,
@@ -14,6 +14,7 @@ import { transformList } from "./inline-transform.js";
 import { tokenFromValue } from "./inline-token.js";
 import { NativeScrollDriver, scrollFeed, } from "./native-drive.js";
 import { firstFrame, rangeOf, scrollChannels } from "./scroll-animation.js";
+import { FontFaces } from "./font-faces.js";
 /**
  * The animation a node's style asks for, with a play state from a rule of its own applied. Both
  * are instructions for this engine and nothing native has heard of them, so they come out of the
@@ -380,6 +381,40 @@ function registeredViewName(elementName) {
  * a paragraph, and a text input on either platform. See `Engine.remeasureText`.
  */
 const MEASURED_VIEWS = new Set(['Paragraph', 'TextInput', 'AndroidTextInput']);
+/** What each mounted app does when faces register. See `fontsRegistered`. */
+const fontListeners = new Set();
+/** Hear about faces registering with the platform, until the returned function is called. */
+export function onFontsRegistered(listener) {
+    fontListeners.add(listener);
+    return () => fontListeners.delete(listener);
+}
+/**
+ * Faces just registered with the platform, by the family names text asks for them by. Every
+ * mounted app lays out again the paragraphs and text inputs that name one: see
+ * `Engine.fontsRegistered`.
+ */
+export function fontsRegistered(families) {
+    const names = new Set(families);
+    if (!names.size)
+        return;
+    for (const listener of [...fontListeners])
+        listener(names);
+}
+/** Whether a paragraph, or a span in it, was committed asking for one of these families. */
+function namesFamily(node, families) {
+    const family = node.committed?.props['fontFamily'];
+    if (typeof family === 'string' && families.has(family))
+        return true;
+    return node.children.some((child) => namesFamily(child, families));
+}
+/** A text size cap far above any a platform offers, so it caps nothing. See `fontsRegistered`. */
+const UNCAPPED = 1000;
+/**
+ * How far a paragraph's cap moves each time a face it names registers: just past the 0.005 React
+ * Native compares text attributes to, so the layout it cached is not found, and too little for
+ * an app's own cap to cap anything visibly differently.
+ */
+const FONT_REFRESH_STEP = 0.006;
 /** The views that take a cursor, on either platform. */
 const TEXT_INPUTS = new Set(['TextInput', 'AndroidTextInput']);
 /** The views that scroll their content, which `focus` brings a field into view within. */
@@ -947,7 +982,7 @@ export class Engine {
         this.now = options.now ?? (() => globalThis.performance?.now?.() ?? Date.now());
         this.onDirty = options.onDirty;
         this.onError = options.onError;
-        this.registerKeyframes(options.globalStyles);
+        this.registerSheet(options.globalStyles);
         this.processColor = options.processColor ?? ((value) => value);
         this.resolveAssetSource = options.resolveAssetSource ?? ((value) => value);
         this.scrollDriver = options.nativeAnimated
@@ -1045,6 +1080,50 @@ export class Engine {
         visit(this.root);
         this.commit();
     }
+    /** Whether any text has been laid out again for a face. See `fontsRegistered`. */
+    fontsRefreshed = false;
+    /** How many times each paragraph or text input has been laid out again for a face. */
+    fontRefreshes = new WeakMap();
+    /** The text inputs whose `fontFamily` the next commit sends again. See `fontsRegistered`. */
+    fontResends = new WeakSet();
+    /**
+     * Faces registered after text naming them was laid out: lay that text out again, and commit.
+     *
+     * Native keeps a paragraph's text layout, face included, keyed by what the paragraph asks for.
+     * iOS caches the attributed string it built and the size it measured, so text laid out before
+     * its face registered stays in the fallback face, and committing it again unchanged hits the
+     * same cache. What it asks for has to change, and nothing visible can: each paragraph naming
+     * one of the families is committed with its text size cap raised by a step too small to see, or
+     * set far above any size the platform offers where it had none. Its view, and everything native
+     * holds for it, stays where it is. Android keys its text layout the same way and applies the
+     * cap the same way, so the same change works there.
+     *
+     * A text input takes its font another way. iOS sets it on the field again only when the input's
+     * text attributes change, which the same cap does. Android sets it only when `fontFamily` is in
+     * the props it is sent, and the engine sends only what changed, so it is sent again once.
+     */
+    fontsRegistered(families) {
+        const visit = (node) => {
+            for (const child of node.children) {
+                if (child.kind !== 'element')
+                    continue;
+                const viewName = viewNameOf(child);
+                const input = TEXT_INPUTS.has(viewName);
+                if (child.committed && (viewName === PARAGRAPH || input) && namesFamily(child, families)) {
+                    this.fontRefreshes.set(child, (this.fontRefreshes.get(child) ?? 0) + 1);
+                    if (input)
+                        this.fontResends.add(child);
+                    this.fontsRefreshed = true;
+                    this.markProps(child, false);
+                }
+                else {
+                    visit(child);
+                }
+            }
+        };
+        visit(this.root);
+        this.commit();
+    }
     /**
      * Put the cursor in a text input; bring anything else on screen, in the scroll view it is in.
      * A form sends the user to the first field that needs fixing this way, and a toggle or a picker
@@ -1428,6 +1507,8 @@ export class Engine {
         // One epoch per commit. Node props do not change while a commit runs, so every node can be
         // resolved once and shared with each of its descendants for the length of this walk.
         this.styleEpoch++;
+        // Faces registered before the walk, the global sheet's among them, reach every node in it.
+        this.facesAdded = false;
         const set = this.fabric.createChildSet(this.rootTag);
         for (const child of this.visibleChildren(this.root)) {
             this.fabric.appendChildToSet(set, this.reconcileUnder(this.root, child));
@@ -1448,6 +1529,8 @@ export class Engine {
         }
         this.flushTransitionEvents();
         this.scrollDriver?.afterCommit();
+        if (this.facesAdded)
+            this.rematchFonts();
         return true;
     }
     scrollDriver;
@@ -1533,8 +1616,8 @@ export class Engine {
             return { text: paragraphText(node) };
         if (this.dev)
             this.checkProps(node);
-        this.registerKeyframes(node.sheet);
-        this.registerKeyframes(node.hostSheet);
+        this.registerSheet(node.sheet);
+        this.registerSheet(node.hostSheet);
         const props = { ...DEFAULT_PROPS[viewName] };
         Object.assign(props, this.styles.resolve(node, this.styleEpoch).style);
         for (const key of Object.keys(node.props)) {
@@ -1552,10 +1635,27 @@ export class Engine {
         if (intrinsic)
             applyIntrinsicSize(style, intrinsic);
         flattenStyle(node.props[STYLE_OVERRIDE], style);
+        this.fontFaces.apply(style);
         if (viewName === PARAGRAPH)
             alignText(style, this.directionOf(node, style));
+        if (this.fontsRefreshed)
+            this.capForFonts(node, style);
         return composeTransform(node, this.animated(node, this.transitioned(node, style)));
     }
+    /**
+     * The text size cap that lays a paragraph or text input out again once a face it names has
+     * registered: a step per face above the app's own cap where it set one (below 1 is none, on
+     * both platforms), or above any text size there is. Counted per view, so an app's cap moves by
+     * a step for each face its text names and no further. See `fontsRegistered`.
+     */
+    capForFonts(node, props) {
+        const refreshes = this.fontRefreshes.get(node);
+        if (refreshes === undefined)
+            return;
+        const own = props['maxFontSizeMultiplier'];
+        props['maxFontSizeMultiplier'] =
+            (typeof own === 'number' && own >= 1 ? own : UNCAPPED) + refreshes * FONT_REFRESH_STEP;
+    }
     /** Set once any node has had a `direction` in its inline style. See `directionOf`. */
     inlineDirection = false;
     /**
@@ -1590,14 +1690,41 @@ export class Engine {
      * A property seen for the first time is recorded and left alone. That is CSS's own rule, and
      * without it every element would fade in from whatever the previous value happened to be.
      */
-    /** Take a sheet's `@keyframes` into the registry. Cheap and idempotent; sheets are few. */
-    registerKeyframes(sheet) {
-        if (!sheet?.keyframes || this.knownSheets.has(sheet))
+    /**
+     * Take a sheet's `@keyframes` and `@font-face` rules into the registries. Cheap and idempotent;
+     * sheets are few.
+     */
+    registerSheet(sheet) {
+        if (!sheet || this.knownSheets.has(sheet))
             return;
         this.knownSheets.add(sheet);
-        for (const name of Object.keys(sheet.keyframes)) {
+        for (const name of Object.keys(sheet.keyframes ?? {})) {
             this.keyframes.set(name, sheet.keyframes[name]);
         }
+        if (sheet.fonts && this.fontFaces.add(sheet.fonts))
+            this.facesAdded = true;
+    }
+    /** Every `@font-face` seen, global as on the web: a face declared in one sheet serves all. */
+    fontFaces = new FontFaces();
+    /** Whether a sheet first used in this commit declared a face. See `rematchFonts`. */
+    facesAdded = false;
+    /**
+     * Faces a sheet declared partway through a commit: text resolved before it, in this commit or
+     * an earlier one, matched without them. Resolve every text naming a family again, and commit.
+     * Once per sheet that declares faces, so walking the tree costs nothing that matters.
+     */
+    rematchFonts() {
+        const visit = (node) => {
+            for (const child of node.children) {
+                if (child.kind !== 'element')
+                    continue;
+                if (typeof child.committed?.props['fontFamily'] === 'string')
+                    this.markProps(child, false);
+                visit(child);
+            }
+        };
+        visit(this.root);
+        this.commit();
     }
     knownSheets = new WeakSet();
     /**
@@ -2000,7 +2127,7 @@ export class Engine {
         // is here only because something beneath it moved has the props it had.
         const propsMoved = node.propsDirty || styleChanged;
         const props = propsMoved ? this.mergeProps(node, viewName) : previous.props;
-        const propsPayload = propsMoved ? diffProps(previous.props, props) : null;
+        const propsPayload = propsMoved ? this.propsPayload(node, previous.props, props) : null;
         const childrenChanged = this.childrenMoved(node, childHandles, previous.childHandles);
         let handle = previous.handle;
         if (childrenChanged || propsPayload) {
@@ -2012,6 +2139,14 @@ export class Engine {
         this.clearFlags(node);
         return handle;
     }
+    /** What a clone sends: the props that changed, and a text input's font once it registered. */
+    propsPayload(node, previous, props) {
+        const payload = diffProps(previous, props);
+        if (payload && this.fontsRefreshed && this.fontResends.delete(node)) {
+            payload['fontFamily'] = props['fontFamily'];
+        }
+        return payload;
+    }
     /**
      * Whether a node has to be committed with its children again.
      *