@sheetxl/grid-react 0.8.0-beta.19 → 0.8.0-beta.20

package/package.json

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

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

@@ -1,4 +1,5 @@
 import { default as React } from 'react';
+import { RangeGlide } from '../range/RangeGlide';
 import { GridAnchor, GridPlacement, GridBoundary } from './useGridAnchor';
 /**
  * A gesture readout anchored to a DOM element rather than to the grid — a scrollbar thumb, which lives
@@ -35,11 +36,18 @@ export interface GestureTipProps {
     /** Offset (px) along the anchored edge (only `start` / `end` align). @defaultValue 0 */
     alignOffset?: number;
     /**
-     * Glide to each new position instead of jumping. Pass the timing of an anchor that glides itself (a
-     * move ghost) so the readout travels with it. Where it first appears is never animated.
+     * Glide to each new position instead of jumping, on CSS timing — for an anchor animated by CSS. For
+     * one drawn by a {@link RangeGlide}, pass {@link GestureTipProps.rangeGlide} instead. Where it first
+     * appears is never animated.
      * @defaultValue none — a readout jumps with its gesture
      */
     glide?: GestureTipGlide;
+    /**
+     * Travel with this glide, frame by frame: while it is in flight the readout is carried by its frame's
+     * offset from its target, so it stays on the moving range rather than waiting at the destination.
+     * The anchor must be the glide's target range. Don't combine with {@link GestureTipProps.glide}.
+     */
+    rangeGlide?: RangeGlide | null;
     /** Where the readout may live (a grid anchor only). @defaultValue 'data' */
     boundary?: GridBoundary;
     /**

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

@@ -1,4 +1,5 @@
 import { CellCoords, RangeCoords } from '@sheetxl/utils';
+import { RangeGlide } from './RangeGlide';
 /** Which corner (`tl`/`tr`/`bl`/`br`) or edge-midpoint (`t`/`b`/`l`/`r`) of the range to sit on. */
 export type HandleAnchor = 'tl' | 'tr' | 'bl' | 'br' | 't' | 'b' | 'l' | 'r';
 /**
@@ -24,6 +25,8 @@ export interface DragHandleRenderProps {
     handleProps: {
         /** The handle's identifying class(es) — `drag-handle` plus whatever the flavor tagged it with. */
         className?: string;
+        /** The handle element, which a glide moves frame by frame. Any element type takes it. */
+        ref: (element: HTMLElement | null) => void;
         onPointerDown: (e: React.PointerEvent) => void;
         onDoubleClick?: (e: React.MouseEvent) => void;
         onPointerEnter?: (e: React.PointerEvent) => void;
