From 9d9e028f97064df77b49186ed86ea74fdd9896a1 Mon Sep 17 00:00:00 2001 From: Sorokin-Oleg Date: Wed, 15 Apr 2026 19:37:06 +0300 Subject: [PATCH 1/4] [dev] Spreadsheet. Added the react wrapper documentation --- .claude/settings.local.json | 8 + docs/react/events.md | 221 ++++++++++++++++ docs/react/index.md | 41 +++ docs/react/installation.md | 78 ++++++ docs/react/localization.md | 75 ++++++ docs/react/nextjs.md | 101 ++++++++ docs/react/overview.md | 201 +++++++++++++++ docs/react/props.md | 249 ++++++++++++++++++ docs/react/quick-start.md | 111 ++++++++ docs/react/state/index.md | 21 ++ docs/react/state/redux-toolkit.md | 181 +++++++++++++ docs/react/state/state-management-basics.md | 176 +++++++++++++ docs/react/themes.md | 95 +++++++ docs/react/types.md | 270 ++++++++++++++++++++ docs/react_integration.md | 8 +- sidebars.js | 35 +++ 16 files changed, 1869 insertions(+), 2 deletions(-) create mode 100644 .claude/settings.local.json create mode 100644 docs/react/events.md create mode 100644 docs/react/index.md create mode 100644 docs/react/installation.md create mode 100644 docs/react/localization.md create mode 100644 docs/react/nextjs.md create mode 100644 docs/react/overview.md create mode 100644 docs/react/props.md create mode 100644 docs/react/quick-start.md create mode 100644 docs/react/state/index.md create mode 100644 docs/react/state/redux-toolkit.md create mode 100644 docs/react/state/state-management-basics.md create mode 100644 docs/react/themes.md create mode 100644 docs/react/types.md diff --git a/.claude/settings.local.json b/.claude/settings.local.json new file mode 100644 index 00000000..8809cb25 --- /dev/null +++ b/.claude/settings.local.json @@ -0,0 +1,8 @@ +{ + "permissions": { + "allow": [ + "Bash(grep -E \"\\\\.\\(md|js\\)$\")", + "Bash(ls /mnt/c/development/work/docs-spreadsheet/docs/*.md)" + ] + } +} diff --git a/docs/react/events.md b/docs/react/events.md new file mode 100644 index 00000000..877577a8 --- /dev/null +++ b/docs/react/events.md @@ -0,0 +1,221 @@ +--- +sidebar_label: Events +title: Events Reference +description: "Event callback props for ReactSpreadsheet: actions, selection, editing, sheets, and derived state." +--- + +# Events Reference + +All event callbacks are optional props. "Before" callbacks can return `false` to cancel the operation. + +:::tip Using a commercial license? +Replace `@dhtmlx/trial-react-spreadsheet` with `@dhx/react-spreadsheet` and configure the private registry. See [Installation](./installation.md). +::: + +:::note +The React wrapper uses `onCamelCase` prop names (e.g. `onAfterAction`) while the JS Spreadsheet API uses `camelCase` event names on the event bus (e.g. `afterAction`). See the [JS API Events Reference](/api/overview/events_overview/) for the imperative API. +::: + +## Action Events + +Fired for any user action (cell edits, formatting, structural changes, etc.). + +| Prop | Cancellable | Description | +|------|:-----------:|-------------| +| `onBeforeAction` | Yes | Fires before any user action executes. Return `false` to cancel. Handler: [`BeforeActionHandler`](./types.md#handler-type-aliases). JS API: [`beforeAction`](/api/spreadsheet_beforeaction_event/). | +| `onAfterAction` | No | Fires after any user action completes. Handler: [`AfterActionHandler`](./types.md#handler-type-aliases). JS API: [`afterAction`](/api/spreadsheet_afteraction_event/). | + +**Example — Block row deletion:** + +~~~tsx +import { Actions } from "@dhtmlx/trial-react-spreadsheet"; + + { + if (action === Actions.deleteRow) return false; + }} +/> +~~~ + +**Example — Log all user actions:** + +~~~tsx + { + console.log("Action:", action, "Cell:", config.cell); + }} +/> +~~~ + +## Selection Events + +Fired when the cell selection or focus changes. + +| Prop | Cancellable | Description | +|------|:-----------:|-------------| +| `onBeforeSelectionSet` | Yes | Fires before a cell is added to the selection. Handler: [`BeforeCellHandler`](./types.md#handler-type-aliases). JS API: [`beforeSelectionSet`](/api/spreadsheet_beforeselectionset_event/). | +| `onAfterSelectionSet` | No | Fires after a cell is added to the selection. Handler: [`AfterCellHandler`](./types.md#handler-type-aliases). JS API: [`afterSelectionSet`](/api/spreadsheet_afterselectionset_event/). | +| `onBeforeSelectionRemove` | Yes | Fires before a cell is removed from the selection. Handler: [`BeforeCellHandler`](./types.md#handler-type-aliases). | +| `onAfterSelectionRemove` | No | Fires after a cell is removed from the selection. Handler: [`AfterCellHandler`](./types.md#handler-type-aliases). | +| `onBeforeFocusSet` | Yes | Fires before the focused cell changes. Handler: [`BeforeCellHandler`](./types.md#handler-type-aliases). JS API: [`beforeFocusSet`](/api/spreadsheet_beforefocusset_event/). | +| `onAfterFocusSet` | No | Fires after the focused cell changes. Handler: [`AfterCellHandler`](./types.md#handler-type-aliases). JS API: [`afterFocusSet`](/api/spreadsheet_afterfocusset_event/). | + +**Example — Track selected cell:** + +~~~tsx +const [selectedCell, setSelectedCell] = useState(""); + + setSelectedCell(cell)} +/> + +

Current cell: {selectedCell}

+~~~ + +## Edit Events + +Fired when cell editing begins or ends. + +| Prop | Cancellable | Description | +|------|:-----------:|-------------| +| `onBeforeEditStart` | Yes | Fires before cell editing begins. Handler: [`BeforeEditHandler`](./types.md#handler-type-aliases). JS API: [`beforeEditStart`](/api/spreadsheet_beforeeditstart_event/). | +| `onAfterEditStart` | No | Fires after cell editing begins. Handler: [`AfterEditHandler`](./types.md#handler-type-aliases). JS API: [`afterEditStart`](/api/spreadsheet_aftereditstart_event/). | +| `onBeforeEditEnd` | Yes | Fires before cell editing ends. Return `false` to cancel and keep editing. Handler: [`BeforeEditHandler`](./types.md#handler-type-aliases). JS API: [`beforeEditEnd`](/api/spreadsheet_beforeeditend_event/). | +| `onAfterEditEnd` | No | Fires after cell editing ends and the value is committed. Handler: [`AfterEditHandler`](./types.md#handler-type-aliases). JS API: [`afterEditEnd`](/api/spreadsheet_aftereditend_event/). | + +**Example — Validate before committing:** + +~~~tsx + { + if (cell.startsWith("B") && isNaN(Number(value))) { + return false; // Cancel: column B must be numeric + } + }} +/> +~~~ + +## Sheet Events + +Fired when the active sheet tab changes. + +| Prop | Cancellable | Description | +|------|:-----------:|-------------| +| `onBeforeSheetChange` | Yes | Fires before the active sheet changes. Handler: [`BeforeSheetHandler`](./types.md#handler-type-aliases). JS API: [`beforeSheetChange`](/api/spreadsheet_beforesheetchange_event/). | +| `onAfterSheetChange` | No | Fires after the active sheet changes. Handler: [`AfterSheetHandler`](./types.md#handler-type-aliases). JS API: [`afterSheetChange`](/api/spreadsheet_aftersheetchange_event/). | + +**Example — Track active sheet:** + +~~~tsx + { + console.log("Switched to sheet:", sheet.name); + }} +/> +~~~ + +## Data Events + +| Prop | Description | +|------|-------------| +| `onAfterDataLoaded` | Fires after data loading completes (via `sheets` or `loadUrl`). JS API: [`afterDataLoaded`](/api/spreadsheet_afterdataloaded_event/). | + +**Example — Show loading state:** + +~~~tsx +const [loading, setLoading] = useState(true); + + setLoading(false)} +/> +~~~ + +## Input Events + +Fired during user input in cells or the formula bar. + +| Prop | Description | +|------|-------------| +| `onGroupFill` | Fires during auto-fill (drag-fill) operations. Handler: `(focusedCell: string, selectedCell: string) => void`. JS API: [`groupFill`](/api/spreadsheet_groupfill_event/). | +| `onEditLineInput` | Fires on input in the formula/edit line. Handler: `(value: string) => void`. | +| `onCellInput` | Fires on input in a cell during editing. Handler: `(cell: string, value: string) => void`. | + +## Derived State Callbacks + +These callbacks notify about computed state changes rather than direct user actions. + +| Prop | Description | +|------|-------------| +| `onStateChange` | Notifies when undo/redo availability changes. Handler: `(state: { canUndo: boolean; canRedo: boolean }) => void`. | +| `onSearchResults` | Notifies with matching cell references when the `search` prop is active. Handler: `(cells: string[]) => void`. | +| `onFilterChange` | Notifies when the user changes filters via the UI. Handler: `(filter: SheetFilter) => void`. | + +**Example — Undo/redo buttons:** + +~~~tsx +import { useRef, useState } from "react"; +import { ReactSpreadsheet, type SpreadsheetRef } from "@dhtmlx/trial-react-spreadsheet"; + +function App() { + const ref = useRef(null); + const [history, setHistory] = useState({ canUndo: false, canRedo: false }); + + return ( + <> + + + + + ); +} +~~~ + +**Example — Controlled search with results:** + +~~~tsx +const [search, setSearch] = useState(); +const [results, setResults] = useState([]); + + setSearch({ query: e.target.value, open: true })} +/> +

{results.length} cells found

