@sheetxl/sdk 0.8.0-beta.1 → 0.8.0-beta.10

package/types/src/type/AbstractCollection.d.ts

@@ -0,0 +1,101 @@
+import { ITransaction } from '../transaction';
+import { IListener } from '../listener';
+import { ListenerEmitter } from '../listener/ListenerEmitter';
+import { ICollection } from './ICollection';
+/**
+ * Base for every {@link ICollection}.
+ *
+ * @remarks
+ * A subclass supplies {@link _getItems} — how its items are stored is its own business, keyed or
+ * ordered, held here or fronted from elsewhere — and gets iteration, the count and every read
+ * helper from that one call. A subclass with a cheaper count overrides {@link getCount}.
+ *
+ * Listeners are uniform: {@link addListeners} on the base, and {@link _notifyCollectionChange} /
+ * {@link _notifyInvalidated} for the subclass to announce with. A subclass that fronts another
+ * collection and forwards its events overrides `addListeners` instead of keeping a second
+ * emitter.
+ */
+export declare abstract class AbstractCollection<T, O extends ICollection.GetItemsOptions = ICollection.GetItemsOptions> implements ICollection<T> {
+    /**
+     * The store transactional listeners are versioned in; `undefined` gives the emitter a transient
+     * store of its own.
+     */
+    protected _transactions: ITransaction.IStore | undefined;
+    /** Created on first use — most collections are never listened to. */
+    private _collectionEmitter;
+    private _closed;
+    constructor(transactions?: ITransaction.IStore);
+    /** {@inheritDoc ICollection.isClosed} */
+    isClosed(): boolean;
+    /**
+     * Closes the collection: flips {@link isClosed} and announces
+     * {@link ICollection.Events.onClose} once.
+     *
+     * @remarks
+     * The base owns the fire so that the event can never be declared and not delivered. A
+     * subclass that is closable calls this from its public `close()` and does its own cleanup
+     * after; a second call is a no-op. The flag flips before the announcement, so a listener asking
+     * `isClosed()` while being told is told the truth.
+     */
+    protected _close(): void;
+    /**
+     * Returns the items, optionally filtered.
+     *
+     * @param options The subclass's own options; `undefined` is every item, in the collection's
+     * order.
+     *
+     * @remarks
+     * Return an array the caller may keep — a fresh one, or one the collection never mutates
+     * after handing it out — never the collection's own mutable storage. Every read on the base is
+     * over what this returns, and {@link toArray} returns it as-is.
+     */
+    protected abstract _getItems(options?: O): T[];
+    /** {@inheritDoc ICollection."[iterator]"} */
+    [Symbol.iterator](): IterableIterator<T>;
+    /** {@inheritDoc ICollection.getItems} */
+    getItems(options?: O): T[];
+    /** {@inheritDoc ICollection.getCount} */
+    getCount(): number;
+    /** {@inheritDoc ICollection.at} */
+    at(index: number): T | undefined;
+    /** {@inheritDoc ICollection.indexOf} */
+    indexOf(item: T): number;
+    /** {@inheritDoc ICollection.find} */
+    find<S extends T>(predicate: (value: T, index: number, items: readonly T[]) => value is S): S | undefined;
+    find(predicate: (value: T, index: number, items: readonly T[]) => boolean): T | undefined;
+    /** {@inheritDoc ICollection.findIndex} */
+    findIndex(predicate: (value: T, index: number, items: readonly T[]) => boolean): number;
+    /** {@inheritDoc ICollection.filter} */
+    filter<S extends T>(predicate: (value: T, index: number, items: readonly T[]) => value is S): S[];
+    filter(predicate: (value: T, index: number, items: readonly T[]) => boolean): T[];
+    /** {@inheritDoc ICollection.map} */
+    map<U>(fn: (value: T, index: number, items: readonly T[]) => U): U[];
+    /** {@inheritDoc ICollection.forEach} */
+    forEach(fn: (value: T, index: number, items: readonly T[]) => void): void;
+    /** {@inheritDoc ICollection.some} */
+    some(predicate: (value: T, index: number, items: readonly T[]) => boolean): boolean;
+    /** {@inheritDoc ICollection.every} */
+    every(predicate: (value: T, index: number, items: readonly T[]) => boolean): boolean;
+    /** {@inheritDoc ICollection.toArray} */
+    toArray(): T[];
+    /** {@inheritDoc ICollection.addListeners} */
+    addListeners(listeners: ICollection.IListeners, options?: IListener.Options): IListener.Remove;
+    protected _getCollectionEmitter(): ListenerEmitter<this, ICollection.Events>;
+    /**
+     * Announces {@link ICollection.Events.onCollectionChange}.
+     *
+     * @remarks
+     * Nothing is created for a collection nobody has listened to.
+     */
+    protected _notifyCollectionChange(): void;
+    /**
+     * Announces {@link ICollection.Events.onInvalidated}.
+     *
+     * @remarks
+     * Nothing is created for a collection nobody has listened to.
+     */
+    protected _notifyInvalidated(): void;
+    /** {@inheritDoc ICollection.isICollection} */
+    get isICollection(): true;
+}
+//# sourceMappingURL=AbstractCollection.d.ts.map

