@ng-native/fabric 0.5.0 → 0.7.0

package/dist/css.d.ts

@@ -222,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. */
@@ -294,6 +299,11 @@ export interface DeferredDeclaration {
         readonly unit: 'em' | 'vw' | 'vh' | 'vmin' | 'vmax';
         readonly factor: number;
         readonly offset?: number;
+        /**
+         * A unitless line-height: the node renders `factor` em, and what it hands down is the number,
+         * which each text under it multiplies its own font size by. See `LineHeightMultiple`.
+         */
+        readonly multiple?: true;
     };
     /**
      * A structured value - a transform list, a shadow, a filter - with lengths like `compute`'s
@@ -325,6 +335,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
@@ -370,11 +382,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.
@@ -472,7 +494,23 @@ export interface StyleCache {
      * 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;
@@ -538,6 +576,9 @@ export interface StyleTarget {
      * 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. */
@@ -577,6 +618,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;
 /**
@@ -584,6 +627,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;
@@ -600,25 +681,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;
 /**
@@ -663,7 +769,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.
@@ -722,6 +833,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;
@@ -733,11 +873,15 @@ export declare class StyleResolver {
      * resolves at most once however many descendants ask for its inherited values.
      */
     resolve(node: StyleTarget, epoch: number): StyleCache;
-    /** The rules a node matched, for its cache to keep, while a sheet uses `:has()`. */
-    private record;
     /**
-     * Set by the engine once a sheet uses `:has()`. Until then no cache keeps the rules it matched,
-     * so an app that never asks pays nothing for it.
+     * 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;
     /**
@@ -746,6 +890,13 @@ export declare class StyleResolver {
      * 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;
     /**
@@ -779,26 +930,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
@@ -856,6 +1015,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. */
@@ -907,6 +1079,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.