@sheetxl/grid-react 0.7.27 → 0.7.28-beta.1

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

@@ -0,0 +1,114 @@
+import { Bounds } from '@sheetxl/utils';
+import { AnimatedStrokeProps, ShapeProps } from './Types';
+/**
+ * CSS keys that the SVG paths paint via **attributes**, not the wrapper's CSS. They are excluded from
+ * {@link VisualSVGProps.style} so `style={{ stroke }}` is a compile error (it would silently no-op) —
+ * set them via the dedicated `stroke`/`fill`/`strokeWidth`/`strokeDasharray` props instead.
+ */
+type PaintCSSKey = 'stroke' | 'fill' | 'strokeWidth' | 'strokeDasharray' | 'strokeDashoffset';
+/**
+ * The visual props shared by {@link RectangleSVG} and {@link RangeRect} — a curated surface, NOT the
+ * full SVG element props. Paint with the dedicated props (`stroke`/`fill`/`strokeWidth`/…); `style` is
+ * the wrapper's CSS for *effects* only (opacity/filter/transition). For raw `<svg>` attributes or
+ * handlers, use {@link RectangleSVGProps.propsRoot}.
+ */
+export interface VisualSVGProps {
+    /**
+     * Fill color. Omit for an outline-only shape.
+     */
+    fill?: string;
+    /**
+     * Set properties for the fill path.
+     */
+    propsFillPath?: React.SVGProps<SVGPathElement>;
+    /**
+     * Stroke color. Omit for a fill-only shape.
+     */
+    stroke?: string;
+    /**
+     * Set properties for the stroke path.
+     */
+    propsStrokePath?: React.SVGProps<SVGPathElement>;
+    /**
+     * Dash the stroke, e.g. `"3 2"` for a dashed marquee.
+     */
+    strokeDasharray?: string | number;
+    /**
+     * Starting dash offset of the stroke (the marching-ants phase).
+     */
+    strokeDashoffset?: string | number;
+    /**
+     * The stroke width — both **painted** and used for device **alignment** (the crisp-snapping parity:
+     * even widths center on a whole device px, odd on a half). In DEVICE px when aligned (the default) —
+     * so 1/2/3 stay crisp at any dpr, like the gridline; in user/CSS units when {@link disableAlign} is
+     * set. Stacked rectangles that share an `alignWidth` snap to the SAME grid, so they stay locked
+     * together while scrolling (no per-layer "shimmy") — e.g. a two-tone selection border draws its inner
+     * ring at the same `alignWidth`, `inset` inward, *under* the outer so only a sliver shows.
+     *
+     * @defaultValue 1
+     */
+    alignWidth?: number;
+    /**
+     * Skip device alignment: the stroke centerline (½-width + parity) and the fill/hole
+     * edges. Turn ON for a raw, unaligned rect (e.g. an invisible hit target).
+     *
+     * @defaultValue false
+     */
+    disableAlign?: boolean;
+    /**
+     * Disable edge-aware stroke placement. When edge-aware (the default), leading edges (top/left) sit
+     * before the divider, trailing (bottom/right) after — so the outline lines up with cell
+     * borders/gridlines; turn ON to center the stroke on the boundary instead. Ignored when
+     * {@link disableAlign} is set. Negated to read alongside {@link disableAlign}.
+     *
+     * @defaultValue false
+     */
+    disableEdgeAware?: boolean;
+    /**
+     * Push the rectangle inward by this many DEVICE px on every side before placement
+     * (still device-aligned) — for an inner ring layered inside an outer outline.
+     *
+     * @defaultValue 0
+     */
+    inset?: number;
+    /**
+     * Marching-ants animation on the stroke (e.g. the copy/cut marquee). `true` uses
+     * 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;
+    /**
+     * CSS on the root `<svg>` for *effects* — `opacity`, `filter`, `transition`, etc. NOT
+     * for paint: `stroke`/`fill`/`strokeWidth`/`strokeDasharray` are excluded here (the paths paint via
+     * attributes, so CSS paint would silently no-op) — use the dedicated props for those.
+     */
+    style?: Omit<React.CSSProperties, PaintCSSKey>;
+}
+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;
+    /**
+     * 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
+     * paint props, `style`, `propsStrokePath`, and `propsFillPath`.
+     */
+    propsRoot?: React.SVGProps<SVGSVGElement>;
+}
+/**
+ * A **shape**: a single device-pixel-aligned SVG rectangle (stroke and/or fill, with an optional
+ * evenodd hole). It owns ALL painting and ALL snapping of its sub-shapes — stroke centerline via
+ * `edgeCenter`, fill/hole edges via `snapDeviceEdge` — from the RAW `bounds` it is handed. It knows
+ * nothing about ranges or the pane: a **layer** ({@link RangeRect}) resolves a range to bounds and
+ * places it. (Shapes take bounds and paint; layers are pane-aware and compose into `renderLayers`.)
+ */
+export declare const RectangleSVG: import('react').MemoExoticComponent<(props: RectangleSVGProps) => import("react").JSX.Element | null>;
+export {};
+//# sourceMappingURL=RectangleSVG.d.ts.map

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

