@ng-native/fabric 0.4.0 → 0.6.0

package/dist/css.d.ts

@@ -37,6 +37,11 @@ export interface Compound {
      * What Tailwind's `group-*` variants compile to.
      */
     readonly ancestors?: readonly Compound[];
+    /**
+     * `:is(<compound> > *)`: every one of these must match the node's parent. What Tailwind's `*:`
+     * variant compiles to.
+     */
+    readonly parents?: readonly Compound[];
     /** Interaction state the engine tracks: `:focus` and `:active`. */
     readonly pseudo?: readonly ('focus' | 'active')[];
     /**
@@ -46,6 +51,14 @@ export interface Compound {
     readonly nth?: readonly NthTest[];
     /** `:empty`: no children at all, text included. */
     readonly empty?: true;
+    /** `:has()`: every one of these must find a match beneath the node. */
+    readonly has?: readonly HasTest[];
+}
+/** One `:has()`: some element beneath the node, or some child of it, matches one of `any`. */
+export interface HasTest {
+    /** `:has(> x)`: a child, not any descendant. */
+    readonly child?: true;
+    readonly any: readonly Compound[];
 }
 /** `an + b`, counted from the start unless `fromEnd`. */
 export interface NthTest {
@@ -73,6 +86,15 @@ export interface StyleRule {
     readonly importantTokens?: readonly string[];
     /** Declarations whose value is a `var()`, resolved once the token map is known. */
     readonly deferred?: readonly DeferredDeclaration[];
+    /**
+     * The corners and edges the rule's plain declarations wrote, in the order it wrote them, where
+     * it wrote one in both its logical form and its physical one. The cascade settles the two as
+     * one property, and a value settled on device is in a list of its own, with no order between
+     * it and the rest.
+     */
+    readonly sides?: readonly string[];
+    /** The same for the rule's important declarations. */
+    readonly importantSides?: readonly string[];
     /** The media query guarding this rule, if any. */
     readonly condition?: MediaCondition;
     /** Memo of the last condition evaluation, and the conditions version it was made against. */
@@ -88,7 +110,8 @@ export type MediaCondition = {
     readonly op: 'gt' | 'gte' | 'lt' | 'lte' | 'eq';
     readonly value: number;
 } | {
-    readonly feature: 'orientation' | 'prefers-color-scheme' | 'prefers-reduced-motion';
+    /** `direction` is not a media feature: it is what `:dir()` asks, of the app as a whole. */
+    readonly feature: 'orientation' | 'prefers-color-scheme' | 'prefers-reduced-motion' | 'direction';
     readonly value: string;
 };
 /** What media queries are evaluated against. Pushed in by the host: the engine imports no RN. */
@@ -109,6 +132,12 @@ export interface Conditions {
      * (`Engine.remeasureText`), which `watchConditions` does after it.
      */
     readonly fontScale?: number;
+    /**
+     * The direction the app is laid out in, which is the device's unless the app forced one:
+     * `I18nManager.isRTL`. Optional, and left to right when absent. It decides which physical
+     * corner or edge a logical one is, where an element has both and no `direction` of its own.
+     */
+    readonly direction?: 'ltr' | 'rtl';
 }
 /** A run of CSS whitespace: spaces, tabs, newlines, carriage returns and form feeds, and no other. */
 export declare const CSS_SPACE: RegExp;
@@ -193,6 +222,11 @@ export interface DeferredDeclaration {
      * unambiguous given a single-valued token, so `padding: var(--gap)` writes all four.
      */
     readonly props: readonly string[];
+    /**
+     * `inherit`, written for these props: each is the parent's value for it, or nothing where the
+     * parent has none.
+     */
+    readonly inherit?: true;
     /** The element a bound declaration is on, by name, for a message about it to say. */
     readonly on?: string;
     /** A `var()` reference. Exactly one of this and `compute` is present. */
@@ -296,6 +330,8 @@ export interface LineTemplate {
     /** `color-mix(in srgb, var(--tint) 35%, transparent)`: the colour, written as a function. */
     readonly colour?: unknown;
     readonly style?: string;
+    /** Each side's own style, which the line's style is written to as well: see `settleBorders`. */
+    readonly marks?: readonly string[];
 }
 /**
  * A colour a deferred value is made of: settled at build time, a token, or a `color-mix()` of two
@@ -341,11 +377,21 @@ export type ColourExpression = {
         readonly space: MixSpace;
         readonly hue?: HueMethod;
         readonly a: ColourExpression;
-        readonly aPercentage?: number;
+        readonly aPercentage?: MixShare;
         readonly b: ColourExpression;
-        readonly bPercentage?: number;
+        readonly bPercentage?: MixShare;
     };
 };
+/**
+ * The share of a colour in a mix: a percentage, or a token multiplied into one, as
+ * `calc(var(--opacity) * 100%)` is the token times a hundred, with the number the token falls
+ * back to where it wrote one.
+ */
+export type MixShare = number | {
+    readonly reference: string;
+    readonly scale: number;
+    readonly fallback?: number;
+};
 /** One component's compiled styles, pre-sorted by specificity then source order. */
 /**
  * A gradient with holes in it: everything but the stop colours is settled at build time.
@@ -394,6 +440,12 @@ 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;
+    /**
+     * Some rule uses `:has()`, so what a node matches can change when something beneath it does.
+     * Said on the sheet for the same reason `structural` is: the cost is invalidation, and only a
+     * sheet that asks has the engine match a changed node's ancestors again.
+     */
+    readonly has?: 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
@@ -432,7 +484,28 @@ export interface StyleCache {
      * values do, and by the same copy-on-write rule, so a subtree that defines none shares one map.
      */
     tokens: Readonly<Record<string, TokenValue>>;
+    /**
+     * The rules the node matched, kept only while a sheet uses `:has()`: what a node whose
+     * subtree changed is compared against, to tell whether it has to be restyled.
+     */
+    matched?: readonly StyleRule[];
+    /**
+     * Set once a child takes a value from this node's own style, an `inherit` for a property CSS
+     * does not hand down: a change to the node's inline style then restyles it, and its children
+     * with it, where otherwise an inline style changes nothing a child resolves to.
+     */
+    heirs?: true;
+    /**
+     * The properties a rule declared `!important`, where any did: an inline style is the last of
+     * the plain declarations, so for these what the rules say stands over it.
+     */
+    important?: ReadonlySet<string>;
 }
+/**
+ * Whether a child is one `:empty` sees. An anchor is a comment on the web, which it does not;
+ * nor text of no length, which a binding to nothing leaves behind.
+ */
+export declare function fills(child: StyleTarget): boolean;
 /** What the matcher needs of a node. The engine's node satisfies this structurally. */
 export interface StyleTarget {
     readonly name: string;
@@ -487,6 +560,22 @@ export interface StyleTarget {
     styleCache: StyleCache | null;
     /** Set when something that could change what this node matches has changed. */
     styleDirty: boolean;
+    /**
+     * Set when something beneath this node changed and a sheet uses `:has()`: the node is matched
+     * again, and restyled only if the rules it matches came out different. Absent on a hand-built
+     * target.
+     */
+    hasDirty?: boolean;
+    /**
+     * Set by the engine when the node's own interaction state changed and nothing else about it
+     * did: a press began or ended on it or under it. It is matched again, and keeps the style it
+     * has, and everything under it, when it matches the rules it did. Not for an element a rule
+     * asks about from another one, which is restyled: see `usesActive`.
+     *
+     * Set as well when its place among its siblings changed and nothing else about it did, which
+     * is the same case: what it is asked about from another element is `placeReadElsewhere`.
+     */
+    stateDirty?: boolean;
     /** `:focus`. Set by the engine from the native focus and blur events. */
     focused?: boolean;
     /**
@@ -505,6 +594,18 @@ export interface StyleTarget {
  * The cost is one integer increment per comparison, against a Set lookup and several property
  * reads, so it does not distort what it measures.
  */
+/**
+ * What a sheet asks about a pressed element. `own` is whether a rule styles one, `.button:active`,
+ * which matching the pressed elements again answers. `elsewhere` is each compound that asks about
+ * a pressed element from another one: `.card:active .title`, `.a:active + .b`, or `:active`
+ * inside `:not()`, `:is()` or `:has()`. An element such a compound could be is restyled with
+ * everything under it when it is pressed, as what it changes is not itself alone.
+ */
+export declare function usesActive(sheet: StyleSheet): ActiveUse;
+export interface ActiveUse {
+    readonly own: boolean;
+    readonly elsewhere: readonly Compound[];
+}
 export declare const styleStats: {
     /** Calls to `matchesCompound`, the innermost unit of matching work. */
     compoundTests: number;
@@ -512,6 +613,8 @@ export declare const styleStats: {
     ruleTests: number;
     /** Nodes cascaded, as opposed to handed back from the memo. */
     nodesResolved: number;
+    /** Rules filed by key selector: each sheet's once, however many sheets come after it. */
+    rulesFiled: number;
 };
 export declare function resetStyleStats(): void;
 /**
@@ -519,6 +622,44 @@ export declare function resetStyleStats(): void;
  * filter and rejects almost everything immediately.
  */
 export declare function matches(node: StyleTarget, rule: StyleRule, sheet?: StyleSheet | null): boolean;
+/** A node's first `count` elements, or its last, skipping everything that is not one. */
+export declare function elementsAtEnd<T extends StyleTarget>(siblings: readonly T[], count: number, fromEnd: boolean): T[];
+/**
+ * Which way from a change in a child list a sheet's rules can match differently, past the
+ * elements at its two ends. An element's place from the start hangs on the elements before it
+ * and on none after, so a change moves the ones after it; its place from the end is the other
+ * way about.
+ */
+export interface SiblingReach {
+    /**
+     * How many elements after a change it reaches. All of them, `Infinity`, where it counts from
+     * the start (`:nth-child(odd)`) or asks about any element before (`~`). Where it asks only
+     * about the element just before (`+`), as many as its longest run of them steps along: one for
+     * `.a + .b`, two for `.a + .b + .c`. Zero where it asks none of these.
+     */
+    readonly after: number;
+    /** It counts from the end (`:nth-last-child(2)`). */
+    readonly before: boolean;
+}
+/**
+ * How far a sheet asks about a child list beyond which element is first and which is last.
+ * Where no sheet reaches either way, only the elements at the two ends can match differently.
+ */
+export declare function siblingReach(sheet: StyleSheet): SiblingReach;
+/**
+ * Each compound in a sheet whose element's place among its siblings is read from another
+ * element: one with something under it in the rule, `.row:nth-child(odd) .label` and
+ * `.a + .b .c`, or one an `:is()` or `:host-context()` looks for above the element styled.
+ *
+ * An element whose place changed is matched again, and where it matches the rules it did, it
+ * and everything under it are left as they were: its own rules are all that its place can
+ * change. Not an element one of these could be. What is under that one can match differently
+ * though it matches the same, so it is styled again with everything under it.
+ *
+ * A place read by the element a rule styles, or by the elements before it that the rule steps
+ * from (`.a:first-child + .b`), is that element's own: the rules it matches say.
+ */
+export declare function placeReadElsewhere(sheet: StyleSheet): readonly Compound[];
 /** One rule in a cascade: the sheet it came from, which `:host` needs, and its weight here. */
 interface RuleEntry {
     readonly rule: StyleRule;
@@ -535,25 +676,50 @@ interface RuleEntry {
  * is offered to everything, because the alternative is a rule that silently stops applying.
  */
 export declare function ruleKey(rule: StyleRule): string;
-/** Where a rule sits in the merged, weight-sorted list. The cascade depends on that order. */
+/**
+ * Every bucket a rule is filed under. One, but for a rule whose rightmost compound is only an
+ * `:is()` of compounds that each have a key: it is filed under each of theirs, since a node it
+ * matches has one of them.
+ *
+ * A rule that says nothing of the node's own name can still say whose child it is, `.row > *`.
+ * It is filed under the parent's class, and offered to the children of an element that has it.
+ */
+export declare function ruleKeys(rule: StyleRule): readonly string[];
+/** A rule in an index, and where it comes among rules of the same weight: the order it was written in. */
 interface IndexedEntry {
     readonly entry: RuleEntry;
     readonly at: number;
 }
 export interface RuleIndex {
-    readonly buckets: ReadonlyMap<string, readonly IndexedEntry[]>;
-    readonly universal: readonly IndexedEntry[];
+    readonly buckets: Map<string, IndexedEntry[]>;
+    readonly universal: IndexedEntry[];
 }
-/** File a merged, sorted rule list by key selector. Done once per sheet pair, not per node. */
-export declare function indexRules(entries: readonly RuleEntry[]): RuleIndex;
 /**
- * The rules worth trying against a node, in the order they were merged in.
+ * File rules by key selector, each at `from` and on: its place among every rule there is, which
+ * settles the order of two of the same weight. Into an index there already where one is given,
+ * so a sheet that arrives later is added to what is filed and nothing is filed again.
+ */
+export declare function indexRules(entries: readonly RuleEntry[], into?: RuleIndex, from?: number): RuleIndex;
+/**
+ * The rules worth trying against a node, in cascade order: `order` says which of two comes
+ * first, and with none it is the order they were filed in.
  *
- * Each bucket is already in order, so the collected list only needs sorting when more than one
- * contributed - which for a node with one class and a name is the common case, and cheap: the
- * lists are short by construction, which is the entire point of the index.
+ * From each index, only the buckets the node's name, id and classes reach, which is the entire
+ * point of the index: the lists are short by construction, so sorting them is cheap.
  */
-export declare function candidateRules(node: StyleTarget, index: RuleIndex): RuleEntry[];
+export declare function candidateRules(node: StyleTarget, indexes: RuleIndex | readonly RuleIndex[], order?: (a: IndexedEntry, b: IndexedEntry) => number): RuleEntry[];
+/** What a sheet's rules are written for: the last compound of each, by its class or its name. */
+export interface Subjects {
+    readonly classes: Set<string>;
+    readonly types: Set<string>;
+    /**
+     * The classes of the boxes that rules for anything are written inside: `.dialog > :first-child`
+     * is for any element, but only one that has an element with `dialog` over it.
+     */
+    readonly inside: Set<string>;
+    /** A rule for anything anywhere: no class, no name, and no such box to be in. */
+    any: boolean;
+}
 /** Whether an inline style sets a property children inherit. Allocates nothing: it runs per set. */
 export declare function setsInherited(style: unknown): boolean;
 /**
@@ -598,7 +764,12 @@ export declare class StyleResolver {
      * selector. Keyed by the creating sheet and then the hosted one, so a component's nodes share a
      * single index.
      */
-    private merged;
+    /** The global sheet and every sheet added to it, filed by key selector. See `rulesFor`. */
+    private filed;
+    /** How many of the added sheets `filed` holds: one added since is filed at the next read. */
+    private filedAdded;
+    /** A component's own sheet, indexed once for each place it can take: a host's, or its creator's. */
+    private readonly ownIndexes;
     /**
      * Whether any sheet merged so far has a rule in a cascade layer. Until one does, rules are
      * ordered by weight alone and the cascade does not look for layers, which is nearly every app.
@@ -657,6 +828,35 @@ export declare class StyleResolver {
      * swap of the component's CSS edits the sheet where it is.
      */
     addGlobalSheet(sheet: StyleSheet, replacing?: StyleSheet): boolean;
+    /**
+     * The sheets added one after another with nothing else changed between them, each with the
+     * generation it began and ended: a cache made before them still stands for a node none of
+     * them could match. Emptied by anything else that moves the generation on.
+     */
+    private readonly additions;
+    /** Whether a sheet could match a node: one of its rules is written for it. */
+    couldMatch(sheet: StyleSheet, node: StyleTarget): boolean;
+    /** How far each class named by the sheets met so far reaches: see `classReach`. */
+    private readonly reach;
+    /** The tests of the `class` attribute itself in those sheets, which any class may answer. */
+    private readonly classTests;
+    private readonly noted;
+    /** Read the classes a sheet names, once, as soon as any node is given it. */
+    noteSheet(sheet: StyleSheet | null | undefined): void;
+    private noteReach;
+    /**
+     * What classes coming to an element or going from it can restyle: `true` for it and all
+     * under it and after it, as any change to it does; the elements under it to restyle, by what
+     * rules are for; or null, where no rule names any of them and nothing is styled again.
+     */
+    reachOf(classes: Iterable<string>): true | Subjects | null;
+    /** Whether one of the rules `subjects` stands for could be for a node. */
+    isFor(subjects: Subjects, node: StyleTarget): boolean;
+    /**
+     * Whether a cache is of this generation, or of one before sheets that could not match the
+     * node were added, which leaves it as it was: it is then brought up to this one.
+     */
+    private current;
     /** Stop matching a sheet `addGlobalSheet` added; false when it is not one. */
     removeGlobalSheet(sheet: StyleSheet): boolean;
     setConditions(next: Conditions): void;
@@ -668,6 +868,37 @@ export declare class StyleResolver {
      * resolves at most once however many descendants ask for its inherited values.
      */
     resolve(node: StyleTarget, epoch: number): StyleCache;
+    /**
+     * A cache of a node just styled, with a context of its own. It keeps the rules the node
+     * matched, for the node to be compared with, once a sheet has a use for them: see `tracksHas`.
+     */
+    private cached;
+    /**
+     * Set by the engine once a sheet uses `:has()`, styles a pressed element or asks about a place
+     * in a child list. Until then no cache keeps the rules it matched, so an app that never asks
+     * pays nothing for it.
+     */
+    tracksHas: boolean;
+    /**
+     * The cache of a node whose subtree changed, and nothing else, when it matches the rules it
+     * did: keeping the object is what leaves everything under it alone. Nothing when it has to be
+     * resolved, as it does with no record of what it matched, made before any sheet asked.
+     */
+    private keptBeneath;
+    /** The rules a node matches now, weakest first. */
+    private matchedBy;
+    /**
+     * The rules `keptBeneath` found the node being resolved to match, where they are other than
+     * it matched before: it is styled from them next, rather than matched a second time.
+     */
+    private justMatched;
+    /** A cache that still stands for a node marked for its subtree or its state alone. */
+    private kept;
+    /**
+     * The cache of a node whose pressed state changed and nothing else, where no rule can match
+     * it at all: it has no style of its own to change, so it and all under it stay as they are.
+     */
+    private keptUnmatched;
     /**
      * Whether a node's last answer still stands under a parent that resolved to `parentContext`,
      * without resolving it. What lets a commit step over a clean child in one comparison.
@@ -694,26 +925,34 @@ export declare class StyleResolver {
      */
     private unstyled;
     /**
-     * The rules worth trying against a node.
+     * The rules worth trying against a node, in cascade order.
      *
-     * The merged list is built once per (creating sheet, hosted sheet) pair and indexed by key
-     * selector; what comes back here is only the buckets this node can reach. For a component's own
-     * sheet that changes little, but a global utility sheet is hundreds of rules and a screen is a
-     * thousand nodes, and the difference is between a million match attempts and a few thousand.
-     */
-    private rulesFor;
-    /**
-     * Weakest first. A host node is matched against two component sheets: the one belonging to the
-     * component it hosts, whose `:host` rules exist to reach exactly this node, and the one that
-     * created it. Both carry the bump; the creator comes later and so wins a tie, as the outer
-     * document does over `:host` on the web. The sort is stable, so within one sheet source order
-     * survives and a later sheet wins equal weight.
+     * Every sheet is filed once, by key selector: the app's global sheet and each sheet added to it
+     * in one index, and a component's own in one of its own. What comes back is only the buckets
+     * this node can reach. A global utility sheet is hundreds of rules and a screen is a thousand
+     * nodes, and the difference is between a million match attempts and a few thousand. A library
+     * adds a sheet for each of its components as the component first renders, dozens on one
+     * screen, so one more is added to what is filed and nothing is filed again.
+     *
+     * Sheets are filed in the order a document holds them, which is the order of two rules of the
+     * same weight, and where a layer gets its place: the app's global sheet, the host's own, the
+     * creating component's, then each added sheet as it came. The component layers get a small
+     * specificity bump, so the encapsulation attribute Angular adds on the web does not have to
+     * be written.
      *
      * A sheet added with `addGlobalSheet` comes last, with no bump: a browser adds a None
      * component's CSS when the component first renders, after the styles of the components around
      * it, so it loses to their extra attribute and wins a tie with them.
      */
-    private merge;
+    private rulesFor;
+    /** Weakest first: by layer where any sheet has one, then by weight, then as they were filed. */
+    private readonly cascadeOrder;
+    /** A component's sheet as the rules of a host or of a creator, which differ only in their place. */
+    private ownIndex;
+    /** The app's global sheet and every sheet added to it, with any added since the last read. */
+    private sharedIndex;
+    /** A sheet's rules at their weight here, with its layers given their places. */
+    private entries;
     /**
      * Gives each of a sheet's layers its place among every sheet's, the first time the sheet is
      * merged, and each of its layered rules that place. Sheets are merged in the order a document
@@ -741,6 +980,16 @@ export declare class StyleResolver {
     private matched;
     /** The declarations of the rules a node matched. The list is sorted, so later simply wins. */
     private cascade;
+    /**
+     * An inline style over the style the cascade settled, both already in `style`: a corner or an
+     * edge the inline style sets takes the other form of it out, as a later rule would.
+     */
+    overOtherForms(inline: Readonly<Record<string, unknown>>, style: Record<string, unknown>): void;
+    /**
+     * The direction an element is laid out in: the last `direction` its own rules give it, the one
+     * it inherits, or the app's. A logical corner is a different physical one in each.
+     */
+    private directionOf;
     /**
      * Whether a rule's media query holds, memoised per rule.
      *
@@ -761,6 +1010,19 @@ export declare class StyleResolver {
      * undefined, which is what a browser does with a value it cannot resolve.
      */
     private applyDeferred;
+    /** Note what the node being resolved takes an `inherit` from, and that its parent has an heir. */
+    private heir;
+    /** What the parent of the node being resolved came to: an `inherit` takes its values from it. */
+    private parentOf;
+    /** That parent's inline style, which is over what its rules gave it. */
+    private parentInline;
+    /** What the parent's inline style sets, under what its rules marked important, as on the parent. */
+    private parentSet;
+    /**
+     * `inherit`: each prop as the parent has it, handed down or its own, and gone where the parent
+     * has none, which is what a weaker rule's value for it gives way to.
+     */
+    private inherit;
     /** One deferred declaration's value, from the tokens in scope and the node's own style. */
     private settled;
     /** A line's longhands from its tokens, with a width in `em` worked out against the font size. */
@@ -812,6 +1074,15 @@ interface CalcMarker {
     readonly expression: CalcExpression;
     readonly kind: 'length' | 'angle' | 'time' | 'number';
 }
+/**
+ * A colour at a fraction of its opacity.
+ *
+ * Multiplied rather than replaced, so a token that was already translucent stays relatively so -
+ * `rgba(0, 0, 0, 0.5)` faded to 90% is 45% opaque, which is what a browser computes for the same
+ * mix. A value that is not one of ours is returned untouched: it may be a platform colour, and a
+ * colour nobody can parse is better painted as it stands than dropped.
+ */
+export declare function faded(value: unknown, fraction: number): unknown;
 /**
  * Where a component's compiled sheet lives: a static on the component class, written by the
  * Metro transformer at build time.