@sheetxl/grid-react 0.8.0-beta.10 → 0.8.0-beta.12

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@sheetxl/grid-react",
   "description": "Grid React - Advanced grid component for React",
-  "version": "0.8.0-beta.10",
+  "version": "0.8.0-beta.12",
   "license": "SEE LICENSE IN <LICENSE>",
   "type": "module",
   "exports": {
@@ -40,8 +40,8 @@
     "table"
   ],
   "dependencies": {
-    "@sheetxl/utils": "^0.8.0-beta.10",
-    "@sheetxl/utils-react": "^0.8.0-beta.10",
+    "@sheetxl/utils": "^0.8.0-beta.12",
+    "@sheetxl/utils-react": "^0.8.0-beta.12",
     "clsx": "^2.1.1",
     "react-merge-refs": "^3.0.2"
   },

package/types/src/cell/CellRenderer.d.ts

@@ -50,4 +50,36 @@ export interface CellRendererProps<T = any> extends React.HTMLAttributes<HTMLEle
      */
     'data-rc'?: string;
 }
+/**
+ * The attribute that marks cell content as **interactive**: an element a rendered cell draws that
+ * takes the pointer itself (a checkbox, a button, a slider's thumb). Spread
+ * {@link CELL_INTERACTIVE_PROPS} onto that element rather than writing the attribute by hand.
+ *
+ * @remarks
+ * A rendered cell is `pointer-events: none`, and the selection layer above the cells starts a
+ * gesture on every press, so without this nothing drawn in a cell can take a press. A primary
+ * press on a marked element selects its cell and starts no drag; the event then reaches the
+ * element's own handlers, which decide what the press does (and stop it, so nothing below acts).
+ * A press with a modifier (Shift, Ctrl) is a selection press as usual. Layers above the selection
+ * still hear the press first.
+ */
+export declare const CELL_INTERACTIVE_ATTRIBUTE = "data-cell-interactive";
+/**
+ * The props that make an element of cell content interactive ({@link CELL_INTERACTIVE_ATTRIBUTE}):
+ * spread them onto the element that takes the pointer, then add its handlers (`onPointerDown`,
+ * `onPointerMove`, …) as on any element. The cell layer gives it `pointer-events: auto`; a drag
+ * captures the pointer on the element itself (`setPointerCapture`), as the Stage honors capture.
+ */
+export declare const CELL_INTERACTIVE_PROPS: Readonly<Record<string, string>>;
+/**
+ * Whether `target` is, or is inside, interactive cell content ({@link CELL_INTERACTIVE_ATTRIBUTE}).
+ */
+export declare const isCellInteractiveTarget: (target: EventTarget | null) => boolean;
+/**
+ * The cell the interactive content under `target` belongs to, read from the layer's `data-rc`
+ * stamp on the content's cell root, or `null` when `target` is not interactive content or the
+ * content carries no stamp. Content can reach past its cell (overflowing link text), so a press
+ * on it is about the content's cell, not the cell under the pointer.
+ */
+export declare const getCellInteractiveCoords: (target: EventTarget | null) => CellCoords | null;
 //# sourceMappingURL=CellRenderer.d.ts.map

package/types/src/cell/GridlineLayer.d.ts

@@ -1,5 +1,6 @@
 import { default as React } from 'react';
-import { OrientationFlags } from '@sheetxl/utils';
+import { RangeCoords, OrientationFlags } from '@sheetxl/utils';
+import { IGridPane } from '../surface';
 import { LayerProps } from '../layer';
 import { CellModelOptions } from './_CellModel';
 /**
@@ -28,6 +29,43 @@ export interface GridlineLayerProps extends Omit<LayerProps, 'children'>, CellMo
     /** Per-`<path>` props for the vertical (column) lines. */
     propsColumns?: React.SVGProps<SVGPathElement>;
 }