@@ -0,0 +1,15 @@
+import { Bounds } from '@sheetxl/utils';
+/**
+ * The RAW (pre-snap) bounds a shape leaf ({@link RectangleSVG} / {@link LineSVG}) draws at, provided
+ * by its container {@link Layer} — already expressed RELATIVE to the layer box's **device-aligned**
+ * origin. The shape still does its own `edgeCenter` / `snapDeviceEdge` snapping; because the origin is
+ * a whole number of device pixels, snapping these box-relative bounds lands on the identical device
+ * pixel as snapping absolute, just offset into the box (which carries the absolute translate).
+ *
+ * `null` when a shape is used standalone (not inside a `Layer`) — it then needs an explicit `bounds`
+ * prop, which always wins over this context.
+ */
+export declare const ShapeBoundsContext: import('react').Context<Bounds | null>;
+/** The container layer's box-relative bounds for a shape; the shape prefers its own `bounds` prop. */
+export declare const useShapeBounds: () => Bounds | null;
+//# sourceMappingURL=ShapeBounds.d.ts.map

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

@@ -0,0 +1,37 @@
+import { Bounds } from '@sheetxl/utils';
+/**
+ * The **shape contract**: a shape paints at the device `bounds` it is handed. `bounds` is OPTIONAL
+ * because a container {@link Layer} provides it via context ({@link useShapeBounds}) — author shapes
+ * without it inside a `Layer`, or pass it directly when standalone. A `Layer` *positions a box*; HTML
+ * children fill it and shape children paint at the box-relative bounds it provides.
+ */
+export interface ShapeProps {
+    /**
+     * The RAW (pre-snap) bounds to paint at. When a shape is inside a {@link Layer} it reads these from
+     * context (box-relative); otherwise pass it directly (absolute). The shape device-snaps it itself.
+     */
+    bounds?: Bounds;
+}
+/**
+ * Props for animated stroke
+ */
+export interface AnimatedStrokeProps {
+    /**
+     * The named of the animation
+     */
+    name?: string;
+    dashGap: number;
+    speed: number;
+    dashLength: number;
+    /**
+     * Color painted in the dash **gaps** — a solid under-stroke drawn beneath the animated dashes so the
+     * gaps reveal THIS color instead of whatever sits under the outline. Defaults to the grid background
+     * (`--sxl-color-base-100`), which keeps the marching ants legible even when the stroke runs directly
+     * over a same-colored fill (e.g. a reference border over the blue selection). Set explicitly to match
+     * a different backdrop.
+     *
+     * @defaultValue `var(--sxl-color-base-100, #fff)`
+     */
+    gapColor?: string;
+}
+//# sourceMappingURL=Types.d.ts.map

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