@@ -88,11 +91,12 @@ export interface DragHandleProps {
      */
     hoverStyle?: React.CSSProperties;
     /**
-     * Glide the handle to its new position (transition `left`/`top`) when `range` changes — pair with
-     * {@link RangeRect}'s `animatedTransition` so the corners track a move-drag's gliding outline
-     * instead of jumping. @defaultValue false
+     * Ride this glide's frames while it is in flight — the same clock as a {@link RangeRect} given the
+     * same glide, so the handle stays on the outline's corner. The glide must be heading to `range`. A
+     * handle pinned to the view ({@link DragHandleProps.clampToView}) hides until the glide lands: its
+     * pinned edge has no place along the way.
      */
-    animatedTransition?: boolean;
+    glide?: RangeGlide | null;
     /**
      * Pin the handle centre INSIDE the pane's viewport instead of letting it sit at the range's true
      * anchored corner. When that corner is far off-grid — e.g. a whole-row / whole-column fill selection

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

@@ -2,6 +2,7 @@ import { default as React } from 'react';
 import { CellCoords, RangeCoords } from '@sheetxl/utils';
 import { VisualSVGProps } from '../svg';
 import { DragHandleRenderProps } from './DragHandle';
+import { RangeGlide } from './RangeGlide';
 /**
  * Props for {@link FillHandle}. Follows the shared **RangeHandle** contract: a controlled `range`
  * (the fill template/source) in, the fill **destination** range out via `onDrag*`. The destination
@@ -61,6 +62,11 @@ export interface FillHandleProps extends VisualSVGProps {
      * Replaces the default dot. Use it for a custom fill mark (e.g. the Excel fill square).
      */
     renderHandle?: (props: DragHandleRenderProps) => React.ReactNode;
+    /**
+     * The glide the template's outline is drawn with, so the handle rides its corner frame by frame
+     * instead of arriving first. See {@link DragHandleProps.glide}.
+     */
+    glide?: RangeGlide | null;
 }
 /**
  * The destination range when filling `template` toward `to`. Excel-style single axis: extend along

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

@@ -0,0 +1,160 @@
+import { Bounds, RangeCoords, TopLeft } from '@sheetxl/utils';
+import { IGridPane } from '../surface';
+/**
+ * What a {@link RangeGlide} travels to: a range, plus the cell cut out of its fill (a selection's
+ * active cell), which travels on the same clock.
+ */
+export interface RangeGlideTarget {
+    range: RangeCoords;
+    hole?: RangeCoords;
+}
+/**
+ * One frame of a glide: the rectangle to draw and its hole, in a pane's VIEW space (the space
+ * `IGridPane.getBoundsFromRange` returns).
+ */
+export interface RangeGlideFrame {
+    outer: Bounds;
+    hole?: Bounds;
+    /**
+     * Where `outer` is heading: the target's box, clamped as `outer` is. Whatever is anchored to the
+     * target travels by `outer`'s offset from it.
+     */
+    to: Bounds;
+}
+/**
+ * The geometry a glide resolves through: one pane's view. A glide keeps no pixels of its own - the
+ * target is a range and the start point is absolute (content) space - so every pane that draws it
+ * asks through its own view, and a scroll mid-glide moves the frame with the cells.
+ */
+export interface RangeGlideView {
+    /** A range's box in view space. */
+    boundsOf(range: RangeCoords): Bounds;
+    /** Absolute (content) space → view space. */
+    toView(bounds: Bounds): Bounds;
+    /** View space → absolute (content) space. */
+    toAbsolute(bounds: Bounds): Bounds;
+    /** The view's visible box (view space). */
+    getViewport(): Bounds;
+    /** Where the view is scrolling to; a change mid-glide that the glide did not start with stops it. */
+    getScrollTarget(): TopLeft;
+    /** Device pixel ratio, for keeping a moving box's size steady. */
+    getDevicePixelRatio(): number;
+}
+/**
+ * Timing of a {@link RangeGlide}.
+ */
+export interface RangeGlideOptions {
+    /** How long a glide takes, in ms. `0` never glides. @defaultValue 60 */
+    duration?: number;
+    /**
+     * How far into the glide its first frame is drawn, in ms. The clock starts on the first animation
+     * frame, not when the target changes: the change usually lands inside the work it causes (a render
+     * of everything that reads the selection), and a clock running through that work would spend the
+     * glide where nothing paints and show it as a jump. @defaultValue one 60Hz frame
+     */
+    frameLead?: number;
+    /**
+     * How long a glide takes when it starts from inside another one - a held arrow key, a drag. Shorter,
+     * so a stream of retargets keeps up instead of trailing. @defaultValue 60% of `duration`
+     */
+    retargetDuration?: number;
+    /** Progress (0..1) → eased progress (0..1). @defaultValue ease-out quad */
+    easing?: (t: number) => number;
+    /** The clock. @defaultValue `performance.now` */
+    now?: () => number;
+    /** Schedule the next frame. @defaultValue `requestAnimationFrame` */
+    requestFrame?: (callback: () => void) => number;
+    /** Cancel a scheduled frame. @defaultValue `cancelAnimationFrame` */
+    cancelFrame?: (handle: number) => void;
+    /** Whether motion is reduced (no glides). @defaultValue the `prefers-reduced-motion` media query */
+    isReducedMotion?: () => boolean;
+}
+/**
+ * Interpolate `from` → `to` at eased progress `e`, edge by edge. Edges shared by both ends are
+ * returned unchanged; with one `e` for a box and its hole, a hole inside its box at both ends stays
+ * inside it throughout.
+ */
+export declare const lerpGlideBounds: (from: Bounds, to: Bounds, e: number, dpr: number) => Bounds;
+/**
+ * How far a frame is from where it is heading, at the edge something hangs off — the offset that
+ * carries a thing anchored to the target (a handle on its corner, a tip off its side) along with the
+ * frame. `side` and `align` name the edge as a grid placement does: `side` the edge, `align` the point
+ * along it.
+ */
+export declare const glideOffset: (frame: RangeGlideFrame, side: "t" | "b" | "l" | "r", align?: "start" | "center" | "end") => {
+    dx: number;
+    dy: number;
+};
+/**
+ * The {@link RangeGlideView} of a grid pane.
+ */
+export declare const paneGlideView: (pane: IGridPane) => RangeGlideView;
+/**
+ * A glide between ranges on one clock: the animation of a selection moving, growing or shrinking from
+ * one range to the next. Everything that travels with the range - its outline, its fill and hole, its
+ * handles, its tip - reads the same frame, so they move in lockstep.
+ *
+ * @remarks
+ * A glide holds ranges and one start point, not pixels: the target is a range and the start is in
+ * absolute (content) space, and each frame is resolved through the view that asks for it. So a glide
+ * is shared by every pane of a surface (one per frozen pane, each drawing its own clipped slice), and
+ * a scroll mid-glide carries the frame with the cells instead of dragging it. A scroll the glide did
+ * not start with - the user's wheel - ends it.
+ *
+ * It renders nothing. Readers {@link subscribe} and pull {@link frame} for their view on each tick;
+ * `frame` is `null` when settled, which means: draw the target as rendered.
+ */
+export declare class RangeGlide {
+    private readonly _duration;
+    private readonly _frameLead;
+    private readonly _retargetDuration;
+    private readonly _easing;
+    private readonly _now;
+    private readonly _requestFrame;
+    private readonly _cancelFrame;
+    private readonly _isReducedMotion;
+    private _target;
+    /** Where the glide started, in absolute space; `null` when settled. */
+    private _from;
+    private _start;
+    private _length;
+    /** Eased progress of the glide in flight. */
+    private _progress;
+    /** The view the glide started in, watched for a scroll it did not start with. */
+    private _view;
+    private _scrollBase;
+    private _handle;
+    private readonly _listeners;
+    constructor(options?: RangeGlideOptions);
+    /** The range the glide is heading to (or rests at). */
+    getTarget(): RangeGlideTarget | null;
+    /** A glide is in flight. */
+    isGliding(): boolean;
+    /**
+     * Head to `target`. The same target again does nothing, so every pane drawing one selection can
+     * call this on each render and only the first change counts. With `animate` the glide starts from
+     * what is drawn now - mid-flight, from the frame in flight; otherwise it jumps.
+     *
+     * @param view The view of the caller, used to capture the start point and watch for a user scroll.
+     * @returns Whether the target changed.
+     */
+    retarget(target: RangeGlideTarget, view: RangeGlideView, animate: boolean): boolean;
+    /** Jump to the target now. */
+    finish(): void;
+    /**
+     * The frame to draw in `view` now, or `null` when settled (draw the target as rendered). A glide
+     * whose start is nowhere near the view - a jump to the far end of the data - draws no frame.
+     */
+    frame(view: RangeGlideView): RangeGlideFrame | null;
+    /** Listen for frames (each tick, and on start and settle). Returns the unsubscribe. */
+    subscribe(listener: () => void): () => void;
+    /**
+     * What is drawn now, in absolute space: the frame in flight, else the target at rest. Unclamped, so
+     * it is the same whichever pane asks - a frozen pane the range is not in included.
+     */
+    private _shownAbsolute;
+    private readonly _tick;
+    private _settle;
+    private _notify;
+}
+//# sourceMappingURL=RangeGlide.d.ts.map

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