+/**
+ * Options for {@link buildGridlinePath}.
+ */
+export interface GridlinePathOptions {
+    /**
+     * Stroke width in device pixels; decides how each line center snaps.
+     *
+     * @defaultValue 1
+     */
+    width?: number;
+    /**
+     * CSS px added to each line's cross-axis position before it snaps (an even-width stroke that
+     * grows toward the trailing side).
+     *
+     * @defaultValue 0
+     */
+    shift?: number;
+    /**
+     * More gaps for one line, as view-relative `[start0, end0, start1, end1, ...]` along the line,
+     * sorted by start. `trailIndex` is the row (horizontal) or column (vertical) whose trailing edge
+     * the line is.
+     */
+    breaksAt?: (trailIndex: number) => readonly number[] | undefined;
+}
+/**
+ * Build a single SVG path `d` for one orientation's gridlines — each line broken around the merged
+ * ranges that straddle it. ONE path with many `M…L…` subpaths (vs one `<path>` per segment) keeps the
+ * DOM to a single node per axis; the segment count changes every scroll tick, so per-segment elements
+ * would thrash the DOM. Device snapping is baked into each subpath's coordinates and the stroke width
+ * is uniform, so a single path renders identically to N separate paths at any dpr.
+ *
+ * @param pane The pane to draw for.
+ * @param isHorizontal `true` for the row lines, `false` for the column lines.
+ * @param ranges Index-space ranges the lines break around (merges, overflow).
+ * @param options See {@link GridlinePathOptions}.
+ */
+export declare const buildGridlinePath: (pane: IGridPane, isHorizontal: boolean, ranges: readonly RangeCoords[], options?: GridlinePathOptions) => string;
 /**
  * A **layer** (pane-aware): paints the gridlines for its pane, broken around merged cells, inside a
  * single full-pane {@link Layer} host box. Sources the merge spans from the merges-only

package/types/src/editor/DefaultEditable.d.ts

@@ -10,7 +10,7 @@ import { EditSession, StartEditOptions, EditModel } from './EditSession';
  * @remarks
  * An implementation detail of {@link DefaultEditable}, not part of the layer-facing contract. Collapses
  * the former `getClean` + `canEdit` + `commit` (`null` ⇒ "not editable"). A story closes over a values
- * map; the real app reads an `ISheet` (and returns `null` for a protected cell).
+ * map; the real app reads an `IWorksheet` (and returns `null` for a protected cell).
  *
  * @typeParam C - clean type. @typeParam D - dirty type. @typeParam A - commit args.
  */
@@ -25,7 +25,7 @@ export type CreateEdit<C, D = string, A = EditCommitArgs> = (coords: CellCoords)
  * (`startEdit`/`commit`/`cancel`); an app-side bridge can publish {@link getSession} onto the edit-mode
  * bus on each `subscribe` notification. It does **not** vend sessions — there is only
  * ever one active edit, held here. {@link DefaultEditable} is the default implementation; the real app
- * supplies its own (or reuses it with an `ISheet`-backed {@link CreateEdit}).
+ * supplies its own (or reuses it with an `IWorksheet`-backed {@link CreateEdit}).
  *
  * @typeParam C - clean type. @typeParam D - dirty type. @typeParam A - commit args.
  */

package/types/src/editor/EditorDiv.d.ts

