@trebco/treb 23.6.5 → 25.0.0-rc2

package/treb-grid/src/types/grid_command.ts

@@ -0,0 +1,470 @@
+/*
+ * This file is part of TREB.
+ *
+ * TREB is free software: you can redistribute it and/or modify it under the 
+ * terms of the GNU General Public License as published by the Free Software 
+ * Foundation, either version 3 of the License, or (at your option) any 
+ * later version.
+ *
+ * TREB is distributed in the hope that it will be useful, but WITHOUT ANY 
+ * WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS 
+ * FOR A PARTICULAR PURPOSE. See the GNU General Public License for more 
+ * details.
+ *
+ * You should have received a copy of the GNU General Public License along 
+ * with TREB. If not, see <https://www.gnu.org/licenses/>. 
+ *
+ * Copyright 2022-2023 trebco, llc. 
+ * info@treb.app
+ * 
+ */
+
+import type { ICellAddress, IArea, Style, CellValue, Table, TableSortType, TableTheme } from 'treb-base-types';
+import type { ExpressionUnit } from 'treb-parser';
+import type { BorderConstants } from './border_constants';
+
+/**
+ * switching to an exec-command based model, so we can serialize
+ * data, layout and style changes; the intent is to support recording,
+ * replaying, and transmitting modifications.
+ *
+ * NOTE regarding commands: let's make them as explicit as possible
+ * (meaning fewer optional parameters). force callers to populate fields.
+ *
+ */
+
+/**
+ * commands are symbolic for (hopefully) faster switching. we use a
+ * discriminated union for build-time parameter checks. see individual
+ * command interfaces for comments.
+ */
+export enum CommandKey {
+
+  /** use an empty value so all commands are non-zero */
+  Null = 0,
+
+  InsertRows,
+  InsertColumns,
+  ResizeRows,
+  ResizeColumns,
+  Select,
+  SetRange,
+  UpdateStyle,
+  UpdateBorders,
+  MergeCells,
+  UnmergeCells,
+  Clear,
+  UpdateTheme,
+  SetNote,
+  SetLink,
+  Freeze,
+  SetName,
+  ShowHeaders,
+  AddSheet,
+  DuplicateSheet,
+  DeleteSheet,
+  ActivateSheet,
+  RenameSheet,
+  ReorderSheet,
+  ShowSheet,
+  DataValidation,
+  Reset,
+  SortTable,
+  InsertTable,
+  RemoveTable,
+
+}
+
+/** base type for sheet commands -- can select sheet by name, id or index */
+export interface SheetSelection {
+  index?: number;
+  name?: string;
+  id?: number;
+}
+
+/**
+ * show or hide sheet.
+ */
+export interface ShowSheetCommand extends SheetSelection {
+  key: CommandKey.ShowSheet;
+  show: boolean;
+}
+
+/*
+export interface CommandBase {
+
+  / **
+   * support commands that are not added to any recording or log.
+   * this is for things like resizing rows/columns -- we don't necessarily
+   * want to transmit every event, and if we don't support ephemeral commands
+   * we will wind up working around the exec-command system, which I would
+   * like to avoid.
+   * /
+  ephemeral?: boolean;
+
+}
+*/
+
+/**
+ * insert a table at the given location
+ */
+export interface InsertTableCommand {
+  key: CommandKey.InsertTable,
+  area: IArea,
+
+  /** optionally include a totals row */
+  totals?: boolean,
+
+  /** 
+   * sortable. defaults to true. you can optionally 
+   * disable sorting, if you want.
+   */
+  sortable?: boolean,
+
+  /**
+   * optional theme
+   */
+  theme?: TableTheme,
+
+}
+
+/**
+ * remove the table
+ */
+export interface RemoveTableCommand {
+  key: CommandKey.RemoveTable,
+  table: Table,
+}
+
+/**
+ * sort a table. sorts are hard, meaning we actually move data around.
+ * use copy/paste semantics for handling relative references (seems strange
+ * to me, but hey).
+ */
+export interface SortTableCommand {
+  key: CommandKey.SortTable,
+  table: Table,
+  column: number,
+  asc: boolean;
+  type: TableSortType,
+}
+
+/**
+ * resize row(s). undefined means "all rows". undefined height
+ * means "auto size".
+ * 
+ * UPDATE: shrink is a flag you can set to prevent shrinking rows
+ * when (and only when) auto-sizing, i.e. height is undefined
+ */
+export interface ResizeRowsCommand {
+  key: CommandKey.ResizeRows;
+  row?: number|number[];
+  height?: number;
+  shrink?: boolean;
+  sheet_id?: number;
+}
+
+/**
+ * resize columns(s). undefined means "all columns". undefined
+ * width means "auto size".
+ */
+export interface ResizeColumnsCommand {
+  key: CommandKey.ResizeColumns;
+  column?: number|number[];
+  width?: number;
+  sheet_id?: number;
+}
+
+/** insert one or more rows at the given insert point */
+export interface InsertRowsCommand {
+  key: CommandKey.InsertRows;
+  before_row: number;
+  count: number;
+  sheet_id?: number;
+}
+
+/** insert one or more columns at the given insert point */
+export interface InsertColumnsCommand {
+  key: CommandKey.InsertColumns;
+  before_column: number;
+  count: number;
+  sheet_id?: number;
+}
+
+/** show or hide headers */
+export interface ShowHeadersCommand {
+  key: CommandKey.ShowHeaders;
+  show: boolean;
+}
+
+/** 
+ * set or clear name (omit range to clear)
+ *  
+ * adding support for named expressions. you can pass either a range or
+ * an expression. 
+ * 
+ * if you use the same name more than once, it will overwrite the old name,
+ * even if you change types range/expression.
+ * 
+ * passing neither will cause it to erase any existing named range OR named 
+ * expression. 
+ * 
+ */
+export interface SetNameCommand {
+  key: CommandKey.SetName;
+  name: string;
+  area?: IArea;
+  expression?: ExpressionUnit;
+}
+
+export interface DataValidationCommand {
+  key: CommandKey.DataValidation;
+  area: ICellAddress;
+  range?: IArea;
+  list?: CellValue[];
+  error?: boolean;
+}
+
+/**
+ * not sure if we should be serializing selections...
+ * we need some indication of primary/alternative
+ */
+export interface SelectCommand {
+  key: CommandKey.Select;
+
+  /** missing area implies clear selection (-> no selection) */
+  area?: IArea;
+
+  /** missing target will set target as first cell of area */
+  target?: ICellAddress;
+}
+
+/** set data in cell or area */
+export interface SetRangeCommand {
+  key: CommandKey.SetRange;
+  area: IArea|ICellAddress;
+
+  /** set as array (usually control-enter) */
+  array?: boolean;
+
+  /** 
+   * support R1C1 notation, which can come from API only (atm). this 
+   * flag does not mean the notation _is_ R1C1, just that we need to
+   * check for it and handle it if found.
+   */
+  r1c1?: boolean;
+
+  /** missing data implies clear cell(s) */
+  value?: CellValue|CellValue[][];
+}
+
+/** update borders for the given area. this is different than updating
+ * style, because borders have slightly different semantics -- when applied
+ * to an area, for example, "outside border" means the outside of the total
+ * area, not the outside of each cell.
+ */
+export interface UpdateBordersCommand {
+  key: CommandKey.UpdateBorders;
+  area: IArea;
+  borders: BorderConstants;
+  // color?: string; // pending
+  color?: Style.Color;
+
+  /** defaults to one. optional for the case of "none" (remove borders) */
+  width?: number;
+}
+
+/** update style in area. area can be cell(s), sheet, row(s), column(s) */
+export interface UpdateStyleCommand {
+  key: CommandKey.UpdateStyle;
+  area: IArea|ICellAddress;
+  style: Style.Properties;
+  delta?: boolean;
+}
+
+/** merge the given cells */
+export interface MergeCellsCommand {
+  key: CommandKey.MergeCells;
+  area: IArea;
+}
+
+/**
+ * unmerge the given cells. if the passed area doesn't exactly match a
+ * merge area, we will look for merge areas inside the larger area and
+ * unmerge those (generally useful when working with selections).
+ */
+export interface UnmergeCellsCommand {
+  key: CommandKey.UnmergeCells;
+  area: IArea;
+}
+
+/** set or clear note at given address. */
+export interface SetNoteCommand {
+  key: CommandKey.SetNote;
+  area: ICellAddress;
+  note?: string;
+}
+
+export interface SetLinkCommand {
+  key: CommandKey.SetLink;
+  area: ICellAddress;
+  reference?: string;
+}
+
+/**
+ * clear an area, or the entire sheet.
+ * 
+ * because this command can omit area (meaning entire sheet), to
+ * support remotes we need to add a separate parameter for sheet id.
+ * 
+ * we could use infinite area as an indication it's a reset, but that's
+ * not really the same thing -- that would be more like select all / clear.
+ * 
+ * not sure why clear doubled as reset, except that it probably dated
+ * from before we had multiple sheets. we're now splitting so there's an
+ * explicit reset event.
+ * 
+ * now that we have a separate reset, clear requires an area. 
+ * 
+ */
+export interface ClearCommand {
+  key: CommandKey.Clear;
+  area: IArea;
+  // sheet_id?: number;
+}
+
+/**
+ * reset everything. 
+ */
+export interface ResetCommand {
+  key: CommandKey.Reset;
+}
+
+/**
+ * set freeze area. set rows and columns to 0 to unfreeze.
+ * highlight defaults to TRUE.
+ */
+export interface FreezeCommand {
+  key: CommandKey.Freeze;
+  rows: number;
+  columns: number;
+  highlight_transition?: boolean;
+  sheet_id?: number;
+}
+
+/**
+ * FIXME: should this command include theme properties, or can we
+ * base it on the local theme? (...) probably the former, otherwise
+ * you lose synchronization
+ * /
+export interface UpdateThemeCommand {
+  key: CommandKey.UpdateTheme;
+}
+*/
+
+export interface NullCommand {
+  key: CommandKey.Null;
+}
+
+export interface AddSheetCommand {
+  key: CommandKey.AddSheet;
+  insert_index?: number;
+  name?: string;
+  
+  /** switch to the sheet immediately */
+  show?: boolean;
+}
+
+export interface DuplicateSheetCommand extends SheetSelection {
+  key: CommandKey.DuplicateSheet;
+  new_name?: string;
+  insert_before?: string|number;
+}
+
+export interface DeleteSheetCommand extends SheetSelection {
+  key: CommandKey.DeleteSheet;
+}
+
+/**
+ * activate a sheet. there are a couple of options for selecting
+ * the sheet, defaulting to index (which defaults to 0) so if you
+ * pass no selector it will select index 0.
+ */
+export interface ActivateSheetCommand extends SheetSelection {
+  key: CommandKey.ActivateSheet;
+
+  /** ... */
+  tab_bar_event?: boolean;
+
+  force?: boolean;
+}
+
+/**
+ * rename a sheet. options are like ActivateSheetCommand, except we
+ * have to be a little careful about name old/new
+ */
+export interface RenameSheetCommand extends SheetSelection {
+  key: CommandKey.RenameSheet;
+  new_name: string; // required
+}
+
+/**
+ * reorder sheet; move sheet (X) before (Y). if (Y) is larger than the
+ * list length, moves to end.
+ */
+export interface ReorderSheetCommand {
+  key: CommandKey.ReorderSheet;
+  index: number;
+  move_before: number;
+}
+
+/**
+ * ephemeral flag added to commands.
+ * /
+export interface Ephemeral {
+  ephemeral?: boolean;
+}
+*/
+
+/**
+ * composite command type and ephemeral flag
+ */
+export type Command =
+  ( NullCommand
+  | ClearCommand
+  | ResetCommand
+  | SelectCommand
+  | FreezeCommand
+  | SetNoteCommand
+  | SetLinkCommand
+  | SetNameCommand
+  | AddSheetCommand
+  | SetRangeCommand
+  | SortTableCommand
+  | ShowSheetCommand
+  | MergeCellsCommand
+  | ResizeRowsCommand
+  | InsertRowsCommand
+  | ShowHeadersCommand
+  | DeleteSheetCommand
+  | UpdateStyleCommand
+  | InsertTableCommand
+  | RemoveTableCommand
+  | RenameSheetCommand
+  | ReorderSheetCommand
+  | UnmergeCellsCommand
+  | ResizeColumnsCommand
+  | InsertColumnsCommand
+  | UpdateBordersCommand
+  | ActivateSheetCommand
+  | DataValidationCommand
+  | DuplicateSheetCommand
+  ) ; // & Ephemeral;
+
+/**
+ * record type for recording/logging commands
+ */
+export interface CommandRecord {
+  command: Command[];
+  timestamp: number;
+}