+ + +~~~ + +**Example — Sync filter state:** + +~~~tsx +const [activeFilter, setActiveFilter] = useState(null); + + setActiveFilter(filter)} +/> +~~~ diff --git a/docs/react/index.md b/docs/react/index.md new file mode 100644 index 00000000..af42e05e --- /dev/null +++ b/docs/react/index.md @@ -0,0 +1,41 @@ +--- +sidebar_label: React Spreadsheet +title: React Spreadsheet +description: "Install, configure, and use DHTMLX Spreadsheet in React with the official declarative wrapper." +--- + +# React Spreadsheet + +The official declarative React wrapper for DHTMLX Spreadsheet. Build spreadsheet UIs with a component-based API — pass data as props, respond to changes via event callbacks, and access the underlying widget through a ref when needed. + +## Get started + +1. [Installation](./installation.md) — install the evaluation or commercial package +2. [Quick Start](./quick-start.md) — build your first spreadsheet app step by step +3. [Props Reference](./props.md) — configure the component behavior + +You can also explore the [GitHub demo repository](https://github.com/DHTMLX/react-spreadsheet-demo) for a complete working example. + +## Data model + +The [`sheets`](./props.md#data-props) prop is the single source of truth for all spreadsheet data. Each sheet is a [`SheetData`](./types.md#sheetdata) object containing cells, row/column configuration, merged ranges, frozen panes, filters, and sorting. + +## State management + +Learn how to keep spreadsheet data in sync with your application state: + +- [State Management Basics](./state/state-management-basics.md) — controlled props, event callbacks, the ref escape hatch +- [Redux Toolkit](./state/redux-toolkit.md) — step-by-step integration guide + +## Framework integrations + +- [Next.js](./nextjs.md) — using React Spreadsheet with Next.js App Router + +## Theming and localization + +- [Themes](./themes.md) — built-in themes and custom CSS overrides +- [Localization](./localization.md) — UI translations and number/date formatting + +## Using JS Spreadsheet directly + +If you need the imperative DHTMLX JavaScript Spreadsheet API without the declarative wrapper, see the [Integration with React](/react_integration/) guide. diff --git a/docs/react/installation.md b/docs/react/installation.md new file mode 100644 index 00000000..c5e95028 --- /dev/null +++ b/docs/react/installation.md @@ -0,0 +1,78 @@ +--- +sidebar_label: Installation +title: Installing React Spreadsheet +description: "How to install the evaluation or commercial version of DHTMLX React Spreadsheet via npm." +--- + +# Installing React Spreadsheet + +:::info Prerequisites +- [Node.js](https://nodejs.org/en/) (LTS version recommended) +- React 18 or newer +::: + +## Evaluation version (public npm) + +The evaluation package is available on the public npm registry — no configuration required. It includes a free 30-day evaluation. + +~~~bash +npm install @dhtmlx/trial-react-spreadsheet +~~~ + +or with yarn: + +~~~bash +yarn add @dhtmlx/trial-react-spreadsheet +~~~ + +## Evaluation version (private npm) + +The evaluation version on the DHTMLX private registry. Configure your project first: + +~~~bash +npm config set @dhx:registry https://npm.dhtmlx.com +~~~ + +Then install: + +~~~bash +npm install @dhx/trial-react-spreadsheet +~~~ + +## Commercial version (private npm) + +The commercial version uses the same private registry. Log in to your account in the [Client's Area](https://dhtmlx.com/docs/products/dhtmlxSpreadsheet/#editions-licenses) to obtain credentials. + +~~~bash +npm config set @dhx:registry https://npm.dhtmlx.com +~~~ + +~~~bash +npm install @dhx/react-spreadsheet +~~~ + +## Package variants + +| Variant | Package Name | Registry | +|---------|-------------|----------| +| Evaluation (public npm) | `@dhtmlx/trial-react-spreadsheet` | npmjs.org (public) | +| Evaluation (private npm) | `@dhx/trial-react-spreadsheet` | npm.dhtmlx.com (private) | +| Commercial | `@dhx/react-spreadsheet` | npm.dhtmlx.com (private) | + +## CSS import + +Import the stylesheet in your application entry point or component: + +~~~tsx +import "@dhtmlx/trial-react-spreadsheet/dist/spreadsheet.react.css"; +~~~ + +For the commercial version: + +~~~tsx +import "@dhx/react-spreadsheet/dist/spreadsheet.react.css"; +~~~ + +## TypeScript + +TypeScript type definitions are bundled with the package. No additional `@types/` package is needed. diff --git a/docs/react/localization.md b/docs/react/localization.md new file mode 100644 index 00000000..cef27f26 --- /dev/null +++ b/docs/react/localization.md @@ -0,0 +1,75 @@ +--- +sidebar_label: Localization +title: React Spreadsheet Localization +description: "Localize UI labels, formula names, and number/date formatting in React Spreadsheet." +--- + +# React Spreadsheet Localization + +React Spreadsheet provides two separate localization mechanisms for different aspects of the UI. + +## Two localization mechanisms + +| Mechanism | Prop | What it controls | +|-----------|------|-----------------| +| UI localization | `spreadsheetLocale` | Menu labels, toolbar tooltips, dialog text, and localized formula names | +| Number/date formatting | `localization` | Decimal separator, currency symbol, date/time display format | + +These props are independent — you can use either or both. + +## UI localization (spreadsheetLocale) + +The `spreadsheetLocale` prop accepts a [`SpreadsheetLocale`](./types.md#spreadsheetlocale) object with two properties: + +- `locale` — a `Record` of UI string overrides +- `formulas` — a `Record` of localized formula names grouped by category + +~~~tsx +const locale: SpreadsheetLocale = { + locale: { + "File": "Datei", + "Edit": "Bearbeiten", + "Insert": "Einfügen", + "Undo": "Rückgängig", + "Redo": "Wiederherstellen", + // ... more UI strings + }, + formulas: { + "Math": [ + ["SUMME", "Returns the sum of values"], + ["MITTELWERT", "Returns the average of values"], + ], + // ... more formula categories + }, +}; + + +~~~ + +:::warning +`spreadsheetLocale` is an init-only prop. Changing it after the initial render causes the widget to be destroyed and recreated. Undo/redo history and UI state (selection, scroll position) are reset. +::: + +## Number/date formatting (localization) + +The `localization` prop controls how numbers and dates are displayed — decimal separators, currency symbols, date patterns, etc. It uses the same format as the DHTMLX Spreadsheet [`localization`](/api/spreadsheet_localization_config/) configuration property. + +~~~tsx + +~~~ + +:::warning +`localization` is also an init-only prop. Changes trigger a full destroy/recreate cycle. +::: + +## Related + +- [Localization](/localization/) — DHTMLX Spreadsheet localization guide +- [SpreadsheetLocale type](./types.md#spreadsheetlocale) — TypeScript interface reference diff --git a/docs/react/nextjs.md b/docs/react/nextjs.md new file mode 100644 index 00000000..547275a3 --- /dev/null +++ b/docs/react/nextjs.md @@ -0,0 +1,101 @@ +--- +sidebar_label: Next.js +title: React Spreadsheet in Next.js +description: "How to use DHTMLX React Spreadsheet in a Next.js application with App Router." +--- + +# React Spreadsheet in Next.js + +:::tip Using a commercial license? +Replace `@dhtmlx/trial-react-spreadsheet` with `@dhx/react-spreadsheet` and configure the private registry. See [Installation](./installation.md). +::: + +## Overview + +DHTMLX Spreadsheet is a client-side widget that requires access to the browser DOM. In Next.js with the App Router, server components are the default — so the spreadsheet must be wrapped in a client component using the `"use client"` directive. + +:::note +The React Spreadsheet wrapper's JS output already includes a `"use client"` banner, but you still need the directive in your own component file that imports it. +::: + +## Setup + +Create a new Next.js project and install React Spreadsheet: + +~~~bash +npx create-next-app@latest my-spreadsheet-app +cd my-spreadsheet-app +npm install @dhtmlx/trial-react-spreadsheet +~~~ + +## Creating a client component + +Create a new file for the spreadsheet component with the `"use client"` directive: + +~~~tsx title="src/components/SpreadsheetView.tsx" +"use client"; + +import { useState } from "react"; +import { ReactSpreadsheet, type SheetData } from "@dhtmlx/trial-react-spreadsheet"; +import "@dhtmlx/trial-react-spreadsheet/dist/spreadsheet.react.css"; + +const initialSheets: SheetData[] = [ + { + id: "sheet1", + name: "Data", + cells: { + A1: { value: "Name", css: "bold" }, + B1: { value: "Value", css: "bold" }, + A2: { value: "Item 1" }, + B2: { value: 100 }, + }, + }, +]; + +const styles = { + bold: { "font-weight": "bold" }, +}; + +export default function SpreadsheetView() { + const [sheets] = useState(initialSheets); + + return ( +
+ +
+ ); +} +~~~ + +## CSS import + +Import the CSS file directly in the client component (as shown above) or in your root layout: + +~~~tsx title="src/app/layout.tsx" +import "@dhtmlx/trial-react-spreadsheet/dist/spreadsheet.react.css"; +~~~ + +## Container sizing + +Ensure the container has explicit dimensions. For a full-page spreadsheet, add these styles to your global CSS: + +~~~css title="src/app/globals.css" +html, +body { + height: 100%; + padding: 0; + margin: 0; +} +~~~ + +## Complete example + +Use the client component in a server page: + +~~~tsx title="src/app/page.tsx" +import SpreadsheetView from "@/components/SpreadsheetView"; + +export default function Home() { + return ; +} +~~~ diff --git a/docs/react/overview.md b/docs/react/overview.md new file mode 100644 index 00000000..52753268 --- /dev/null +++ b/docs/react/overview.md @@ -0,0 +1,201 @@ +--- +sidebar_label: Overview +title: React Spreadsheet Overview +description: "Overview of the official React wrapper: declarative data model, props, theming, events, and ref access." +--- + +# React Spreadsheet Overview + +`ReactSpreadsheet` is a declarative React wrapper for the DHTMLX Spreadsheet widget. It provides a component-based API where props describe the spreadsheet state, and the wrapper handles synchronization with the underlying widget. + +:::note +The React Spreadsheet wrapper is available with the DHTMLX Spreadsheet **Commercial** license. For evaluation, use the free 30-day evaluation package. +::: + +## Spreadsheet features + +The React wrapper provides access to the full feature set of DHTMLX Spreadsheet: + +- Multi-sheet spreadsheets with sheet tabs (add, remove, rename) +- Cell values, formulas (85+ built-in functions), and number formatting +- Cell styling, merged cells, frozen panes, data validation +- Sorting, filtering, and search +- Row/column operations (add, delete, hide/show, resize, auto-fit) +- Excel (XLSX) import and export via WebAssembly modules +- Customizable toolbar and context menu +- Cell locking and read-only mode +- 4 built-in themes (light, dark, contrast-light, contrast-dark) with CSS variable customization +- Localization of UI labels, formula names, and number/date formatting +- Undo/redo history +- TypeScript support with bundled type definitions and JSDoc descriptions + +## Wrapper design principles + +- **Props describe state, not actions.** There are no "trigger" props. Pass data, and the component updates the widget accordingly. +- **`sheets` is the single source of truth** for all spreadsheet data — cells, merged ranges, frozen panes, filters, sorting. +- **Ref is an escape hatch.** For operations that don't map to declarative props (export, programmatic selection, undo/redo), access the underlying widget instance via ref. +- **All widget events are exposed as typed `onXxx` callback props.** "Before" callbacks can return `false` to cancel the operation. + +## Version Requirements + +- React 18+ +- ESM-only package + +## Quick Start + +~~~tsx +import { useState } from "react"; +import { ReactSpreadsheet, type SheetData } from "@dhtmlx/trial-react-spreadsheet"; +import "@dhtmlx/trial-react-spreadsheet/dist/spreadsheet.react.css"; + +function App() { + const [sheets] = useState([ + { + id: "sheet1", + name: "Sales", + cells: { + A1: { value: "Product", css: "bold" }, + B1: { value: "Revenue", css: "bold", format: "currency" }, + A2: { value: "Widget" }, + B2: { value: 15000, format: "currency" }, + }, + }, + ]); + + const styles = { + bold: { "font-weight": "bold" }, + }; + + return ; +} +~~~ + +:::tip Using a commercial license? +Replace `@dhtmlx/trial-react-spreadsheet` with `@dhx/react-spreadsheet` and configure the private registry. See [Installation](./installation.md). +::: + +## Import paths + +**Evaluation** (public npm, free 30-day evaluation): + +~~~tsx +import { ReactSpreadsheet } from "@dhtmlx/trial-react-spreadsheet"; +import "@dhtmlx/trial-react-spreadsheet/dist/spreadsheet.react.css"; +~~~ + +**Commercial** (private npm, requires license): + +~~~tsx +import { ReactSpreadsheet } from "@dhx/react-spreadsheet"; +import "@dhx/react-spreadsheet/dist/spreadsheet.react.css"; +~~~ + +See [Installation](./installation.md) for registry configuration and all available package variants. + +## Prop Update Behavior + +Props are categorized by how the component handles changes: + +| Category | Props | What happens on change | +|----------|-------|----------------------| +| **Init-only** | `menu`, `editLine`, `toolbarBlocks`, `multiSheets`, `formats`, `localization`, `importModulePath`, `exportModulePath`, `spreadsheetLocale` | The widget is destroyed and recreated. Spreadsheet data is preserved, but undo/redo history and UI state (selection, scroll position) are reset. | +| **Runtime** | `readonly`, `rowsCount`, `colsCount` | Applied immediately without data loss or UI state reset. | +| **Data** | `sheets`, `activeSheet` | Applied incrementally — only changed cells, ranges, or settings are updated. | +| **Re-parse** | `styles` | Style changes require a full data reload. Spreadsheet data is preserved, but undo/redo history and UI state are reset. | +| **State** | `search`, `theme`, `loadUrl` | Applied via dedicated widget APIs with no side effects. | +| **Container** | `className`, `style` | Standard React DOM props on the wrapper `
`. | + +## Examples + +### Multi-sheet with formulas + +~~~tsx +const [sheets] = useState([ + { + id: "revenue", + name: "Revenue", + cells: { + A1: { value: "Q1" }, B1: { value: "Q2" }, C1: { value: "Q3" }, D1: { value: "Q4" }, + A2: { value: 12000 }, B2: { value: 15000 }, C2: { value: 18000 }, D2: { value: 21000 }, + A3: { value: "Total" }, B3: { value: "=SUM(A2:D2)", format: "currency" }, + }, + }, + { + id: "expenses", + name: "Expenses", + cells: { + A1: { value: "Category" }, B1: { value: "Amount", format: "currency" }, + A2: { value: "Marketing" }, B2: { value: 5000, format: "currency" }, + A3: { value: "Operations" }, B3: { value: 8000, format: "currency" }, + }, + }, +]); + + +~~~ + +### Custom toolbar + +~~~tsx + +~~~ + +### Read-only with locked cells + +~~~tsx +const sheets: SheetData[] = [ + { + id: "sheet1", + name: "Report", + cells: { + A1: { value: "Metric", locked: true }, + B1: { value: "Value", locked: true }, + A2: { value: "Revenue", locked: true }, + B2: { value: 50000, format: "currency", locked: true }, + }, + }, +]; + + +~~~ + +## Imperative Access via Ref + +~~~tsx +import { useRef } from "react"; +import { ReactSpreadsheet, type SpreadsheetRef } from "@dhtmlx/trial-react-spreadsheet"; + +function App() { + const ref = useRef(null); + + const handleExport = () => { + const data = ref.current?.instance?.serialize(); + console.log(data); + }; + + const handleUndo = () => { + ref.current?.instance?.undo(); + }; + + return ( + <> + + + + + ); +} +~~~ + +The `instance` property is `null` before the widget initializes and after unmount. + +## Documentation + +| Document | Contents | +|----------|----------| +| [Props Reference](./props.md) | All component props with types, defaults, and examples | +| [Events Reference](./events.md) | Event callback props grouped by category | +| [Types Reference](./types.md) | TypeScript interfaces, enums, and type aliases | diff --git a/docs/react/props.md b/docs/react/props.md new file mode 100644 index 00000000..fc0ed676 --- /dev/null +++ b/docs/react/props.md @@ -0,0 +1,249 @@ +--- +sidebar_label: Props +title: Props Reference +description: "Complete reference of all ReactSpreadsheet component props with types and examples." +--- + +# Props Reference + +All props are optional. The component renders an empty spreadsheet with default settings when no props are provided. + +:::tip Using a commercial license? +Replace `@dhtmlx/trial-react-spreadsheet` with `@dhx/react-spreadsheet` and configure the private registry. See [Installation](./installation.md). +::: + +## Init-Only Props + +Changing any of these props causes the widget to be destroyed and recreated. Spreadsheet data is preserved, but undo/redo history and UI state (selection, scroll position) are reset. + +| Prop | Type | Description | +|------|------|-------------| +| `menu` | `boolean` | Show the context menu. See JS API: [`menu`](/api/spreadsheet_menu_config/). | +| `editLine` | `boolean` | Show the formula/edit line above the grid. See JS API: [`editLine`](/api/spreadsheet_editline_config/). | +| `toolbarBlocks` | `ToolbarBlocks[]` | Toolbar blocks to display. See JS API: [`toolbarBlocks`](/api/spreadsheet_toolbarblocks_config/). | +| `multiSheets` | `boolean` | Enable multiple sheet tabs. See JS API: [`multisheets`](/api/spreadsheet_multisheets_config/). | +| `formats` | `IFormats[]` | Custom number format definitions. See JS API: [`formats`](/api/spreadsheet_formats_config/). | +| `localization` | `ISpreadsheetConfig["localization"]` | Number/date formatting locale (decimal separator, currency symbol, etc.). Separate from `spreadsheetLocale`. See JS API: [`localization`](/api/spreadsheet_localization_config/). | +| `importModulePath` | `string` | Path to the XLSX import module. See JS API: [`importModulePath`](/api/spreadsheet_importmodulepath_config/). | +| `exportModulePath` | `string` | Path to the XLSX export module. See JS API: [`exportModulePath`](/api/spreadsheet_exportmodulepath_config/). | +| `spreadsheetLocale` | [`SpreadsheetLocale`](./types.md#spreadsheetlocale) | UI translations and localized formula names. Separate from `localization`. | + +:::warning +Changing any init-only prop triggers a full destroy/recreate cycle. Undo/redo history, selection, and scroll position will be reset. +::: + +## Runtime Props + +These props are applied immediately without destroying the widget. No data loss or UI state reset. + +| Prop | Type | Description | +|------|------|-------------| +| `rowsCount` | `number` | Number of rows in the grid. See JS API: [`rowsCount`](/api/spreadsheet_rowscount_config/). | +| `colsCount` | `number` | Number of columns in the grid. See JS API: [`colsCount`](/api/spreadsheet_colscount_config/). | +| `readonly` | `boolean` | Enable read-only mode. See JS API: [`readonly`](/api/spreadsheet_readonly_config/). | + +## Data Props + +| Prop | Type | Description | +|------|------|-------------| +| `sheets` | [`SheetData[]`](./types.md#sheetdata) | The single source of truth for all spreadsheet data. Each entry represents a sheet with its cells, structure, and metadata. Changes are applied incrementally. | +| `styles` | `Record>` | Shared CSS style definitions referenced by `CellData.css`. Keys are class names, values are CSS property maps. See [Styles example](#styles-example). | +| `activeSheet` | `Id` | Id of the active (visible) sheet. Changing this switches the displayed sheet tab. | + +:::warning +Changing `styles` triggers a full data reload. Spreadsheet data is preserved, but undo/redo history and UI state (selection, scroll position) are reset. +::: + +## Search Props + +| Prop | Type | Description | +|------|------|-------------| +| `search` | [`SearchConfig`](./types.md#searchconfig) | Controlled search state. Pass a `SearchConfig` object to trigger/update search. Pass `undefined` to dismiss the search bar. | + +## Data Loading Props + +| Prop | Type | Description | +|------|------|-------------| +| `loadUrl` | `string` | URL to load spreadsheet data from. If both `loadUrl` and `sheets` are provided, `sheets` takes precedence. | +| `loadFormat` | `FileFormat` | File format hint for `loadUrl`. Default: `"json"`. | + +## Theme + +| Prop | Type | Description | +|------|------|-------------| +| `theme` | [`SpreadsheetTheme`](./types.md#spreadsheettheme) | Color theme. Built-in values: `"light"`, `"dark"`, `"contrast-light"`, `"contrast-dark"`. Also accepts custom theme name strings. See [Themes](./themes.md). | + +## Container Props + +| Prop | Type | Description | +|------|------|-------------| +| `className` | `string` | CSS class name appended to the wrapper `
`. | +| `style` | `React.CSSProperties` | Inline styles applied to the wrapper `
`. | + +--- + +## Examples + +### Sheets with Cell Data + +~~~tsx +const [sheets, setSheets] = useState([ + { + id: "sheet1", + name: "Budget", + cells: { + A1: { value: "Item", css: "header" }, + B1: { value: "Amount", css: "header", format: "currency" }, + A2: { value: "Rent" }, + B2: { value: 2000, format: "currency" }, + A3: { value: "=SUM(B2:B2)" }, + }, + rows: { 0: { height: 40 } }, + cols: { 0: { width: 150 }, 1: { width: 120 } }, + merged: [{ from: { row: 0, column: 0 }, to: { row: 0, column: 1 } }], + freeze: { row: 1 }, + }, +]); + + +~~~ + +### Styles Example + +~~~tsx +const styles = { + header: { + "font-weight": "bold", + "background": "#e3f2fd", + "color": "#1565c0", + }, + highlight: { + "background": "#ffeb3b", + "color": "#333", + }, +}; + + +~~~ + +### Toolbar Customization + +~~~tsx + +~~~ + +### Multi-Sheet Mode + +~~~tsx + +~~~ + +To disable sheet tabs: + +~~~tsx + +~~~ + +### Excel Import/Export + +~~~tsx + +~~~ + +### European Number Formatting + +~~~tsx + +~~~ + +### Controlled Search + +~~~tsx +const [search, setSearch] = useState(); +const [results, setResults] = useState([]); + + setSearch({ query: e.target.value, open: true })} /> + +

Found in: {results.join(", ")}

+ + +~~~ + +### Theme Switching + +~~~tsx +const [theme, setTheme] = useState("light"); + + + + +~~~ + +### Read-Only Mode + +~~~tsx + +~~~ + +### Loading Data from URL + +~~~tsx + +~~~ + +### Locked Cells + +~~~tsx +const sheets: SheetData[] = [ + { + id: "sheet1", + name: "Protected", + cells: { + A1: { value: "Header", locked: true }, + A2: { value: "Editable" }, + }, + }, +]; + + +~~~ + +### Cell Validation + +~~~tsx +const sheets: SheetData[] = [ + { + id: "sheet1", + name: "Form", + cells: { + A1: { value: "Status" }, + B1: { validation: ["Active", "Inactive", "Pending"] }, + }, + }, +]; + + +~~~ diff --git a/docs/react/quick-start.md b/docs/react/quick-start.md new file mode 100644 index 00000000..2696bbca --- /dev/null +++ b/docs/react/quick-start.md @@ -0,0 +1,111 @@ +--- +sidebar_label: Quick Start +title: Quick Start with React Spreadsheet +description: "Step-by-step guide to rendering your first DHTMLX React Spreadsheet component." +--- + +# Quick Start with React Spreadsheet + +This tutorial walks you through creating a React application with DHTMLX Spreadsheet from scratch. + +:::tip Using a commercial license? +Replace `@dhtmlx/trial-react-spreadsheet` with `@dhx/react-spreadsheet` and configure the private registry. See [Installation](./installation.md). +::: + +## Create a new project + +~~~bash +npm create vite@latest my-spreadsheet-app -- --template react-ts +cd my-spreadsheet-app +~~~ + +## Install React Spreadsheet + +~~~bash +npm install @dhtmlx/trial-react-spreadsheet +~~~ + +For other package variants, see [Installation](./installation.md). + +## Create demo data + +Create a file `src/data.ts` with sample spreadsheet data: + +~~~ts title="src/data.ts" +import type { SheetData } from "@dhtmlx/trial-react-spreadsheet"; + +export const sheets: SheetData[] = [ + { + id: "sheet1", + name: "Sales", + cells: { + A1: { value: "Product", css: "bold" }, + B1: { value: "Revenue", css: "bold", format: "currency" }, + A2: { value: "Widget" }, + B2: { value: 15000, format: "currency" }, + A3: { value: "Gadget" }, + B3: { value: 22000, format: "currency" }, + A4: { value: "Total" }, + B4: { value: "=SUM(B2:B3)", format: "currency" }, + }, + }, +]; + +export const styles = { + bold: { "font-weight": "bold" }, +}; +~~~ + +## Create the component + +Replace the contents of `src/App.tsx`: + +~~~tsx title="src/App.tsx" +import { useState } from "react"; +import { ReactSpreadsheet, type SheetData } from "@dhtmlx/trial-react-spreadsheet"; +import "@dhtmlx/trial-react-spreadsheet/dist/spreadsheet.react.css"; +import { sheets as initialSheets, styles } from "./data"; + +function App() { + const [sheets] = useState(initialSheets); + + return ( +
+ +
+ ); +} + +export default App; +~~~ + +## Add styles + +Update `src/index.css` to ensure full-height layout: + +~~~css title="src/index.css" +html, +body, +#root { + height: 100%; + padding: 0; + margin: 0; +} +~~~ + +## Start the app + +~~~bash +npm run dev +~~~ + +Open the URL shown in your terminal (typically `http://localhost:5173`) to see the spreadsheet. + +## Next steps + +- [Props Reference](./props.md) — configure the spreadsheet behavior +- [Events Reference](./events.md) — respond to user actions +- [Types Reference](./types.md) — TypeScript interfaces and enums +- [Data & State Management](./state/index.md) — manage spreadsheet data in application state + +You can also explore the [GitHub demo repository](https://github.com/DHTMLX/react-spreadsheet-demo) for a complete working example. diff --git a/docs/react/state/index.md b/docs/react/state/index.md new file mode 100644 index 00000000..3165c919 --- /dev/null +++ b/docs/react/state/index.md @@ -0,0 +1,21 @@ +--- +sidebar_label: "Data & State" +title: "Data & State Management" +description: "Patterns for managing DHTMLX Spreadsheet data in React state or with state management libraries." +--- + +# Data & State Management + +This section covers patterns for managing spreadsheet data in sync with your application state — from basic React `useState` to state management libraries. + +## Start here + +- [State Management Basics](./state-management-basics.md) — core patterns: controlled props, event callbacks, the ref escape hatch, and performance tips + +## State library guides + +- [Redux Toolkit](./redux-toolkit.md) — step-by-step integration with Redux Toolkit + +## Key concept + +The `sheets` prop is the **single source of truth** for all spreadsheet data. Pass an array of [`SheetData`](../types.md#sheetdata) objects, and the wrapper diffs your data against the current widget state, applying only the changes. Use immutable updates (spread operators, functional `setState` updaters) so React can detect changes efficiently. diff --git a/docs/react/state/redux-toolkit.md b/docs/react/state/redux-toolkit.md new file mode 100644 index 00000000..f4988c5f --- /dev/null +++ b/docs/react/state/redux-toolkit.md @@ -0,0 +1,181 @@ +--- +sidebar_label: Redux Toolkit +title: React Spreadsheet with Redux Toolkit +description: "Step-by-step integration of DHTMLX React Spreadsheet with Redux Toolkit." +--- + +# React Spreadsheet with Redux Toolkit + +This tutorial shows how to manage spreadsheet data in a Redux Toolkit store. + +:::tip Using a commercial license? +Replace `@dhtmlx/trial-react-spreadsheet` with `@dhx/react-spreadsheet` and configure the private registry. See [Installation](../installation.md). +::: + +## Prerequisites + +- Familiarity with React, TypeScript, and [Redux Toolkit](https://redux-toolkit.js.org/) basics +- Completed the [State Management Basics](./state-management-basics.md) guide + +## Setup + +Create a Vite project and install dependencies: + +~~~bash +npm create vite@latest my-rtk-spreadsheet -- --template react-ts +cd my-rtk-spreadsheet +npm install @dhtmlx/trial-react-spreadsheet @reduxjs/toolkit react-redux +~~~ + +## Create the slice + +~~~ts title="src/store/spreadsheetSlice.ts" +import { createSlice, type PayloadAction } from "@reduxjs/toolkit"; +import type { SheetData } from "@dhtmlx/trial-react-spreadsheet"; + +interface SpreadsheetState { + sheets: SheetData[]; + activeSheet: string; +} + +const initialState: SpreadsheetState = { + sheets: [ + { + id: "sheet1", + name: "Data", + cells: { + A1: { value: "Product", css: "bold" }, + B1: { value: "Price", css: "bold", format: "currency" }, + A2: { value: "Widget" }, + B2: { value: 25.99, format: "currency" }, + }, + }, + ], + activeSheet: "sheet1", +}; + +const spreadsheetSlice = createSlice({ + name: "spreadsheet", + initialState, + reducers: { + setSheets(state, action: PayloadAction) { + state.sheets = action.payload; + }, + setActiveSheet(state, action: PayloadAction) { + state.activeSheet = action.payload; + }, + updateCell( + state, + action: PayloadAction<{ sheetId: string; cell: string; value: string | number }> + ) { + const { sheetId, cell, value } = action.payload; + const sheet = state.sheets.find((s) => s.id === sheetId); + if (sheet) { + sheet.cells[cell] = { ...sheet.cells[cell], value }; + } + }, + }, +}); + +export const { setSheets, setActiveSheet, updateCell } = spreadsheetSlice.actions; +export default spreadsheetSlice.reducer; +~~~ + +## Configure the store + +~~~ts title="src/store/index.ts" +import { configureStore } from "@reduxjs/toolkit"; +import spreadsheetReducer from "./spreadsheetSlice"; + +export const store = configureStore({ + reducer: { + spreadsheet: spreadsheetReducer, + }, +}); + +export type RootState = ReturnType; +export type AppDispatch = typeof store.dispatch; +~~~ + +Wrap your app with the provider: + +~~~tsx title="src/main.tsx" +import React from "react"; +import ReactDOM from "react-dom/client"; +import { Provider } from "react-redux"; +import { store } from "./store"; +import App from "./App"; +import "./index.css"; + +ReactDOM.createRoot(document.getElementById("root")!).render( + + + + + +); +~~~ + +## Create the component + +~~~tsx title="src/App.tsx" +import { useRef } from "react"; +import { useSelector, useDispatch } from "react-redux"; +import { ReactSpreadsheet, type SpreadsheetRef } from "@dhtmlx/trial-react-spreadsheet"; +import "@dhtmlx/trial-react-spreadsheet/dist/spreadsheet.react.css"; +import type { RootState } from "./store"; +import { setSheets } from "./store/spreadsheetSlice"; + +const styles = { + bold: { "font-weight": "bold" }, +}; + +function App() { + const ref = useRef(null); + const dispatch = useDispatch(); + const sheets = useSelector((state: RootState) => state.spreadsheet.sheets); + const activeSheet = useSelector((state: RootState) => state.spreadsheet.activeSheet); + + const handleAfterAction = () => { + const data = ref.current?.instance?.serialize(); + if (data?.sheets) { + dispatch(setSheets(data.sheets)); + } + }; + + return ( +
+ +
+ ); +} + +export default App; +~~~ + +## Reading data via ref + +Use `ref.current.instance` for read-only operations like serialization or getting cell values: + +~~~tsx +const handleExport = () => { + const data = ref.current?.instance?.serialize(); + // Send to API, download, etc. +}; + +const getCellValue = (cell: string) => { + return ref.current?.instance?.getValue(cell); +}; +~~~ + +## Related + +- [Props Reference](../props.md) — all component props +- [Events Reference](../events.md) — event callback props +- [State Management Basics](./state-management-basics.md) — core patterns diff --git a/docs/react/state/state-management-basics.md b/docs/react/state/state-management-basics.md new file mode 100644 index 00000000..9a42b0ab --- /dev/null +++ b/docs/react/state/state-management-basics.md @@ -0,0 +1,176 @@ +--- +sidebar_label: Basics +title: Data Binding & State Management Basics +description: "Core patterns for managing spreadsheet data in React: controlled props, event callbacks, and the ref escape hatch." +--- + +# Data Binding & State Management Basics + +:::tip Using a commercial license? +Replace `@dhtmlx/trial-react-spreadsheet` with `@dhx/react-spreadsheet` and configure the private registry. See [Installation](../installation.md). +::: + +## The declarative model + +React Spreadsheet follows a declarative approach: you store sheet data in React state, pass it as props, and the wrapper automatically diffs your data against the current widget state — applying only the changes. + +~~~tsx +import { useState } from "react"; +import { ReactSpreadsheet, type SheetData } from "@dhtmlx/trial-react-spreadsheet"; +import "@dhtmlx/trial-react-spreadsheet/dist/spreadsheet.react.css"; + +function App() { + const [sheets, setSheets] = useState([ + { + id: "sheet1", + name: "Data", + cells: { + A1: { value: "Hello" }, + }, + }, + ]); + + return ; +} +~~~ + +## Updating cells + +Use immutable state updates with the functional `setState` updater: + +~~~tsx +const updateCell = (sheetId: string, cell: string, value: string | number) => { + setSheets((prev) => + prev.map((sheet) => + sheet.id === sheetId + ? { + ...sheet, + cells: { + ...sheet.cells, + [cell]: { ...sheet.cells[cell], value }, + }, + } + : sheet + ) + ); +}; +~~~ + +## Responding to user actions + +Use `onAfterAction` to react to user changes. Combine it with `ref` to read the current widget data: + +~~~tsx +import { useRef } from "react"; +import { ReactSpreadsheet, type SpreadsheetRef } from "@dhtmlx/trial-react-spreadsheet"; + +function App() { + const ref = useRef(null); + const [sheets, setSheets] = useState([/* ... */]); + + const handleAfterAction = () => { + const data = ref.current?.instance?.serialize(); + if (data) { + // Sync widget state back to React state + console.log("Spreadsheet data:", data); + } + }; + + return ( + + ); +} +~~~ + +## The ref escape hatch + +For operations that don't map to declarative props, use the [`SpreadsheetRef`](../types.md#spreadsheetref) to access the underlying widget instance: + +- **Serialize data:** `ref.current?.instance?.serialize()` +- **Undo/redo:** `ref.current?.instance?.undo()` / `ref.current?.instance?.redo()` +- **Get cell value:** `ref.current?.instance?.getValue("A1")` +- **Programmatic selection:** `ref.current?.instance?.selection.setSelectedCell("A1:C5")` + +~~~tsx +const ref = useRef(null); + +const handleExport = () => { + const data = ref.current?.instance?.serialize(); + console.log(data); +}; + + +~~~ + +:::warning +Avoid mixing imperative writes (e.g. `instance.setValue()`) with the declarative `sheets` prop. The wrapper may overwrite imperative changes on the next render cycle. Use the ref only for **reading** data and for operations like undo/redo, selection, and export. +::: + +## Controlled search + +Use the `search` prop with `onSearchResults` for controlled search: + +~~~tsx +const [search, setSearch] = useState(); +const [results, setResults] = useState([]); + + setSearch({ query: e.target.value, open: true })} +/> +