@@ -1,6 +1,7 @@
 import { RangeCoords } from '@sheetxl/utils';
 import { VirtualDivProps } from '../layer';
 import { VisualSVGProps } from '../svg';
+import { RangeGlide } from './RangeGlide';
 /**
  * Props for {@link RangeRect}: a thin range→bounds wrapper that places the {@link RectangleSVG}
  * **shape** at a grid range — it resolves the range to bounds via the pane, culls off-screen,
@@ -23,6 +24,12 @@ export interface RangeRectProps extends Omit<VirtualDivProps, 'fill'>, Omit<Visu
      * concern {@link RectangleSVG} can't express (it has no pane and does no culling).
      */
     clipInsets?: number;
+    /**
+     * Draw the frames of this glide while it is in flight; at rest, `range` and `hole` as given. The glide
+     * must be heading to `range` (and to `hole`, when there is one) - the caller retargets it. Every
+     * rectangle reading one glide moves on one clock.
+     */
+    glide?: RangeGlide | null;
 }
 /**
  * Places one device-aligned {@link RectangleSVG} at a grid range. Resolves the range to bounds via

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

@@ -1,6 +1,7 @@
 import { RangeCoords } from '@sheetxl/utils';
 import { VisualSVGProps } from '../svg';
 import { HandleAnchor, DragHandleRenderProps } from './DragHandle';
+import { RangeGlide } from './RangeGlide';
 /** The four corner handles (chart series / formula precedent rectangles use these). */
 export declare const RESIZE_ANCHORS_4: readonly HandleAnchor[];
 /** Corners + edge midpoints. */