package/treb-grid/src/types/grid_events.ts

@@ -0,0 +1,124 @@
+/*
+ * This file is part of TREB.
+ *
+ * TREB is free software: you can redistribute it and/or modify it under the 
+ * terms of the GNU General Public License as published by the Free Software 
+ * Foundation, either version 3 of the License, or (at your option) any 
+ * later version.
+ *
+ * TREB is distributed in the hope that it will be useful, but WITHOUT ANY 
+ * WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS 
+ * FOR A PARTICULAR PURPOSE. See the GNU General Public License for more 
+ * details.
+ *
+ * You should have received a copy of the GNU General Public License along 
+ * with TREB. If not, see <https://www.gnu.org/licenses/>. 
+ *
+ * Copyright 2022-2023 trebco, llc. 
+ * info@treb.app
+ * 
+ */
+
+import type { GridSelection } from './grid_selection';
+import type { Annotation } from './annotation';
+import type { Sheet } from './sheet';
+import type { Area } from 'treb-base-types';
+
+export enum ErrorCode {
+
+  /** no error: zero so it's falsy */
+  none = 0,
+
+  /** placeholder for new errors */
+  unknown,
+
+  /** you can't change part of an array */
+  array,
+
+  /** invalid value (data validation) */
+  data_validation,
+
+  /** invalid area for insert table: there's a merge, array or existing table within the range */
+  invalid_area_for_table,
+
+}
+
+export interface SheetChangeEvent {
+  type: 'sheet-change';
+  activate: Sheet;
+  deactivate: Sheet;
+}
+
+export interface GridSelectionEvent {
+  type: 'selection';
+  selection: GridSelection;
+}
+
+export interface GridAlternateSelectionEvent {
+  type: 'alternate-selection';
+  selection: GridSelection;
+}
+
+/**
+ * we used to return strings here, changed to error codes for l10n
+ */
+export interface GridErrorEvent {
+  type: 'error';
+  code: ErrorCode;
+}
+
+export interface StructureEvent {
+  type: 'structure';
+
+  /**
+   * this flag should be set if the structure change changes references,
+   * insert or delete events. resize events don't need to set it.
+   *
+   * FIXME: merge/unmerge? (...) I think yes
+   */
+  rebuild_required?: boolean;
+}
+
+export interface AnnotationEvent {
+  type: 'annotation';
+  annotation?: Annotation;
+  event?: 'move'|'resize'|'create'|'delete'|'update';
+}
+
+export interface CellEvent {
+  type: 'cell-event',
+  data?: any,
+}
+
+export interface DataEvent {
+  type: 'data';
+  area?: Area;
+}
+
+export interface FlushEvent {
+  type: 'flush';
+}
+
+export interface StyleEvent {
+  type: 'style';
+  area?: Area;
+}
+
+export interface ScaleEvent {
+  type: 'scale';
+  scale: number;
+}
+
+export type GridEvent
+  = DataEvent
+  | CellEvent
+  | StyleEvent
+  | FlushEvent
+  | ScaleEvent
+  | GridErrorEvent
+  | StructureEvent
+  | AnnotationEvent
+  | SheetChangeEvent
+  | GridSelectionEvent
+  | GridAlternateSelectionEvent
+  ;