{results.length} cells found

+ + +~~~ + +## Undo / redo + +Use `onStateChange` to track undo/redo availability, and call `undo()`/`redo()` via ref: + +~~~tsx +const ref = useRef(null); +const [history, setHistory] = useState({ canUndo: false, canRedo: false }); + + + + + +~~~ + +## Performance + +- Use `useMemo` for derived sheets to avoid unnecessary recalculations: + +~~~tsx +const filteredSheets = useMemo( + () => sheets.filter((s) => s.name !== "Hidden"), + [sheets] +); + + +~~~ + +- Avoid recreating the `styles` object on every render — define it outside the component or wrap it in `useMemo`. +- Use the functional `setState` updater to avoid stale closure issues in event callbacks. diff --git a/docs/react/themes.md b/docs/react/themes.md new file mode 100644 index 00000000..d317e78f --- /dev/null +++ b/docs/react/themes.md @@ -0,0 +1,95 @@ +--- +sidebar_label: Themes +title: React Spreadsheet Themes +description: "Apply built-in or custom themes to DHTMLX React Spreadsheet." +--- + +# React Spreadsheet Themes + +:::tip Using a commercial license? +Replace `@dhtmlx/trial-react-spreadsheet` with `@dhx/react-spreadsheet` and configure the private registry. See [Installation](./installation.md). +::: + +## Built-in themes + +The [`SpreadsheetTheme`](./types.md#spreadsheettheme) type defines four built-in themes: + +- `"light"` (default) +- `"dark"` +- `"contrast-light"` +- `"contrast-dark"` + +You can also pass a custom theme name as a string. + +## Applying a theme + +Pass the `theme` prop to `ReactSpreadsheet`: + +~~~tsx + +~~~ + +## Switching at runtime + +Use React state to switch themes dynamically: + +~~~tsx +import { useState } from "react"; +import { ReactSpreadsheet, type SheetData, type SpreadsheetTheme } from "@dhtmlx/trial-react-spreadsheet"; +import "@dhtmlx/trial-react-spreadsheet/dist/spreadsheet.react.css"; + +function App() { + const [sheets] = useState([/* ... */]); + const [theme, setTheme] = useState("light"); + + return ( + <> + + + + + ); +} +~~~ + +## Custom CSS variables + +DHTMLX Spreadsheet uses a layered CSS variable system. You can override these variables to customize the appearance beyond the built-in themes. + +### Creating a custom theme + +Define a custom `data-dhx-theme` selector, override the variables you need, and pass the theme name as a prop: + +~~~css title="src/custom-theme.css" +[data-dhx-theme='corporate'] { + /* color scheme */ + --dhx-h-primary: 220; + --dhx-s-primary: 60%; + --dhx-l-primary: 45%; + + /* toolbar and grid */ + --dhx-s-toolbar-background: #f0f4f8; + --dhx-s-grid-header-background: #e2e8f0; + + /* spreadsheet range colors */ + --dhx-spreadsheet-range-background-1: #bee3f8; + --dhx-spreadsheet-range-color-1: #2b6cb0; +} +~~~ + +~~~tsx +import "./custom-theme.css"; + + +~~~ + +## Related + +- [Themes](/themes/themes/) — built-in theme overview for DHTMLX Spreadsheet +- [Base themes configuration](/themes/base_themes_configuration/) — configuring base themes +- [Custom theme](/themes/custom_theme/) — creating custom themes diff --git a/docs/react/types.md b/docs/react/types.md new file mode 100644 index 00000000..43607a54 --- /dev/null +++ b/docs/react/types.md @@ -0,0 +1,270 @@ +--- +sidebar_label: Types +title: Types Reference +description: "TypeScript interfaces, enums, and type aliases exported from @dhx/react-spreadsheet." +--- + +# Types Reference + +All types are exported from `@dhx/react-spreadsheet`. + +~~~tsx +import type { SheetData, CellData, SpreadsheetRef /* ... */ } from "@dhtmlx/trial-react-spreadsheet"; +~~~ + +## CellData + +A single cell's declarative state. All properties are optional — omitted properties retain their current value during updates. + +| Property | Type | Description | +|----------|------|-------------| +| `value` | `string \| number` | Cell value: text, number, or formula string (prefixed with `=`). | +| `css` | `string` | CSS class name(s) referencing keys in the top-level `styles` map. | +| `format` | `string` | Number format mask or alias (e.g. `"currency"`, `"#,##0.00"`). | +| `locked` | `boolean` | Whether the cell is locked (protected from editing). | +| `validation` | `string \| string[]` | Data validation dropdown options. | + +## RowConfig + +Row metadata. Only rows with non-default config need entries. + +| Property | Type | Description | +|----------|------|-------------| +| `height` | `number` | Row height in pixels. | +| `hidden` | `boolean` | Whether the row is hidden. | + +## ColConfig + +Column metadata. Only columns with non-default config need entries. + +| Property | Type | Description | +|----------|------|-------------| +| `width` | `number` | Column width in pixels. | +| `hidden` | `boolean` | Whether the column is hidden. | + +## MergedRange + +Defines a merged cell range using 0-indexed row/column coordinates. + +| Property | Type | Description | +|----------|------|-------------| +| `from` | `{ row: number; column: number }` | Top-left corner of the merge (0-indexed). | +| `to` | `{ row: number; column: number }` | Bottom-right corner of the merge (0-indexed). | + +**Example:** + +~~~ts +// Merge A1:B2 +const merge: MergedRange = { + from: { row: 0, column: 0 }, + to: { row: 1, column: 1 }, +}; +~~~ + +## FreezeConfig + +Freeze pane configuration for a sheet. + +| Property | Type | Description | +|----------|------|-------------| +| `col` | `number` | Freeze columns up to this 0-indexed column number. `undefined` = no column freeze. | +| `row` | `number` | Freeze rows up to this 0-indexed row number. `undefined` = no row freeze. | + +## SheetFilter + +Filter configuration for a column within a sheet. + +| Property | Type | Description | +|----------|------|-------------| +| `cell` | `string` | Cell reference identifying the filtered column (e.g. `"A1"`). | +| `rules` | `IFilterRules[]` | Filter rules to apply. Empty array clears the filter. | + +## SheetSort + +Sort configuration for a column within a sheet. + +| Property | Type | Description | +|----------|------|-------------| +| `cell` | `string` | Cell reference or range for the sort operation (e.g. `"B1"` or `"A1:E8"`). Use a range to sort multiple columns together while maintaining row integrity. | +| `dir` | `1 \| -1` | Sort direction: `1` = ascending, `-1` = descending. | + +## SheetData + +Complete declarative state for a single spreadsheet sheet. + +| Property | Type | Required | Description | +|----------|------|:--------:|-------------| +| `id` | `Id` | Yes | Unique sheet identifier. Must be stable across renders. | +| `name` | `string` | Yes | Display name shown on the sheet tab. | +| `cells` | `Record` | Yes | Cell data keyed by cell reference (e.g. `"A1"`, `"B2"`). Only cells with non-default data need entries. | +| `rows` | `Record` | No | Row configuration keyed by 0-indexed row number. | +| `cols` | `Record` | No | Column configuration keyed by 0-indexed column number. | +| `merged` | `MergedRange[]` | No | Merged cell ranges. | +| `freeze` | `FreezeConfig` | No | Frozen pane configuration. | +| `filter` | `SheetFilter` | No | Column filter configuration. Set to `undefined` to clear. | +| `sort` | `SheetSort` | No | Sort configuration. | + +**Example:** + +~~~ts +const sheet: SheetData = { + id: "sheet1", + name: "Inventory", + cells: { + A1: { value: "Product", css: "bold" }, + B1: { value: "Quantity", css: "bold" }, + A2: { value: "Laptop" }, + B2: { value: 42 }, + }, + cols: { 0: { width: 200 } }, + freeze: { row: 1 }, +}; +~~~ + +## SearchConfig + +Controlled search state. Pass an object to trigger/update search, pass `undefined` to dismiss. + +| Property | Type | Required | Description | +|----------|------|:--------:|-------------| +| `query` | `string` | Yes | Text to search for. | +| `open` | `boolean` | No | Whether to open the built-in search UI. Default: `false`. | +| `sheetId` | `Id` | No | Restrict search to a specific sheet by id. | + +## SpreadsheetLocale + +Localization configuration for UI labels and formula names. + +| Property | Type | Description | +|----------|------|-------------| +| `locale` | `Record` | UI string overrides. Keys match the library's locale dictionary. | +| `formulas` | `Record` | Localized formula names grouped by category. Each entry is a tuple: `[localizedName, optionalDescription?]`. | + +## SpreadsheetTheme + +~~~ts +type SpreadsheetTheme = "light" | "dark" | "contrast-light" | "contrast-dark" | string; +~~~ + +Built-in color themes. Also accepts custom theme name strings. + +## IExecuteConfig + +Action execution configuration passed to `onBeforeAction` / `onAfterAction`. Shape varies by action type. + +| Property | Type | Description | +|----------|------|-------------| +| `row` | `number` | Target row index. | +| `col` | `number` | Target column index. | +| `target` | `unknown` | Action-specific target. | +| `val` | `unknown` | New value. | +| `prev` | `unknown` | Previous value. | +| `action` | `Actions \| string` | Action identifier. | +| `groupAction` | `Actions \| string` | Parent group action identifier. | +| `cell` | `string` | Cell reference (e.g. `"A1"`). | +| `pageId` | `Id` | Target sheet id. | +| `pageName` | `string` | Target sheet name. | +| `[key: string]` | `unknown` | Additional action-specific properties. | + +## SpreadsheetRef + +Imperative handle exposed via `React.forwardRef`. Provides direct access to the underlying DHTMLX Spreadsheet instance for operations that don't map to declarative props. + +| Property | Type | Description | +|----------|------|-------------| +| `instance` | `ISpreadsheet \| null` | The underlying widget instance. `null` before initialization and after unmount. | + +**Example:** + +~~~tsx +const ref = useRef(null); + +// Serialize data +const data = ref.current?.instance?.serialize(); + +// Programmatic selection +ref.current?.instance?.selection.setSelectedCell("A1:C5"); + +// Undo/redo +ref.current?.instance?.undo(); +ref.current?.instance?.redo(); +~~~ + +## Actions Enum + +Known spreadsheet action identifiers. Used in `onBeforeAction` / `onAfterAction` for type-safe action matching. The `| string` union on handler params allows forward-compatibility with future actions. + +| Value | Description | +|-------|-------------| +| `setCellStyle` | Apply CSS style to cell(s). | +| `setCellValue` | Set cell value. | +| `setCellFormat` | Set number format on cell(s). | +| `removeCellStyles` | Remove CSS styles from cell(s). | +| `lockCell` | Lock or unlock cell(s). | +| `deleteRow` | Delete row(s). | +| `addRow` | Insert row(s). | +| `deleteColumn` | Delete column(s). | +| `addColumn` | Insert column(s). | +| `groupAction` | Batch action (multiple sub-actions). | +| `groupRowAction` | Batch row action. | +| `groupColAction` | Batch column action. | +| `addSheet` | Add a new sheet. | +| `deleteSheet` | Delete a sheet. | +| `renameSheet` | Rename a sheet. | +| `clearSheet` | Clear all data in a sheet. | +| `clear` | Clear selected cells. | +| `resizeCol` | Resize column width. | +| `resizeRow` | Resize row height. | +| `setValidation` | Set data validation on cell(s). | +| `sortCells` | Sort cells. | +| `insertLink` | Insert a hyperlink. | +| `fitColumn` | Auto-fit column width to content. | +| `filter` | Apply or change column filter. | +| `merge` | Merge cells. | +| `unmerge` | Unmerge cells. | +| `toggleFreeze` | Toggle freeze panes. | +| `toggleVisibility` | Toggle row/column visibility. | + +## Handler Type Aliases + +| Type | Signature | Used by | +|------|-----------|---------| +| `BeforeActionHandler` | `(action: Actions \| string, config: IExecuteConfig) => boolean \| void` | `onBeforeAction` | +| `AfterActionHandler` | `(action: Actions \| string, config: IExecuteConfig) => void` | `onAfterAction` | +| `BeforeCellHandler` | `(cell: string) => boolean \| void` | `onBeforeSelectionSet`, `onBeforeSelectionRemove`, `onBeforeFocusSet` | +| `AfterCellHandler` | `(cell: string) => void` | `onAfterSelectionSet`, `onAfterSelectionRemove`, `onAfterFocusSet` | +| `BeforeEditHandler` | `(cell: string, value: string) => boolean \| void` | `onBeforeEditStart`, `onBeforeEditEnd` | +| `AfterEditHandler` | `(cell: string, value: string) => void` | `onAfterEditStart`, `onAfterEditEnd` | +| `BeforeSheetHandler` | `(sheet: ISheet) => boolean \| void` | `onBeforeSheetChange` | +| `AfterSheetHandler` | `(sheet: ISheet) => void` | `onAfterSheetChange` | + +## SpreadsheetConfigProps + +~~~ts +type SpreadsheetConfigProps = Omit< + ISpreadsheetConfig, + "leftSplit" | "topSplit" | "dateFormat" | "timeFormat" +>; +~~~ + +Base type for component props. Exposes all `ISpreadsheetConfig` constructor options as flat props. + +## Re-exported Upstream Types + +These types are re-exported from `@dhx/ts-spreadsheet` for convenience: + +| Type | Description | +|------|-------------| +| `ISpreadsheet` | Main spreadsheet widget instance interface. | +| `ISpreadsheetConfig` | Constructor configuration interface. | +| `ISheet` | Sheet instance interface (used in sheet event callbacks). | +| `IFormats` | Custom number format definition. | +| `IFilterRules` | Filter rule configuration. | +| `IFilter` | Filter instance interface. | +| `IStylesList` | Style definitions map. | +| `IDataWithStyles` | Data structure with embedded styles (used by `serialize()`/`parse()`). | +| `ICellInfo` | Cell information returned by widget methods. | +| `FileFormat` | File format for data loading (e.g. `"json"`, `"xlsx"`). | +| `ToolbarBlocks` | Toolbar block identifiers (e.g. `"default"`, `"undo"`, `"font"`). | +| `FilterConditions` | Enum of available filter condition types. | +| `Id` | Generic identifier type (`string \| number`). | diff --git a/docs/react_integration.md b/docs/react_integration.md index 27a3cc03..e1374741 100644 --- a/docs/react_integration.md +++ b/docs/react_integration.md @@ -6,6 +6,10 @@ description: You can learn about the React integration of the DHTMLX JavaScript # Integration with React +:::note +Looking for the declarative React wrapper? See [**React Spreadsheet**](/react/) for the official component-based API with props, events, and TypeScript support. +::: + :::tip You should be familiar with the basic concepts and patterns of [**React**](https://react.dev) to use this documentation. To refresh your knowledge, please refer to the [**React documentation**](https://react.dev/learn). ::: @@ -214,11 +218,11 @@ export default function SpreadsheetComponent(props) { } ~~~ -Now the Spreadsheet component is ready to use. When the element will be added to the page, it will initialize the Spreadsheet with data. You can provide necessary configuration settings as well. Visit our [Spreadsheet API docs](spreadsheet/api/overview/properties_overview.md) to check the full list of available properties. +Now the Spreadsheet component is ready to use. When the element will be added to the page, it will initialize the Spreadsheet with data. You can provide necessary configuration settings as well. Visit our [Spreadsheet API docs](/api/overview/properties_overview/) to check the full list of available properties. #### Handling events -When a user makes some action in the Spreadsheet, it invokes an event. You can use these events to detect the action and run the desired code for it. See the [full list of events](spreadsheet/api/overview/events_overview.md). +When a user makes some action in the Spreadsheet, it invokes an event. You can use these events to detect the action and run the desired code for it. See the [full list of events](/api/overview/events_overview/). Open ***Spreadsheet.jsx*** and complete the `useEffect()` method in the following way: diff --git a/sidebars.js b/sidebars.js index 857abcc2..ddf3b300 100644 --- a/sidebars.js +++ b/sidebars.js @@ -223,6 +223,41 @@ module.exports = { } ] }, + { + type: "category", + label: "React", + collapsible: true, + collapsed: true, + link: { + type: 'doc', + id: "react/index" + }, + items: [ + "react/overview", + "react/installation", + "react/quick-start", + "react/props", + "react/events", + "react/types", + "react/themes", + "react/localization", + { + type: "category", + label: "Data & State Management", + collapsible: true, + collapsed: true, + link: { + type: 'doc', + id: "react/state/index" + }, + items: [ + "react/state/state-management-basics", + "react/state/redux-toolkit" + ] + }, + "react/nextjs" + ] + }, { type: "category", label: "Guides", From 45041edb802c59bc459653c78a2d45397ea79b0a Mon Sep 17 00:00:00 2001 From: osorokin Date: Fri, 17 Apr 2026 17:32:09 +0300 Subject: [PATCH 2/4] [update] React documentation updates and edits --- .claude/settings.local.json | 8 ------ .gitignore | 1 + docs/react/events.md | 32 +++++++++------------ docs/react/index.md | 22 ++++++-------- docs/react/installation.md | 4 +-- docs/react/localization.md | 10 +++---- docs/react/nextjs.md | 8 ++---- docs/react/overview.md | 18 +++++------- docs/react/props.md | 21 +++++++------- docs/react/quick-start.md | 18 +++++------- docs/react/state/index.md | 6 ++-- docs/react/state/redux-toolkit.md | 16 ++++------- docs/react/state/state-management-basics.md | 8 ++---- docs/react/themes.md | 10 ++----- docs/react/types.md | 2 +- sidebars.js | 2 +- 16 files changed, 73 insertions(+), 113 deletions(-) delete mode 100644 .claude/settings.local.json diff --git a/.claude/settings.local.json b/.claude/settings.local.json deleted file mode 100644 index 8809cb25..00000000 --- a/.claude/settings.local.json +++ /dev/null @@ -1,8 +0,0 @@ -{ - "permissions": { - "allow": [ - "Bash(grep -E \"\\\\.\\(md|js\\)$\")", - "Bash(ls /mnt/c/development/work/docs-spreadsheet/docs/*.md)" - ] - } -} diff --git a/.gitignore b/.gitignore index c5a42c3d..95b2e35c 100644 --- a/.gitignore +++ b/.gitignore @@ -21,6 +21,7 @@ yarn-error.log* # Code .vscode +.claude # Idea .idea diff --git a/docs/react/events.md b/docs/react/events.md index 877577a8..a0b386c1 100644 --- a/docs/react/events.md +++ b/docs/react/events.md @@ -8,10 +8,6 @@ description: "Event callback props for ReactSpreadsheet: actions, selection, edi All event callbacks are optional props. "Before" callbacks can return `false` to cancel the operation. -:::tip Using a commercial license? -Replace `@dhtmlx/trial-react-spreadsheet` with `@dhx/react-spreadsheet` and configure the private registry. See [Installation](./installation.md). -::: - :::note The React wrapper uses `onCamelCase` prop names (e.g. `onAfterAction`) while the JS Spreadsheet API uses `camelCase` event names on the event bus (e.g. `afterAction`). See the [JS API Events Reference](/api/overview/events_overview/) for the imperative API. ::: @@ -22,8 +18,8 @@ Fired for any user action (cell edits, formatting, structural changes, etc.). | Prop | Cancellable | Description | |------|:-----------:|-------------| -| `onBeforeAction` | Yes | Fires before any user action executes. Return `false` to cancel. Handler: [`BeforeActionHandler`](./types.md#handler-type-aliases). JS API: [`beforeAction`](/api/spreadsheet_beforeaction_event/). | -| `onAfterAction` | No | Fires after any user action completes. Handler: [`AfterActionHandler`](./types.md#handler-type-aliases). JS API: [`afterAction`](/api/spreadsheet_afteraction_event/). | +| `onBeforeAction` | Yes | Fires before any user action executes. Return `false` to cancel. Handler: [`BeforeActionHandler`](/react/types#handler-type-aliases). JS API: [`beforeAction`](/api/spreadsheet_beforeaction_event/). | +| `onAfterAction` | No | Fires after any user action completes. Handler: [`AfterActionHandler`](/react/types#handler-type-aliases). JS API: [`afterAction`](/api/spreadsheet_afteraction_event/). | **Example — Block row deletion:** @@ -55,12 +51,12 @@ Fired when the cell selection or focus changes. | Prop | Cancellable | Description | |------|:-----------:|-------------| -| `onBeforeSelectionSet` | Yes | Fires before a cell is added to the selection. Handler: [`BeforeCellHandler`](./types.md#handler-type-aliases). JS API: [`beforeSelectionSet`](/api/spreadsheet_beforeselectionset_event/). | -| `onAfterSelectionSet` | No | Fires after a cell is added to the selection. Handler: [`AfterCellHandler`](./types.md#handler-type-aliases). JS API: [`afterSelectionSet`](/api/spreadsheet_afterselectionset_event/). | -| `onBeforeSelectionRemove` | Yes | Fires before a cell is removed from the selection. Handler: [`BeforeCellHandler`](./types.md#handler-type-aliases). | -| `onAfterSelectionRemove` | No | Fires after a cell is removed from the selection. Handler: [`AfterCellHandler`](./types.md#handler-type-aliases). | -| `onBeforeFocusSet` | Yes | Fires before the focused cell changes. Handler: [`BeforeCellHandler`](./types.md#handler-type-aliases). JS API: [`beforeFocusSet`](/api/spreadsheet_beforefocusset_event/). | -| `onAfterFocusSet` | No | Fires after the focused cell changes. Handler: [`AfterCellHandler`](./types.md#handler-type-aliases). JS API: [`afterFocusSet`](/api/spreadsheet_afterfocusset_event/). | +| `onBeforeSelectionSet` | Yes | Fires before a cell is added to the selection. Handler: [`BeforeCellHandler`](/react/types#handler-type-aliases). JS API: [`beforeSelectionSet`](/api/spreadsheet_beforeselectionset_event/). | +| `onAfterSelectionSet` | No | Fires after a cell is added to the selection. Handler: [`AfterCellHandler`](/react/types#handler-type-aliases). JS API: [`afterSelectionSet`](/api/spreadsheet_afterselectionset_event/). | +| `onBeforeSelectionRemove` | Yes | Fires before a cell is removed from the selection. Handler: [`BeforeCellHandler`](/react/types#handler-type-aliases). | +| `onAfterSelectionRemove` | No | Fires after a cell is removed from the selection. Handler: [`AfterCellHandler`](/react/types#handler-type-aliases). | +| `onBeforeFocusSet` | Yes | Fires before the focused cell changes. Handler: [`BeforeCellHandler`](/react/types#handler-type-aliases). JS API: [`beforeFocusSet`](/api/spreadsheet_beforefocusset_event/). | +| `onAfterFocusSet` | No | Fires after the focused cell changes. Handler: [`AfterCellHandler`](/react/types#handler-type-aliases). JS API: [`afterFocusSet`](/api/spreadsheet_afterfocusset_event/). | **Example — Track selected cell:** @@ -81,10 +77,10 @@ Fired when cell editing begins or ends. | Prop | Cancellable | Description | |------|:-----------:|-------------| -| `onBeforeEditStart` | Yes | Fires before cell editing begins. Handler: [`BeforeEditHandler`](./types.md#handler-type-aliases). JS API: [`beforeEditStart`](/api/spreadsheet_beforeeditstart_event/). | -| `onAfterEditStart` | No | Fires after cell editing begins. Handler: [`AfterEditHandler`](./types.md#handler-type-aliases). JS API: [`afterEditStart`](/api/spreadsheet_aftereditstart_event/). | -| `onBeforeEditEnd` | Yes | Fires before cell editing ends. Return `false` to cancel and keep editing. Handler: [`BeforeEditHandler`](./types.md#handler-type-aliases). JS API: [`beforeEditEnd`](/api/spreadsheet_beforeeditend_event/). | -| `onAfterEditEnd` | No | Fires after cell editing ends and the value is committed. Handler: [`AfterEditHandler`](./types.md#handler-type-aliases). JS API: [`afterEditEnd`](/api/spreadsheet_aftereditend_event/). | +| `onBeforeEditStart` | Yes | Fires before cell editing begins. Handler: [`BeforeEditHandler`](/react/types#handler-type-aliases). JS API: [`beforeEditStart`](/api/spreadsheet_beforeeditstart_event/). | +| `onAfterEditStart` | No | Fires after cell editing begins. Handler: [`AfterEditHandler`](/react/types#handler-type-aliases). JS API: [`afterEditStart`](/api/spreadsheet_aftereditstart_event/). | +| `onBeforeEditEnd` | Yes | Fires before cell editing ends. Return `false` to cancel and keep editing. Handler: [`BeforeEditHandler`](/react/types#handler-type-aliases). JS API: [`beforeEditEnd`](/api/spreadsheet_beforeeditend_event/). | +| `onAfterEditEnd` | No | Fires after cell editing ends and the value is committed. Handler: [`AfterEditHandler`](/react/types#handler-type-aliases). JS API: [`afterEditEnd`](/api/spreadsheet_aftereditend_event/). | **Example — Validate before committing:** @@ -105,8 +101,8 @@ Fired when the active sheet tab changes. | Prop | Cancellable | Description | |------|:-----------:|-------------| -| `onBeforeSheetChange` | Yes | Fires before the active sheet changes. Handler: [`BeforeSheetHandler`](./types.md#handler-type-aliases). JS API: [`beforeSheetChange`](/api/spreadsheet_beforesheetchange_event/). | -| `onAfterSheetChange` | No | Fires after the active sheet changes. Handler: [`AfterSheetHandler`](./types.md#handler-type-aliases). JS API: [`afterSheetChange`](/api/spreadsheet_aftersheetchange_event/). | +| `onBeforeSheetChange` | Yes | Fires before the active sheet changes. Handler: [`BeforeSheetHandler`](/react/types#handler-type-aliases). JS API: [`beforeSheetChange`](/api/spreadsheet_beforesheetchange_event/). | +| `onAfterSheetChange` | No | Fires after the active sheet changes. Handler: [`AfterSheetHandler`](/react/types#handler-type-aliases). JS API: [`afterSheetChange`](/api/spreadsheet_aftersheetchange_event/). | **Example — Track active sheet:** diff --git a/docs/react/index.md b/docs/react/index.md index af42e05e..6b6729b3 100644 --- a/docs/react/index.md +++ b/docs/react/index.md @@ -10,32 +10,28 @@ The official declarative React wrapper for DHTMLX Spreadsheet. Build spreadsheet ## Get started -1. [Installation](./installation.md) — install the evaluation or commercial package -2. [Quick Start](./quick-start.md) — build your first spreadsheet app step by step -3. [Props Reference](./props.md) — configure the component behavior +1. [Installation](/react/installation/) — install the evaluation or commercial package +2. [Quick start](/react/quick-start/) — build your first spreadsheet app step by step +3. [Props reference](/react/props) — configure the component behavior You can also explore the [GitHub demo repository](https://github.com/DHTMLX/react-spreadsheet-demo) for a complete working example. ## Data model -The [`sheets`](./props.md#data-props) prop is the single source of truth for all spreadsheet data. Each sheet is a [`SheetData`](./types.md#sheetdata) object containing cells, row/column configuration, merged ranges, frozen panes, filters, and sorting. +The [`sheets`](/react/props#data-props) prop is the single source of truth for all spreadsheet data. Each sheet is a [`SheetData`](/react/types#sheetdata) object containing cells, row/column configuration, merged ranges, frozen panes, filters, and sorting. ## State management Learn how to keep spreadsheet data in sync with your application state: -- [State Management Basics](./state/state-management-basics.md) — controlled props, event callbacks, the ref escape hatch -- [Redux Toolkit](./state/redux-toolkit.md) — step-by-step integration guide +- [State management basics](/react/state/state-management-basics/) — controlled props, event callbacks, the ref escape hatch +- [Redux toolkit](/react/state/redux-toolkit/) — step-by-step integration guide ## Framework integrations -- [Next.js](./nextjs.md) — using React Spreadsheet with Next.js App Router +- [Next.js](/react/nextjs/) — using React Spreadsheet with Next.js App Router ## Theming and localization -- [Themes](./themes.md) — built-in themes and custom CSS overrides -- [Localization](./localization.md) — UI translations and number/date formatting - -## Using JS Spreadsheet directly - -If you need the imperative DHTMLX JavaScript Spreadsheet API without the declarative wrapper, see the [Integration with React](/react_integration/) guide. +- [Themes](/react/themes/) — built-in themes and custom CSS overrides +- [Localization](/react/localization) — UI translations and number/date formatting diff --git a/docs/react/installation.md b/docs/react/installation.md index c5e95028..8225f318 100644 --- a/docs/react/installation.md +++ b/docs/react/installation.md @@ -64,13 +64,13 @@ npm install @dhx/react-spreadsheet Import the stylesheet in your application entry point or component: ~~~tsx -import "@dhtmlx/trial-react-spreadsheet/dist/spreadsheet.react.css"; +import "@dhtmlx/trial-react-spreadsheet/spreadsheet.react.css"; ~~~ For the commercial version: ~~~tsx -import "@dhx/react-spreadsheet/dist/spreadsheet.react.css"; +import "@dhx/react-spreadsheet/spreadsheet.react.css"; ~~~ ## TypeScript diff --git a/docs/react/localization.md b/docs/react/localization.md index cef27f26..b8c2dd45 100644 --- a/docs/react/localization.md +++ b/docs/react/localization.md @@ -19,7 +19,7 @@ These props are independent — you can use either or both. ## UI localization (spreadsheetLocale) -The `spreadsheetLocale` prop accepts a [`SpreadsheetLocale`](./types.md#spreadsheetlocale) object with two properties: +The `spreadsheetLocale` prop accepts a [`SpreadsheetLocale`](/react/types#spreadsheetlocale) object with two properties: - `locale` — a `Record` of UI string overrides - `formulas` — a `Record` of localized formula names grouped by category @@ -35,9 +35,9 @@ const locale: SpreadsheetLocale = { // ... more UI strings }, formulas: { - "Math": [ - ["SUMME", "Returns the sum of values"], - ["MITTELWERT", "Returns the average of values"], + "MATCH": [ + ["Suchwert", "Erforderlich. Der Wert, der im Sucharray abgeglichen werden soll."], + ["Sucharray", "Erforderlich. Ein Zellbereich oder ein Array-Bezug."], ], // ... more formula categories }, @@ -72,4 +72,4 @@ The `localization` prop controls how numbers and dates are displayed — decimal ## Related - [Localization](/localization/) — DHTMLX Spreadsheet localization guide -- [SpreadsheetLocale type](./types.md#spreadsheetlocale) — TypeScript interface reference +- [SpreadsheetLocale type](/react/types/#spreadsheetlocale) — TypeScript interface reference diff --git a/docs/react/nextjs.md b/docs/react/nextjs.md index 547275a3..2f596cef 100644 --- a/docs/react/nextjs.md +++ b/docs/react/nextjs.md @@ -6,10 +6,6 @@ description: "How to use DHTMLX React Spreadsheet in a Next.js application with # React Spreadsheet in Next.js -:::tip Using a commercial license? -Replace `@dhtmlx/trial-react-spreadsheet` with `@dhx/react-spreadsheet` and configure the private registry. See [Installation](./installation.md). -::: - ## Overview DHTMLX Spreadsheet is a client-side widget that requires access to the browser DOM. In Next.js with the App Router, server components are the default — so the spreadsheet must be wrapped in a client component using the `"use client"` directive. @@ -37,7 +33,7 @@ Create a new file for the spreadsheet component with the `"use client"` directiv import { useState } from "react"; import { ReactSpreadsheet, type SheetData } from "@dhtmlx/trial-react-spreadsheet"; -import "@dhtmlx/trial-react-spreadsheet/dist/spreadsheet.react.css"; +import "@dhtmlx/trial-react-spreadsheet/spreadsheet.react.css"; const initialSheets: SheetData[] = [ { @@ -72,7 +68,7 @@ export default function SpreadsheetView() { Import the CSS file directly in the client component (as shown above) or in your root layout: ~~~tsx title="src/app/layout.tsx" -import "@dhtmlx/trial-react-spreadsheet/dist/spreadsheet.react.css"; +import "@dhtmlx/trial-react-spreadsheet/spreadsheet.react.css"; ~~~ ## Container sizing diff --git a/docs/react/overview.md b/docs/react/overview.md index 52753268..d114ee3e 100644 --- a/docs/react/overview.md +++ b/docs/react/overview.md @@ -46,7 +46,7 @@ The React wrapper provides access to the full feature set of DHTMLX Spreadsheet: ~~~tsx import { useState } from "react"; import { ReactSpreadsheet, type SheetData } from "@dhtmlx/trial-react-spreadsheet"; -import "@dhtmlx/trial-react-spreadsheet/dist/spreadsheet.react.css"; +import "@dhtmlx/trial-react-spreadsheet/spreadsheet.react.css"; function App() { const [sheets] = useState([ @@ -70,27 +70,23 @@ function App() { } ~~~ -:::tip Using a commercial license? -Replace `@dhtmlx/trial-react-spreadsheet` with `@dhx/react-spreadsheet` and configure the private registry. See [Installation](./installation.md). -::: - ## Import paths **Evaluation** (public npm, free 30-day evaluation): ~~~tsx import { ReactSpreadsheet } from "@dhtmlx/trial-react-spreadsheet"; -import "@dhtmlx/trial-react-spreadsheet/dist/spreadsheet.react.css"; +import "@dhtmlx/trial-react-spreadsheet/spreadsheet.react.css"; ~~~ **Commercial** (private npm, requires license): ~~~tsx import { ReactSpreadsheet } from "@dhx/react-spreadsheet"; -import "@dhx/react-spreadsheet/dist/spreadsheet.react.css"; +import "@dhx/react-spreadsheet/spreadsheet.react.css"; ~~~ -See [Installation](./installation.md) for registry configuration and all available package variants. +See [Installation](/react/installation/) for registry configuration and all available package variants. ## Prop Update Behavior @@ -196,6 +192,6 @@ The `instance` property is `null` before the widget initializes and after unmoun | Document | Contents | |----------|----------| -| [Props Reference](./props.md) | All component props with types, defaults, and examples | -| [Events Reference](./events.md) | Event callback props grouped by category | -| [Types Reference](./types.md) | TypeScript interfaces, enums, and type aliases | +| [Props Reference](/react/props/) | All component props with types, defaults, and examples | +| [Events Reference](/react/events/) | Event callback props grouped by category | +| [Types Reference](/react/types/) | TypeScript interfaces, enums, and type aliases | diff --git a/docs/react/props.md b/docs/react/props.md index fc0ed676..94e86c72 100644 --- a/docs/react/props.md +++ b/docs/react/props.md @@ -8,10 +8,6 @@ description: "Complete reference of all ReactSpreadsheet component props with ty All props are optional. The component renders an empty spreadsheet with default settings when no props are provided. -:::tip Using a commercial license? -Replace `@dhtmlx/trial-react-spreadsheet` with `@dhx/react-spreadsheet` and configure the private registry. See [Installation](./installation.md). -::: - ## Init-Only Props Changing any of these props causes the widget to be destroyed and recreated. Spreadsheet data is preserved, but undo/redo history and UI state (selection, scroll position) are reset. @@ -26,7 +22,7 @@ Changing any of these props causes the widget to be destroyed and recreated. Spr | `localization` | `ISpreadsheetConfig["localization"]` | Number/date formatting locale (decimal separator, currency symbol, etc.). Separate from `spreadsheetLocale`. See JS API: [`localization`](/api/spreadsheet_localization_config/). | | `importModulePath` | `string` | Path to the XLSX import module. See JS API: [`importModulePath`](/api/spreadsheet_importmodulepath_config/). | | `exportModulePath` | `string` | Path to the XLSX export module. See JS API: [`exportModulePath`](/api/spreadsheet_exportmodulepath_config/). | -| `spreadsheetLocale` | [`SpreadsheetLocale`](./types.md#spreadsheetlocale) | UI translations and localized formula names. Separate from `localization`. | +| `spreadsheetLocale` | [`SpreadsheetLocale`](/react/types/#spreadsheetlocale) | UI translations and localized formula names. Separate from `localization`. | :::warning Changing any init-only prop triggers a full destroy/recreate cycle. Undo/redo history, selection, and scroll position will be reset. @@ -46,7 +42,7 @@ These props are applied immediately without destroying the widget. No data loss | Prop | Type | Description | |------|------|-------------| -| `sheets` | [`SheetData[]`](./types.md#sheetdata) | The single source of truth for all spreadsheet data. Each entry represents a sheet with its cells, structure, and metadata. Changes are applied incrementally. | +| `sheets` | [`SheetData[]`](/react/types#sheetdata) | The single source of truth for all spreadsheet data. Each entry represents a sheet with its cells, structure, and metadata. Changes are applied incrementally. | | `styles` | `Record>` | Shared CSS style definitions referenced by `CellData.css`. Keys are class names, values are CSS property maps. See [Styles example](#styles-example). | | `activeSheet` | `Id` | Id of the active (visible) sheet. Changing this switches the displayed sheet tab. | @@ -58,7 +54,7 @@ Changing `styles` triggers a full data reload. Spreadsheet data is preserved, bu | Prop | Type | Description | |------|------|-------------| -| `search` | [`SearchConfig`](./types.md#searchconfig) | Controlled search state. Pass a `SearchConfig` object to trigger/update search. Pass `undefined` to dismiss the search bar. | +| `search` | [`SearchConfig`](/react/types#searchconfig) | Controlled search state. Pass a `SearchConfig` object to trigger/update search. Pass `undefined` to dismiss the search bar. | ## Data Loading Props @@ -71,7 +67,7 @@ Changing `styles` triggers a full data reload. Spreadsheet data is preserved, bu | Prop | Type | Description | |------|------|-------------| -| `theme` | [`SpreadsheetTheme`](./types.md#spreadsheettheme) | Color theme. Built-in values: `"light"`, `"dark"`, `"contrast-light"`, `"contrast-dark"`. Also accepts custom theme name strings. See [Themes](./themes.md). | +| `theme` | [`SpreadsheetTheme`](/react/types#spreadsheettheme) | Color theme. Built-in values: `"light"`, `"dark"`, `"contrast-light"`, `"contrast-dark"`. Also accepts custom theme name strings. See [Themes](/react/themes/). | ## Container Props @@ -100,7 +96,10 @@ const [sheets, setSheets] = useState([ }, rows: { 0: { height: 40 } }, cols: { 0: { width: 150 }, 1: { width: 120 } }, - merged: [{ from: { row: 0, column: 0 }, to: { row: 0, column: 1 } }], + merged: [{ + from: { row: 0, column: 0 }, + to: { row: 0, column: 1 } + }], freeze: { row: 1 }, }, ]); @@ -152,8 +151,8 @@ To disable sheet tabs: ~~~tsx ~~~ diff --git a/docs/react/quick-start.md b/docs/react/quick-start.md index 2696bbca..a08255e5 100644 --- a/docs/react/quick-start.md +++ b/docs/react/quick-start.md @@ -1,5 +1,5 @@ --- -sidebar_label: Quick Start +sidebar_label: Quick start title: Quick Start with React Spreadsheet description: "Step-by-step guide to rendering your first DHTMLX React Spreadsheet component." --- @@ -8,10 +8,6 @@ description: "Step-by-step guide to rendering your first DHTMLX React Spreadshee This tutorial walks you through creating a React application with DHTMLX Spreadsheet from scratch. -:::tip Using a commercial license? -Replace `@dhtmlx/trial-react-spreadsheet` with `@dhx/react-spreadsheet` and configure the private registry. See [Installation](./installation.md). -::: - ## Create a new project ~~~bash @@ -25,7 +21,7 @@ cd my-spreadsheet-app npm install @dhtmlx/trial-react-spreadsheet ~~~ -For other package variants, see [Installation](./installation.md). +For other package variants, see [Installation](/react/installation/). ## Create demo data @@ -63,7 +59,7 @@ Replace the contents of `src/App.tsx`: ~~~tsx title="src/App.tsx" import { useState } from "react"; import { ReactSpreadsheet, type SheetData } from "@dhtmlx/trial-react-spreadsheet"; -import "@dhtmlx/trial-react-spreadsheet/dist/spreadsheet.react.css"; +import "@dhtmlx/trial-react-spreadsheet/spreadsheet.react.css"; import { sheets as initialSheets, styles } from "./data"; function App() { @@ -103,9 +99,9 @@ Open the URL shown in your terminal (typically `http://localhost:5173`) to see t ## Next steps -- [Props Reference](./props.md) — configure the spreadsheet behavior -- [Events Reference](./events.md) — respond to user actions -- [Types Reference](./types.md) — TypeScript interfaces and enums -- [Data & State Management](./state/index.md) — manage spreadsheet data in application state +- [Props Reference](/react/props/) — configure the spreadsheet behavior +- [Events Reference](/react/events/) — respond to user actions +- [Types Reference](/react/types/) — TypeScript interfaces and enums +- [Data & State Management](/react/state/index/) — manage spreadsheet data in application state You can also explore the [GitHub demo repository](https://github.com/DHTMLX/react-spreadsheet-demo) for a complete working example. diff --git a/docs/react/state/index.md b/docs/react/state/index.md index 3165c919..2bc76ac1 100644 --- a/docs/react/state/index.md +++ b/docs/react/state/index.md @@ -10,12 +10,12 @@ This section covers patterns for managing spreadsheet data in sync with your app ## Start here -- [State Management Basics](./state-management-basics.md) — core patterns: controlled props, event callbacks, the ref escape hatch, and performance tips +- [State Management Basics](/react/state/state-management-basics/) — core patterns: controlled props, event callbacks, the ref escape hatch, and performance tips ## State library guides -- [Redux Toolkit](./redux-toolkit.md) — step-by-step integration with Redux Toolkit +- [Redux Toolkit](/react/state/redux-toolkit/) — step-by-step integration with Redux Toolkit ## Key concept -The `sheets` prop is the **single source of truth** for all spreadsheet data. Pass an array of [`SheetData`](../types.md#sheetdata) objects, and the wrapper diffs your data against the current widget state, applying only the changes. Use immutable updates (spread operators, functional `setState` updaters) so React can detect changes efficiently. +The `sheets` prop is the **single source of truth** for all spreadsheet data. Pass an array of [`SheetData`](/react/types#sheetdata) objects, and the wrapper diffs your data against the current widget state, applying only the changes. Use immutable updates (spread operators, functional `setState` updaters) so React can detect changes efficiently. diff --git a/docs/react/state/redux-toolkit.md b/docs/react/state/redux-toolkit.md index f4988c5f..9a98505c 100644 --- a/docs/react/state/redux-toolkit.md +++ b/docs/react/state/redux-toolkit.md @@ -1,5 +1,5 @@ --- -sidebar_label: Redux Toolkit +sidebar_label: Redux toolkit title: React Spreadsheet with Redux Toolkit description: "Step-by-step integration of DHTMLX React Spreadsheet with Redux Toolkit." --- @@ -8,14 +8,10 @@ description: "Step-by-step integration of DHTMLX React Spreadsheet with Redux To This tutorial shows how to manage spreadsheet data in a Redux Toolkit store. -:::tip Using a commercial license? -Replace `@dhtmlx/trial-react-spreadsheet` with `@dhx/react-spreadsheet` and configure the private registry. See [Installation](../installation.md). -::: - ## Prerequisites - Familiarity with React, TypeScript, and [Redux Toolkit](https://redux-toolkit.js.org/) basics -- Completed the [State Management Basics](./state-management-basics.md) guide +- Completed the [State Management Basics](/react/state/state-management-basics) guide ## Setup @@ -122,7 +118,7 @@ ReactDOM.createRoot(document.getElementById("root")!).render( import { useRef } from "react"; import { useSelector, useDispatch } from "react-redux"; import { ReactSpreadsheet, type SpreadsheetRef } from "@dhtmlx/trial-react-spreadsheet"; -import "@dhtmlx/trial-react-spreadsheet/dist/spreadsheet.react.css"; +import "@dhtmlx/trial-react-spreadsheet/spreadsheet.react.css"; import type { RootState } from "./store"; import { setSheets } from "./store/spreadsheetSlice"; @@ -176,6 +172,6 @@ const getCellValue = (cell: string) => { ## Related -- [Props Reference](../props.md) — all component props -- [Events Reference](../events.md) — event callback props -- [State Management Basics](./state-management-basics.md) — core patterns +- [Props Reference](/react/props/) — all component props +- [Events Reference](/react/events/) — event callback props +- [State Management Basics](/react/state/state-management-basics/) — core patterns diff --git a/docs/react/state/state-management-basics.md b/docs/react/state/state-management-basics.md index 9a42b0ab..542d9cf9 100644 --- a/docs/react/state/state-management-basics.md +++ b/docs/react/state/state-management-basics.md @@ -6,10 +6,6 @@ description: "Core patterns for managing spreadsheet data in React: controlled p # Data Binding & State Management Basics -:::tip Using a commercial license? -Replace `@dhtmlx/trial-react-spreadsheet` with `@dhx/react-spreadsheet` and configure the private registry. See [Installation](../installation.md). -::: - ## The declarative model React Spreadsheet follows a declarative approach: you store sheet data in React state, pass it as props, and the wrapper automatically diffs your data against the current widget state — applying only the changes. @@ -17,7 +13,7 @@ React Spreadsheet follows a declarative approach: you store sheet data in React ~~~tsx import { useState } from "react"; import { ReactSpreadsheet, type SheetData } from "@dhtmlx/trial-react-spreadsheet"; -import "@dhtmlx/trial-react-spreadsheet/dist/spreadsheet.react.css"; +import "@dhtmlx/trial-react-spreadsheet/spreadsheet.react.css"; function App() { const [sheets, setSheets] = useState([ @@ -88,7 +84,7 @@ function App() { ## The ref escape hatch -For operations that don't map to declarative props, use the [`SpreadsheetRef`](../types.md#spreadsheetref) to access the underlying widget instance: +For operations that don't map to declarative props, use the [`SpreadsheetRef`](/react/types#spreadsheetref) to access the underlying widget instance: - **Serialize data:** `ref.current?.instance?.serialize()` - **Undo/redo:** `ref.current?.instance?.undo()` / `ref.current?.instance?.redo()` diff --git a/docs/react/themes.md b/docs/react/themes.md index d317e78f..19c4d51e 100644 --- a/docs/react/themes.md +++ b/docs/react/themes.md @@ -6,13 +6,9 @@ description: "Apply built-in or custom themes to DHTMLX React Spreadsheet." # React Spreadsheet Themes -:::tip Using a commercial license? -Replace `@dhtmlx/trial-react-spreadsheet` with `@dhx/react-spreadsheet` and configure the private registry. See [Installation](./installation.md). -::: - ## Built-in themes -The [`SpreadsheetTheme`](./types.md#spreadsheettheme) type defines four built-in themes: +The [`SpreadsheetTheme`](/react/types#spreadsheettheme) type defines four built-in themes: - `"light"` (default) - `"dark"` @@ -36,7 +32,7 @@ Use React state to switch themes dynamically: ~~~tsx import { useState } from "react"; import { ReactSpreadsheet, type SheetData, type SpreadsheetTheme } from "@dhtmlx/trial-react-spreadsheet"; -import "@dhtmlx/trial-react-spreadsheet/dist/spreadsheet.react.css"; +import "@dhtmlx/trial-react-spreadsheet/spreadsheet.react.css"; function App() { const [sheets] = useState([/* ... */]); @@ -90,6 +86,6 @@ import "./custom-theme.css"; ## Related -- [Themes](/themes/themes/) — built-in theme overview for DHTMLX Spreadsheet +- [Themes](/themes/) — built-in theme overview for DHTMLX Spreadsheet - [Base themes configuration](/themes/base_themes_configuration/) — configuring base themes - [Custom theme](/themes/custom_theme/) — creating custom themes diff --git a/docs/react/types.md b/docs/react/types.md index 43607a54..54ecfb96 100644 --- a/docs/react/types.md +++ b/docs/react/types.md @@ -6,7 +6,7 @@ description: "TypeScript interfaces, enums, and type aliases exported from @dhx/ # Types Reference -All types are exported from `@dhx/react-spreadsheet`. +All types are exported from `@dhx/react-spreadsheet` | `@dhtmlx/trial-react-spreadsheet`. ~~~tsx import type { SheetData, CellData, SpreadsheetRef /* ... */ } from "@dhtmlx/trial-react-spreadsheet"; diff --git a/sidebars.js b/sidebars.js index ddf3b300..6164c39a 100644 --- a/sidebars.js +++ b/sidebars.js @@ -243,7 +243,7 @@ module.exports = { "react/localization", { type: "category", - label: "Data & State Management", + label: "Data & state management", collapsible: true, collapsed: true, link: { From c02916f76d2a127a8a64ae01be57bc85d24c7075 Mon Sep 17 00:00:00 2001 From: Tatyana Date: Mon, 20 Apr 2026 13:16:39 -0400 Subject: [PATCH 3/4] [update] restructure sidebar and lowercase headings - Frameworks & integrations section added as top-level nav item - React Spreadsheet moved under Frameworks & integrations - Angular, Svelte, Vue integrations moved to same section - react_integration.md removed (replaced by React Spreadsheet docs) - heading capitalization lowercased across React docs - broken links fixed after restructure --- docs/guides.md | 2 +- docs/react/events.md | 16 +- docs/react/localization.md | 2 +- docs/react/overview.md | 10 +- docs/react/props.md | 38 +-- docs/react/quick-start.md | 4 +- docs/react/state/index.md | 2 +- docs/react/state/state-management-basics.md | 2 +- docs/react/themes.md | 2 +- docs/react/types.md | 8 +- docs/react_integration.md | 250 -------------------- docs/whats_new.md | 2 +- sidebars.js | 105 ++++---- 13 files changed, 96 insertions(+), 347 deletions(-) delete mode 100644 docs/react_integration.md diff --git a/docs/guides.md b/docs/guides.md index 8ba9f99a..ac48dd03 100644 --- a/docs/guides.md +++ b/docs/guides.md @@ -40,7 +40,7 @@ Shows the ways of loading data into Spreadsheet, handling events and using main Describes how to add DHTMLX Spreadsheet into apps based on other JavaScript frameworks. - [Integration with Angular](angular_integration.md) -- [Integration with React](react_integration.md) +- [React Spreadsheet](/react/) - [Integration with Vue.js](vuejs_integration.md) ## User guides diff --git a/docs/react/events.md b/docs/react/events.md index a0b386c1..4ef329c0 100644 --- a/docs/react/events.md +++ b/docs/react/events.md @@ -4,7 +4,7 @@ title: Events Reference description: "Event callback props for ReactSpreadsheet: actions, selection, editing, sheets, and derived state." --- -# Events Reference +# Events reference All event callbacks are optional props. "Before" callbacks can return `false` to cancel the operation. @@ -12,7 +12,7 @@ All event callbacks are optional props. "Before" callbacks can return `false` to The React wrapper uses `onCamelCase` prop names (e.g. `onAfterAction`) while the JS Spreadsheet API uses `camelCase` event names on the event bus (e.g. `afterAction`). See the [JS API Events Reference](/api/overview/events_overview/) for the imperative API. ::: -## Action Events +## Action events Fired for any user action (cell edits, formatting, structural changes, etc.). @@ -45,7 +45,7 @@ import { Actions } from "@dhtmlx/trial-react-spreadsheet"; /> ~~~ -## Selection Events +## Selection events Fired when the cell selection or focus changes. @@ -71,7 +71,7 @@ const [selectedCell, setSelectedCell] = useState("");