package/types/src/type/ICollection.d.ts

@@ -2,6 +2,16 @@ import { JSONSerializableAsync } from '@sheetxl/utils';
 import { IListener } from '../listener';
 /**
  * Interface used for all ICollections.
+ *
+ * @remarks
+ * A collection is the read side of a `ReadonlyArray` without the index operator: it iterates,
+ * counts, and offers the familiar helpers (`at`, `find`, `filter`, `map`, ...), but it is not an
+ * array and has no `[i]` or `length`. Call {@link toArray} when an array is really wanted.
+ *
+ * Iteration order is the collection's own order — insertion order for the ordered collections
+ * (sheets, tables, movables) and unspecified for the keyed ones (resources, functions). Every
+ * read is over a snapshot: neither {@link getItems} nor the helpers observe a change made while
+ * they run.
  */
 export interface ICollection<T> {
     /**
@@ -19,6 +29,11 @@ export interface ICollection<T> {
     [Symbol.iterator](): IterableIterator<T>;
     /**
      * Returns the items in the collection.
+     *
+     * @remarks
+     * The optioned call — filtering, ordering, anything parameterized — and a snapshot: the array
+     * returned does not follow later changes to the collection. For the unfiltered items as a plain
+     * array prefer {@link toArray}.
      */
     getItems(options?: ICollection.GetItemsOptions): T[];
     /**
@@ -28,6 +43,100 @@ export interface ICollection<T> {
      * returns the total number of items available.
      */
     getCount(): number;
+    /**
+     * Returns the item at the given index, or `undefined` if there is none.
+     *
+     * @param index The position in iteration order. A negative index counts back from the end, as
+     * `Array.prototype.at` does.
+     */
+    at(index: number): T | undefined;
+    /**
+     * Returns the index of the item in iteration order, or `-1` if it is not in the collection.
+     *
+     * @param item The item to find.
+     */
+    indexOf(item: T): number;
+    /**
+     * Returns the first item the predicate accepts, or `undefined` if it accepts none.
+     *
+     * @param predicate Called once per item in iteration order until it returns `true`.
+     */
+    find<S extends T>(predicate: (value: T, index: number, items: readonly T[]) => value is S): S | undefined;
+    /**
+     * Returns the first item the predicate accepts, or `undefined` if it accepts none.
+     *
+     * @param predicate Called once per item in iteration order until it returns `true`.
+     */
+    find(predicate: (value: T, index: number, items: readonly T[]) => boolean): T | undefined;
+    /**
+     * Returns the index of the first item the predicate accepts, or `-1` if it accepts none.
+     *
+     * @param predicate Called once per item in iteration order until it returns `true`.
+     */
+    findIndex(predicate: (value: T, index: number, items: readonly T[]) => boolean): number;
+    /**
+     * Returns the items the predicate accepts, in iteration order.
+     *
+     * @param predicate Called once per item.
+     */
+    filter<S extends T>(predicate: (value: T, index: number, items: readonly T[]) => value is S): S[];
+    /**
+     * Returns the items the predicate accepts, in iteration order.
+     *
+     * @param predicate Called once per item.
+     */
+    filter(predicate: (value: T, index: number, items: readonly T[]) => boolean): T[];
+    /**
+     * Returns the result of calling the function on every item, in iteration order.
+     *
+     * @param fn Called once per item.
+     */
+    map<U>(fn: (value: T, index: number, items: readonly T[]) => U): U[];
+    /**
+     * Calls the function once per item, in iteration order.
+     *
+     * @param fn Called once per item.
+     */
+    forEach(fn: (value: T, index: number, items: readonly T[]) => void): void;
+    /**
+     * Returns `true` if the predicate accepts at least one item.
+     *
+     * @param predicate Called once per item in iteration order until it returns `true`.
+     */
+    some(predicate: (value: T, index: number, items: readonly T[]) => boolean): boolean;
+    /**
+     * Returns `true` if the predicate accepts every item, including when there are none.
+     *
+     * @param predicate Called once per item in iteration order until it returns `false`.
+     */
+    every(predicate: (value: T, index: number, items: readonly T[]) => boolean): boolean;
+    /**
+     * Returns the items as a fresh array, in iteration order.
+     *
+     * @remarks
+     * The call to make when an array is really wanted. The array is the caller's: changing it does
+     * not change the collection, and it does not follow later changes to the collection.
+     */
+    toArray(): T[];
+    /**
+     * Returns `true` once the collection has been closed.
+     *
+     * @remarks
+     * A closed collection is empty and announces nothing further. Collections that are closed by
+     * their owner (the workbook's names, functions and modules, when the workbook closes) announce
+     * it once with {@link ICollection.Events.onClose}; the others are never closed and always
+     * return `false`.
+     */
+    isClosed(): boolean;
+    /**
+     * Add Listeners.
+     *
+     * @see
+     * {@link IListener.ISource.addListeners}
+     */
+    addListeners(listeners: ICollection.IListeners, options?: IListener.Options): IListener.Remove;
+    /** For runtime type checking. */
+    readonly isICollection: true;
 }
 /**
  * {@inheritDoc ICollection}
@@ -103,6 +212,14 @@ export declare namespace ICollection {
          * Called when the collection has been updated due to a undo/redo and a rerender is required.
          */
         onInvalidated?(source: ICollection<any>): void;
