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

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.11",
   "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.11",
+    "@sheetxl/utils-react": "^0.8.0-beta.11",
     "clsx": "^2.1.1",
     "react-merge-refs": "^3.0.2"
   },

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/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.
  */