unifyedx-storybook-syncfusion 0.4.0

package/claude-skill/SKILL.md

@@ -0,0 +1,219 @@
+---
+name: storybook-syncfusion-components
+description: Use CustomDataGrid, CustomGridToolbar and CustomDatePicker from unifyedx-storybook-syncfusion instead of building data tables, grid toolbars or Syncfusion date/time pickers by hand. Covers install, licence registration, CSS, the server-controlled grid state contract and the grid API ref.
+paths:
+  - "**/*.jsx"
+  - "**/*.tsx"
+  - "**/*.js"
+  - "**/*.ts"
+---
+
+# UnifyedX Syncfusion Components (`unifyedx-storybook-syncfusion`)
+
+Package version: 0.4.x | Last updated: 2026-09-15
+
+> **Install this skill** in a consuming app by copying
+> `node_modules/unifyedx-storybook-syncfusion/claude-skill/SKILL.md` to
+> `.claude/skills/storybook-syncfusion-components/SKILL.md`.
+> Pair it with the `storybook-components` skill from `unifyedx-storybook-new`.
+
+## 1. When to use this package — and when not to
+
+This package holds the **only** Syncfusion-backed UnifyedX components. It was split
+out of `unifyedx-storybook-new` in 0.4.0 so that apps without a data grid do not
+download the Syncfusion runtime (~1.3 GB installed) or its ~1.9 MB stylesheet.
+
+| Need | Use |
+|---|---|
+| A server-paged data table | `CustomDataGrid` (this package) |
+| Title / search / filter / export bar above that table | `CustomGridToolbar` (this package) |
+| Date **range**, **datetime** or **datetime range** picker | `CustomDatePicker` (this package) |
+| A plain date or time field that returns a `Date` | `DateField` / `TimeField` from **`unifyedx-storybook-new`** — do NOT pull in Syncfusion for this |
+| A numeric range slider | `RangeSlider` from **`unifyedx-storybook-new`** |
+| Page numbers without a grid | `Pagination` from **`unifyedx-storybook-new`** |
+
+**Rule:** only add this package if the app renders `CustomDataGrid`, `CustomGridToolbar`
+or a range/datetime `CustomDatePicker`. Otherwise use the core package alone.
+
+## 2. Install & setup
+
+```bash
+npm i unifyedx-storybook-syncfusion unifyedx-storybook-new \
+  @syncfusion/ej2-base@32.1.19 @syncfusion/ej2-react-base@32.1.19 \
+  @syncfusion/ej2-react-grids@32.1.19 @syncfusion/ej2-react-calendars@32.1.19 \
+  @syncfusion/ej2-react-inputs@32.1.19
+```
+
+All Syncfusion packages are **peer dependencies pinned to 32.1.19**. Declare them in
+the app's own `package.json` — do not rely on hoisting. Mixing Syncfusion majors on
+one page breaks `ej2-base`.
+
+```jsx
+// main.jsx — once, before rendering
+import 'unifyedx-storybook-new/style.css';
+import 'unifyedx-storybook-syncfusion/syncfusion.css';   // Syncfusion theme + component styles
+import { registerSyncfusionLicense } from 'unifyedx-storybook-syncfusion';
+
+registerSyncfusionLicense(import.meta.env.VITE_APP_SYNCFUSION_LICENSE_KEY);
+```
+
+- `registerSyncfusionLicense` is idempotent; calling it twice is harmless.
+- Import it from **this** package so the licence registers on the same `ej2-base` instance the components use.
+- Never hardcode the licence key in source; read it from env.
+
+## 3. Imports
+
+```jsx
+import { CustomDataGrid, CustomGridToolbar, CustomDatePicker } from 'unifyedx-storybook-syncfusion';
+import { UnifyedCoreButton, GenericFilter, notify } from 'unifyedx-storybook-new';
+```
+
+These three were removed from `unifyedx-storybook-new` in 0.4.0 — importing them from there fails.
+
+## 4. CustomDataGrid
+
+A lean, **server-controlled** Syncfusion grid. It cancels client-side data operations:
+the parent fetches one page and passes `data` + `totalCount`.
+
+```
+data=[]  totalCount={0}  columns=[]  uniqueId="grid"  height="600"
+pageIndex={1} (1-based)  pageSize={20}
+allowPaging={true}  allowSorting={true}  allowReordering={true}  allowResizing={true}
+allowFiltering={false}  allowGrouping={false}  allowExcelExport={false}  allowPdfExport={false}
+showColumnChooser={false}  enableSearchApi={false}  enableCheckbox={false}  selectionSettings
+onGridStateChange(state, rawArgs)  onRowSelected  onRowDeselected  onRowDoubleClick
+allowEditing={false}  editSettings  onCellSave
+apiRef  tableId  gridProps={}  ariaLabel  ariaLabelledBy  ariaDescribedBy
+```
+
+### State contract — `onGridStateChange(state)`
+
+```js
+{
+  reason: "paging" | "sorting" | "searching" | "filtering" | "grouping" | "reorder" | "columnstate" | "other",
+  page:   { index, size, skip, take },     // index is 1-based; skip/take ready for the API
+  sort:   [{ field, dir: "asc" | "desc" }],
+  search: "",
+  filters: [],
+  rawEvent,                                // the original Syncfusion args
+}
+```
+
+```jsx
+const [rows, setRows] = useState([]);
+const [total, setTotal] = useState(0);
+const apiRef = useRef(null);
+
+const load = useCallback(async ({ page, sort, search }) => {
+  const res = await axiosGet(`/api/users?skip=${page.skip}&take=${page.take}` +
+    `&sort=${sort[0]?.field ?? ''}&dir=${sort[0]?.dir ?? ''}&q=${encodeURIComponent(search)}`);
+  setRows(res.data.items); setTotal(res.data.total);
+}, []);
+
+<CustomDataGrid
+  data={rows}
+  totalCount={total}
+  columns={columns}
+  apiRef={apiRef}
+  tableId="users"
+  onGridStateChange={load}
+/>
+```
+
+**Never** pass the full dataset for client paging — fetch per page.
+
+### Columns
+
+Syncfusion column objects: `{ field, headerText, width, textAlign, template, allowSorting, allowEditing, isPrimaryKey, freeze }`.
+A column whose `headerText` is `"Action"`/`"Actions"` gets the Freeze service injected automatically (use `freeze: "Right"` to pin it).
+Mark one column `isPrimaryKey` when `enableCheckbox` / `persistSelection` is on, or Syncfusion logs *PRIMARY KEY MISSING*.
+
+### `apiRef` methods
+
+```
+getInstance()  refresh()  getSelectedRecords()  getSelectedRowIndexes()  clearSelection()
+selectRow(i)  selectRows([i])  deselectByPrimaryKey(k)  deselectByPrimaryKeys([k])
+search(text)          // needs enableSearchApi
+print()
+excelExport(opts)     // needs allowExcelExport
+pdfExport(opts)       // needs allowPdfExport
+openColumnChooser(x, y) // needs showColumnChooser
+getColumns()  getFilteredRecords()  autoFitColumns(fields)
+```
+Calling a gated method without its `allow*` / `show*` prop logs a warning and does nothing.
+
+### Inline editing
+
+`allowEditing`, `editSettings` and `onCellSave` are wired to the grid (fixed in 0.4.0 —
+before that they were accepted but ignored). Defaults: `mode: "Batch"`, no add/delete,
+no confirm dialogs. Override any default via `editSettings`.
+
+```js
+onCellSave({ field, columnName, value, previousValue, rowData, cancel(), originalEvent })
+// call cancel() to reject the edit (e.g. validation failed)
+```
+
+### State persistence
+
+Pass a stable `tableId` (or omit it to derive one from the route; `false`/`null` opts out).
+Page, page size and sort restore through `useTablePreferences` / `useRestoredGridState`
+from `unifyedx-storybook-new`. Use the **same** `tableId` on `CustomGridToolbar` and
+`GenericFilter` so search and filters restore alongside.
+
+## 5. CustomGridToolbar
+
+```
+heading="Data Grid"  subheading=""  totalCount={0}  apiRef (or legacy gridRef)  tableId
+showSearch={true}  showDelete={true}  showColumnChooser={true}
+showFilter={false}  showPrint={false}  showExcel={false}  showPdf={false}  showRefresh={false}  showAdd={false}
+onAdd  addBtnText="Add"  onFilterOpen  filterCount
+iSelectedRecords={0}  selectedRecords  searchPlaceholder="Search..."
+handleSearchChange  handleDeleteClick  handleRefreshClick
+excelFileName  pdfFileName  actionButtons=[]
+```
+
+`actionButtons` entries by `type`:
+- `"button"` (default) — a `UnifyedCoreButton`, or an `IconButton` when `iconOnly: true` and `icon` are set
+- `"segmented"` — `{ id, value, options:[{key,label}], onChange, ariaLabel }` renders a `SegmentedControl`
+- `"multioptions"` — a `UnifyedCoreButton` with a dropdown menu
+- `"custom"` — `{ id, render: () => <YourNode/> }`
+
+```jsx
+<CustomGridToolbar
+  heading="Users" totalCount={total} apiRef={apiRef} tableId="users"
+  showAdd addBtnText="Invite" onAdd={openInvite}
+  showFilter filterCount={countActiveFilters(filters)} onFilterOpen={() => setFilterOpen(true)}
+  showExcel excelFileName="users.xlsx"
+/>
+<CustomDataGrid apiRef={apiRef} tableId="users" allowExcelExport ... />
+```
+Export/print/column-chooser buttons call the grid through `apiRef`, so the grid must have the matching `allow*` prop.
+
+## 6. CustomDatePicker
+
+```
+mode="date" | "daterange" | "time" | "datetime" | "datetimerange"
+value  onChange  min  max  format  placeholder  step={30} (minutes)
+label  required  errorMessage  disabled  readOnly  showClearButton={true}
+strictMode={false}  typeable={true}  openOnFocus={false}  weekNumber  firstDayOfWeek
+width  cssClass  id  name  ariaLabel  ariaLabelledBy  ariaDescribedBy
+daterange:      startDate  endDate  separator="-"  presets  startPlaceholder  endPlaceholder
+datetimerange:  startValue  endValue  onStartChange  onEndChange
+events:         onOpen  onClose  onFocus  onBlur  onNavigated  onRenderDayCell  onCleared
+```
+
+- Single modes: `onChange({ value: Date, event })`.
+- `daterange`: `onChange({ startDate, endDate, ... })`.
+- `datetimerange`: separate `onStartChange` / `onEndChange`, each `{ value }`.
+
+**Prefer the core package** for `mode="date"` and `mode="time"`: `DateField` and
+`TimeField` in `unifyedx-storybook-new` emit the identical `{ value: Date }` and need
+no Syncfusion. Reach for `CustomDatePicker` only for range and datetime modes.
+
+## 7. Gotchas
+
+1. **CSS order**: import `unifyedx-storybook-syncfusion/syncfusion.css` once. It already contains the Syncfusion theme followed by the component overrides — do not import individual `@syncfusion/*/styles` files too, or the overrides lose.
+2. **One `unifyedx-storybook-new` instance**: this package imports core as a peer. If `npm ls unifyedx-storybook-new` shows two copies, hooks break with *Invalid hook call*. Keep both packages on the same version.
+3. **Peers must be explicit**: several older apps imported `CustomDataGrid` without declaring `@syncfusion/ej2-react-grids` and worked only via hoisting. Declare every peer in section 2.
+4. **Migrating from ≤0.3.x**: change the import specifier from `unifyedx-storybook-new` to `unifyedx-storybook-syncfusion`, add the package + peers, and add the `syncfusion.css` import. Nothing else changes.
+5. **Accessibility**: pass `label` or `ariaLabel` to every picker and `ariaLabel` to the grid; UnifyedX targets WCAG 2.0 AAA.