@@ -0,0 +1,9 @@
+/**
+ * **Shapes**: low-level SVG painters. They take resolved `bounds` and paint — no pane, no range. A
+ * **layer** ({@link VirtualDiv} / {@link RangeRect}) resolves a range to bounds and places them.
+ */
+export * from './Types';
+export * from './ShapeBounds';
+export * from './LineSVG';
+export * from './RectangleSVG';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1,56 @@
+import { CSSProperties } from 'react';
+import { TokenTheme, ThemeMode } from '@sheetxl/utils-react';
+/**
+ * grid-react's own **surfaces** — the `grid` (paper + gridlines) and `header` (elevated) token overrides,
+ * layered over the generic app baseline (utils-react `defaultTheme`). Headers have no non-sheet consumers, so
+ * they belong here, not in the shared util. First-pass values (tune against the storybook diff); a later
+ * step can DERIVE these from the app baseline (the `createGridStyleFromMUITheme` elevate/divider math)
+ * instead of authoring them.
+ *
+ * A "surface" is just a partial {@link TokenTheme} merged over the baseline — see utils-react `themeVars`.
+ */
+export declare const GRID_SURFACE: Record<ThemeMode, Partial<TokenTheme>>;
+/**
+ * @remarks
+ * States `color-base-100` in both modes rather than letting it fall through to the app desktop
+ * ({@link buildGridThemeCSS}): with the neutral `defaultTheme`, the dark desktop and the dark grid paper are
+ * both `#1e1e1e`, so an unstated header would equal the cell fill and erase the row/column gutters.
+ *
+ * Header *hover* is `color-base-hover`, not `color-base-200`. `base-100/200/300` is a depth ramp — paper →
+ * recessed ground → border — and a pointer state is not a step on it. Parking hover on `base-200` gave one
+ * ramp token two unrelated meanings (the desktop on the app surface, a hover here); the header now simply
+ * doesn't restate `base-200` and inherits the app's desktop, like every other surface.
+ */
+export declare const HEADER_SURFACE: Record<ThemeMode, Partial<TokenTheme>>;
+/** The grid-surface `--sxl-*` var block for a mode (baseline + grid overrides + any client tweaks). */
+export declare const gridThemeVars: (mode: ThemeMode, ...overrides: Array<Partial<TokenTheme> | undefined>) => CSSProperties;
+/** The header-surface `--sxl-*` var block for a mode (baseline + header overrides + any client tweaks). */
+export declare const headerThemeVars: (mode: ThemeMode, ...overrides: Array<Partial<TokenTheme> | undefined>) => CSSProperties;
+export interface GridThemeCSSOptions {
+    /** App baseline per mode. @defaultValue utils-react `defaultTheme` (via `buildThemeCSS`). */
+    app?: Record<ThemeMode, TokenTheme>;
+    /** `grid` surface overrides per mode. @defaultValue {@link GRID_SURFACE}. */
+    grid?: Record<ThemeMode, Partial<TokenTheme>>;
+    /**
+     * `header` surface overrides per mode. A cell that omits `color-base-100` defaults to the app's
+     * `color-base-200` — the desktop — resolved to a value at emission time (THEMING-DESIGN §4).
+     * @defaultValue {@link HEADER_SURFACE}.
+     */
+    header?: Record<ThemeMode, Partial<TokenTheme>>;
+    /** @defaultValue `'sxl-defaults'` */
+    layer?: string;
+    /**
+     * Scope selector (e.g. `.sheetxl-sheet-<id>`) to emit a per-instance theme. Omit for global (interim).
+     * @defaultValue undefined
+     */
+    scope?: string;
+}
+/**
+ * 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
+ * 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.
+ */
+export declare const buildGridThemeCSS: ({ app, grid, header, layer, scope }?: GridThemeCSSOptions) => string;
+//# sourceMappingURL=GridTheme.d.ts.map

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

@@ -0,0 +1,2 @@
+export * from './GridTheme';
+//# sourceMappingURL=index.d.ts.map

package/node/assets/style.css

@@ -1 +0,0 @@
-._sheetxl-grid_h9wwa_7{position:relative;box-sizing:border-box;user-select:none}._sheetxl-grid_h9wwa_7 *{box-sizing:border-box!important}._sheetxl-grid_h9wwa_7 *:focus{outline:none}._sheetxl-grid_h9wwa_7 .cell-container{position:absolute;overflow:visible;white-space:pre}._sheetxl-grid_h9wwa_7 .cell-container>*{inset:0;position:absolute}._sheetxl-grid_h9wwa_7 .sheetxl-stage{contain:strict}._sheetxl-grid_h9wwa_7 .sheetxl-stage>*{contain:strict}