package/treb-grid/src/types/grid_options.ts

@@ -0,0 +1,97 @@
+/*
+ * This file is part of TREB.
+ *
+ * TREB is free software: you can redistribute it and/or modify it under the 
+ * terms of the GNU General Public License as published by the Free Software 
+ * Foundation, either version 3 of the License, or (at your option) any 
+ * later version.
+ *
+ * TREB is distributed in the hope that it will be useful, but WITHOUT ANY 
+ * WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS 
+ * FOR A PARTICULAR PURPOSE. See the GNU General Public License for more 
+ * details.
+ *
+ * You should have received a copy of the GNU General Public License along 
+ * with TREB. If not, see <https://www.gnu.org/licenses/>. 
+ *
+ * Copyright 2022-2023 trebco, llc. 
+ * info@treb.app
+ * 
+ */
+
+import type { CellValue } from 'treb-base-types';
+import type { StatsEntry } from './tab_bar';
+
+export type StatsFunction = (data: CellValue|CellValue[][]|undefined) => StatsEntry[];
+
+export interface GridOptions {
+
+  /** can expand rows/columns */
+  expand?: boolean;
+
+  /**
+   * if you are running a calculator, you might not want the grid
+   * to repaint any time there's a data change (which is the default
+   * behavior).
+   */
+  repaint_on_cell_change?: boolean;
+
+  /** support in-cell editing */
+  in_cell_editor?: boolean;
+
+  /** show the formula bar (and allow editing; TODO: read-only option) */
+  formula_bar?: boolean;
+
+  /** show the tab bar */
+  tab_bar?: boolean|'auto';
+
+  /** scale controls. implies tab bar */
+  scale_control?: boolean;
+
+  /** stats panel. implies tab bar */
+  stats?: boolean|StatsFunction;
+
+  /** save/load scale to storage, with the given key */
+  persist_scale_key?: string;
+
+  /** allow add tab */
+  add_tab?: boolean;
+
+  /** show delete tab in the tab bar */
+  delete_tab?: boolean;
+
+  /** show the "insert function" button. requires formula bar. */
+  insert_function_button?: boolean;
+
+  /** button to increase/reduce size of formula editor */
+  expand_formula_button?: boolean;
+
+  /** scale (wip) */
+  // scale?: number;
+
+  /** enable scrolling (default true) */
+  scrollbars?: boolean;
+
+  /** always show grid, even if there is background color */
+  grid_over_background?: boolean;
+
+  /** initial scale for layout */
+  initial_scale?: number;
+
+  /** support MD formatting in text */
+  markdown?: boolean;
+
+}
+
+export const DefaultGridOptions: GridOptions = {
+  scrollbars: true,
+  in_cell_editor: true,
+  formula_bar: true,
+  add_tab: false,
+  tab_bar: 'auto',
+  insert_function_button: false,
+  expand_formula_button: false,
+  expand: true,
+  repaint_on_cell_change: true,
+  grid_over_background: false, // true,
+};