package/dist/components/CustomDataGrid/CustomDataGrid.d.ts

@@ -0,0 +1,2 @@
+export function CustomDataGrid(props: any): React.JSX.Element;
+import React from "react";

package/dist/components/CustomDatePicker/CustomDatePicker.d.ts

@@ -0,0 +1,107 @@
+/**
+ * CustomDatePicker — a unified Syncfusion-based date/time picker.
+ *
+ * Modes:
+ *  - "date"           → single date
+ *  - "daterange"      → start + end date
+ *  - "time"           → time only
+ *  - "datetime"       → single date + time
+ *  - "datetimerange"  → start + end date-time (two DateTimePickers)
+ */
+export function CustomDatePicker({ mode, value, onChange, min, max, format, placeholder, disabled, readOnly, showClearButton, floatLabelType, strictMode, typeable, openOnFocus, cssClass, width, step, weekNumber, firstDayOfWeek, label, labelId, ariaLabel, ariaLabelledBy, ariaDescribedBy, required, errorMessage, startDate, endDate, separator, presets, startPlaceholder, endPlaceholder, startValue, endValue, onStartChange, onEndChange, onOpen, onClose, onFocus, onBlur, onNavigated, onRenderDayCell, onCleared, id, name, htmlAttributes, ...rest }: {
+    [x: string]: any;
+    mode?: string;
+    value: any;
+    onChange: any;
+    min: any;
+    max: any;
+    format: any;
+    placeholder: any;
+    disabled?: boolean;
+    readOnly?: boolean;
+    showClearButton?: boolean;
+    floatLabelType?: string;
+    strictMode?: boolean;
+    typeable?: boolean;
+    openOnFocus?: boolean;
+    cssClass?: string;
+    width: any;
+    step?: number;
+    weekNumber?: boolean;
+    firstDayOfWeek: any;
+    label: any;
+    labelId: any;
+    ariaLabel: any;
+    ariaLabelledBy: any;
+    ariaDescribedBy: any;
+    required?: boolean;
+    errorMessage: any;
+    startDate: any;
+    endDate: any;
+    separator?: string;
+    presets: any;
+    startPlaceholder: any;
+    endPlaceholder: any;
+    startValue: any;
+    endValue: any;
+    onStartChange: any;
+    onEndChange: any;
+    onOpen: any;
+    onClose: any;
+    onFocus: any;
+    onBlur: any;
+    onNavigated: any;
+    onRenderDayCell: any;
+    onCleared: any;
+    id: any;
+    name: any;
+    htmlAttributes: any;
+}): React.JSX.Element;
+export namespace CustomDatePicker {
+    namespace propTypes {
+        let mode: any;
+        let value: any;
+        let onChange: any;
+        let min: any;
+        let max: any;
+        let format: any;
+        let placeholder: any;
+        let disabled: any;
+        let readOnly: any;
+        let showClearButton: any;
+        let floatLabelType: any;
+        let strictMode: any;
+        let typeable: any;
+        let openOnFocus: any;
+        let cssClass: any;
+        let width: any;
+        let step: any;
+        let weekNumber: any;
+        let firstDayOfWeek: any;
+        let label: any;
+        let labelId: any;
+        let required: any;
+        let errorMessage: any;
+        let startDate: any;
+        let endDate: any;
+        let separator: any;
+        let presets: any;
+        let startPlaceholder: any;
+        let endPlaceholder: any;
+        let startValue: any;
+        let endValue: any;
+        let onStartChange: any;
+        let onEndChange: any;
+        let onOpen: any;
+        let onClose: any;
+        let onFocus: any;
+        let onBlur: any;
+        let onNavigated: any;
+        let onRenderDayCell: any;
+        let onCleared: any;
+        let id: any;
+        let name: any;
+        let htmlAttributes: any;
+    }
+}
+import React from "react";

