@trebco/treb 29.5.2 → 29.6.2

package/dist/treb.d.ts

@@ -1,4 +1,4 @@
-/*! API v29.5. Copyright 2018-2024 trebco, llc. All rights reserved. LGPL: https://treb.app/license */
+/*! API v29.6. Copyright 2018-2024 trebco, llc. All rights reserved. LGPL: https://treb.app/license */
 
 /**
  * add our tag to the map
@@ -388,8 +388,6 @@ export declare class EmbeddedSpreadsheet<USER_DATA_TYPE = unknown> {
      * Use this function to batch multiple document changes. Essentially the
      * grid stops broadcasting events for the duration of the function call,
      * and collects them instead. After the function call we update as necessary.
-     *
-     * @public
      */
     Batch(func: () => void, paint?: boolean): Promise<void>;
 
@@ -964,6 +962,38 @@ export declare class EmbeddedSpreadsheet<USER_DATA_TYPE = unknown> {
      */
     Select(range?: RangeReference): void;
 
+    /**
+     *
+     * @param target - the target to paste data into. this can be larger
+     * than the clipboard data, in which case values will be recycled in
+     * blocks. if the target is smaller than the source data, we will expand
+     * it.
+     *
+     * @param data - clipboard data to paste.
+     *
+     * @param style - optional paste style. default is to paste formulas and
+     * source formatting. paste options can be usef to paste values, values
+     * and number formats, or retain the target formatting.
+     */
+    Paste(target?: RangeReference, data?: ClipboardData | undefined, options?: PasteOptions): Promise<void>;
+
+    /**
+     * copy data. this method returns the copied data. it does not put it on
+     * the system clipboard. this is for API access when the system clipboard
+     * might not be available.
+     */
+    Copy(source?: RangeReference): ClipboardData;
+
+    /**
+     * cut data. this method returns the cut data. it does not put it on the
+     * system clipboard. this method is similar to the Copy method, with
+     * two differences: (1) we remove the source data, effectively clearing
+     * the source range; and (2) the clipboard data retains references, meaning
+     * if you paste the data in a different location it will refer to the same
+     * cells.
+     */
+    Cut(source?: RangeReference): ClipboardData;
+
     /**
      *
      * @param range target range. leave undefined to use current selection.
@@ -1004,6 +1034,50 @@ export declare class EmbeddedSpreadsheet<USER_DATA_TYPE = unknown> {
     Cancel(token: number): void;
 }
 
+/**
+ * this is a structure for copy/paste data. clipboard data may include
+ * relative formauls and resolved styles, so it's suitable for pasting into
+ * other areas of the spreadsheet.
+ */
+export interface ClipboardDataElement {
+
+    /** calculated cell value */
+    calculated: CellValue;
+
+    /** the actual cell value or formula */
+    value: CellValue;
+
+    /** cell style. this may include row/column styles from the copy source */
+    style?: CellStyle;
+}
+
+/** clipboard data is a 2d array */
+export type ClipboardData = ClipboardDataElement[][];
+
+/**
+ * optional paste options. we can paste formulas or values, and we
+ * can use the source style, target style, or just use the source
+ * number formats.
+ */
+export interface PasteOptions {
+
+    /**
+     * when clipboard data includes formulas, optionally paste calculated
+     * values instead of the original formulas. defaults to false.
+     */
+    values?: boolean;
+
+    /**
+     * when pasting data from the clipboard, we can copy formatting/style
+     * from the original data, or we can retain the target range formatting
+     * and just paste data. a third option allows pasting source number
+     * formats but dropping other style information.
+     *
+     * defaults to "source", meaning paste source styles.
+     */
+    formatting?: 'source' | 'target' | 'number-formats';
+}
+
 /**
  * options for saving files. we add the option for JSON formatting.
  */
@@ -1087,46 +1161,6 @@ export interface SheetScrollOptions {
  * function type used for filtering tables
  */
 export type TableFilterFunction = (value: CellValue, calculated_value: CellValue, style: CellStyle) => boolean;
-export interface FreezePane {
-    rows: number;
-    columns: number;
-}
-
-/**
- * options for serializing data
- */
-export interface SerializeOptions {
-
-    /** optimize for size */
-    optimize?: 'size' | 'speed';
-
-    /** include the rendered/calculated value in export */
-    rendered_values?: boolean;
-
-    /** translate colors to xlsx-friendly values */
-    export_colors?: boolean;
-
-    /** export cells that have no value, but have a border or background color */
-    decorated_cells?: boolean;
-
-    /** prune unused rows/columns */
-    shrink?: boolean;
-
-    /**
-     * include tables. tables will be serialized in the model, so we can
-     * drop them from cells. but you can leave them in if that's useful.
-     */
-    tables?: boolean;
-
-    /** share resources (images, for now) to prevent writing data URIs more than once */
-    share_resources?: boolean;
-
-    /**
-     * if a function has an export() handler, call that
-     */
-    export_functions?: boolean;
-}
-export type AnnotationType = 'treb-chart' | 'image' | 'textbox' | 'external';
 
 /**
  * Structure represents a 2d range of cells.
@@ -1350,6 +1384,46 @@ export interface EvaluateOptions {
      */
     r1c1?: boolean;
 }
+export interface FreezePane {
+    rows: number;
+    columns: number;
+}
+
+/**
+ * options for serializing data
+ */
+export interface SerializeOptions {
+
+    /** optimize for size */
+    optimize?: 'size' | 'speed';
+
+    /** include the rendered/calculated value in export */
+    rendered_values?: boolean;
+
+    /** translate colors to xlsx-friendly values */
+    export_colors?: boolean;
+
+    /** export cells that have no value, but have a border or background color */
+    decorated_cells?: boolean;
+
+    /** prune unused rows/columns */
+    shrink?: boolean;
+
+    /**
+     * include tables. tables will be serialized in the model, so we can
+     * drop them from cells. but you can leave them in if that's useful.
+     */
+    tables?: boolean;
+
+    /** share resources (images, for now) to prevent writing data URIs more than once */
+    share_resources?: boolean;
+
+    /**
+     * if a function has an export() handler, call that
+     */
+    export_functions?: boolean;
+}
+export type AnnotationType = 'treb-chart' | 'image' | 'textbox' | 'external';
 export declare type BorderConstants = "none" | "all" | "outside" | "top" | "bottom" | "left" | "right";
 
 /**
@@ -1589,23 +1663,6 @@ export interface SelectionEvent {
 export interface FocusViewEvent {
     type: 'focus-view';
 }
-export interface SerializedMacroFunction {
-    name: string;
-    function_def: string;
-    argument_names?: string[];
-    description?: string;
-}
-
-/**
- * this type is no longer in use, but we retain it to parse old documents
- * that use it.
- *
- * @deprecated
- */
-export interface SerializedNamedExpression {
-    name: string;
-    expression: string;
-}
 
 /**
  * serialized type is a composite of expression/range. we determine
@@ -1970,6 +2027,23 @@ export interface Corner {
     address: ICellAddress;
     offset: AddressOffset;
 }
+export interface SerializedMacroFunction {
+    name: string;
+    function_def: string;
+    argument_names?: string[];
+    description?: string;
+}
+
+/**
+ * this type is no longer in use, but we retain it to parse old documents
+ * that use it.
+ *
+ * @deprecated
+ */
+export interface SerializedNamedExpression {
+    name: string;
+    expression: string;
+}
 
 /**
  * options for exporting CSV/TSV

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@trebco/treb",
-  "version": "29.5.2",
+  "version": "29.6.2",
   "license": "LGPL-3.0-or-later",
   "homepage": "https://treb.app",
   "repository": {

package/treb-calculator/src/functions/matrix-functions.ts

@@ -147,7 +147,7 @@ export const MatrixFunctionLibrary: FunctionMap = {
   },
 
   MMult: {
-    description: 'Returns the dot product of A and B',
+    description: 'Returns the dot product A ⋅ B',
     arguments: [
       { name: 'A', boxed: true }, 
       { name: 'B', boxed: true }, 

package/treb-data-model/src/data_model.ts

@@ -21,34 +21,13 @@
 
 import type { Sheet } from './sheet';
 import { SheetCollection } from './sheet_collection';
+import { type UnitAddress, type UnitStructuredReference, type UnitRange, Parser, QuotedSheetNameRegex, DecimalMarkType, ArgumentSeparatorType } from 'treb-parser';
 import type { IArea, ICellAddress, Table, CellStyle } from 'treb-base-types';
-import type { SerializedSheet } from './sheet_types';
-import { type ExpressionUnit, type UnitAddress, type UnitStructuredReference, type UnitRange, Parser, QuotedSheetNameRegex, DecimalMarkType, ArgumentSeparatorType } from 'treb-parser';
 import { Area, IsCellAddress, Style } from 'treb-base-types';
 import type { SerializedNamed } from './named';
 import { NamedRangeManager } from './named';
+import type { ConnectedElementType, MacroFunction } from './types';
 
-export interface ConnectedElementType {
-  formula: string;
-  update?: (instance: ConnectedElementType) => void;
-  internal?: unknown; // opaque type to prevent circular dependencies
-}
-
-export interface SerializedMacroFunction {
-  name: string;
-  function_def: string;
-  argument_names?: string[];
-  description?: string;
-}
-
-/**
- * we define this as extending the serialized version, rather
- * than taking out the parameter, so we can make that def public
- * in the API types.
- */
-export interface MacroFunction extends SerializedMacroFunction {
-  expression?: ExpressionUnit;
-}
 
 /**
  * 
@@ -546,43 +525,3 @@ export class DataModel {
 
 }
 
-/**
- * @internal
- */
-export interface ViewModel {
-  active_sheet: Sheet;
-  view_index: number;
-}
-
-/** 
- * this type is no longer in use, but we retain it to parse old documents
- * that use it. 
- * 
- * @deprecated
- */
-export interface SerializedNamedExpression {
-  name: string;
-  expression: string;
-}
-
-export interface SerializedModel {
-  sheet_data: SerializedSheet[];
-  active_sheet: number;
-
-  /** @deprecated */
-  named_ranges?: Record<string, IArea>;
-
-  /** @deprecated */
-  named_expressions?: SerializedNamedExpression[];
-
-  /** 
-   * new type for consolidated named ranges & expressions. the old
-   * types are retained for backwards compatibility on import but we won't 
-   * export them anymore.
-   */
-  named?: SerializedNamed[];
-
-  macro_functions?: MacroFunction[];
-  tables?: Table[];
-  decimal_mark?: ','|'.';
-}

package/treb-data-model/src/index.ts

@@ -20,16 +20,6 @@
  */
 
 export { DataModel } from './data_model';
-
-export type { 
-  MacroFunction, 
-  ConnectedElementType,
-  SerializedNamedExpression, 
-  SerializedModel, 
-  ViewModel, 
-  SerializedMacroFunction,
-} from './data_model';
-
 export type { SerializedNamed } from './named';
 
 export { Sheet } from './sheet';
@@ -43,3 +33,5 @@ export type { ViewData as AnnotationViewData } from './annotation';
 export type { AnnotationData, AnnotationType } from './annotation';
 
 export * from './data-validation';
+export * from './types';
+

package/treb-data-model/src/serialize_options.ts

@@ -74,4 +74,9 @@ export interface SerializeOptions {
    */
   export_functions?: boolean;
 
+  /**
+   * @internal
+   */
+  apply_row_pattern?: boolean;
+
 }

package/treb-data-model/src/sheet.ts

@@ -2519,8 +2519,6 @@ export class Sheet {
 
     // same here (note broken naming)
     const sheet_style = JSON.parse(JSON.stringify(this.sheet_style));
-    // const row_style = JSON.parse(JSON.stringify(this.row_styles));
-    // const column_style = JSON.parse(JSON.stringify(this.column_styles));
     const row_pattern = JSON.parse(JSON.stringify(this.row_pattern));
 
     // row and column styles are Record<number, props> and not arrays.
@@ -2545,13 +2543,36 @@ export class Sheet {
       }
     }
 
-    for (const key of Object.keys(this.row_styles)) {
-      const index = Number(key);
-      const style = this.row_styles[index];
-      if (style) {
-        const reference = StyleToRef(style);
+    if (this.row_pattern && this.row_pattern.length && options.apply_row_pattern) {
+
+      let count = this.rows + 1;
+
+      for (const key of Object.keys(this.row_styles)) {
+        const index = Number(key);
+        if (!isNaN(index) && index >= count) { count = index + 1; }
+      }
+
+      for (let i = 0; i< count; i++) {
+        const pattern = this.row_pattern[i % this.row_pattern.length];
+        const style = this.row_styles[i] || {}; 
+        const composite = Style.Composite([pattern, style]);      
+        const reference = StyleToRef(composite);
+
         if (reference) {
-          row_style[index] = reference;
+          row_style[i] = reference;
+        }
+      }
+      
+    }
+    else {
+      for (const key of Object.keys(this.row_styles)) {
+        const index = Number(key);
+        const style = this.row_styles[index];
+        if (style) {
+          const reference = StyleToRef(style);
+          if (reference) {
+            row_style[index] = reference;
+          }
         }
       }
     }

package/treb-data-model/src/types.ts

@@ -0,0 +1,71 @@
+
+import type { SerializedSheet } from './sheet_types';
+import type { Sheet } from './sheet';
+import type { IArea } from 'treb-base-types';
+import type { SerializedNamed } from './named';
+import type { Table } from 'treb-base-types';
+import type { ExpressionUnit } from 'treb-parser';
+
+export interface ConnectedElementType {
+  formula: string;
+  update?: (instance: ConnectedElementType) => void;
+  internal?: unknown; // opaque type to prevent circular dependencies
+}
+
+export interface SerializedMacroFunction {
+  name: string;
+  function_def: string;
+  argument_names?: string[];
+  description?: string;
+}
+
+/**
+ * we define this as extending the serialized version, rather
+ * than taking out the parameter, so we can make that def public
+ * in the API types.
+ */
+export interface MacroFunction extends SerializedMacroFunction {
+  expression?: ExpressionUnit;
+}
+
+/**
+ * @internal
+ */
+export interface ViewModel {
+  active_sheet: Sheet;
+  view_index: number;
+}
+
+/** 
+ * this type is no longer in use, but we retain it to parse old documents
+ * that use it. 
+ * 
+ * @deprecated
+ */
+export interface SerializedNamedExpression {
+  name: string;
+  expression: string;
+}
+
+export interface SerializedModel {
+  sheet_data: SerializedSheet[];
+  active_sheet: number;
+
+  /** @deprecated */
+  named_ranges?: Record<string, IArea>;
+
+  /** @deprecated */
+  named_expressions?: SerializedNamedExpression[];
+
+  /** 
+   * new type for consolidated named ranges & expressions. the old
+   * types are retained for backwards compatibility on import but we won't 
+   * export them anymore.
+   */
+  named?: SerializedNamed[];
+
+  macro_functions?: MacroFunction[];
+  tables?: Table[];
+  decimal_mark?: ','|'.';
+}
+