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

package/types/src/cell/ICell.d.ts

@@ -1,7 +1,7 @@
 import { Scalar, ScalarType, InteropScalarType, InteropScalar, IRange } from '@sheetxl/primitives';
 import { Size, Rectangle, Bounds } from '@sheetxl/utils';
 import { ITypes } from '../type';
-import { ITextFrame, TextRotation } from '../text';
+import { ITextFrame, TextRotation, TextStacked } from '../text';
 import { NumberFormat } from '../numFmt';
 import { ITable } from '../table';
 import { IDataValidation } from '../dataValidation';
@@ -53,16 +53,21 @@ export interface ICell {
      * Returns the formula assigned to the cell.
      *
      * @remarks
-     * Returns `null` if the cell has no formula.
+     * Returns `null` if the cell has no formula, or if its protection hides the formula (see
+     * {@link ICell.isFormulaHidden}).
      */
     getFormula(options?: ICalculation.FormulaTextOptions): ICalculation.IFormula | null;
     /**
-     * Returns the formula text assigned to the cell, WITHOUT a leading `=`.
+     * Returns the formula text assigned to the cell, with its leading `=` (`'=SUM(A1:A3)'`).
      *
      * @remarks
-     * A convenience for `getFormula()?.getExpression()` — the stored shape, so `null` and `''` stay
-     * distinguishable from a formula and the text can be re-parsed as-is. Displaying it the way
-     * Excel's API answers means prefixing `'=' +`; see {@link ICalculation.IFormula.getExpression}.
+     * The form a formula is entered in and the form Excel's API answers, so it can be written back
+     * with {@link ICellRange.setValue}. The `=` is what keeps a formula like `=+A1` apart from the
+     * text `+A1`. For the stored form without the `=`, use
+     * {@link ICalculation.IFormula.getExpression} on {@link ICell.getFormula}.
+     *
+     * Returns `null` for a cell without a formula, and when protection hides the formula, like
+     * {@link ICell.getFormula}.
      */
     getFormulaText(options?: ICalculation.FormulaTextOptions): string | null;
     /**
@@ -77,35 +82,37 @@ export interface ICell {
      *
      * @remarks
      * These represent the direct inputs required to compute the cell's value.
-     * Returns `null` if the cell has no precedents.
+     * Resolves `null` if the cell has no precedents.
+     * A question for the calculation engine: it resolves once the engine has answered, in order
+     * behind the writes made before it, and with `null` while the engine is `Off`.
      */
-    getDirectPrecedents(): ICellRanges;
+    getDirectPrecedents(): Promise<ICellRanges | null>;
     /**
      * Returns the cells that directly reference this cell in their own formulas.
      *
      * @remarks
      * These represent the immediate consumers of this cell's value.
-     * Returns `null` if the cell has no dependents.
+     * Resolves `null` if the cell has no dependents.
      */
-    getDirectDependents(): ICellRanges;
+    getDirectDependents(): Promise<ICellRanges | null>;
     /**
      * Returns all ranges that contribute to this cell's value, including
      * those referenced indirectly through the full calculation chain.
      *
      * @remarks
      * This performs a recursive search upstream to find all root data sources.
-     * Returns `null` if the cell has no precedents.
+     * Resolves `null` if the cell has no precedents.
      */
-    getPrecedents(): ICellRanges;
+    getPrecedents(): Promise<ICellRanges | null>;
     /**
      * Returns all cells that are eventually affected by this cell, including
      * those that depend on it indirectly through the full calculation chain.
      *
      * @remarks
      * This performs a recursive search downstream to find the total impact of a value change.
-     * Returns `null` if the cell has no dependents.
+     * Resolves `null` if the cell has no dependents.
      */
-    getDependents(): ICellRanges;
+    getDependents(): Promise<ICellRanges | null>;
     /**
      * Returns the hyperlink assigned to the cell.
      *
@@ -114,11 +121,13 @@ export interface ICell {
      */
     getHyperlink(): IHyperlink | null;
     /**
-     * Retrieves a list of comments associated with the cell.
+     * Returns the comment on the cell, or `null` if there is none.
      *
-     * **Note**: This feature is not yet implemented.
+     * @remarks
+     * One per cell — the thread's root, with its replies, or a note. The sheet's
+     * {@link ISheet.getComments} is where one is added.
      */
-    getComments(): Readonly<IComment.Properties>;
+    getComments(): IComment | null;
     /**
      * Retrieves any warnings attached to the cell.
      *
@@ -215,7 +224,11 @@ export interface ICell {
      */
     getBestFit(colWidth?: number, minContent?: boolean): Readonly<Partial<Size>> | null;
     /**
-     * Returns protection information.
+     * Returns the cell's protection format, the same as `getStyle().getProtection()`.
+     *
+     * @remarks
+     * Whether the cell can be edited right now also depends on its sheet and its unlocked ranges; see
+     * {@link ICell.isEditAllowed}.
      */
     getProtection(): ICellProtection;
     /**
@@ -237,6 +250,15 @@ export interface ICell {
      * Returns the range of the cell if it is a spill cell.
      */
     getSpill(): ICellRange | null;
+    /**
+     * Returns which {@link ITypes.FormulaArrayKind | kind} of array block the cell belongs to, or
+     * `null` if it is not part of one.
+     *
+     * @remarks
+     * Answers for every cell of the block, not only the anchor — a `fixed` (array-entered) block
+     * shows `{=…}` on all of its cells, as Excel does.
+     */
+    getSpillKind(): ITypes.FormulaArrayKind | null;
     /**
      * Returns `true` if the cell is a spill and not the top left.
      */
@@ -270,10 +292,13 @@ export interface ICell {
      */
     getColumn(): ITable.IColumn | null;
     /**
-     * Returns the data validation assigned to the cell if there is one.
+     * Returns the cell's primary data validation: the highest-priority one that covers it, or `null`
+     * when none does.
      *
      * @remarks
-     * Will return null if there is no data validation assigned.
+     * Validations may overlap, and every one that covers the cell applies; see
+     * {@link ICellRange.getDataValidations} for all of them. The primary one is also the one Excel
+     * honors when it opens a file whose validations overlap.
      */
     getDataValidation(): IDataValidation | null;
     /**
@@ -322,7 +347,13 @@ export interface ICell {
      */
     isEditAllowed(): boolean;
     /**
-     * Returns `true` if the formula is hidden.
+     * Returns `true` if protection hides this cell's formula.
+     *
+     * @remarks
+     * The sheet is protected (not paused), and neither the sheet's `showFormulas` nor the cell style's
+     * allows it.
+     * A hidden formula reads as no formula: {@link ICell.getFormula} and {@link ICell.getFormulaText}
+     * return `null`. It still calculates, and is still saved with the workbook.
      */
     isFormulaHidden(): boolean;
     /**
@@ -452,6 +483,13 @@ export declare namespace ICell {
          * horizontally. See {@link TextRotation.layoutLines} for the model.
          */
         rotation?: TextRotation.Layout;
+        /**
+         * Present when the cell's text is stacked ("vertical text"): per-column slot geometry — every
+         * glyph upright in its own slot of the line pitch, columns from line breaks (and from wrapping
+         * against the content height), each column aligned on its own. See
+         * {@link TextStacked.layoutColumns} for the model. {@link bounds} is then the column group.
+         */
+        stacked?: TextStacked.Layout;
     }
     /**
      * Expansive way to set cell updates options.
@@ -475,6 +513,10 @@ export declare namespace ICell {
          * Allow to to set a hyperlink to this value.
          */
         hyperlink?: IHyperlink.Update;
+        /**
+         * Update the comment: modifiers, a plain string as the content, or `null` to remove.
+         */
+        comments?: IComment.Update;
     }
     /**
      * Configuration options for customizing the parsing of a string into an `ICell.Update` object.
@@ -675,13 +717,26 @@ export declare namespace ICell {
         /**
          * Represents notes associated with the cells.
          * @remarks
-         * **NOT IMPLEMENTED**
+         * A note is a comment carrying `asNote` — the two share one store — so this selects the
+         * notes out of a range rather than naming a store of its own. Displaying a note as Excel's
+         * simple yellow box, rather than as a comment, is **NOT IMPLEMENTED**.
          */
         readonly Notes: "notes";
         /**
-         * Represents comments attached to the cells.
+         * Represents comments attached to the cells, notes included.
+         * @remarks
+         * Excel offers a single `Clear Comments and Notes`, and this is it. {@link Content.Notes}
+         * is the narrower one, for the notes alone.
          */
         readonly Comments: "comments";