+        /**
+         * Called once, when the collection is closed.
+         *
+         * @remarks
+         * {@link ICollection.isClosed} is already `true` when this is delivered, and nothing is
+         * announced after it. Only the collections an owner closes ever fire it.
+         */
+        onClose?(source: ICollection<any>): void;
     }
     interface IListeners extends IListener.Callbacks<ICollection<any>, ICollection.Events> {
     }

package/types/src/type/ITypes.d.ts

@@ -30,16 +30,18 @@ export declare namespace ITypes {
      *
      * * `dynamic` - the extent is *derived from* the result. It spills, and it resizes when the
      *   result shape changes.
-     * * `dynamicSpillError` - a `dynamic` formula whose spill is currently blocked. The recorded
+     * * `error` - a `dynamic` formula whose spill is currently blocked (`#SPILL!`). The recorded
      *   extent collapses to the anchor cell.
-     * * `static` - legacy array-entered (Ctrl+Shift+Enter). The extent is *authoritative* and the
-     *   result is fitted to it; it never spills and never resizes.
+     * * `fixed` - array-entered (Ctrl+Shift+Enter). The extent is *authoritative* and the result is
+     *   fitted to it (a dimension of 1 broadcasts, a longer one is clipped, a shorter one is padded
+     *   with `#N/A`); it never spills and never resizes. Written through
+     *   {@link ICellRange.SetValuesOptions.arrayFixed}.
      *
-     * `static + spillError` is not a state: a stored fixed block owns its cells, so a spill
-     * collision is rejected at entry rather than detected at calc. That is what lets these three be
-     * one enum rather than two booleans.
+     * `fixed + error` is not a state: a fixed block owns its cells, so a write into part of it is
+     * refused at the write site rather than detected at calc. That is what lets these three be one
+     * enum rather than two booleans.
      */
-    type FormulaArrayKind = 'dynamic' | 'dynamicSpillError' | 'static';
+    type FormulaArrayKind = 'dynamic' | 'fixed' | 'error';
     /**
      * Options for controlling selection behavior, including scrolling and focus.
      */

package/types/src/type/index.d.ts

@@ -1,5 +1,6 @@
 export * from './ITypes';
 export * from './IProperties';
 export * from './ICollection';
+export * from './AbstractCollection';
 export * from './Registry';
 //# sourceMappingURL=index.d.ts.map

package/types/src/utils/_CSSUtils.d.ts

@@ -4,7 +4,7 @@ import { IColor } from '../color';
 import { IFill } from '../fill';
 import { IFont } from '../font';
 import { ITextFrame } from '../text';
-import { IBorder } from '../border';
+import { IBorders } from '../border';
 export interface ParsedFont {
     family: string | null;
     size?: string | null;
@@ -118,8 +118,8 @@ export declare function parsePattern(value: string): Partial<IFill.PatternProper
  */
 export declare const toCSSGradient: (gradientFill: IFill.IGradient, mode?: IColor.CSSMode, size?: Size | null) => string | null;
 export declare function toCSSPattern(patternType: IFill.BuiltInSheetPattern): string;
-export declare function toCSSBorderStroke(stroke: IBorder.IStroke): string | null;
-export declare function parseBorderStroke(value: string, parseColor?: (str: string) => string): IBorder.StrokeProperties | null;
+export declare function toCSSBorderStroke(stroke: IBorders.IStroke): string | null;
+export declare function parseBorderStroke(value: string, parseColor?: (str: string) => string): IBorders.StrokeProperties | null;
 /**
  * @see
  * {@link https://developer.mozilla.org/en-US/docs/Web/CSS/text-align}

package/types/src/wasm/_sdkWasm.d.ts

@@ -0,0 +1,7 @@
+import { WasmBindgenExports } from '@sheetxl/utils';
+import * as glue from '../../wasm/sdk.js';
+/** The binding's exports, once instantiated. */
+export type SdkWasmExports = WasmBindgenExports<typeof glue>;
+/** The binding's exports, instantiated and ready to call. */
+export declare const wasm: SdkWasmExports;
+//# sourceMappingURL=_sdkWasm.d.ts.map

package/types/src/wasm/index.d.ts

@@ -0,0 +1,2 @@
+export * from './sdkWasm';
+//# sourceMappingURL=index.d.ts.map

package/types/src/wasm/sdkWasm.d.ts

@@ -0,0 +1,29 @@
+import { SdkWasmExports } from './_sdkWasm';
+export type { SdkWasmExports } from './_sdkWasm';
+/**
+ * `@sheetxl/sdk`'s Rust code, compiled to WebAssembly, loaded on first use.
+ *
+ * @remarks
+ * Nothing is downloaded or compiled until {@link SdkWasm.load} is called. One module serves the
+ * browser and Node. Internal to the sdk: the measurer and the wrapper call it; nothing outside the
+ * package does, so it is not exported from the index.
+ *
+ * @example
+ * ```ts
+ * const wasm = await SdkWasm.load();
+ * wasm.line_pitch(12, 3); // 17
+ * ```
+ */
+export declare const SdkWasm: {
+    /**
+     * Loads and instantiates the WebAssembly, or returns it if it is already loaded.
+     *
+     * @remarks
+     * Concurrent calls share one attempt; a failed attempt is retried by the next call. Rejects with
+     * a `LazyLoadError`.
+     */
+    load: () => Promise<SdkWasmExports>;
+    /** The exports if the WebAssembly has loaded, otherwise `undefined`. */
+    peek: () => SdkWasmExports | undefined;
+};
+//# sourceMappingURL=sdkWasm.d.ts.map