Gridsheet#

Note

Installation#

$ npm install @gridsheet/react-core --save

How to use#

Simple example.

import * as React from "react";
import { GridSheet } from "@gridsheet/react-core";

export default function App() {
  return (<div>
    <GridSheet
      initialCells={{
        default: {style: { fontStyle: "italic" }},
        A: {style: backgroundColor: "#ddf", width: 300},
        3: {height: 100},
        A1: {value: "a", style: {color: "#00f"}},
        B1: {value: 1},
        C1: {value: true},
        A2: {value: "b"},
        B2: {value: 2},
        C2: {value: false},
        B1: {value: 3},
      }}
      options={{ // Optional
      }}
      className="some-class"
      style={{ maxWidth: "100%" }}
    />
  </div>);
}

Another example using matrix.

import * as React from "react";
import { GridSheet, constructInitialCells } from "@gridsheet/react-core";

export default function App() {
  return (<div>
    <GridSheet
      initialCells={
        constructInitialCells({
          matrices: {
            A1: [
              ["a", 1, true],
              ["b", 2, false],
              ["c", undefined, null],
            ],
          }
          cells: {
            A1: {
              style: {color: "#50f"}
            },
            B3: {
              value: 33,
            },
          }
        })
      }
      options={{ // Optional
      }}
      className="some-class"
      style={{ maxWidth: "100%" }}
    />
  </div>);
}

Note

More examples are here.

initialCells prop#

This prop affects the cells matching the keys.

Key rules:

  • default (lowercase) field matches all rows, columns and cells.

    • You can set default height and width here.

      • defaultHeight and defaultWidth has been dropped.

  • An upppercase letter field means a config for a column.

    • e.g. A: 1st column, B: 2nd column

  • A number Fields means a config for a row.

    • e.g. 1: 1st row, 2: 2nd row.

  • An upppercase letter + A number field means a unique cell.

    • e.g. A1: Most top left cell.

    • If a cell matches multiple cell configs, it applys the configs in the following order: cell > column > row > default.

Value of the cell is an object having following keys.

value:

cell value.

label:

Header’s label instead of Column ID. Only row and column configs work.

width:

Horizontal header’s width. (px)

height:

Vertical header’s height. (px)

style:

  • Cell style object. (React.CSSProperties)

  • When specifying a border, separate it into borderTop, borderLeft, borderBottom, and borderRight. This is to avoid styling bugs in of conflicting property.

alignItems:

  • Adjusts the position of the content vertically.

  • verticalAlign prop has switched to this property at v0.10.x.

  • This field equals css align-items property.

justifyContent:

  • Adjusts the position of the content horizontally.

  • This field equals css justify-content property.

render:

Renderer identity. (string)

parser:

Parser identity. (string)

labeler:

Labeler identity. (string)

prevention:

  • Prevents operations from changing the cell.

    • Add

      • AddRow

        • AddRowAbove

        • AddRowBelow

      • AddCol

        • AddColLeft

        • AddColRight

    • Delete

      • DeleteRow

      • DeleteCol

    • Move

      • MoveFrom

      • MoveTo

    • Update

      • Write

      • Style

      • Resize

      • SetRenderer

      • SetParser

tableRef#

tableRef can be created by createTableRef().

We can access to table through it.

Example of writing “test” in cell A1.