+        /**
+         * Represents the data validations covering the cells.
+         * @remarks
+         * A clear cuts the cells out of every validation covering them; a validation left covering
+         * nothing is deleted, and one that also covers other cells keeps them. Office Scripts'
+         * `range.getDataValidation().clear()`.
+         */
+        readonly DataValidations: "dataValidations";
     };
     type Content = typeof Content[keyof typeof Content];
 }

package/types/src/cell/ICellProtection.d.ts

@@ -1,20 +1,52 @@
+import { IStyle } from '../style';
 /**
- * Additional cell protection properties.
+ * The protection format of a cell: whether it stays editable, and whether it shows its formula,
+ * while its sheet is protected.
  *
+ * @remarks
+ * * Part of the style, so it travels with the format — copy, paste, fill and named styles carry it,
+ *   and clearing formats resets it.
+ * * Only consulted while the sheet is protected. {@link ICell.isEditAllowed} and
+ *   {@link ICell.isFormulaHidden} combine it with the sheet's protection and its unlocked ranges.
  */
 export interface ICellProtection {
     /**
-     * This is specified in ooxml but not sure what behavior it has.
-     * @defaultValue true
+     * Returns `true` if the cell stays editable when its sheet is protected.
+     *
+     * @remarks
+     * * This is Excel's *Locked* format, inverted.
+     * * It never asks for a password, even inside a password-protected unlocked range. An unlocked
+     *   range is the other way to make a cell editable; either one is enough.
+     *
+     * @defaultValue false
      */
-    isEditAllowed(): boolean;
+    isAlwaysUnlocked(): boolean;
     /**
-     * If the formula will be hidden when the worksheet is protected.
+     * Sets whether the cell stays editable when its sheet is protected.
+     *
+     * @param alwaysUnlocked `true` to keep the cell editable. `null` to clear.
+     */
+    setAlwaysUnlocked(alwaysUnlocked: boolean | null, options?: IStyle.UpdateOptions): ICellProtection;
+    /**
+     * Returns `true` if the cell's formula stays visible on a protected sheet that hides formulas.
+     *
      * @remarks
-     * This is called hidden in ooxml but in Excel object model it is formulaHidden.
+     * * An exception, like {@link isAlwaysUnlocked}: a formula shows when the sheet
+     *   (`ISheetProtection.isShowFormulasAllowed`) or the cell allows it, so this only matters while
+     *   the sheet hides them.
+     * * A hidden formula reads as no formula ({@link ICell.getFormula} is `null`), but it still
+     *   calculates and is still saved with the workbook. It is a view rule, not secrecy.
+     *
      * @defaultValue false
      */
-    isFormulaHidden(): boolean;
+    isShowFormulas(): boolean;
+    /**
+     * Sets whether the cell's formula stays visible on a protected sheet that hides formulas.
+     *
+     * @param showFormulas `true` to keep the formula visible. `null` to clear.
+     */
+    setShowFormulas(showFormulas: boolean | null, options?: IStyle.UpdateOptions): ICellProtection;
+    toJSON(): ICellProtection.JSON;
     /**
      * For runtime type checking.
      */
@@ -29,13 +61,21 @@ export interface ICellProtection {
  */
 export declare namespace ICellProtection {
     /**
-     * Properties for ICellProperties.
+     * Properties for ICellProtection.
      */
     interface Properties {
-        edit?: boolean;
-        formulaHidden?: boolean;
+        alwaysUnlocked?: boolean;
+        showFormulas?: boolean;
     }
     interface JSON extends Properties {
     }
+    /**
+     * Modifiers describe a partial list of properties that can be set.
+     */
+    type Modifiers = Partial<ICellProtection.Properties>;
+    /**
+     * Options for updating an ICellProtection.
+     */
+    type Update = ICellProtection | Modifiers | null;
 }
 //# sourceMappingURL=ICellProtection.d.ts.map