@@ -55,8 +55,9 @@ export interface EditorDivProps<C, D = string, A = EditCommitArgs> {
  *
  * @remarks
  * Unlike the layer, this is **always visible** — while idle it shows {@link EditorDivProps.idleClean}
- * (the active cell). It never auto-grabs focus (`autoFocus: false`): the field is focused by the
- * user's click, so the in-grid editor and the formula bar don't fight over focus when an edit begins.
+ * (the active cell). It does not grab focus for an ordinary edit: the field is focused by the user's
+ * click, so the in-grid editor and the formula bar don't fight over focus when an edit begins. An edit
+ * whose session names this host as its active editor from the start is the exception: it opens here.
  */
 export declare function EditorDiv<C, D = string, A = EditCommitArgs>(props: EditorDivProps<C, D, A>): React.ReactElement;
 export declare namespace EditorDiv {

package/types/src/editor/EditorStartLayer.d.ts

@@ -24,9 +24,10 @@ export interface EditorStartLayerProps<C, D = string, A = EditCommitArgs> {
  * Keys are positionless, so the floor position alone is not enough for them: a focused widget that
  * does not consume a printable key (it has no use for it, and must let keys through so its own
  * commands can resolve) would otherwise still reach this tap. The key start therefore acts only when
- * the key is aimed at the grid surface itself — the surface is the focused element — which is what
- * "the grid is in ready mode" means. A double-click needs no such guard: it has a position, and a
- * widget that owns that position consumes it.
+ * the key is aimed at the grid surface itself — the surface (or the pane's focus target, which
+ * stands in for it) is the focused element — which is what "the grid is in
+ * ready mode" means. A double-click needs no such guard: it has a position, and a widget that owns
+ * that position consumes it.
  */
 export declare function EditorStartLayer<C, D = string, A = EditCommitArgs>(props: EditorStartLayerProps<C, D, A>): React.ReactElement;
 //# sourceMappingURL=EditorStartLayer.d.ts.map

package/types/src/grid/Grid.d.ts

@@ -3,7 +3,7 @@ import { GridProps, IGrid } from './IGrid';
 /**
  * A virtualized grid: a thin wrapper around {@link GridSurface} that re-adds the cell + gridline
  * rendering the surface itself is agnostic to. It composes a `CellLayer` (cells), a `GridlineLayer`
- * (gridlines) and an optional `renderBorders` slot as ordinary layers — in the conventional z-order
+ * (gridlines) and an optional `borderLayers` slot as ordinary layers — in the conventional z-order
  * (gridlines → borders → below-layers → cells → above-layers) — and owns the content cache token the
  * cells bust on. Everything else is forwarded to the surface.
  *

package/types/src/grid/IGrid.d.ts

@@ -36,13 +36,13 @@ export interface GridProps extends GridSurfaceProps {
      * Layer(s) rendered BELOW the cells/borders (but above the gridlines) — the place for fills and
      * highlights. The `children` are the layers ABOVE the cells/borders.
      */
-    renderBelow?: LayerNode;
+    layersBelow?: LayerNode;
     /**
-     * Optional border layer(s), rendered just below the cells (above {@link GridProps.renderBelow} /
-     * gridlines). A render slot for a custom border treatment — distinct from the light
+     * Optional border layer(s), rendered just below the cells (above {@link GridProps.layersBelow} /
+     * gridlines), for a custom border treatment — distinct from the light
      * {@link GridProps.showGridLines} gridlines.
      */
-    renderBorders?: LayerNode;
+    borderLayers?: LayerNode;
     /**
      * Show grid lines. Useful for spreadsheets.
      */

package/types/src/header/HeaderDividerAnchor.d.ts

@@ -56,6 +56,8 @@ export interface IHeaderDividerAttributes {
 export interface IHeaderDividerElement extends HTMLDivElement, IHeaderDividerAttributes {
 }
 export interface HeaderDividerRendererProps extends HeaderDividerProps {
+    /** The pane the divider is drawn in. */
+    pane: IGridPane;
     /**
      * The divider's line in pane coordinates — zero-width for a column divider, zero-height for a row —
      * snapped to the device pixel the gridline paints. The renderer positions its element (hit area and
@@ -76,7 +78,7 @@ export interface HeaderDividerRendererProps extends HeaderDividerProps {
     isActive?: boolean;
 }
 export interface HeaderDividerAnchorProps extends HeaderDividerProps {
-    renderDivider?: (props: HeaderDividerRendererProps, pane: IGridPane) => React.ReactNode;
+    renderDivider?: (props: HeaderDividerRendererProps) => React.ReactNode;
     /**
      * The clipped bounds of the pane's visible headers, from {@link getHeaderDividerBounds}. Computed when
      * omitted; pass it when rendering a pane's worth of dividers so it is computed once.
@@ -135,6 +137,10 @@ export interface HeaderDividerAnchorProps extends HeaderDividerProps {
      */
     onDividerUnhide?: (index: number) => void;
 }
+/**
+ * The class on the default divider's root element, for styling and for finding dividers in the DOM.
+ */
+export declare const HEADER_DIVIDER_CLASS = "header-divider";
 export declare const DefaultHeaderDivider: import('react').NamedExoticComponent<Omit<HeaderDividerRendererProps, "ref"> & import('react').RefAttributes<IHeaderDividerElement>>;
 /**
  * A divider placed between headers to provider a visual cue for various actions.

package/types/src/layer/TooltipProvider.d.ts

@@ -1,4 +1,5 @@
 import { default as React } from 'react';
+import { RenderSlotFn } from '@sheetxl/utils-react';
 import { GridPlacement } from './useGridAnchor';
 import { HoverTipProps } from './useHoverIntent';
 /**
@@ -29,7 +30,7 @@ export interface TooltipRenderProps {
     style?: React.CSSProperties;
 }
 /** The bubble around a tip's content — the host's chrome, arrow and theme. */
-export type RenderTooltip = (props: TooltipRenderProps) => React.ReactNode;
+export type RenderTooltip = RenderSlotFn<TooltipRenderProps>;
 /**
  * A tip registered with its {@link TooltipGroup}. One per `useHoverIntent`; the per-pane copies of a
  * layer share a `key`, so they count as one tip.
@@ -97,5 +98,5 @@ export interface TooltipProviderProps {
  */
 export declare const TooltipProvider: React.FC<TooltipProviderProps>;
 /** The grid's default bubble — used when no provider supplies `renderTooltip`. */
-export declare const renderDefaultTooltip: RenderTooltip;
+export declare const defaultRenderTooltip: RenderTooltip;
 //# sourceMappingURL=TooltipProvider.d.ts.map

package/types/src/list/CheckboxList.d.ts

@@ -15,6 +15,12 @@ export interface ICheckboxListElement extends HTMLDivElement, CheckboxListAttrib
 /**
  * Props for {@link CheckboxList}.
  */
+/** What {@link CheckboxListProps.renderCheckbox} is handed. */
+export interface CheckboxRenderProps {
+    checked: boolean;
+    /** Set for the `(Select All)` tri-state when only some rows are checked. */
+    indeterminate?: boolean;
+}
 export interface CheckboxListProps extends React.HTMLAttributes<HTMLDivElement> {
     /** Number of rows. */
     itemCount: number;
@@ -37,7 +43,7 @@ export interface CheckboxListProps extends React.HTMLAttributes<HTMLDivElement>
      * `pointerEvents:none`). `indeterminate` is set for the `(Select All)` tri-state. Override to use a
      * styled control (MUI etc.). @defaultValue a native checkbox.
      */
-    renderCheckbox?: (checked: boolean, indeterminate?: boolean) => React.ReactNode;
+    renderCheckbox?: (props: CheckboxRenderProps) => React.ReactNode;
     /**
      * Render a divider between the `(Select All)` header and the list, or elsewhere as needed.
      */

package/types/src/list/PickList.d.ts

@@ -5,6 +5,11 @@ export interface PickListItem {
     /** The row's text. */
     text: string;
 }
+/** What {@link PickListProps.renderItem} is handed. */
+export interface PickListItemRenderProps {
+    item: PickListItem;
+    index: number;
+}
 export interface PickListAttributes {
     isPickList: () => true;
     /** The highlighted row, or `-1` when the list is empty. */
@@ -47,7 +52,7 @@ export interface PickListProps extends React.HTMLAttributes<HTMLDivElement> {
      */
     measureText?: (text: string) => number;
     /** Render a row's content. @defaultValue the text, clipped with an ellipsis. */
-    renderItem?: (item: PickListItem, index: number) => React.ReactNode;
+    renderItem?: (props: PickListItemRenderProps) => React.ReactNode;
     /** Take focus on mount, so the Arrow keys work without a click first. @defaultValue false */
     autoFocus?: boolean;
     /** The scroll state, when the caller owns it (see `ListSurfaceProps.viewport`). */

package/types/src/range/Draggable.d.ts

@@ -29,6 +29,12 @@ export interface DragInsert {
  * the drop will DO, and no pointer event carries that. Read the modifiers from here, never off the
  * event handed to the same callback (which is the last one the *pointer* fired).
  */
+/** What {@link DraggableProps.renderMove} is handed. */
+export interface DragMoveRenderProps {
+    /** The in-flight range. */
+    range: RangeCoords;
+    info: DragMoveInfo;
+}
 export interface DragMoveInfo {
     /** The live Ctrl / Shift / Alt / Meta state (Excel: Ctrl = copy, Shift = insert). */
     mods: DragModifiers;
@@ -169,7 +175,7 @@ export interface DraggableProps {
      * `info` re-renders the preview on a modifier change, so the ghost can become an insert I-beam the
      * moment Shift goes down.
      */
-    renderMove?: (range: RangeCoords, info: DragMoveInfo) => React.ReactNode;
+    renderMove?: (props: DragMoveRenderProps) => React.ReactNode;
     /**
      * The cursor painted for the duration of the drag. The grip's element is pointer-captured, so ITS
      * cursor is the one the browser shows once a drag is in flight — pass a mode-derived cursor (`copy`

package/types/src/surface/GridPane.d.ts

@@ -35,6 +35,8 @@ export interface GridPaneDef {
     rowIndex: number;
     elemStage: React.ReactNode;
     refStage: IStageElement | null;
+    /** See {@link IGridPane.registerFocusTarget}. */
+    focusTarget?: (() => HTMLElement | null) | null;
     scrollOrientation: OrientationFlags;
     insets: Rectangle;
 }

package/types/src/surface/IGridPane.d.ts

@@ -6,9 +6,22 @@ import { IGridMetrics } from '../metrics';
  */
 export interface IGridPane {
     /**
-     * Sets focus to the view.
+     * Sets focus to the view: its surface, or its {@link getFocusTarget | focus target} when there is one.
      */
     focus(options?: FocusOptions): void;
+    /**
+     * Register a focus target: an element inside the pane that takes the pane's focus in place of its
+     * surface while `target` returns it. A key aimed at it is a key aimed at the surface. The latest
+     * registration wins.
+     *
+     * @param target Asked each time the pane is focused; `null` lets the surface take focus.
+     */
+    registerFocusTarget(target: () => HTMLElement | null): RemoveListener;
+    /**
+     * The element focusing the pane lands on in place of its surface right now, or `null` for the
+     * surface itself.
+     */
+    getFocusTarget(): HTMLElement | null;
     /**
      * Set pointer capture to the view.
      */
@@ -161,7 +174,7 @@ export interface IGridPane {
      * For the freeze STRUCTURE use {@link getAllPanes} — the `Top` / `Left` / `TopLeft` entries exist only
      * when frozen — and each frozen pane's {@link getPaneRange} is exactly its frozen cell band, so
      * `getPaneRange().colEnd + 1` / `.rowEnd + 1` gives the frozen column / row COUNT. The configured
-     * freeze count as a model value lives on `ISheetView.getFreezePanes().coords`.
+     * freeze count as a model value lives on `IWorksheetView.getFreezePanes().coords`.
      */
     getFreezeTopLeft(): TopLeft;
     /**

package/types/src/surface/SurfaceStateProvider.d.ts

@@ -36,7 +36,7 @@ export interface SurfaceStateProviderProps {
  *
  * 1. an explicit {@link SurfaceStateProviderProps.store} prop (override);
  * 2. a store **inherited** from an ancestor `SurfaceStateProvider` — so a wider parent (e.g. a
- *    `SheetElement` wrapping its top-left corner + both header `GridSurface`s + the main `GridSurface`)
+ *    `WorksheetElement` wrapping its top-left corner + both header `GridSurface`s + the main `GridSurface`)
  *    shares one scope across sibling surfaces, letting a layer keyed the same in a header and in the body
  *    read one cell;
  * 3. otherwise a **lazily-created own** store (the standalone default).

package/types/src/surface/getPrimaryPane.d.ts

@@ -0,0 +1,13 @@
+import { AnchorLocation } from '@sheetxl/utils';
+import { IGridPane } from './IGridPane';
+/**
+ * The pane to use when no particular pane is called for: the one that owns a once-per-grid job, or
+ * takes focus and scrolling with nothing else to go by. The center (scrolling) pane when there is
+ * one, else the first frozen pane.
+ *
+ * @remarks
+ * The center pane is not always there: a freeze larger than the view leaves it no room, and the grid
+ * builds no pane without room. `null` only while the grid has no panes at all (it has no size).
+ */
+export declare const getPrimaryPane: (panes: Readonly<Partial<Record<AnchorLocation, IGridPane>>>) => IGridPane | null;
+//# sourceMappingURL=getPrimaryPane.d.ts.map

package/types/src/surface/index.d.ts

@@ -1,4 +1,5 @@
 export * from './IGridPane';
+export * from './getPrimaryPane';
 export * from './IGridSurface';
 export * from './GridSurface';
 export * from './useGridPane';

package/types/src/theme/GridTheme.d.ts

@@ -48,7 +48,7 @@ export interface GridThemeCSSOptions {
 /**
  * grid-react's theme stylesheet — the app baseline (utils-react `defaultTheme`, or a passed one) + the
  * `grid` / `header` surface overrides, compiled to the `data-sxl-theme-*` attribute matrix. Called by the
- * react `SheetElement` with neutral defaults into `@layer sxl-defaults` (so even a chromeless sheet is
+ * react `WorksheetElement` with neutral defaults into `@layer sxl-defaults` (so even a chromeless sheet is
  * themed), and by studio-mui with MUI-derived values into `sxl-app` on top; clients override in
  * `sxl-overrides`. Consumers just set `data-sxl-theme-*` attributes.
  */