@@ -9,7 +10,7 @@ export declare const RESIZE_ANCHORS_8: readonly HandleAnchor[];
  * Props for {@link RangeResizer}. Follows the shared **RangeHandle** contract: a controlled
  * `range` in, the resized range out via `onDrag*`. Extends {@link VisualSVGProps} (like
  * {@link RangeRectProps}) so the outline's paint props — `stroke`, `fill`, `strokeWidth`,
- * `animatedStroke`, `animatedTransition`, … — are passed directly; the handles inherit
+ * `animatedStroke`, … — are passed directly; the handles inherit
  * {@link DEFAULT_HANDLE_STYLE} for whatever you don't set. The grip color follows `stroke`.
  */
 export interface RangeResizerProps extends VisualSVGProps {
@@ -51,6 +52,11 @@ export interface RangeResizerProps extends VisualSVGProps {
     renderHandle?: (props: DragHandleRenderProps) => React.ReactNode;
     /** Keep the current focus across a handle drag (forwarded to {@link DragHandle.preserveFocus}). */
     preserveFocus?: boolean;
+    /**
+     * Draw the outline and its grips from this glide's frames while it is in flight, on one clock. The
+     * glide must be heading to `range`.
+     */
+    glide?: RangeGlide | null;
 }
 /**
  * A draggable, resizable rectangle: an outlined range with {@link DragHandle} grips on the requested

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

@@ -5,6 +5,8 @@
  * (`useWindowDragCells`) for their gesture mechanics — capture, de-dup, edge auto-scroll, touch, cancel.
  */
 export * from './RangeStyle';
+export * from './RangeGlide';
+export * from './useRangeGlide';
 export * from './RangeRect';
 export * from './RangeInsertBar';
 export * from './DragHandle';

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

@@ -0,0 +1,11 @@
+import { RangeGlide, RangeGlideOptions } from './RangeGlide';
+/**
+ * The {@link RangeGlide} shared by every pane of the surface under `key` - one clock for one logical
+ * range (a selection), so each pane's copy, and everything that travels with the range, reads the same
+ * frame. Never re-renders: readers subscribe to the glide itself.
+ *
+ * @param key Unique within the surface. `null` returns `null` (no glide).
+ * @param options Timing, read when the glide is first created under `key`.
+ */
+export declare const useRangeGlide: (key: string | null, options?: RangeGlideOptions) => RangeGlide | null;
+//# sourceMappingURL=useRangeGlide.d.ts.map

package/types/src/selection/RangesPickerLayer.d.ts

@@ -55,7 +55,10 @@ export interface RangesPickerLayerProps extends LayerProps {
      * {@link RESIZE_ANCHORS_8} for corners + edge midpoints.
      */
     anchors?: readonly HandleAnchor[];
-    /** Enable the move grip (drag the border to relocate a range, keeping its size). @defaultValue false */
+    /**
+     * Enable the move grip (drag the border to relocate a range, keeping its size). The moved range glides
+     * from cell to cell, its corner grips with it. @defaultValue false
+     */
     enabledMove?: boolean;
     /**
      * Don't claim the grid-wide **draw** gesture — the pointer-drag over empty grid that re-scopes the

package/types/src/selection/SelectionLayer.d.ts

@@ -57,6 +57,21 @@ export interface MoveDrop {
      */
     refused?: boolean;
 }
+/**
+ * How a selection glides from one range to the next — see {@link SelectionLayerProps.animate}.
+ */
+export interface SelectionAnimateOptions {
+    /**
+     * Names the selection's glide within the surface. Every pane drawing ONE selection must share it, and
+     * two selections drawn on one surface must not, so a host that swaps the model underneath (a sheet
+     * switch) puts the model's identity in it: a new key starts at rest rather than gliding in from the
+     * last model's range.
+     * @defaultValue 'selection'
+     */
+    key?: string;
+    /** How long a glide takes, in ms. @defaultValue 60 */
+    duration?: number;
+}
 /**
  * Props for {@link SelectionLayer}.
  */
@@ -292,6 +307,16 @@ export interface SelectionLayerProps extends LayerProps {
      * @defaultValue true
      */
     anchorHole?: boolean;
+    /**
+     * Glide the single-range selection from one range to the next — moving, growing and shrinking edge by
+     * edge, its active-cell cutout on the same clock — instead of jumping. Edges that don't change stay
+     * put, a scroll during a glide carries it with the cells, and a scroll the user starts ends it. A
+     * multi-range selection, and the selection a move or fill commits, jump. Off under
+     * `prefers-reduced-motion`.
+     *
+     * @defaultValue false
+     */
+    animate?: boolean | SelectionAnimateOptions;
 }
 /**
  * The selection layer: renders the selection (single-range "rich" treatment vs multi-range), routes

package/types/src/selection/SelectionTouchGrips.d.ts

@@ -1,4 +1,5 @@
 import { default as React } from 'react';
+import { RangeGlide } from '../range';
 import { ISelection } from './ISelection';
 /**
  * Props for {@link SelectionTouchGrips}.
@@ -6,6 +7,11 @@ import { ISelection } from './ISelection';
 export interface SelectionTouchGripsProps {
     /** The selection the touch handles read (for placement) and extend (via `modify`). */
     selection: ISelection;
+    /**
+     * The glide the selection is drawn with (the `SelectionLayer`'s, by its `animate` key), so the grips
+     * ride its frames on the outline's corners instead of arriving first.
+     */
+    glide?: RangeGlide | null;
 }
 /**
  * Touch selection handles: round grips at the active range's corners (or edges, for a whole row/column)

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

@@ -28,6 +28,16 @@ export declare function useSurfaceState<T>(key: string, initialValue: T | (() =>
  * @param initialValue The value an updater function receives while the cell has never been written.
  */
 export declare function useSurfaceStateSetter<T>(key: string, initialValue: T): Dispatch<SetStateAction<T>>;