Current cell: {selectedCell}

~~~ -## Edit Events +## Edit events Fired when cell editing begins or ends. @@ -95,7 +95,7 @@ Fired when cell editing begins or ends. /> ~~~ -## Sheet Events +## Sheet events Fired when the active sheet tab changes. @@ -115,7 +115,7 @@ Fired when the active sheet tab changes. /> ~~~ -## Data Events +## Data events | Prop | Description | |------|-------------| @@ -132,7 +132,7 @@ const [loading, setLoading] = useState(true); /> ~~~ -## Input Events +## Input events Fired during user input in cells or the formula bar. @@ -142,7 +142,7 @@ Fired during user input in cells or the formula bar. | `onEditLineInput` | Fires on input in the formula/edit line. Handler: `(value: string) => void`. | | `onCellInput` | Fires on input in a cell during editing. Handler: `(cell: string, value: string) => void`. | -## Derived State Callbacks +## Derived state callbacks These callbacks notify about computed state changes rather than direct user actions. diff --git a/docs/react/localization.md b/docs/react/localization.md index b8c2dd45..52392586 100644 --- a/docs/react/localization.md +++ b/docs/react/localization.md @@ -4,7 +4,7 @@ title: React Spreadsheet Localization description: "Localize UI labels, formula names, and number/date formatting in React Spreadsheet." --- -# React Spreadsheet Localization +# React Spreadsheet localization React Spreadsheet provides two separate localization mechanisms for different aspects of the UI. diff --git a/docs/react/overview.md b/docs/react/overview.md index d114ee3e..0237b03e 100644 --- a/docs/react/overview.md +++ b/docs/react/overview.md @@ -4,7 +4,7 @@ title: React Spreadsheet Overview description: "Overview of the official React wrapper: declarative data model, props, theming, events, and ref access." --- -# React Spreadsheet Overview +# React Spreadsheet overview `ReactSpreadsheet` is a declarative React wrapper for the DHTMLX Spreadsheet widget. It provides a component-based API where props describe the spreadsheet state, and the wrapper handles synchronization with the underlying widget. @@ -36,12 +36,12 @@ The React wrapper provides access to the full feature set of DHTMLX Spreadsheet: - **Ref is an escape hatch.** For operations that don't map to declarative props (export, programmatic selection, undo/redo), access the underlying widget instance via ref. - **All widget events are exposed as typed `onXxx` callback props.** "Before" callbacks can return `false` to cancel the operation. -## Version Requirements +## Version requirements - React 18+ - ESM-only package -## Quick Start +## Quick start ~~~tsx import { useState } from "react"; @@ -88,7 +88,7 @@ import "@dhx/react-spreadsheet/spreadsheet.react.css"; See [Installation](/react/installation/) for registry configuration and all available package variants. -## Prop Update Behavior +## Prop update behavior Props are categorized by how the component handles changes: @@ -158,7 +158,7 @@ const sheets: SheetData[] = [ ~~~ -## Imperative Access via Ref +## Imperative access via ref ~~~tsx import { useRef } from "react"; diff --git a/docs/react/props.md b/docs/react/props.md index 94e86c72..2138a6de 100644 --- a/docs/react/props.md +++ b/docs/react/props.md @@ -4,11 +4,11 @@ title: Props Reference description: "Complete reference of all ReactSpreadsheet component props with types and examples." --- -# Props Reference +# Props reference All props are optional. The component renders an empty spreadsheet with default settings when no props are provided. -## Init-Only Props +## Init-only props Changing any of these props causes the widget to be destroyed and recreated. Spreadsheet data is preserved, but undo/redo history and UI state (selection, scroll position) are reset. @@ -28,7 +28,7 @@ Changing any of these props causes the widget to be destroyed and recreated. Spr Changing any init-only prop triggers a full destroy/recreate cycle. Undo/redo history, selection, and scroll position will be reset. ::: -## Runtime Props +## Runtime props These props are applied immediately without destroying the widget. No data loss or UI state reset. @@ -38,7 +38,7 @@ These props are applied immediately without destroying the widget. No data loss | `colsCount` | `number` | Number of columns in the grid. See JS API: [`colsCount`](/api/spreadsheet_colscount_config/). | | `readonly` | `boolean` | Enable read-only mode. See JS API: [`readonly`](/api/spreadsheet_readonly_config/). | -## Data Props +## Data props | Prop | Type | Description | |------|------|-------------| @@ -50,13 +50,13 @@ These props are applied immediately without destroying the widget. No data loss Changing `styles` triggers a full data reload. Spreadsheet data is preserved, but undo/redo history and UI state (selection, scroll position) are reset. ::: -## Search Props +## Search props | Prop | Type | Description | |------|------|-------------| | `search` | [`SearchConfig`](/react/types#searchconfig) | Controlled search state. Pass a `SearchConfig` object to trigger/update search. Pass `undefined` to dismiss the search bar. | -## Data Loading Props +## Data loading props | Prop | Type | Description | |------|------|-------------| @@ -69,7 +69,7 @@ Changing `styles` triggers a full data reload. Spreadsheet data is preserved, bu |------|------|-------------| | `theme` | [`SpreadsheetTheme`](/react/types#spreadsheettheme) | Color theme. Built-in values: `"light"`, `"dark"`, `"contrast-light"`, `"contrast-dark"`. Also accepts custom theme name strings. See [Themes](/react/themes/). | -## Container Props +## Container props | Prop | Type | Description | |------|------|-------------| @@ -80,7 +80,7 @@ Changing `styles` triggers a full data reload. Spreadsheet data is preserved, bu ## Examples -### Sheets with Cell Data +### Sheets with cell data ~~~tsx const [sheets, setSheets] = useState([ @@ -107,7 +107,7 @@ const [sheets, setSheets] = useState([ ~~~ -### Styles Example +### Styles example ~~~tsx const styles = { @@ -125,7 +125,7 @@ const styles = { ~~~ -### Toolbar Customization +### Toolbar customization ~~~tsx ~~~ -### Multi-Sheet Mode +### Multi-sheet mode ~~~tsx @@ -146,7 +146,7 @@ To disable sheet tabs: ~~~ -### Excel Import/Export +### Excel import/export ~~~tsx ~~~ -### European Number Formatting +### European number formatting ~~~tsx ~~~ -### Controlled Search +### Controlled search ~~~tsx const [search, setSearch] = useState(); @@ -186,7 +186,7 @@ const [results, setResults] = useState([]); /> ~~~ -### Theme Switching +### Theme switching ~~~tsx const [theme, setTheme] = useState("light"); @@ -201,19 +201,19 @@ const [theme, setTheme] = useState("light"); ~~~ -### Read-Only Mode +### Read-only mode ~~~tsx ~~~ -### Loading Data from URL +### Loading data from URL ~~~tsx ~~~ -### Locked Cells +### Locked cells ~~~tsx const sheets: SheetData[] = [ @@ -230,7 +230,7 @@ const sheets: SheetData[] = [ ~~~ -### Cell Validation +### Cell validation ~~~tsx const sheets: SheetData[] = [ diff --git a/docs/react/quick-start.md b/docs/react/quick-start.md index a08255e5..b5cdd61d 100644 --- a/docs/react/quick-start.md +++ b/docs/react/quick-start.md @@ -4,7 +4,7 @@ title: Quick Start with React Spreadsheet description: "Step-by-step guide to rendering your first DHTMLX React Spreadsheet component." --- -# Quick Start with React Spreadsheet +# Quick start with React Spreadsheet This tutorial walks you through creating a React application with DHTMLX Spreadsheet from scratch. @@ -102,6 +102,6 @@ Open the URL shown in your terminal (typically `http://localhost:5173`) to see t - [Props Reference](/react/props/) — configure the spreadsheet behavior - [Events Reference](/react/events/) — respond to user actions - [Types Reference](/react/types/) — TypeScript interfaces and enums -- [Data & State Management](/react/state/index/) — manage spreadsheet data in application state +- [Data & State Management](/react/state/) — manage spreadsheet data in application state You can also explore the [GitHub demo repository](https://github.com/DHTMLX/react-spreadsheet-demo) for a complete working example. diff --git a/docs/react/state/index.md b/docs/react/state/index.md index 2bc76ac1..6bb39445 100644 --- a/docs/react/state/index.md +++ b/docs/react/state/index.md @@ -4,7 +4,7 @@ title: "Data & State Management" description: "Patterns for managing DHTMLX Spreadsheet data in React state or with state management libraries." --- -# Data & State Management +# Data & state management This section covers patterns for managing spreadsheet data in sync with your application state — from basic React `useState` to state management libraries. diff --git a/docs/react/state/state-management-basics.md b/docs/react/state/state-management-basics.md index 542d9cf9..7f5100a3 100644 --- a/docs/react/state/state-management-basics.md +++ b/docs/react/state/state-management-basics.md @@ -4,7 +4,7 @@ title: Data Binding & State Management Basics description: "Core patterns for managing spreadsheet data in React: controlled props, event callbacks, and the ref escape hatch." --- -# Data Binding & State Management Basics +# Data binding & state management basics ## The declarative model diff --git a/docs/react/themes.md b/docs/react/themes.md index 19c4d51e..aa902755 100644 --- a/docs/react/themes.md +++ b/docs/react/themes.md @@ -4,7 +4,7 @@ title: React Spreadsheet Themes description: "Apply built-in or custom themes to DHTMLX React Spreadsheet." --- -# React Spreadsheet Themes +# React Spreadsheet themes ## Built-in themes diff --git a/docs/react/types.md b/docs/react/types.md index 54ecfb96..9677c072 100644 --- a/docs/react/types.md +++ b/docs/react/types.md @@ -4,7 +4,7 @@ title: Types Reference description: "TypeScript interfaces, enums, and type aliases exported from @dhx/react-spreadsheet." --- -# Types Reference +# Types reference All types are exported from `@dhx/react-spreadsheet` | `@dhtmlx/trial-react-spreadsheet`. @@ -190,7 +190,7 @@ ref.current?.instance?.undo(); ref.current?.instance?.redo(); ~~~ -## Actions Enum +## Actions enum Known spreadsheet action identifiers. Used in `onBeforeAction` / `onAfterAction` for type-safe action matching. The `| string` union on handler params allows forward-compatibility with future actions. @@ -225,7 +225,7 @@ Known spreadsheet action identifiers. Used in `onBeforeAction` / `onAfterAction` | `toggleFreeze` | Toggle freeze panes. | | `toggleVisibility` | Toggle row/column visibility. | -## Handler Type Aliases +## Handler type aliases | Type | Signature | Used by | |------|-----------|---------| @@ -249,7 +249,7 @@ type SpreadsheetConfigProps = Omit< Base type for component props. Exposes all `ISpreadsheetConfig` constructor options as flat props. -## Re-exported Upstream Types +## Re-exported upstream types These types are re-exported from `@dhx/ts-spreadsheet` for convenience: diff --git a/docs/react_integration.md b/docs/react_integration.md deleted file mode 100644 index e1374741..00000000 --- a/docs/react_integration.md +++ /dev/null @@ -1,250 +0,0 @@ ---- -sidebar_label: Integration with React -title: React Integration -description: You can learn about the React integration of the DHTMLX JavaScript Spreadsheet library in the documentation. Browse developer guides and API reference, try out code examples and live demos, and download a free 30-day evaluation version of DHTMLX Spreadsheet. ---- - -# Integration with React - -:::note -Looking for the declarative React wrapper? See [**React Spreadsheet**](/react/) for the official component-based API with props, events, and TypeScript support. -::: - -:::tip -You should be familiar with the basic concepts and patterns of [**React**](https://react.dev) to use this documentation. To refresh your knowledge, please refer to the [**React documentation**](https://react.dev/learn). -::: - -DHTMLX Spreadsheet is compatible with **React**. We have prepared code examples of how to use DHTMLX Spreadsheet with **React**. For more information, refer to the corresponding [**Example on GitHub**](https://github.com/DHTMLX/react-spreadsheet-demo). - -## Creating a project - -:::info -Before you start to create a new project, install [**Vite**](https://vite.dev/) (optional) and [**Node.js**](https://nodejs.org/en/). -::: - -You can create a basic **React** project or use **React with Vite**. Let's name the project as **my-react-spreadsheet-app**: - -~~~json -npx create-react-app my-react-spreadsheet-app -~~~ - -### Installation of dependencies - -Go to the new created app directory: - -~~~json -cd my-react-spreadsheet-app -~~~ - -Install dependencies and start the dev server. For this, use a package manager: - -- if you use [**yarn**](https://yarnpkg.com/), run the following commands: - -~~~json -yarn -yarn start -~~~ - -- if you use [**npm**](https://www.npmjs.com/), run the following commands: - -~~~json -npm install -npm run dev -~~~ - -The app should run on a localhost (for instance `http://localhost:3000`). - -## Creating Spreadsheet - -Now you should get the DHTMLX Spreadsheet source code. First of all, stop the app and proceed with installing the Spreadsheet package. - -### Step 1. Package installation - -Download the [**trial Spreadsheet package**](/how_to_start/#installing-spreadsheet-via-npm-or-yarn) and follow steps mentioned in the README file. Note that trial Spreadsheet is available 30 days only. - -### Step 2. Component creation - -Now you need to create a React component, to add Spreadsheet into the application. Create a new file in the ***src/*** directory and name it ***Spreadsheet.jsx***. - -#### Import source files - -Open the ***Spreadsheet.jsx*** file and import Spreadsheet source files. Note that: - -- if you use PRO version and install the Spreadsheet package from a local folder, the import paths look like this: - -~~~jsx title="Spreadsheet.jsx" -import { Spreadsheet } from 'dhx-spreadsheet-package'; -import 'dhx-spreadsheet-package/codebase/spreadsheet.css'; -~~~ - -Note that depending on the used package, the source files can be minified. In this case make sure that you are importing the CSS file as **spreadsheet.min.css**. - -- if you use the trial version of Spreadsheet, specify the following paths: - -~~~jsx title="Spreadsheet.jsx" -import { Spreadsheet } from '@dhx/trial-spreadsheet'; -import '@dhx/trial-spreadsheet/codebase/spreadsheet.min.css'; -~~~ - -In this tutorial you can see how to configure the **trial** version of Spreadsheet. - -#### Setting the container and adding Spreadsheet - -To display Spreadsheet on the page, you need to create the container for Spreadsheet, and initialize this component using the corresponding constructor: - -~~~jsx {2,6,9-10} title="Spreadsheet.jsx" -import { useEffect, useRef } from "react"; -import { Spreadsheet } from "@dhx/trial-spreadsheet"; -import "@dhx/trial-spreadsheet/codebase/spreadsheet.min.css"; // include Spreadsheet styles - -export default function SpreadsheetComponent(props) { - let container = useRef(); // initialize container for Spreadsheet - - useEffect(() => { - // initialize the Spreadsheet component - const spreadsheet = new Spreadsheet(container.current, {}); - - return () => { - spreadsheet.destructor(); // destruct Spreadsheet - } - }); - - return
; -} -~~~ - -#### Adding styles - -To display Spreadsheet correctly, you need to specify important styles for Spreadsheet and its container in the main css file of the project: - -~~~css title="index.css" -/* specify styles for initial page */ -html, -body, -#root { - height: 100%; - padding: 0; - margin: 0; -} - -/* specify styles for the Spreadsheet container */ -.widget { - height: 100%; -} -~~~ - -#### Loading data - -To add data into the Spreadsheet, we need to provide a data set. Let's create the ***data.js*** file in the ***src/*** directory and add some data into it: - -~~~jsx title="data.js" -export function getData() { - return { - styles: { - bold: { - "font-weight": "bold" - }, - right: { - "justify-content": "flex-end", - "text-align": "right" - } - }, - data: [ - { cell: "a1", value: "Country", css:"bold" }, - { cell: "b1", value: "Product", css:"bold" }, - { cell: "c1", value: "Price", css:"right bold" }, - { cell: "d1", value: "Amount", css:"right bold" }, - { cell: "e1", value: "Total Price", css:"right bold" }, - - { cell: "a2", value: "Ecuador" }, - { cell: "b2", value: "Banana" }, - { cell: "c2", value: 6.68, format: "currency" }, - { cell: "d2", value: 430 }, - { cell: "e2", value: 2872.4, format: "currency" }, - - { cell: "a3", value: "Belarus" }, - { cell: "b3", value: "Apple" }, - { cell: "c3", value: 3.75, format: "currency" }, - { cell: "d3", value: 600 }, - { cell: "e3", value: 2250, format: "currency" }, - - { cell: "a4", value: "Peru" }, - { cell: "b4", value: "Grapes" }, - { cell: "c4", value: 7.69, format: "currency" }, - { cell: "d4", value: 740 }, - { cell: "e4", value: 5690.6, format: "currency" }, - - // more cells with data - ] - } -} -~~~ - -Then open the ***App.js*** file and import data. After this you can pass data into the new created `` components as **props**: - -~~~jsx {2,5-6} title="App.js" -import Spreadsheet from "./Spreadsheet"; -import { getData } from "./data"; - -function App() { - let data = getData(); - return ; -} - -export default App; -~~~ - -Go to the ***Spreadsheet.jsx*** file and apply the passed **props** to the Spreadsheet via the [`parse()`](/api/spreadsheet_parse_method/) method: - -~~~jsx {5,11} title="Spreadsheet.jsx" -import { useEffect, useRef } from "react"; -import { Spreadsheet } from "@dhx/trial-spreadsheet"; -import "@dhx/trial-spreadsheet/codebase/spreadsheet.min.css"; - -export default function SpreadsheetComponent(props) { - let container = useRef(); - - useEffect(() => { - const spreadsheet = new Spreadsheet(container.current, {}); - - spreadsheet.parse(props.data); - - return () => { - spreadsheet.destructor(); - } - }); - - return
; -} -~~~ - -Now the Spreadsheet component is ready to use. When the element will be added to the page, it will initialize the Spreadsheet with data. You can provide necessary configuration settings as well. Visit our [Spreadsheet API docs](/api/overview/properties_overview/) to check the full list of available properties. - -#### Handling events - -When a user makes some action in the Spreadsheet, it invokes an event. You can use these events to detect the action and run the desired code for it. See the [full list of events](/api/overview/events_overview/). - -Open ***Spreadsheet.jsx*** and complete the `useEffect()` method in the following way: - -~~~jsx {5-8} title="Spreadsheet.jsx" -// ... -useEffect(() => { - const spreadsheet = new Spreadsheet(container.current, {}); - - spreadsheet.events.on("afterFocusSet", function(cell){ - console.log("Focus is set on a cell " + spreadsheet.selection.getSelectedCell()); - console.log(cell); - }); - - return () => { - spreadsheet.destructor(); - } -}, []); -// ... -~~~ - -After that, you can start the app to see Spreadsheet loaded with data on a page. - -![Spreadsheet initialization](assets/integrations/trial_spreadsheet.png) - -Now you know how to integrate DHTMLX Spreadsheet with React. You can customize the code according to your specific requirements. The final example you can find on [**GitHub**](https://github.com/DHTMLX/react-spreadsheet-demo). diff --git a/docs/whats_new.md b/docs/whats_new.md index dc920782..5b7d890c 100644 --- a/docs/whats_new.md +++ b/docs/whats_new.md @@ -261,7 +261,7 @@ Released on December 7, 2023 ### Updates -- Renewed [integrations with React, Angular and Vue.js](spreadsheet/category/integrations.md) +- Renewed [integrations with React, Angular and Vue.js](/integrations/) - Automatic [conversion of lowercase letters to upper case](spreadsheet/functions.md) in formulas - Auto closing of formulas diff --git a/sidebars.js b/sidebars.js index 6164c39a..b0826d3c 100644 --- a/sidebars.js +++ b/sidebars.js @@ -223,41 +223,6 @@ module.exports = { } ] }, - { - type: "category", - label: "React", - collapsible: true, - collapsed: true, - link: { - type: 'doc', - id: "react/index" - }, - items: [ - "react/overview", - "react/installation", - "react/quick-start", - "react/props", - "react/events", - "react/types", - "react/themes", - "react/localization", - { - type: "category", - label: "Data & state management", - collapsible: true, - collapsed: true, - link: { - type: 'doc', - id: "react/state/index" - }, - items: [ - "react/state/state-management-basics", - "react/state/redux-toolkit" - ] - }, - "react/nextjs" - ] - }, { type: "category", label: "Guides", @@ -309,24 +274,6 @@ module.exports = { "themes/custom_theme" ] }, - { - type: "category", - label: "Integrations", - collapsible: true, - collapsed: true, - link: { - type: 'generated-index', - title: "Integrations", - keywords: ['integrations'], - image: '/img/docusaurus.png' - }, - items: [ - "angular_integration", - "react_integration", - "svelte_integration", - "vuejs_integration" - ] - }, "using_typescript" ] }, @@ -370,6 +317,58 @@ module.exports = { ] } ] + }, + { + type: "category", + label: "Frameworks & integrations", + collapsible: true, + collapsed: true, + link: { + type: 'generated-index', + title: "Frameworks & integrations", + slug: '/integrations', + image: '/img/docusaurus.png' + }, + items: [ + { + type: "category", + label: "React Spreadsheet", + collapsible: true, + collapsed: true, + link: { + type: 'doc', + id: "react/index" + }, + items: [ + "react/overview", + "react/installation", + "react/quick-start", + "react/props", + "react/events", + "react/types", + "react/themes", + "react/localization", + { + type: "category", + label: "Data & state management", + collapsible: true, + collapsed: true, + link: { + type: 'doc', + id: "react/state/index" + }, + items: [ + "react/state/state-management-basics", + "react/state/redux-toolkit" + ] + }, + "react/nextjs" + ] + }, + "angular_integration", + "svelte_integration", + "vuejs_integration" + ] } ] }; From 440e04f12120d82cef49d2e29d4a17bb8a6aa83e Mon Sep 17 00:00:00 2001 From: Tatyana Date: Mon, 20 Apr 2026 14:17:08 -0400 Subject: [PATCH 4/4] [update] Frameworks & integrations section in guides - renamed section from "Integrations with other frameworks" - added Svelte, React Spreadsheet first with description - Angular, Svelte, Vue marked as GitHub demos --- docs/guides.md | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-) diff --git a/docs/guides.md b/docs/guides.md index ac48dd03..2ae1896b 100644 --- a/docs/guides.md +++ b/docs/guides.md @@ -35,13 +35,12 @@ Shows the ways of loading data into Spreadsheet, handling events and using main - [Event handling](handling_events.md) - [Customization](customization.md) -### Integrations with other frameworks +### Frameworks & integrations -Describes how to add DHTMLX Spreadsheet into apps based on other JavaScript frameworks. - -- [Integration with Angular](angular_integration.md) -- [React Spreadsheet](/react/) -- [Integration with Vue.js](vuejs_integration.md) +- [React Spreadsheet](/react/) - official React component with props, events, and TypeScript support +- [Integration with Angular](angular_integration.md) - GitHub demo of using Spreadsheet in an Angular app +- [Integration with Svelte](svelte_integration.md) - GitHub demo of using Spreadsheet in a Svelte app +- [Integration with Vue.js](vuejs_integration.md) - GitHub demo of using Spreadsheet in a Vue app ## User guides