export default function App() {
  const tableRef = createTableRef();
  React.useEffect(() => {
    const { dispatch, table } = tableRef.current;
    dispatch(table.write({point: {x: 1, y: 1}, value: "test"});
  }, [something]);
  // ...
};

options prop#

Warning

  • options.cells was deleted. (=> 0.6.x).

options.sheetHeight:

  • Sheet height size.

  • default: 500

options.sheetWidth:

  • Sheet width size.

  • default: 1000

options.minNumRows:

  • Min number of rows

  • default: 1

options.maxNumRows:

  • Max number of rows

  • default: -1

options.minNumCols:

  • Min number of columns

  • default: 1

options.maxNumCols:

  • Max number of columns

  • default: -1

options.historyLimit:

  • History (undo, redo) size.

  • default: 10

options.headerHeight:

  • Horizontal header height. (number)

  • default: 20

options.headerWidth:

  • Vertical header width. (number)

  • default: 50

options.editingOnEnter:

  • Whether ENTER key gets down and set the cell editing.

  • default: true

options.cellLabel:

  • Whether cell labels (navigator) show.

  • default: true

options.mode:

  • color mode. It allows "light" or "dark".

  • default: "light"

options.showAddress:

  • Whether address shows on a cell.

  • default: true

options.showFormulaBar:

  • Whether formula bar shows.

  • default: true

options.renderers:

  • You can use existing mixins or create a custom mixin.

  • Renderer mixins override default methods. - The available fields are as follows.

    • render: calls and separates the following methods according to the value type.

    • stringify: changes cell value to string when the cell editing and pasting. (from v0.5.7)

    • string: renders cell value when type of the cell is string.

    • bool: renders cell value when type of the cell is boolean.

    • number: renders cell value when type of the cell is number.

    • date: renders cell value when type of the cell is date.

    • array: renders cell value when type of the cell is array.

    • object: renders cell value when type of the cell is object.

    • null: renders cell value when type of the cell is null.

    • undefined: renders cell value when type of the cell is undefined.

  • default: {}

  • To use a Renderer mixin, specify its Mixin object in the mixins props when creating the Renderer instance. Specify the Renderer instance as an object in options.renderers. The key is the identifier of the Renderer. This identifier is specified as the renderer key of cell.

import * as React from "react";
import {
  GridSheet,
  Renderer,
  RendererMixinType,
  CheckboxRendererMixin,
} from "@gridsheet/react-core";

const QuoteRendererMixin: RendererMixinType = {
  string(cell) {
    return `"${cell.value}"`;
  }
  stringify(cell) {
    return "" + cell.value;
  }
}

export default function App() {
  return (<GridSheet
    data={[ // any[][]
      ["a", 1, true],
      ["b", 2, false],
      ["c", 3, null],
    ]}
    options={{
      renderers: {
        quote: new Renderer({mixins: [QuoteRendererMixin, CheckboxRendererMixin]}),
      },
      cells: {
        A: { renderer: "quote" },
      },
    }}
  />)
}
options.parsers:

  • Parser, like Renderer, can control its movement through Mixin.

    • Parser mixins override default methods.

    • The available fields are as follows.

      • parseFunctions: An array of functions that convert a string input from the user. The function takes a string and returns an arbitrary value.

      • callback: calls the parse method and stores the value in the cell. This is used to reflect input values in non-value fields.

      • parse: parses an input string. The following parse methods are called in sequence, returning the successfully parsed value. The parsing method to be called depends on parseFunctions.

      • number: parses it to number type.

      • timedelta: parses it to timedelta type.

      • date: parses it to date type.

      • bool: parses it to boolean type.

  • To use the parser, you have to specify the parser’s identity to options.cells[column].parser.

  • default: {}

import * as React from "react";
import {
  GridSheet,
  Parser,
  constructInitialCellsOrigin,
} from "@gridsheet/react-core";

const EvalParserMixin = {
  parseFunctions = [
    eval,
  ];
}

export default function App() {
  return (<GridSheet
    initialCells={
      constructInitialCellsOrigin({
        matrix: [
          ["a", 1, true],
          ["b", 2, false],
          ["c", 3, null],
        ],
      })
    options={{
      parsers: {
        eval: new Parser({mixins: [EvalParserMixin]}),
      },
      cells: {
        C: { parser: "eval" },
      },
    }}
  />)
}
options.resize:
both:

allows resizing both directions.

vertical:

allows resizing vertically.

horizontal:

allows resizing horizontally.

none:

does not allow resizing.

options.onSave:

  • A callback function on you saving.

    • Saving events are emitted by Ctrl + s or Command + s.

  • (table, positions) => void

    • positions argument has 3 keys. Every values gets cell position indeces like [Y as number, X as number].

      • pointing: A pointing cell.

      • selectingFrom: A cell selected (dragged) from. If no cells dragged, it will be [-1, -1].

      • selectingTo: A cell selected (dragged) to. If no cells dragged, it will be [-1, -1].

options.onChange:

  • A callback function on table changed.

  • (table, positions) => void (same as onSave)

Warning

onChangeDiff was dropped.

options.onSelect:

  • A callback function on select or dragging cells.

  • (table, positions) => void (same as onSave)