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

package/types/src/dataValidation/IDataValidation.d.ts

@@ -1,4 +1,4 @@
-import { IRange } from '@sheetxl/primitives';
+import { IRange, Scalar } from '@sheetxl/primitives';
 import { ReferenceableClipboard } from '@sheetxl/utils';
 import { ITransaction } from '../transaction';
 import { IHistory } from '../history';
@@ -9,10 +9,19 @@ import { ICondition } from '../condition';
 import { ICellRange, ICellRanges } from '../cellRange';
 import { IDataValidationCollection } from './IDataValidationCollection';
 /**
- * Represents a data validation range.
+ * A data validation: a rule that a cell's value must satisfy, over one or more ranges of a sheet,
+ * with the prompt shown when the cell is selected and the alert for a value that fails.
  *
  * @remarks
- * Used for modifying the type and rules of a data validation entry.
+ * Validations may overlap, and every one covering a cell applies: the cell is valid only when each
+ * of them accepts its value. Where a single answer is needed, the rule with the lowest
+ * {@link getIndex} wins: the prompt is the first covering rule's that has one, the alert the first
+ * failing rule's, and the dropdown offers the items every covering list rule accepts. Excel keeps
+ * one validation per cell, and when it opens a file whose validations overlap it honors only the
+ * first; see {@link ICell.getDataValidation}.
+ *
+ * The rule judges the value a cell holds, whatever wrote it. A value set through the API, pasted
+ * or filled is never refused; it is simply invalid, and {@link getAlertAt} says so.
  */
 export interface IDataValidation extends IAnchored, ICondition.Stateful {
     /** @inheritdoc ICondition.Stateful.getCondition */
@@ -22,27 +31,83 @@ export interface IDataValidation extends IAnchored, ICondition.Stateful {
      */
     setCondition(condition: ICondition.Input | null, options?: ITransaction.OperationOptions): this;
     /**
-     * Creates a default condition for the data validation based on its range and the data.
-     */
-    createDefaultCondition(): ICondition;
-    /**
-     * Returns the validation results at the specified cell coordinates.
+     * Whether the cell at the specified coordinates fails this validation.
+     *
+     * @param rowIndex The sheet row.
+     * @param columnIndex The sheet column.
      *
      * @remarks
-     * If there are multiple validations this will return the first one to fail.
+     * This validation's answer alone. Where validations overlap, a cell is invalid when any of the
+     * ones covering it fails ({@link ICellRange.getDataValidations}).
+     *
+     * An empty cell fails when Ignore blank is off ({@link isIncludeBlanks} is `false`) and the rule
+     * rejects a blank there, as Excel's Circle Invalid Data circles it. With Ignore blank on, an
+     * empty cell never fails. A cell holding `""` (a formula's empty text) is a value, and is judged.
      */
     getAlertAt(rowIndex: number, columnIndex: number): boolean;
     /**
-     * Returns an iterator that allows you to iterate over the individual alert entries within the range,
-     * yielding pairs of `IteratorContext` and a `Value`.
+     * The cells that fail this validation, each as a `[coords, true]` entry, empty cells included.
+     *
+     * @param options `axis` and `reverse` set the order within each of the validation's ranges; the
+     * ranges are visited in their own order.
      *
-     * @returns An iterator that yields `ICellRange.Entry<IDataValidation.Results>` tuples for each value within the range.
+     * @remarks
+     * Lazy: the cost is what the caller reads. Stop early to pay for the first few entries only. When
+     * empty cells pass (Ignore blank on), they are skipped without being visited. When they fail, a
+     * whole-column rule yields every one of its empty cells, so take what you need.
      */
     getAlertEntries(options?: ICellRange.IteratorOptions): IGrid.EntryIterator<boolean>;
     /**
-     * Returns the count of alert entries within the range.
+     * The number of cells that fail this validation, empty cells included.
+     *
+     * @remarks
+     * A rule that judges every empty cell alike (no formula) counts them without visiting any. A rule
+     * with a formula, a custom formula or a range list source, reads each empty cell's answer, so
+     * the first call over a large range can be slow. The answer is kept until the values change.
      */
     getAlertCount(): number;
+    /**
+     * The items a list validation offers at a cell: what its in-cell dropdown lists.
+     *
+     * @param rowIndex The cell's row.
+     * @param columnIndex The cell's column. A relative source (`$F1:$G1`, `INDIRECT($E1)`) gives each
+     *                    cell its own list, as it does in Excel.
+     *
+     * @returns The set's members: its `items`, then what its `source` lists in source order,
+     *          duplicates kept, then its typed `additions`, with any `subtractions` left out. Empty
+     *          when this is not a list validation or the set lists nothing. Blank source cells are
+     *          not listed.
+     *
+     * @remarks
+     * Evaluated when asked, for one cell — the check itself does not need the items, so nothing is
+     * resolved until a dropdown or a preview asks. `text` is what a source cell shows (a date list
+     * reads as dates), the item itself for a typed one.
+     */
+    getListItemsAt(rowIndex: number, columnIndex: number): Promise<readonly IDataValidation.ListItem[]>;
+    /**
+     * Whether an entry would pass this validation if it were typed into a cell: the check a cell
+     * editor makes before it writes.
+     *
+     * @param input What would be written, as `setValue` takes it. Text is read as typed text is: a
+     *              number, a date or a boolean when it reads as one, a formula when it starts with
+     *              `=`. Any other value is taken as is.
+     * @param rowIndex The cell's row.
+     * @param columnIndex The cell's column.
+     *
+     * @returns `false` when the entry fails. `true` when it passes, when the cell is outside this
+     *          validation, or when the validation has no condition.
+     *
+     * @remarks
+     * Nothing is written. A formula is judged by its result at that cell (`=9` fails a whole number
+     * between 1 and 5). A blank entry passes whatever {@link isIncludeBlanks} says, as typed entry does
+     * in Excel. Everything else is read as it stands, so a rule that reads the cell itself
+     * (`=COUNTIF($A:$A,A1)=1`) sees the value the cell holds now, not the entry — as Excel does.
+     *
+     * This validation's answer alone, whatever {@link isShowAlertMessage} says: the caller decides
+     * which validations to ask and what to show. Excel asks the active cell's rule only, and only for
+     * what is typed or picked; a value set through the API, pasted or filled is never checked.
+     */
+    validateInputAt(input: string | Scalar, rowIndex: number, columnIndex: number): Promise<boolean>;
     /**
      * Set whether to suppress the in-cell dropdown arrow for a list validation.
      *
@@ -59,10 +124,11 @@ export interface IDataValidation extends IAnchored, ICondition.Stateful {
      */
     isHideDropdown(): boolean;
     /**
-     * Message for a user prompt.
+     * The message shown while a cell the rule covers is selected (Excel's *Input Message*).
      *
      * @remarks
-     * This may be a tooltip or other indicator depending on the client.
+     * Shown only while {@link isShowPromptMessage} is on. Where validations overlap, the first
+     * covering rule with a prompt shows its own.
      */
     setPromptMessage(message: string, options?: ITransaction.OperationOptions): this;
     /**
@@ -80,7 +146,11 @@ export interface IDataValidation extends IAnchored, ICondition.Stateful {
      */
     getPromptTitle(): string;
     /**
-     * Sets whether to show the prompt message when the cell is selected.
+     * Sets whether to show the prompt when a cell the rule covers is selected.
+     *
+     * @remarks
+     * Separate from the prompt's text, as in Excel: turning the prompt off keeps its title and
+     * message, and turning it back on shows them again.
      */
     setShowPromptMessage(show: boolean, options?: ITransaction.OperationOptions): this;
     /**
@@ -88,7 +158,7 @@ export interface IDataValidation extends IAnchored, ICondition.Stateful {
      */
     isShowPromptMessage(): boolean;
     /**
-     * Message text of the alert.
+     * The message of the alert raised for a value that fails the rule (Excel's *Error Message*).
      */
     setAlertMessage(message: string, options?: ITransaction.OperationOptions): this;
     /**
@@ -106,7 +176,11 @@ export interface IDataValidation extends IAnchored, ICondition.Stateful {
      */
     getAlertTitle(): string;
     /**
-     * Sets whether to show the alert message when the cell is selected.
+     * Sets whether a value that fails the rule raises the alert when a user enters it.
+     *
+     * @remarks
+     * With the alert off, a failing entry is accepted silently, whatever the {@link getAlertStyle}.
+     * It is still invalid: {@link getAlertAt} reports it either way.
      */
     setShowAlertMessage(show: boolean, options?: ITransaction.OperationOptions): this;
     /**
@@ -114,12 +188,20 @@ export interface IDataValidation extends IAnchored, ICondition.Stateful {
      */
     isShowAlertMessage(): boolean;
     /**
-     * Sets the style of the alert shown when validation fails.
+     * Sets the style of the alert raised when a user enters a value that fails the rule.
      *
      * @remarks
-     * This controls whether alert values are blocked (`Stop`),
-     * allowed with a warning (`Warning`), or allowed with an informational
-     * message (`Information`).
+     * `Stop` refuses the entry, `Warning` asks before accepting it, and `Information` accepts it with
+     * a message. Where validations overlap, the first failing rule's style is the one used.
+     *
+     * The alert answers what a user types or picks, as in Excel. A value written through the API,
+     * pasted or filled raises no alert and is never refused.
+     *
+     * The style applies only while {@link setShowAlertMessage} is on. With it off, an invalid entry
+     * is accepted without a word whatever the style, as in Excel, so a rule meant to refuse entry
+     * needs both.
+     *
+     * @defaultValue `Stop`
      */
     setAlertStyle(alertStyle: IDataValidation.AlertStyle, options?: ITransaction.OperationOptions): this;
     /**
@@ -127,10 +209,15 @@ export interface IDataValidation extends IAnchored, ICondition.Stateful {
      */
     getAlertStyle(): IDataValidation.AlertStyle;
     /**
-     * If the cell has custom rendering.
+     * How a cell the rule covers asks to be drawn and edited, as keywords a client may honor.
      *
      * @remarks
-     * This could be a list or a checkbox or a custom editor
+     * Derived from the condition, never stored on it: a rule whose param carries candidates (its
+     * operator {@link ICondition.IOperator.getCandidates | lists them}, as `inSet` does under any
+     * selector) answers `list`, which is what an in-cell dropdown is shown for; a rule under a date selector
+     * answers `date` and `calendar`, under the time selector `time` and `clock`. Whether the
+     * dropdown is actually shown is the rule's own {@link isHideDropdown}. Empty when the rule has
+     * no condition or nothing to ask for.
      */
     getRenderHints(): readonly string[];
     /**
@@ -154,18 +241,22 @@ export interface IDataValidation extends IAnchored, ICondition.Stateful {
      */
     update(update: Partial<IDataValidation.Properties> | IDataValidation, options?: ITransaction.OperationOptions): this;
     /**
-     * Returns the index of this data validation within its container.
+     * Returns the index of this data validation within its container: its priority, `0` first.
+     *
+     * @remarks
+     * Where validations overlap, the lowest index supplies the prompt and the alert style; see
+     * {@link IDataValidation}. The writer saves the rules in this order.
      */
     getIndex(): number;
     /**
      * Sets the index of this data validation within its container.
-     * @param index The new index to set.
+     * @param index The new index to set. See {@link getIndex}.
      */
     setIndex(index: number): this;
     /**
      * Re-anchors this rule to `address`, REPLACING every range it currently covers.
      *
-     * @param address The range or ranges to cover — anything `ISheet.getRanges` accepts
+     * @param address The range or ranges to cover — anything `IWorksheet.getRanges` accepts
      *   (`'A1:C20'`, `'A1:A5, C1:C5'`, coords). Resolved against this rule's own sheet.
      * @param options Transaction options; `description` names the entry in undo history.
      *
@@ -199,7 +290,7 @@ export interface IDataValidation extends IAnchored, ICondition.Stateful {
     readonly isIDataValidation: true;
 }
 /**
- * Capabilities for working with conditional styling ranges.
+ * Types for working with data validations.
  *
  * @see
  * ### **Interface**
@@ -215,19 +306,28 @@ export declare namespace IDataValidation {
      */
     const AlertStyle: {
         /**
-         * Stops the user from entering alert data.
+         * Refuses an invalid entry.
          */
         readonly Stop: "stop";
         /**
-         * Shows a warning message when the user enters alert data.
+         * Warns about an invalid entry and asks whether to keep it.
          */
         readonly Warning: "warning";
         /**
-         * Shows an information message when the user enters alert data.
+         * Accepts an invalid entry with an informational message.
          */
         readonly Information: "information";
     };
     type AlertStyle = typeof AlertStyle[keyof typeof AlertStyle];
+    /**
+     * One item a list validation offers. See {@link IDataValidation.getListItemsAt}.
+     */
+    interface ListItem {
+        /** The value a pick enters. */
+        value: Scalar;
+        /** The item as shown. */
+        text: string;
+    }
     /**
      * A set of values that can be set on a IDataValidation.
      *
@@ -235,12 +335,31 @@ export declare namespace IDataValidation {
      * {@link IDataValidation}
      */
     interface Properties {
+        /** See {@link IDataValidation.setPromptMessage}. */
         prompt?: string;
+        /** See {@link IDataValidation.setPromptTitle}. */
         promptTitle?: string;
+        /**
+         * See {@link IDataValidation.setShowPromptMessage}.
+         *
+         * @defaultValue false
+         */
         showPromptMessage?: boolean;
+        /** See {@link IDataValidation.setAlertMessage}. */
         alert?: string;
+        /** See {@link IDataValidation.setAlertTitle}. */
         alertTitle?: string;
+        /**
+         * See {@link IDataValidation.setShowAlertMessage}.
+         *
+         * @defaultValue false
+         */
         showAlertMessage?: boolean;
+        /**
+         * See {@link IDataValidation.setAlertStyle}.
+         *
+         * @defaultValue `Stop`
+         */
         alertStyle?: IDataValidation.AlertStyle;
         /**
          * The predicate a value must satisfy to be valid.

package/types/src/dataValidation/IDataValidationCollection.d.ts

@@ -7,7 +7,8 @@ import { IDataValidation } from './IDataValidation';
  */
 export interface IDataValidationCollection extends ICollection<IDataValidation> {
     /**
-     * Returns items that match the filter criteria.
+     * Returns items that match the filter criteria, in priority order
+     * ({@link IDataValidation.getIndex}).
      *
      * If no filter criteria is provided, all items will be returned.
      *
@@ -18,7 +19,12 @@ export interface IDataValidationCollection extends ICollection<IDataValidation>
      * Add an `IDataValidation` to the container.
      *
      * @param address The address of the item. May name several discontiguous ranges.
-     * @param options Additional options available when adding a table or a `boolean` that indicates if the table has headers.
+     * @param options The new validation's properties, and where it goes in priority order.
+     *
+     * @remarks
+     * A validation already covering some of the cells keeps them, and both apply there (see
+     * {@link IDataValidation}); Excel's dialog would replace it. To take cells away from an existing
+     * validation, clear them first with `ICellRange.clear(ICell.Content.DataValidations)`.
      */
     add(address: ICellRanges.Address | IDataValidation, options?: IDataValidationCollection.AddOptions): IDataValidation;
     /**
@@ -27,6 +33,16 @@ export interface IDataValidationCollection extends ICollection<IDataValidation>
      * @param template A template to use for the temporary item.
      */
     createItem(template?: IDataValidation): IDataValidation;
+    /**
+     * The sheet-wide validation settings.
+     *
+     * @remarks
+     * Carried from the file (`dataValidations` `disablePrompts`, `xWindow`, `yWindow`); there is no
+     * setter, as Excel offers none. Excel keeps them only while the sheet has a validation.
+     */
+    getSettings(): Readonly<IDataValidationCollection.Settings>;
+    /** For runtime type checking. */
+    readonly isIDataValidationCollection: true;
 }
 /**
  * {@inheritDoc IDataValidationCollection}
@@ -36,6 +52,22 @@ export interface IDataValidationCollection extends ICollection<IDataValidation>
  * {@link IDataValidationCollection}
  */
 export declare namespace IDataValidationCollection {
+    /**
+     * See {@link IDataValidationCollection.getSettings}.
+     */
+    interface Settings {
+        /**
+         * No validation on the sheet shows its prompt message, whatever its
+         * {@link IDataValidation.isShowPromptMessage}.
+         *
+         * @defaultValue false
+         */
+        disablePrompts?: boolean;
+        /** The left of the prompt window, in pixels, as the file states it. Not used to place the prompt. */
+        windowX?: number;
+        /** The top of the prompt window, in pixels, as the file states it. Not used to place the prompt. */
+        windowY?: number;
+    }
     /**
      * Options for adding a data validation to the collection.
      *

package/types/src/date/DateUtils.d.ts

@@ -1,3 +1,23 @@
+/**
+ * The unit a date step counts — what makes one date series a different series from another.
+ *
+ * @remarks
+ * `Weekday` is a BUSINESS day: Saturday and Sunday are not units of it, so `Fri` plus one weekday
+ * is the following Monday.
+ *
+ * @see {@link IAutoFill.DateSeries}, which reports the unit a template turns out to hold.
+ */
+export declare const DateUnit: {
+    /** A calendar day. */
+    readonly Day: "d";
+    /** A business day — Saturday and Sunday are skipped. */
+    readonly Weekday: "wd";
+    /** A calendar month, the day-of-month carried across it. */
+    readonly Month: "m";
+    /** A calendar year. */
+    readonly Year: "y";
+};
+export type DateUnit = typeof DateUnit[keyof typeof DateUnit];
 /**
  * Returns Date.now() rounded to a nearest time.
  *

package/types/src/date/_DateUtils.d.ts

@@ -1,5 +1,6 @@
 import { NumberFormatRef } from '../numFmt/BuiltInFormats';
 import { IRuntime } from '@sheetxl/primitives';
+import { DateUnit } from './DateUtils';
 export declare const MAX_SERIAL_DATE = 2958465;
 export declare function isValidDate(d: any, jsDateOnly?: boolean): boolean;
 export declare function minutesSinceMidnight(date: Date): number;
@@ -7,12 +8,82 @@ export declare function dayDiff(d1: Date, d2: Date): number;
 export declare function monthDiff(startDate: Date, endDate: Date): number;
 export declare function yearDiff(d1: Date, d2: Date): number;
 export declare function dateUnitDiff(d1: Date, d2: Date, unit: DateUnit | string): number | undefined;
-export declare const DateUnit: {
-    readonly Day: "d";
-    readonly Month: "m";
-    readonly Year: "y";
-};
-export type DateUnit = typeof DateUnit[keyof typeof DateUnit];
+/**
+ * Days in a 1-based `month` — the real calendar. Excel's phantom `1900-02-29` is not modelled here;
+ * `serialFromCivil` carries it in serial space, which is where it matters.
+ */
+export declare function daysInMonth(year: number, month: number): number;
+/**
+ * The month a serial falls in, as a single ordinal, so a whole-month delta is plain subtraction.
+ * `NaN` for a serial outside the calendar.
+ */
+export declare function serialMonthOrdinal(serial: number, date1904?: boolean): number;
+/** The day-of-month a serial falls on, or `NaN` for a serial outside the calendar. */
+export declare function serialDayOfMonth(serial: number, date1904?: boolean): number;
+/** `true` when the serial falls on the last day of its own month. */
+export declare function serialIsMonthEnd(serial: number, date1904?: boolean): boolean;
+/**
+ * Step `count` whole months in SERIAL space — no `Date` is constructed. The day-of-month is kept
+ * where the target month is long enough and clamped where it is not (Excel's `EDATE`: Jan 31 plus
+ * one month is Feb 28), and because every step is measured from the same anchor serial a day
+ * clamped through a short month recovers afterwards (Dec 29 → Feb 28 → Mar 29).
+ *
+ * @param monthEnd Land on the target month's LAST day instead — Excel's end-of-month series, where
+ * Feb 28 continues Mar 31, Apr 30 rather than Mar 28, Apr 28.
+ *
+ * @remarks
+ * The time-of-day fraction rides along untouched.
+ */
+export declare function addMonthsToSerial(serial: number, count: number, monthEnd?: boolean, date1904?: boolean): number;
+/**
+ * `true` when the serial falls on a Saturday or a Sunday.
+ *
+ * @remarks
+ * A weekend serial has no business day of its own, so this is what a caller checks before reading
+ * {@link serialWeekdayOrdinal} as a position: the ordinal rounds a weekend forward to the following
+ * Monday, which is right for stepping and wrong for deciding whether a template is a weekday series.
+ */
+export declare function serialIsWeekend(serial: number, date1904?: boolean): boolean;
+/**
+ * A serial's position in the run of BUSINESS days, so a difference of two of these is a count of
+ * weekdays — `Fri` to the following `Mon` is `1`, not `3`.
+ *
+ * @remarks
+ * A weekend serial has no business day of its own and takes the following Monday's, which makes
+ * this monotonic but not injective: `Sat`, `Sun` and `Mon` all report the same ordinal, so a
+ * template of weekend dates reads as a step of zero rather than as a series.
+ */
+export declare function serialWeekdayOrdinal(serial: number, date1904?: boolean): number;
+/**
+ * Step `count` BUSINESS days in SERIAL space — Saturday and Sunday are skipped, and no `Date` is
+ * constructed. The time-of-day fraction rides along untouched.
+ *
+ * @remarks
+ * A weekend anchor is not a business day, so it steps off in the direction of travel first: a
+ * Saturday going forward is one step from Monday (Excel's `Fri + 1` and `Sat + 1` are both Monday),
+ * and going back is one step from Friday. A `count` of zero simply lands on the next business day,
+ * which is what Excel's weekday series does from a weekend.
+ */
+export declare function addWeekdaysToSerial(serial: number, count: number, date1904?: boolean): number;
+/** The number of days in `month` (0-based) of `year` — JS day `0` is the previous month's last. */
+export declare function lastDayOfMonth(year: number, month: number): number;
+/** `true` when `date` falls on the last day of its own month. */
+export declare function isMonthEnd(date: Date): boolean;
+/** A date's month as a single ordinal, so a whole-month delta is plain subtraction. */
+export declare function monthOrdinal(date: Date): number;
+/**
+ * Step `count` whole months from `date`, keeping the day-of-month where the target month is long
+ * enough and clamping it where it is not — Excel's `EDATE`: Jan 31 plus one month is Feb 28, NOT
+ * March 3. Because every step is measured from the same anchor, a day clamped through a short month
+ * recovers afterwards (Dec 29 → Feb 28 → Mar 29).
+ *
+ * @param monthEnd Land on the target month's LAST day instead of the anchor's day — Excel's
+ * end-of-month series, where Feb 28 continues Mar 31, Apr 30 rather than Mar 28, Apr 28.
+ *
+ * @remarks
+ * Time-of-day is carried through untouched.
+ */
+export declare function addMonthsClamped(date: Date, count: number, monthEnd?: boolean): Date;
 export declare function addDateUnit(date: Date, count: number, unit: DateUnit | string): Date | null;
 export declare function stringToLocalDate(value: string): Date | null;
 export declare function isISODateString(value: string): boolean;
@@ -46,6 +117,19 @@ export interface ParsedDateTime {
 /**
  * Splits a serial date into its calendar and clock fields.
  *
+ * @remarks
+ * Excel resolves a serial to whole seconds by adding HALF A SECOND TO THE SERIAL and then
+ * truncating — not by rounding the seconds themselves. The distinction is measurable, because
+ * the addition happens at the serial's magnitude, where a day is ~3e-7 s wide in the last bit:
+ * 12:30:30.5 comes back as :30 (the half second is lost in the sum) while 23:59:59.5 comes back
+ * as the next day's midnight. So a serial within half a second of midnight belongs to the NEXT
+ * day, in every field at once — `DAY`, `MONTH`, `YEAR` and `WEEKDAY` move together with the
+ * clock.
+ *
+ * Not every date function reads its argument through this. `WEEKNUM`, `ISOWEEKNUM`, `DAYS`,
+ * `EDATE`, `EOMONTH`, `WORKDAY` and `NETWORKDAYS` TRUNCATE the same serial instead, and each
+ * floors before it gets here — a per-function fact, not a rule with exceptions.
+ *
  * @param reuseParts Avoids allocating a fresh `ParsedDateTime`:
  * - An object: the fields are written into THIS object, which is returned. The caller owns the
  *   buffer's lifetime — do not hold onto a previous result across a reused call, each call
@@ -60,7 +144,7 @@ export declare function parseSerialDate(serialDate: number, date1904?: boolean,
  * Serial date from parsed date/time fields.
  *
  * Computed directly from the fields (see {@link serialFromFields}) rather than
- * by building a JS `Date` and converting it — that round trip was both lossy
+ * by building a JS `Date` and converting it — that round trip is both lossy
  * (~1e-12, catastrophic for bare times) and unable to express Excel's phantom
  * `1900-02-29`, which a `Date` normalizes away.
  */

package/types/src/documentProperties/DocumentProperties.d.ts

@@ -0,0 +1,66 @@
+import { IDocumentProperties } from './IDocumentProperties';
+import { ICustomProperty } from './ICustomProperty';
+type CustomValue = string | number | boolean | Date;
+/**
+ * {@link ICustomProperty} held as its JSON, owned by a {@link DocumentProperties}.
+ */
+declare class CustomProperty implements ICustomProperty {
+    private _json;
+    private readonly _owner;
+    constructor(json: ICustomProperty.JSON, owner: DocumentProperties);
+    getKey(): string;
+    getType(): ICustomProperty.Type;
+    getLinkTarget(): string | null;
+    getValue(): CustomValue;
+    setValue(value: CustomValue): void;
+    delete(): void;
+    toJSON(): ICustomProperty.JSON;
+}
+/**
+ * {@link IDocumentProperties} held as its JSON.
+ *
+ * @param assertOpen Throws when the owning workbook is closed; called before every change.
+ */
+export declare class DocumentProperties implements IDocumentProperties {
+    /** Everything but {@link IDocumentProperties.JSON.custom}, which is {@link _custom}. */
+    private _json;
+    private _custom;
+    private readonly _assertOpen;
+    constructor(assertOpen: () => void);
+    private _text;
+    private _setText;
+    getAuthor(): string | null;
+    setAuthor(author: string | null): this;
+    getCategory(): string | null;
+    setCategory(category: string | null): this;
+    getComments(): string | null;
+    setComments(comments: string | null): this;
+    getCompany(): string | null;
+    setCompany(company: string | null): this;
+    getContentStatus(): string | null;
+    setContentStatus(contentStatus: string | null): this;
+    getCreationDate(): Date | null;
+    getKeywords(): string | null;
+    setKeywords(keywords: string | null): this;
+    getLastAuthor(): string | null;
+    getManager(): string | null;
+    setManager(manager: string | null): this;
+    getRevisionNumber(): number | null;
+    setRevisionNumber(revisionNumber: number | null): this;
+    getSubject(): string | null;
+    setSubject(subject: string | null): this;
+    getTitle(): string | null;
+    setTitle(title: string | null): this;
+    getCustom(): ICustomProperty[];
+    getCustomProperty(key: string): ICustomProperty | undefined;
+    addCustomProperty(key: string, value: CustomValue): ICustomProperty;
+    deleteAllCustomProperties(): void;
+    /** @internal Throws when `property` can no longer change: the workbook is closed or it was deleted. */
+    _assertCustomEditable(property: CustomProperty): void;
+    /** @internal */
+    _removeCustom(property: CustomProperty): void;
+    fromJSON(json: IDocumentProperties.JSON | undefined): void;
+    toJSON(): IDocumentProperties.JSON;
+}
+export {};
+//# sourceMappingURL=DocumentProperties.d.ts.map

package/types/src/documentProperties/ICustomProperty.d.ts

@@ -0,0 +1,69 @@
+/**
+ * A property a user or an application added to the workbook: a name and a value. Saved with the
+ * workbook; it affects nothing else.
+ *
+ * @remarks
+ * Shaped after Office Scripts' `CustomProperty`.
+ *
+ * @see {@link IDocumentProperties.getCustom}
+ */
+export interface ICustomProperty {
+    /** The property's name. Unique within the workbook, ignoring case. */
+    getKey(): string;
+    /** The kind of value, chosen by {@link setValue} from the value it is given. */
+    getType(): ICustomProperty.Type;
+    /**
+     * The property's value. A {@link ICustomProperty.Type.Date} property returns a `Date`.
+     */
+    getValue(): string | number | boolean | Date;
+    /**
+     * Sets {@link getValue}, and with it {@link getType}: a whole number that fits in 32 bits is a
+     * {@link ICustomProperty.Type.Number}, any other number a {@link ICustomProperty.Type.Float}.
+     */
+    setValue(value: string | number | boolean | Date): void;
+    /**
+     * The defined name the value is linked to ("Link to content"), or `null` when it is not linked.
+     *
+     * @remarks
+     * VBA's `DocumentProperty.LinkSource`. Carried from the file: SheetXL does not refresh the value
+     * from the name, and {@link setValue} keeps the link.
+     */
+    getLinkTarget(): string | null;
+    /** Removes the property from the workbook. */
+    delete(): void;
+    /** For persisting. */
+    toJSON(): ICustomProperty.JSON;
+}
+export declare namespace ICustomProperty {
+    /**
+     * The kind of value a custom property holds. Shaped after Office Scripts' `DocumentPropertyType`.
+     */
+    const Type: {
+        /** A whole number. */
+        readonly Number: "number";
+        /** `true` or `false`. */
+        readonly Boolean: "boolean";
+        /** A point in time. */
+        readonly Date: "date";
+        /** Text. */
+        readonly String: "string";
+        /** A number with a fraction, or one too large for {@link ICustomProperty.Type.Number}. */
+        readonly Float: "float";
+    };
+    type Type = typeof Type[keyof typeof Type];
+    /**
+     * The serialized form.
+     */
+    interface JSON {
+        key: string;
+        type: Type;
+        /** A {@link ICustomProperty.Type.Date} is an ISO 8601 string in UTC. */
+        value: string | number | boolean;
+        /**
+         * A defined name the value is kept in step with. The value is the last one the name gave;
+         * an application that understands the link refreshes it.
+         */
+        linkTarget?: string;
+    }
+}
+//# sourceMappingURL=ICustomProperty.d.ts.map