+/**
+ * A stable OBJECT shared by every pane of the surface under `key` — created on first use, then the same
+ * instance for every caller. Unlike {@link useSurfaceState} it never re-renders: the object is the
+ * channel (a clock, an animator, an imperative store with its own `subscribe`), not a value to render.
+ *
+ * @param key The cell's key, unique within the surface — the same rule as `useSurfaceState`. `null`
+ *   opts out and returns `null`, so a caller can make the object conditional without breaking hook order.
+ * @param create Builds the object the first time the key is asked for.
+ */
+export declare function useSurfaceObject<T extends object>(key: string | null, create: () => T): T | null;
 /**
  * Read one {@link useSurfaceState} cell from a given store — for the component that OWNS the store and so
  * sits above its {@link SurfaceStateProvider} (it passes the store to the provider and reads it here).

package/types/src/svg/RectangleSVG.d.ts

@@ -76,10 +76,6 @@ export interface VisualSVGProps {
      * defaults; pass {@link AnimatedStrokeProps} to tune the dash/speed.
      */
     animatedStroke?: boolean | AnimatedStrokeProps;
-    /**
-     * Transition the path `d` so the shape glides when its bounds change (move-drag).
-     */
-    animatedTransition?: boolean;
     /** Class on the root `<svg>`. */
     className?: string;
     /**
@@ -89,12 +85,33 @@ export interface VisualSVGProps {
      */
     style?: Omit<React.CSSProperties, PaintCSSKey>;
 }
+/**
+ * Bounds that change faster than React renders - an animation - for {@link RectangleSVGProps.frameSource}.
+ */
+export interface RectangleFrameSource {
+    /**
+     * The bounds (and hole) to draw now, in the same space as {@link RectangleSVGProps.bounds}; `null`
+     * draws the rendered `bounds`.
+     */
+    getFrame(): {
+        bounds: Bounds;
+        hole?: Bounds;
+    } | null;
+    /** Called when the frame changes. Returns the unsubscribe. */
+    subscribe(onFrame: () => void): () => void;
+}
 export interface RectangleSVGProps extends VisualSVGProps, ShapeProps {
     /**
      * RAW bounds of an evenodd cut-out of the FILL (e.g. the active cell inside a
      * selection). Area-snapped (`snapDeviceEdge`), not stroke-snapped. Ignored for the stroke.
      */
     hole?: Bounds;
+    /**
+     * Draw each frame of an animation from here instead of re-rendering: the paths are rewritten in
+     * place, snapped exactly as a render would snap them, and a `null` frame puts back the rendered
+     * `bounds`.
+     */
+    frameSource?: RectangleFrameSource;
     /**
      * Escape hatch: props spread onto the root `<svg>` element (raw attributes, event handlers). Rare —
      * the wrapper is `pointerEvents: 'none'` by default and overlays seldom need it. Prefer the dedicated

package/types/src/svg/_Glide.d.ts

@@ -1,9 +0,0 @@
-/**
- * How a moving range outline glides between cells. What travels with it — its corner handles, its
- * gesture tip — rides the same timing, or it reads as trailing.
- */
-export declare const RANGE_GLIDE: {
-    readonly duration: 60;
-    readonly easing: "ease-in-out";
-};
-//# sourceMappingURL=_Glide.d.ts.map