@sheetxl/primitives 0.8.0-beta.2 → 0.8.0-beta.21

package/types/src/IFunction.d.ts

@@ -37,13 +37,19 @@ export interface IFunction {
      */
     isBuiltIn(): boolean;
     /**
-     * Indicates whether the function is a defined name whose body is `LAMBDA(…)`.
+     * Indicates whether the function is a `LAMBDA` rather than a built-in or registered function.
      *
      * @remarks
-     * A named lambda is reachable by name like any other function, so signature help and function
-     * lookups can describe it: its parameters are the lambda's, and its summary is the name's
-     * comment, or the name's formula when it has no comment. A formula calls it through the NAME,
-     * never through {@link execute}, which answers `#CALC!`.
+     * Two kinds of function answer `true`:
+     *
+     * - **A defined name whose body is `LAMBDA(…)`.** It is reachable by name like any other
+     *   function, so signature help and function lookups can describe it: its parameters are the
+     *   lambda's, and its summary is the name's comment, or the name's formula when it has no
+     *   comment. A formula calls it through the NAME, never through {@link execute}, which answers
+     *   `#CALC!`.
+     * - **A `LAMBDA` passed as a value** and received by
+     *   {@link IFunctionArguments.getFunctionsAt}. It has no name ({@link getName} is `''`), its
+     *   parameters are the lambda's, and {@link execute} applies it.
      */
     isLambda(): boolean;
     /**
@@ -278,11 +284,9 @@ export declare namespace IFunction {
         getMembers(): readonly IFunction.IEnumMember[];
     }
     /**
-     * Describes the runtime return behavior of a function, including modifiers like
-     * async resolution, streaming data, or volatility.
+     * Describes the runtime return behavior of a function, including modifiers like volatility.
      *
      * @remarks
-     * All return type modifiers are mutually exclusive.
      * If none are specified, The value will be returned with no special behavior.
      */
     interface IReturnType extends IValueType {
@@ -294,26 +298,13 @@ export declare namespace IFunction {
          * @see {@link ReturnTypeJSON.kind}
          */
         getKind(): ValueKind | null;
-        /**
-         * Indicates the return value is a Promise or Promise-like (i.e., async).
-         * The system will mark the result as pending and re-trigger evaluation once resolved.
-         *
-         * Can be combined with any scalar, array, or range return type.
-         */
-        isAsync(): boolean;
-        /**
-         * Indicates whether the function produces a continuous stream of output (e.g., real-time data).
-         *
-         * @defaultValue `false`
-         */
-        isStreaming(): boolean;
         /**
          * True when the result can change with nothing dirty, so a cell naming this function
          * recalculates on every pass — the `Volatile<T>` marker.
          *
          * @remarks
          * STATIC, and read from the formula text at compile time: it is true of the call whether or
-         * not the call runs, which is what a lazy argument (and Excel) requires.
+         * not the call runs, which is what a lazy argument requires.
          *
          * @see {@link ReturnTypeJSON.volatile}
          */
@@ -352,7 +343,7 @@ export declare namespace IFunction {
          * @remarks
          * Only meaningful for a VARIADIC function; a fixed parameter list is already its own maximum.
          * The number is the whole CALL's argument count, prefix and optional suffix included, and it
-         * is refused where Excel refuses it — at entry, before evaluation.
+         * is refused at entry, before evaluation.
          *
          * @see {@link Repeating}
          */
@@ -363,6 +354,15 @@ export declare namespace IFunction {
          * @defaultValue `{ type: 'void' }`
          */
         getReturnType(): IReturnType;
+        /**
+         * Whether the function is left out of function lists, from its `@hidden` or `@deprecated` tag.
+         *
+         * @remarks
+         * A hidden function is still callable from a formula and still found by name. Listing calls
+         * leave it out unless asked to include it. {@link IDescriptor.isDeprecated} carries the tag's
+         * label, if it has one.
+         */
+        isHidden(): boolean;
     }
     /**
      * Locale-specific, user-facing metadata: display name, summary, category, and
@@ -395,14 +395,11 @@ export declare namespace IFunction {
          */
         getCategory(): string;
         /**
-         * If `true` the function is available but will not be returned in search
-         * results unless hidden is specifically requested.
-         *
-         * @defaultValue 'null'
+         * The label of the function's `@hidden` or `@deprecated` tag (`Unimplemented`), `true` for a tag
+         * with no label, or `false`.
          *
          * @remarks
-         * * If this is a string it can be used to provide a deprecated label.
-         * * This is useful for functions that are in beta or deprecated.
+         * Whether the function is listed is {@link IDeclaration.isHidden}; this is the text to show for it.
          */
         isDeprecated(): boolean | string;
         /**
@@ -648,8 +645,8 @@ export declare namespace IFunction {
          * Generated from the `NoLift<T>` marker.
          *
          * @remarks
-         * Per parameter, because Excel is: `NETWORKDAYS.INTL` refuses a reference at its date slots
-         * and lifts one at `weekend`. An ARRAY at the slot still lifts, a one-cell reference is an
+         * Per parameter, because Excel's built-ins differ by slot: `NETWORKDAYS.INTL` refuses a
+         * reference at its date slots and lifts one at `weekend`. An ARRAY at the slot still lifts, a one-cell reference is an
          * ordinary argument, and a repeating slot absorbs a container as members, so the marker only
          * ever applies to a non-repeating scalar parameter.
          */
@@ -689,7 +686,7 @@ export declare namespace IFunction {
          * union is the range arm, handed over whole. The slot never lifts.
          *
          * @remarks
-         * Excel reads a one-cell argument at some array slots as THE ARGUMENT rather than as a
+         * Some array slots read a one-cell argument as THE ARGUMENT rather than as a
          * one-cell container: `SORT(<#N/A cell>,1,1,<#DIV/0! cell>)` is `#N/A` where
          * `TAKE(<#N/A cell>,<#DIV/0! cell>)` is `#DIV/0!`. The engine's default
          * for a range slot is TAKE's; this flag is SORT's. {@link scalar} and {@link range} each carry
@@ -726,8 +723,7 @@ export declare namespace IFunction {
         members: [name: string, value: number | string, deprecated?: string | true][];
     }
     /**
-     * Describes the runtime return behavior of a function, including modifiers like
-     * async resolution, streaming data, or volatility.
+     * Describes the runtime return behavior of a function, including modifiers like volatility.
      *
      * @remarks
      * If none are specified, The value will be returned with no special behavior.
@@ -751,29 +747,15 @@ export declare namespace IFunction {
          * is a scalar is its member value downstream.
          */
         kind?: ValueKind;
-        /**
-         * Indicates the return value is a Promise or Promise-like (i.e., async).
-         * The system will mark the result as pending and re-trigger evaluation once resolved.
-         *
-         * Can be combined with any scalar, array, or range return type.
-         */
-        async?: boolean;
-        /**
-         * Indicates whether the function produces a continuous stream of output (e.g., real-time data).
-         *
-         * @defaultValue `false`
-         */
-        stream?: boolean;
         /**
          * The result can change with nothing dirty — a cell naming this function recalculates on
          * every pass. Generated from the `Volatile<T>` marker.
          *
          * @remarks
          * Collected at COMPILE time from the formula text (`CompiledFormula.hasVolatile`), because
-         * that is where Excel decides it: `=IF(TRUE,1,RAND())` recalculates on every idle pass though
+         * that is where volatility is decided: `=IF(TRUE,1,RAND())` recalculates on every idle pass though
          * no branch selects the arm, and with lazy arguments the call never happens for the engine to
-         * observe. Sits beside {@link async} and {@link stream} because all three are about WHEN a
-         * result arrives rather than what it is.
+         * observe.
          *
          * @see {@link Volatile}
          */
@@ -794,11 +776,10 @@ export declare namespace IFunction {
          * parameter. Omitted at the default of 255.
          *
          * @remarks
-         * Excel keeps one such number per NAME and compares it against the whole call's argument
-         * count in its front end, so a call past it is refused AT ENTRY rather than answered — which
-         * is why the cap lives on the declaration and not in a body. It is not derivable from the
-         * shape: `STDEV` takes 255 arguments and `STDEV.S`, the same function under its dotted name,
-         * takes 254.
+         * The cap is one number per NAME, compared against the whole call's argument count, so a call
+         * past it is refused AT ENTRY rather than answered — which is why the cap lives on the
+         * declaration and not in a body. It is not derivable from the shape: in Excel `STDEV` takes 255
+         * arguments and `STDEV.S`, the same function under its dotted name, takes 254.
          *
          * @defaultValue 255
          */
@@ -825,6 +806,14 @@ export declare namespace IFunction {
          * * If the context is not `IFunction.Calculation` then the function must return `void` or a cleanup function.
          */
         context?: string;
+        /**
+         * Leave the function out of function lists.
+         *
+         * @defaultValue `false`
+         *
+         * @see {@link IDeclaration.isHidden}
+         */
+        hidden?: boolean;
         /**
         * Additional metadata about the function's behavior or requirements.
         */
@@ -859,13 +848,12 @@ export declare namespace IFunction {
          */
         category?: string;
         /**
-         * If `true` or has a string value then is usable in calculation but not provided in the ui.
+         * The label of a `@hidden` or `@deprecated` tag, or `true` for a tag with no label.
          *
-         * @defaultValue 'null'
+         * @defaultValue `false`
          *
          * @remarks
-         * * If this is a string it can be used to provide a deprecated label.
-         * * This is useful for functions that are in beta or deprecated.
+         * Display text only. Whether the function is listed is {@link DeclarationJSON.hidden}.
          */
         deprecated?: string | boolean;
         /**

package/types/src/IFunctionArguments.d.ts

@@ -2,6 +2,7 @@ import { Scalar } from './Scalar';
 import { ValueKind } from './ValueKind';
 import { IRange } from './IRange';
 import { Lambda } from './Lambda';
+import { IFunction } from './IFunction';
 /**
  * The current call's arguments, as the body sees them — argument **reflection**.
  *
@@ -14,9 +15,8 @@ import { Lambda } from './Lambda';
  * - What was the value BEFORE the parameter's type coerced it?
  * - Was that empty slot an omission, or a blank cell the caller pointed at?
  *
- * Excel has behaviors that turn on exactly those questions, and they cluster at the
- * parameters Excel declares `any` — where there is nothing to express as a type, because Excel
- * declined to express one. `CUMIPMT` refuses a boolean at every slot while `FV` coerces one at
+ * Some functions have behaviors that turn on exactly those questions, and they cluster at
+ * parameters declared `any` — where there is nothing to express as a type. `CUMIPMT` refuses a boolean at every slot while `FV` coerces one at
  * every slot; the difference is not the values, it is that `CUMIPMT`'s slots are `any` and its
  * body decides.
  *
@@ -141,7 +141,7 @@ export interface IFunctionArguments {
      */
     getKindAt(index: number): ValueKind;
     /**
-     * True when the argument at `index` is DIRECT — Excel's "typed into the list of arguments":
+     * True when the argument at `index` is DIRECT — typed into the list of arguments:
      * the evaluated value IS a value, not a container or a callable.
      *
      * @param index The PARAMETER index — the position in the body's own signature.
@@ -170,6 +170,27 @@ export interface IFunctionArguments {
      * other slot the marshaller has already answered `#VALUE!`.
      */
     getAreaCountAt(index: number): number;
+    /**
+     * The functions the argument at `index` holds, in row-major order — or `null` unless it holds
+     * nothing but functions.
+     *
+     * @param index The PARAMETER index — the position in the body's own signature.
+     *
+     * @remarks
+     * A formula can pass a function as a value: `LAMBDA(x, x * 2)`, or a built-in by name, as `SUM`
+     * is in `BYROW(A1:C3, SUM)`. A `Lambda` parameter takes ONE such value. This is for an untyped
+     * parameter that also takes an ARRAY of them, as `HSTACK(SUM, AVERAGE)` makes.
+     *
+     * The argument's shape is its own: {@link getKindAt} is `Lambda` for one function and `Array`
+     * for several, and {@link getRawAt} is that array. A function value IS an {@link IFunction}: a
+     * built-in by name answers as the registry's function does, and a `LAMBDA` is one whose
+     * {@link IFunction.isLambda} is `true`. A body whose untyped parameter holds the value reads the
+     * functions from it directly; this is reflection, for when the declaration does not hand it over.
+     *
+     * Nothing is collected until every member has proved to be a function, so a data range given by
+     * mistake costs one member.
+     */
+    getFunctionsAt(index: number): readonly IFunction[] | null;
 }
 /**
  * {@inheritDoc IFunctionArguments}

package/types/src/IRange.d.ts

@@ -255,7 +255,7 @@ export interface IRange<T extends Scalar = Scalar> {
      * @remarks
      * Errors INSIDE a range are the body's to judge: the engine hands a valid range over whole and
      * never looks inside, so a function whose answer depends on every member says so with this
-     * line, placed before its own validation where Excel's error outranks it. A reshaper or a
+     * line, placed before its own validation where the member's error outranks it. A reshaper or a
      * lookup, whose members pass through or are never read, needs no line at all.
      */
     firstError(): FormulaError.Known | null;
@@ -268,7 +268,7 @@ export interface IRange<T extends Scalar = Scalar> {
      * @remarks
      * `options.axis` is the TRAVERSAL order feeding the ordinal, not the orientation of the result:
      * the result is always Nx1, and a row is `flatten().transpose()`. The default is row-major,
-     * which is the order Excel pairs two range operands in.
+     * which is the order two range operands pair in.
      *
      * `options.type` carries a read type onto the result, so a member the type filters out becomes
      * a HOLE at its ordinal rather than compacting the column. That is what lets two operands be
@@ -787,6 +787,24 @@ export declare namespace IRange {
          * If passing a large bound care must be taken.
          */
         includeEmpty?: boolean;
+        /**
+         * Skips rows of the range: given the next row that would be read, answers the row to read
+         * instead - the same row when it is read, or the next one that is (the previous, when
+         * `reverse`).
+         *
+         * @param index The 0-based row about to be read.
+         * @param reverse Whether the read runs from the last row back.
+         * @returns The row to read, at or past `index`.
+         *
+         * @remarks
+         * A skipped cell is not visited, reads as empty and is left out of the statistics; the shape
+         * of the range is unchanged. `SUBTOTAL` reads a range this way when it skips hidden rows.
+         */
+        processRowSkip?: (index: number, reverse?: boolean) => number;
+        /**
+         * Skips columns of the range, as {@link processRowSkip} skips rows.
+         */
+        processColumnSkip?: (index: number, reverse?: boolean) => number;
         /**
          * Useful for callback functions that want a this.
          */
@@ -898,7 +916,7 @@ export declare namespace IRange {
          *
          * - By default, `broadcast()` follows strict alignment rules like NumPy and will
          *   throw an error if the input ranges cannot be broadcasted together.
-         * - When `misalignValue` is provided, `broadcast()` will instead mimic Excel behavior:
+         * - When `misalignValue` is provided, `broadcast()` will instead follow Excel's behavior:
          *   - It finds the **largest valid intersection** of the ranges.
          *   - It expands the result to the **union of both range sizes**.
          *   - Any cells that do not have valid corresponding values from the inputs
@@ -956,7 +974,7 @@ export declare namespace IRange {
          *
          * @remarks
          * Off, a dimension of 1 is a short dimension like any other and pads `misalignValue` past
-         * its one position: Excel's `MAP` rule, where a 1-row array is not stretched.
+         * its one position: the `MAP` rule, where a 1-row array is not stretched.
          */
         tile?: boolean;
         /**

package/types/src/IRangeStats.d.ts

@@ -71,7 +71,7 @@ export interface IRangeStats {
      */
     getAggregates(options?: IRange.IteratorOptions): Readonly<IRangeStats.Aggregates>;
     /**
-     * Returns the sum as Excel's `SUM` reports it — {@link getAggregates}'s `sum` with Excel's
+     * Returns the sum as `SUM` reports it — {@link getAggregates}'s `sum` with Excel's
      * cancellation-to-zero rule applied.
      *
      * @param total A total the caller accumulated across SEVERAL stats instances. Omit for a
@@ -82,7 +82,7 @@ export interface IRangeStats {
      * @remarks
      * Collapses a total to exactly zero when it lands at least 50 binary exponents below the
      * operands that produced it, so `SUM(0.1,0.2,-0.3)` is `0` rather than `5.55111512312578E-17`.
-     * Use this wherever you mean "the number Excel's SUM would show" — a status bar, a report
+     * Use this wherever you mean "the number SUM shows" — a status bar, a report
      * total, a formula. Use `getAggregates().sum` where you mean the true total of the data.
      *
      * The two genuinely differ, and neither is a rounding of the other:
@@ -92,12 +92,12 @@ export interface IRangeStats {
      *   and `PERCENTOF`, and to NOTHING else — `SUMIF`, `SUMPRODUCT`, `SERIESSUM`, `DSUM`, the
      *   `SUMX2MY2` family and every binary operator all keep the residue over the same values.
      *   That is why this is a method you call and not a change to `getAggregates`.
-     * - `AVERAGE` divides THIS, not the raw sum: snapping the mean instead is measurably wrong.
+     * - `AVERAGE` divides THIS, not the raw sum: snapping the mean instead is wrong.
      *
      * It is also cheap when it does not fire: a bound derived from `min`/`max` rejects any
      * ordinary total without re-reading the range.
      *
-     * **Multiple ranges.** Excel evaluates the rule on the *final* accumulation step, so a total
+     * **Multiple ranges.** The rule applies on the *final* accumulation step, so a total
      * spanning several ranges must be judged against the range holding the LAST value — pass the
      * running total as `total` and call this on that range. (Snapping each range separately gets
      * `SUM(A1:A3,0)` and `SUM(A1:A1,A2:A2,A3:A3)` wrong in opposite directions.) A composite
@@ -160,7 +160,8 @@ export interface IRangeStats {
      *
      * - Every requested type (all types when omitted) is present with an explicit count —
      *   a `0` is a fact about the range, a missing key would be ambiguous.
-     * - Blanks report under {@link ScalarType.Null}: total cells minus non-empty values.
+     * - Blanks report under {@link ScalarType.Null}: total cells minus non-empty values. A cell the
+     *   range skips ({@link IRange.IteratorOptions.processRowSkip}) is not a blank; it is not counted.
      * - Never throws on error values — errors are population here, not faults — regardless of
      *   the `onError` iterator policy the stats were created with.
      */
@@ -244,7 +245,7 @@ export declare namespace IRangeStats {
      * Sorting requires materializing the full numeric population (O(n log n), one allocation).
      * Unlike `Aggregates`, sorted views are **not composable across sub-ranges**.
      *
-     * Covers the following Excel functions (all share one sort per coords per calc cycle):
+     * Covers the following functions (all share one sort per coords per calc cycle):
      * - `LARGE`, `SMALL`
      * - `MEDIAN`, `PERCENTILE`, `PERCENTILE.INC`, `PERCENTILE.EXC`
      * - `QUARTILE`, `QUARTILE.INC`, `QUARTILE.EXC`  (q1 = k=0.25, q3 = k=0.75)
@@ -309,7 +310,7 @@ export declare namespace IRangeStats {
          * one outside the population is not found.
          * @param exclusive If true, uses exclusive formula (0 and 1 are excluded).
          * @param significance Number of DECIMAL PLACES to TRUNCATE the result to — despite what
-         * Excel's own help calls the argument, it is not significant digits and it does not round.
+         * Excel's help calls the argument, it is not significant digits and it does not round.
          * Truncated toward zero first (1.9 places means 1), and must be at least 1. Omit it for the
          * exact untruncated rank, which is also the only form that cannot fail.
          * @returns The percent rank of x; `null` if x is not found or there are no numbers in range.

package/types/src/IRichData.d.ts

@@ -1,37 +1,77 @@
 import { Scalar } from './Scalar';
+import { IRichMeta, IRichType } from './IRichType';
 /**
  * A complex object type. This allows for more complex data types to be stored in a cell.
  */
 export interface IRichData {
     /**
-     * Reference to either a known typename or a JSON Type Definition.
-     * * {@link https://jsontypedef.com/}
+     * The value's kind: the properties it has and how they show. Every value of a kind returns the
+     * same instance.
      */
-    getType(): string;
+    getKind(): IRichType;
     /**
      * @param name The name of the property to retrieve.
      */
     getProperty(name: string): Scalar;
     /**
-     * For clients that don't support IRichData.
+     * How the property `name` shows on this value: the value's own presentation where it differs
+     * from its kind's (a price in another currency), else the kind's ({@link IRichType.Property.meta}).
+     * `null`, or the method absent, for none.
+     */
+    getPropertyMeta?(name: string): IRichMeta | null;
+    /**
+     * The text shown for this value where nothing renders it: a client with no renderer for the
+     * kind, a log, a placeholder. A rich text shows its text; an image a short description.
      *
      * @remarks
-     * `toString()` can used when a Rich Data is not supported for example clipboard and sorting.
+     * Display only. What the value reads as to calculation, sorting and the clipboard is
+     * {@link toPrimitive}.
      */
     toString(): string;
     /**
-     * Indicates this is an IRichData type.
+     * The primitive this value reads as wherever one is consumed: `LEN`, `&`, `+`, comparison,
+     * `ISTEXT`, `TYPE()`, sort, filter, find. A rich text reads as its text; an error that carries
+     * more than its code reads as that error; an image reads as nothing (`null`, or the method
+     * absent), and is `#VALUE!` wherever a primitive is needed.
+     *
+     * @remarks
+     * The ordinary rules then apply to the primitive (text-to-number coercion, collation, error
+     * propagation), so a value adds no coercions of its own.
+     */
+    toPrimitive?(): Exclude<Scalar, IRichData>;
+    /**
+     * The items this value unpacks to where a range or array is accepted (a list); `null`, or the
+     * method absent, for a value that is one value.
+     */
+    toArray?(): Scalar[][] | null;
+    /**
+     * The value as JSON, which its kind makes it again from. A value that holds a resource (a
+     * picture's bytes) names it by the id `toResourceId` answers, and the file saves the resource;
+     * without `toResourceId` it names none.
      */
-    toJSON?(): IRichData.JSON | Promise<IRichData.JSON>;
+    toJSON?(toResourceId?: IRichData.ToResourceId): IRichData.JSON | Promise<IRichData.JSON>;
     /**
      * For runtime type checking.
      */
     get isIRichData(): true;
 }
 export declare namespace IRichData {
+    /**
+     * The id a file being saved gives a resource a value holds (an `IResource`); `null` when the
+     * file does not save it.
+     */
+    type ToResourceId = (resource: any) => number | null;
     interface JSON {
+        /** The name of the value's kind ({@link IRichType.getName}). */
         type: string;
+        /** The value's own data, as its kind reads it. */
         data?: any;
+        /**
+         * Presentation for the properties where this value differs from its kind, by property name.
+         */
+        meta?: {
+            readonly [property: string]: IRichMeta;
+        };
     }
 }
 //# sourceMappingURL=IRichData.d.ts.map

package/types/src/IRichType.d.ts

@@ -0,0 +1,139 @@
+import { Scalar } from './Scalar';
+/**
+ * The kind of a rich value: its class. A kind is a static set of typed property definitions, and
+ * every value of a kind shares the one `IRichType` its {@link IRichData.getKind} returns.
+ *
+ * @remarks
+ * For introspection: a renderer, a card, a formula editor offering `A1.` completions, or a
+ * function reading a field asks the value's kind which properties it has. What a value reads as
+ * where a primitive is consumed is the value's own answer ({@link IRichData.toPrimitive}).
+ */
+export interface IRichType {
+    /**
+     * The kind's name: what a value's JSON names as its `type`.
+     */
+    getName(): string;
+    /**
+     * The name a UI shows for the kind, such as in a list of what can be inserted. The name when the
+     * kind has no label of its own.
+     */
+    getLabel(): string;
+    /**
+     * The kind's properties, in the order the kind declares them.
+     */
+    getProperties(): readonly IRichType.Property[];
+    /**
+     * The property `name`, or `null` when the kind has none by that name.
+     */
+    getProperty(name: string): IRichType.Property | null;
+    /**
+     * The property whose value is the text a cell shows for a value of this kind, or `null` when
+     * the kind shows none (an image).
+     */
+    getDisplayProperty(): string | null;
+    /**
+     * The kind's own presentation (a card, an icon, a provider), or `null` for none.
+     */
+    getMeta(): IRichMeta | null;
+}
+export declare namespace IRichType {
+    /**
+     * What a property holds.
+     *
+     * @remarks
+     * `rich` is another rich value (a capital city, an image); `array` is an array value; `resource`
+     * is a workbook resource such as a picture's bytes.
+     */
+    type ValueType = 'number' | 'integer' | 'string' | 'boolean' | 'error' | 'rich' | 'array' | 'resource';
+    /**
+     * One property a kind declares.
+     */
+    interface Property {
+        /** The property's name. */
+        readonly name: string;
+        /** What it holds. */
+        readonly valueType: ValueType;
+        /** What it reads as on a value that holds none. Omitted, `null`. */
+        readonly defaultValue?: Scalar;
+        /** How the property shows, unless a value says otherwise. */
+        readonly meta?: IRichMeta;
+    }
+    /**
+     * A kind saved with the workbook whose values name it: one that is not registered in code, such
+     * as a kind read from a file.
+     */
+    interface JSON {
+        /** {@inheritDoc IRichType.getName} */
+        name: string;
+        /** {@inheritDoc IRichType.getLabel} */
+        label?: string;
+        /** {@inheritDoc IRichType.getProperties} */
+        properties?: readonly Property[];
+        /** {@inheritDoc IRichType.getDisplayProperty} */
+        displayProperty?: string | null;
+        /** {@inheritDoc IRichType.getMeta} */
+        meta?: IRichMeta;
+    }
+}
+/**
+ * How a rich value, or one of its properties, is presented: the number format and caption of a
+ * property, where it is offered, its sources; a kind's card, icon and provider.
+ *
+ * @remarks
+ * Presentation only, never a value. A kind gives each of its properties a default; a value gives
+ * one only for a property where it differs (a price in another currency).
+ */
+export interface IRichMeta {
+    /** The number format a number property shows in. */
+    readonly numberFormat?: string;
+    /** A short caption shown beside the property, such as its unit or the year of its data. */
+    readonly sublabel?: string;
+    /** Where the property is not offered. Each omitted entry is `false`. */
+    readonly excludeFrom?: IRichMeta.ExcludeFrom;
+    /** Where the property's data comes from and under what license. */
+    readonly attribution?: readonly IRichMeta.Attribution[];
+    /** A kind's card. */
+    readonly card?: IRichMeta.Card;
+    /** A kind's icon, by name. */
+    readonly icon?: string;
+    /** Who provides a kind's data. */
+    readonly provider?: IRichMeta.Provider;
+}
+export declare namespace IRichMeta {
+    /** Where a property is not offered. */
+    interface ExcludeFrom {
+        /** Not shown on the card. */
+        readonly cardView?: boolean;
+        /** Not offered after `A1.` in a formula. */
+        readonly dotNotation?: boolean;
+        /** Not offered by formula autocomplete. */
+        readonly autoComplete?: boolean;
+        /** A change to the property is not a change to the value. */
+        readonly calcCompare?: boolean;
+    }
+    /** One source of a property's data. */
+    interface Attribution {
+        readonly sourceText?: string;
+        readonly sourceAddress?: string;
+        readonly licenseText?: string;
+        readonly licenseAddress?: string;
+    }
+    /** A kind's card: which properties it shows, and how. */
+    interface Card {
+        /** The properties shown, in order. Omitted, the kind's order. */
+        readonly order?: readonly string[];
+        /** The property shown as the title. */
+        readonly title?: string;
+        /** The property shown under the title. */
+        readonly subTitle?: string;
+        /** The image property shown at the top. */
+        readonly mainImage?: string;
+    }
+    /** Who provides a kind's data. */
+    interface Provider {
+        readonly description?: string;
+        readonly logoSourceAddress?: string;
+        readonly logoTargetAddress?: string;
+    }
+}
+//# sourceMappingURL=IRichType.d.ts.map

package/types/src/Repeating.d.ts

@@ -46,12 +46,12 @@
  * omitted when there is a single repetition. `SORTBY`'s legal arities are 2 and 1+2n and nothing
  * else — `SORTBY(array, by1)` is legal, `SORTBY(array, by1, o1, by2)` is not. It is not a general
  * "the final element of the final group may be omitted" rule; that rule would accept a formula
- * Excel refuses. An optional slot anywhere else in the group is a compiler error.
+ * that must be refused. An optional slot anywhere else in the group is a compiler error.
  *
  * ### The maximum, `Max`
  *
- * The second type argument is the largest number of arguments the WHOLE CALL accepts, which is
- * how Excel states it: one number per NAME, compared against the call's total argument count and
+ * The second type argument is the largest number of arguments the WHOLE CALL accepts: one
+ * number per NAME, compared against the call's total argument count and
  * refused at entry (`Excess_function_arguments`), never a count of this parameter's own share.
  * `SWITCH`'s 254 therefore covers its `expression` and its trailing `default` as well as the
  * pairs, and `CHOOSEROWS`' covers its `array`.

package/types/src/ReportType.d.ts

@@ -27,8 +27,8 @@
  * what can arrive and {@link IFunctionArguments.getAreaCountAt} answers the union question the
  * kind cannot — a plain reference is one area, a union is more.
  *
- * Its use is meant to stay countable: a slot earns it with a rule Excel actually shows, never
- * with a guess.
+ * Its use is meant to stay countable: a slot earns it with a concrete behavior that needs it,
+ * never speculatively.
  *
  * @example
  * ```ts