package/dist/components/CustomGridToolbar/CustomGridToolbar.d.ts

@@ -0,0 +1,35 @@
+export function CustomGridToolbar({ heading, subheading, totalCount, gridRef, apiRef, onAdd, onFilterOpen, addBtnText, showSearch, showDelete, showColumnChooser, showFilter, showPrint, showExcel, showPdf, showRefresh, showAdd, iSelectedRecords, selectedRecords, searchPlaceholder, handleRefreshClick, handleSearchChange, handleDeleteClick, excelFileName, pdfFileName, searchIconSize, searchIconClass, inputStyle, filterCount, actionButtons, tableId: tableIdProp, ...props }: {
+    [x: string]: any;
+    heading?: string;
+    subheading?: string;
+    totalCount?: number;
+    gridRef: any;
+    apiRef: any;
+    onAdd: any;
+    onFilterOpen: any;
+    addBtnText?: string;
+    showSearch?: boolean;
+    showDelete?: boolean;
+    showColumnChooser?: boolean;
+    showFilter?: boolean;
+    showPrint?: boolean;
+    showExcel?: boolean;
+    showPdf?: boolean;
+    showRefresh?: boolean;
+    showAdd?: boolean;
+    iSelectedRecords?: number;
+    selectedRecords: any;
+    searchPlaceholder?: string;
+    handleRefreshClick?: () => void;
+    handleSearchChange?: () => void;
+    handleDeleteClick?: () => void;
+    excelFileName: any;
+    pdfFileName: any;
+    searchIconSize: any;
+    searchIconClass: any;
+    inputStyle: any;
+    filterCount: any;
+    actionButtons?: any[];
+    tableId: any;
+}): React.JSX.Element;
+import React from "react";

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export * from "./components/CustomDataGrid/CustomDataGrid";
+export * from "./components/CustomGridToolbar/CustomGridToolbar";
+export * from "./components/CustomDatePicker/CustomDatePicker";
+export * from "./utils/registerSyncfusionLicense";