@sheetxl/grid-react 0.8.0-beta.11 → 0.8.0-beta.13

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@sheetxl/grid-react",
   "description": "Grid React - Advanced grid component for React",
-  "version": "0.8.0-beta.11",
+  "version": "0.8.0-beta.13",
   "license": "SEE LICENSE IN <LICENSE>",
   "type": "module",
   "exports": {
@@ -40,8 +40,8 @@
     "table"
   ],
   "dependencies": {
-    "@sheetxl/utils": "^0.8.0-beta.11",
-    "@sheetxl/utils-react": "^0.8.0-beta.11",
+    "@sheetxl/utils": "^0.8.0-beta.13",
+    "@sheetxl/utils-react": "^0.8.0-beta.13",
     "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/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/RangeFloatLayer.d.ts

@@ -108,7 +108,7 @@ export interface RangeFloatOptions<T = unknown> {
     /** Grace (ms) before a hovered float hides (bridges the gap to the float). @defaultValue the group's `leaveDelay` (400) */
     closeDelay?: number;
     /**
-     * A hovered float joins the grid's tooltip group (one tip at a time, closed by any press or key).
+     * A hovered float joins the grid's tooltip group (one tip at a time, closed by a press outside it or Escape).
      * `false` for a hover-opened float that is not a tooltip — a toolbar — which must survive a tip
      * opening beside it and a press on its own buttons.
      * @defaultValue true
@@ -202,6 +202,11 @@ export interface RangeFloatLayerProps<T = unknown> extends Omit<LayerProps, 'chi
      * selection — the layer only ever reads the active cell and subscribes to it.
      */
     selection?: ICellAnchor;
+    /**
+     * What the pointer is over that the cells cannot tell the tap: something drawn above them, which
+     * takes the pointer first. Wins over the probed cell while it is set.
+     */
+    hoveredOver?: RangeFloatTarget<T> | null;
 }
 /**
  * The **range float layer**: a {@link VirtualRangeFloat} as a layer of its own, whose tap probes the

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

@@ -113,6 +113,11 @@ export declare const RangeTooltipProvider: React.FC<RangeTooltipProviderProps>;
 export declare const RangeTooltip: (props: RangeTooltipProps) => null;
 export interface RangeTooltipHostProps extends Omit<LayerProps, 'children'> {
     className?: string;
+    /**
+     * Close the open tip and open no other while this holds, for whatever reason the host's owner has
+     * (the cell under the pointer is being edited, say).
+     */
+    dismiss?: boolean;
 }
 /**
  * The layer that draws the {@link RangeTooltip}s of the nearest {@link RangeTooltipProvider}: one tap,

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

@@ -42,7 +42,7 @@ export interface RangeTooltipLayerProps<T = unknown> extends Omit<RangeFloatLaye
  * The **tooltip kind** of range float: transient, opened by hovering a cell the probe recognizes, one
  * at a time grid-wide. A preset of {@link RangeFloatLayer} (`activateOn: 'hover'`) whose hover intent is
  * the tooltip group's client — so it inherits the group's timing, single-open rule, armed re-open, and
- * closes on any press or key — drawn in the group's bubble, in the tooltip band.
+ * closes on a press outside it or Escape — drawn in the group's bubble, under any menu.
  *
  * @remarks
  * Reach for `RangeFloatLayer` directly when the float is activated by the selection, driven by a

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.
@@ -39,19 +40,21 @@ export interface TooltipClient {
     readonly key: string;
     /**
      * A gesture tip holds the group: hover tips may not open while it is up. It is not closed by a press
-     * or a key (its gesture's modifiers), and its close does not arm the group.
+     * or Escape, and its close does not arm the group.
      */
     readonly gesture: boolean;
     /** The tip's element once mounted — a pointerdown inside it does not close it. */
     getElement(): Element | null;
-    /** Close now, no grace (the group took the slot, or the user pressed / typed). */
+    /** Close now, no grace (the group took the slot, or the user pressed elsewhere or hit Escape). */
     forceClose(): void;
 }
 /**
  * The single-open coordinator: at most one tip (by key) is up at a time, the next open is fast for
- * {@link TooltipTiming.armedFor} after a close, a gesture tip preempts hover, and any pointerdown or
- * keydown closes an open hover tip (a gesture tip closes with its gesture). Owned by the top {@link TooltipProvider} (or one that `isolate`s);
- * a built-in default serves a tree with no provider.
+ * {@link TooltipTiming.armedFor} after a close, a gesture tip preempts hover, and a pointerdown outside
+ * an open hover tip or Escape closes it (a gesture tip closes with its gesture). No other key and no
+ * selection change closes a tip; a layer's owner closes one for its own reasons through `dismiss`. Owned
+ * by the top {@link TooltipProvider} (or one that `isolate`s); a built-in default serves a tree with no
+ * provider.
  */
 export interface TooltipGroup {
     /** `client` is opening: every client open on another key closes first, with no grace. */
@@ -97,5 +100,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/layer/_Utils.d.ts

@@ -2,6 +2,8 @@ import { RangeCoords } from '@sheetxl/utils';
 import { LayerNode } from './LayerTypes';
 /** Content key for a range — stable across object identity (dedupe / memo / hover-target keys). */
 export declare const rangeKey: (r: RangeCoords) => string;
+/** Where a cell's hover tip stacks: over the grid's other floats, and under any menu. */
+export declare const GRID_TIP_Z_INDEX: string;
 /**
  * A layer's **derived stacking order** — its index in the normalized layer list, i.e. the react list
  * order with explicit-`zIndex` overrides already folded in (see {@link normalizeLayers}). This is the

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

@@ -13,8 +13,8 @@ export interface UseHoverIntentOptions {
      */
     closeDelay?: number;
     /**
-     * Join the grid's tooltip group: one tip open at a time, a fast re-open while armed, closed by any
-     * pointerdown or key, refused while a gesture tip is up. `false` for a hover-opened float that is not
+     * Join the grid's tooltip group: one tip open at a time, a fast re-open while armed, closed by a
+     * pointerdown outside it or Escape, refused while a gesture tip or a popup is up. `false` for a hover-opened float that is not
      * a tooltip — a table toolbar, a note's box — which must survive a tip opening beside it.
      * @defaultValue true
      */
@@ -65,7 +65,7 @@ export interface UseHoverIntentResult {
 /**
  * The **hover-intent state machine** behind a tip — the per-tip client of the grid's tooltip group
  * ({@link TooltipProvider}): dwell / grace timing, keep-open-on-tip-hover, and the group's rules
- * (single open, armed re-open, gesture preempts hover, closed by a press or a key). It does NO
+ * (single open, armed re-open, gesture and popup preempt hover, closed by a press outside it or Escape). It does NO
  * hit-testing: feed it a target key via {@link UseHoverIntentResult.setTarget} (`null` = nothing) and
  * spread {@link UseHoverIntentResult.tipProps} on the float.
  *

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`