@dash-builder/react 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,7 @@
+# @dash-builder/react
+
+## 0.1.0
+
+### Minor Changes
+
+- 37f3acf: First public release: a dashboard grid where widgets flow into a fixed number of columns and can be dragged and resized, with four drop modes (insert, block, shrink, swap), drag handles, locked widgets, a row limit and a narrow (stacked) view. `@dash-builder/core` works on its own; `@dash-builder/angular` and `@dash-builder/react` wrap it.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 dash-builder contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,142 @@
-# Temporary Holding Version
+# @dash-builder/react
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+React bindings for [`@dash-builder/core`](https://www.npmjs.com/package/@dash-builder/core), a dashboard grid where widgets flow left to right into a fixed number of columns and can be dragged and resized. The layout is an ordered list: array order is position, there are no x/y coordinates.
+
+Requires React 19. Safe under `<StrictMode>` and for server rendering: the grid touches the DOM only in effects, and React does not re-render while you drag.
+
+## Install
+
+`react`, `react-dom` and `@dash-builder/core` are peer dependencies, so install them together:
+
+```sh
+pnpm add @dash-builder/react @dash-builder/core react react-dom
+# or: npm install @dash-builder/react @dash-builder/core react react-dom
+```
+
+## Styles
+
+Import the grid stylesheet once, in your entry file:
+
+```ts
+import '@dash-builder/core/grid.css';
+```
+
+## Usage
+
+```tsx
+import { useState } from 'react';
+import { Grid, Widget, type LayoutItem } from '@dash-builder/react';
+import '@dash-builder/core/grid.css';
+
+export function Dashboard() {
+  const [layout, setLayout] = useState<LayoutItem[]>([
+    { id: 'a', w: 2, h: 2 },
+    { id: 'b', w: 1, h: 1 },
+    { id: 'c', w: 1, h: 1, locked: true },
+  ]);
+
+  return (
+    <Grid columns={4} dropMode="insert" layout={layout} onLayoutChange={setLayout}>
+      {layout.map((i) => (
+        <Widget key={i.id} id={i.id}>
+          <Widget.Handle>{i.id}</Widget.Handle>
+          <p>Widget content</p>
+        </Widget>
+      ))}
+    </Grid>
+  );
+}
+```
+
+- `<Grid>` renders the grid container (a `div` with the class `dash-grid` and `display: grid`). Each `<Widget id>` is a widget; the id must match a layout entry.
+- `Widget.Handle` marks the only element a widget can be dragged by. Without one, the whole widget is the drag surface.
+
+### Rules
+
+- **The layout is controlled.** You own `layout`; update it from `onLayoutChange`. The grid never keeps its own copy. Changing `layout` from outside never calls `onLayoutChange`.
+- **Widgets must be `<Widget>` elements that are direct DOM children of the grid.** A wrapper component is fine as long as it renders the `Widget` element itself (`function Card(p) { return <Widget id={p.id}>...</Widget>; }`), including one that shows, hides or re-ids its widget from its own state, or a `<Suspense>` boundary around widgets: every `Widget` tells the grid when it commits or unmounts, so the grid picks it up without re-rendering. An extra wrapper `<div>` between the grid and the widgets is not fine: those widgets are not found. A plain `<div data-grid-id>` is not a supported widget either.
+- **Key widgets by id** (`key={item.id}`). The grid emits copies of the items, so keying by object identity or by index would remount widgets after every drop.
+- **Interactive controls don't start drags.** In a widget without a handle, `input`, `textarea`, `select`, `button`, `option`, `label`, `a[href]`, `contenteditable` elements and anything inside `[data-grid-no-drag]` ignore pointer-down for dragging. For a custom control (a canvas, a map), add `data-grid-no-drag` to it, or give the widget a `Widget.Handle`. A widget root that is itself a link, label or button can still be dragged; put `data-grid-no-drag` on the root to opt out.
+- **Locked widgets** (`locked: true`) can't be dragged or resized and keep their index.
+
+## API
+
+### `<Grid>`
+
+Extra props (`className`, `style`, `data-*`, ...) go to the container `div`. `className` is appended to `dash-grid`; `display: grid` is always applied, so `<Grid hidden>` stays visible: wrap the grid in an element you hide, or hide it with CSS (`display: none !important`).
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `layout` | `LayoutItem[]` | required | The layout, owned by the parent. |
+| `columns` | `number` | required | Number of columns. |
+| `onLayoutChange` | `(layout: LayoutItem[]) => void` | none | A drop or resize is released, `addItem` / `removeItem` succeed, or a `columns` change normalizes widths. |
+| `dropMode` | `'insert' \| 'block' \| 'shrink' \| 'swap'` | `'insert'` | Changeable at runtime. |
+| `maxRows` | `number` | none | Hard row limit for drops, resizes and `addItem`. |
+| `rowHeight` | `number` | `80` | Row height in px. |
+| `gap` | `number` | `8` | Gap between cells in px. |
+| `breakpoint` | `number` | `640` | Container width in px below which the narrow view is used. |
+| `ghost` | `(el: HTMLElement) => HTMLElement` | sanitized clone | Builds the drag ghost (see the core README). |
+| `onReject` | `(reason: RejectReason) => void` | none | An `addItem` is refused (`'max-rows'`, `'duplicate'` or `'invalid'`). |
+| `ref` | `Ref<GridHandle>` | none | Imperative `addItem` / `removeItem`, see below. |
+
+### `<Widget>` and `Widget.Handle`
+
+`<Widget id>` renders a `div` with the class `dash-item` and `data-grid-id={id}` (not a DOM `id`); `Widget.Handle` renders a `span` with `data-grid-handle`. Other props go to the element, but the grid attributes always win: `className` is appended to `dash-item`.
+
+- Changing a widget's `className` while it is being dragged drops the core's drag-state classes (`dash-item--placeholder`, `dash-item--swap-target`, `dash-item--swap-blocked`) until the pointer moves again (swap target) or the next drag (placeholder). The drag and its drop are not affected.
+- `dangerouslySetInnerHTML` on a `Widget` is not supported: the grid adds its own resize handle inside the widget, and React's inner HTML replaces the widget's whole content. Set it on an element inside the widget instead.
+
+### Adding widgets: use the ref
+
+```tsx
+import { useRef, useState } from 'react';
+import { Grid, Widget, type GridHandle, type LayoutItem } from '@dash-builder/react';
+
+export function Dashboard() {
+  const grid = useRef<GridHandle>(null);
+  const [layout, setLayout] = useState<LayoutItem[]>([]);
+
+  function add() {
+    const result = grid.current!.addItem({ id: crypto.randomUUID(), w: 1, h: 1 });
+    if (!result.ok) console.warn('not added:', result.reason);
+  }
+
+  return (
+    <>
+      <button type="button" onClick={add}>
+        Add
+      </button>
+      <Grid ref={grid} columns={4} layout={layout} onLayoutChange={setLayout}>
+        {layout.map((i) => (
+          <Widget key={i.id} id={i.id}>
+            {i.id}
+          </Widget>
+        ))}
+      </Grid>
+    </>
+  );
+}
+```
+
+| Method | Description |
+| --- | --- |
+| `addItem(item: LayoutItem, index?: number): DropResult` | Inserts at `index` (default: append). On success calls `onLayoutChange` with the new layout; otherwise calls `onReject` and returns `{ ok: false, reason }`. Consecutive calls in one handler build on each other. |
+| `removeItem(id: string): void` | Removes the item and calls `onLayoutChange`; an unknown id does nothing. |
+
+Prefer `addItem` over `setLayout([...layout, item])`: it enforces `maxRows`, refuses duplicate ids and reports the refusal through `onReject`. A plain `setLayout` bypasses all of that, because the grid shows whatever layout it is given.
+
+## Narrow view
+
+When the grid is narrower than `breakpoint` (default 640 px), widgets stack in a single column in list order and resizing is disabled. Dragging still reorders them, but only temporarily: a narrow-view reorder never calls `onLayoutChange`, so your layout is untouched. Set `breakpoint={0}` to turn the narrow view off. Near the edges of a scroll container, dragging autoscrolls.
+
+## Drop modes
+
+`insert`, `block`, `shrink` and `swap` are described in the [core README](https://www.npmjs.com/package/@dash-builder/core#drop-modes), together with locked widgets, `maxRows` and the layout JSON format.
+
+## Demo
+
+From the repository root: `pnpm --filter @dash-builder/core build && pnpm --filter @dash-builder/react demo`.
+
+## License
+
+MIT

package/dist/context.d.ts

@@ -0,0 +1,8 @@
+export interface GridContextValue {
+    /**
+     * Asks the grid to rescan and re-render its widgets. Calls coalesce into one refresh;
+     * outside a `<Grid>` (or during server rendering) this does nothing.
+     */
+    requestRefresh(): void;
+}
+export declare const GridContext: import("react").Context<GridContextValue>;

package/dist/context.js

@@ -0,0 +1,2 @@
+import { createContext } from 'react';
+export const GridContext = createContext({ requestRefresh() { } });

package/dist/grid.d.ts

@@ -0,0 +1,36 @@
+import type { ComponentPropsWithoutRef, ReactNode, Ref } from 'react';
+import type { DropMode, DropResult, GridOptions, LayoutItem, RejectReason } from '@dash-builder/core';
+export interface GridProps extends Omit<ComponentPropsWithoutRef<'div'>, 'children'> {
+    columns: number;
+    /** The layout, owned by the parent: update it from `onLayoutChange`. */
+    layout: LayoutItem[];
+    onLayoutChange?: (layout: LayoutItem[]) => void;
+    /** Default `'insert'`. */
+    dropMode?: DropMode;
+    maxRows?: number;
+    /** Default 80 (px). */
+    rowHeight?: number;
+    /** Default 8 (px). */
+    gap?: number;
+    /** Below this container width the grid stacks in one column. Default 640 (px). */
+    breakpoint?: number;
+    ghost?: GridOptions['ghost'];
+    onReject?: (reason: RejectReason) => void;
+    children?: ReactNode;
+    ref?: Ref<GridHandle>;
+}
+export interface GridHandle {
+    /**
+     * Adds `item` at `index` (default: append), enforcing `maxRows`. On success
+     * `onLayoutChange` is called with the new layout; otherwise `onReject` gets the reason.
+     */
+    addItem(item: LayoutItem, index?: number): DropResult;
+    /** Removes the item with `id`; an unknown id changes nothing and calls nothing. */
+    removeItem(id: string): void;
+}
+/**
+ * A dashboard grid around the `@dash-builder/core` controller. The rendered div is the
+ * grid container; its direct `<Widget>` children are the widgets. Controlled: the
+ * parent owns `layout`.
+ */
+export declare function Grid(props: GridProps): import("react").JSX.Element;

package/dist/grid.js

@@ -0,0 +1,148 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useImperativeHandle, useLayoutEffect, useRef, useState } from 'react';
+import { addItem as planAdd, createGrid, normalizeLayout, removeItem as planRemove } from '@dash-builder/core';
+import { GridContext } from './context.js';
+function shallowEqual(a, b) {
+    if (a === b)
+        return true;
+    if (!a || !b)
+        return false;
+    const ka = Object.keys(a);
+    return ka.length === Object.keys(b).length && ka.every((k) => Object.is(a[k], b[k]));
+}
+/**
+ * A dashboard grid around the `@dash-builder/core` controller. The rendered div is the
+ * grid container; its direct `<Widget>` children are the widgets. Controlled: the
+ * parent owns `layout`.
+ */
+export function Grid(props) {
+    const { columns, layout, onLayoutChange, dropMode = 'insert', maxRows, rowHeight = 80, gap = 8, breakpoint = 640, ghost, onReject, children, ref, className, style, ...divProps } = props;
+    const opts = { columns, dropMode, maxRows, rowHeight, gap, breakpoint, ghost };
+    const container = useRef(null);
+    const controller = useRef(undefined);
+    /** The layout last handed to the controller. */
+    const applied = useRef(undefined);
+    /** Set while setOptions runs before a new layout replaces the current one. */
+    const superseded = useRef(false);
+    /** A widget committed (or unmounted) since the controller last rendered. */
+    const dirty = useRef(false);
+    /** The className and style the container was last rendered with. */
+    const lastLook = useRef({ className, style });
+    /**
+     * The newest committed props, so callbacks never go stale and never re-create the
+     * controller. addItem/removeItem also advance `layout` to what they emitted, so calls
+     * chained before the parent re-renders compose; the next commit overwrites it.
+     */
+    const latest = useRef({ opts, layout, onLayoutChange, onReject });
+    // Widgets call this after each of their commits and when they unmount. When the Grid
+    // commits too, its sync effect below (which runs after its children's effects) refreshes
+    // at once; otherwise (a wrapper's own state, a Suspense boundary resolving) the queued
+    // microtask does, before the browser paints. Many requests make one refresh. Once the
+    // controller is destroyed (unmount), a queued refresh finds none and does nothing.
+    const [context] = useState(() => {
+        let queued = false;
+        return {
+            requestRefresh() {
+                dirty.current = true;
+                if (queued)
+                    return;
+                queued = true;
+                queueMicrotask(() => {
+                    queued = false;
+                    if (!dirty.current || !controller.current)
+                        return;
+                    dirty.current = false;
+                    controller.current.refresh();
+                });
+            },
+        };
+    });
+    // Declared first, so the effects below and anything after the commit see these props.
+    useLayoutEffect(() => {
+        latest.current = { opts, layout, onLayoutChange, onReject };
+    });
+    useLayoutEffect(() => {
+        const el = container.current;
+        const { opts: o, layout: l } = latest.current;
+        applied.current = l;
+        controller.current = createGrid(el, {
+            ...o,
+            layout: l,
+            onLayoutChange: (next) => {
+                if (!superseded.current)
+                    latest.current.onLayoutChange?.(next);
+            },
+            onReject: (r) => latest.current.onReject?.(r),
+        });
+        dirty.current = false; // createGrid has bound and placed the widgets
+        return () => {
+            controller.current?.destroy();
+            controller.current = undefined;
+        };
+    }, []);
+    // After every commit: apply options and layout, then refresh if a widget committed or the
+    // container was restyled. The core skips equal options and layouts.
+    useLayoutEffect(() => {
+        const g = controller.current;
+        if (!g)
+            return;
+        if (layout !== applied.current) {
+            applied.current = layout;
+            // The layout re-normalized for new columns is about to be replaced: don't emit it.
+            superseded.current = true;
+            try {
+                g.setOptions(opts);
+            }
+            finally {
+                superseded.current = false;
+            }
+            g.setLayout(layout); // normalized against the new columns; no-op on our own echo
+        }
+        else {
+            g.setOptions(opts); // a columns change may normalize the layout and emit
+        }
+        // A className or style change makes React rewrite the class attribute or style keys,
+        // dropping what core set imperatively; core's render restores dash-grid--narrow and the
+        // --dash-* variables (dash-grid and display: grid are rendered by React below).
+        // dash-grid--dragging, set during a drag, is not restored: a className change mid-drag
+        // drops it until the next drag (it only disables text selection / page scroll).
+        const look = lastLook.current;
+        const restyled = className !== look.className || !shallowEqual(style, look.style);
+        lastLook.current = { className, style };
+        // Every widget added, removed or re-id'd commits (or unmounts) itself, so `dirty` covers
+        // what scanning the children's ids here would; a reorder needs no refresh (the core
+        // places widgets by layout order, not DOM order).
+        if (dirty.current || restyled) {
+            dirty.current = false;
+            g.refresh();
+        }
+    });
+    useImperativeHandle(ref, () => ({
+        addItem(item, index) {
+            const { opts: o, layout: l, onLayoutChange: change, onReject: reject } = latest.current;
+            const config = { columns: o.columns, maxRows: o.maxRows, mode: o.dropMode };
+            // Plan on what the core renders (normalized), so maxRows holds for e.g. minH > h.
+            const result = planAdd(normalizeLayout(l, o.columns), config, item, index);
+            if (result.ok) {
+                latest.current.layout = result.layout; // a following add/remove builds on this
+                change?.(result.layout);
+            }
+            else {
+                reject?.(result.reason);
+            }
+            return result;
+        },
+        removeItem(id) {
+            const { layout: l, onLayoutChange: change } = latest.current;
+            const next = planRemove(l, id);
+            if (next === l)
+                return;
+            latest.current.layout = next; // a following add/remove builds on this
+            change?.(next);
+        },
+    }), []);
+    return (_jsx("div", { ...divProps, 
+        // Core styles hang off dash-grid and need display: grid; rendering them here keeps them
+        // when React rewrites the class attribute or style (and applies them in SSR markup).
+        className: className ? `dash-grid ${className}` : 'dash-grid', style: { ...style, display: 'grid' }, ref: container, children: _jsx(GridContext, { value: context, children: children }) }));
+}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { Grid } from './grid.js';
+export type { GridProps, GridHandle } from './grid.js';
+export { Widget, WidgetHandle } from './widget.js';
+export type { WidgetProps } from './widget.js';
+export type { LayoutItem, DropMode, RejectReason, DropResult } from '@dash-builder/core';

package/dist/index.js

@@ -0,0 +1,2 @@
+export { Grid } from './grid.js';
+export { Widget, WidgetHandle } from './widget.js';

package/dist/widget.d.ts

@@ -0,0 +1,27 @@
+import type { ComponentPropsWithRef } from 'react';
+export type WidgetProps = {
+    id: string;
+} & Omit<ComponentPropsWithRef<'div'>, 'id'>;
+/**
+ * A grid widget. `id` is the layout item id; it is exposed as `data-grid-id`, not as a DOM `id`.
+ *
+ * React owns the element, so a commit can undo what the core set on it imperatively:
+ * - `dash-item` is rendered here, because a `className` change rewrites the class attribute
+ *   and the core adds `dash-item` only when it first binds an element. The drag-state classes
+ *   (`dash-item--placeholder`, `--swap-target`, `--swap-blocked`) are set by the active drag,
+ *   not by the core's render, so a `className` change in the middle of a drag drops them:
+ *   the swap-target classes come back on the next pointer move, the placeholder class
+ *   only with the next drag. The drag itself and its drop are unaffected.
+ * - Text children are written with `textContent`, which deletes the core's resize handle.
+ * - The widget may mount, unmount or change id without the `<Grid>` re-rendering (a wrapper
+ *   with its own state, a Suspense boundary resolving).
+ * So after every commit, and when it unmounts, a widget asks the grid for a refresh: the
+ * core rescans its children and re-renders placement and handles. Requests coalesce into
+ * one refresh, which does not cancel an active drag or resize.
+ */
+export declare function Widget({ id, className, ...rest }: WidgetProps): import("react").JSX.Element;
+export declare namespace Widget {
+    export { WidgetHandle as Handle };
+}
+/** Marks the part of a widget that starts a drag (when the grid uses handles). */
+export declare function WidgetHandle(props: ComponentPropsWithRef<'span'>): import("react").JSX.Element;

package/dist/widget.js

@@ -0,0 +1,33 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useContext, useLayoutEffect } from 'react';
+import { GridContext } from './context.js';
+/**
+ * A grid widget. `id` is the layout item id; it is exposed as `data-grid-id`, not as a DOM `id`.
+ *
+ * React owns the element, so a commit can undo what the core set on it imperatively:
+ * - `dash-item` is rendered here, because a `className` change rewrites the class attribute
+ *   and the core adds `dash-item` only when it first binds an element. The drag-state classes
+ *   (`dash-item--placeholder`, `--swap-target`, `--swap-blocked`) are set by the active drag,
+ *   not by the core's render, so a `className` change in the middle of a drag drops them:
+ *   the swap-target classes come back on the next pointer move, the placeholder class
+ *   only with the next drag. The drag itself and its drop are unaffected.
+ * - Text children are written with `textContent`, which deletes the core's resize handle.
+ * - The widget may mount, unmount or change id without the `<Grid>` re-rendering (a wrapper
+ *   with its own state, a Suspense boundary resolving).
+ * So after every commit, and when it unmounts, a widget asks the grid for a refresh: the
+ * core rescans its children and re-renders placement and handles. Requests coalesce into
+ * one refresh, which does not cancel an active drag or resize.
+ */
+export function Widget({ id, className, ...rest }) {
+    const { requestRefresh } = useContext(GridContext);
+    useLayoutEffect(() => {
+        requestRefresh();
+        return requestRefresh;
+    });
+    return _jsx("div", { ...rest, className: className ? `dash-item ${className}` : 'dash-item', "data-grid-id": id });
+}
+/** Marks the part of a widget that starts a drag (when the grid uses handles). */
+export function WidgetHandle(props) {
+    return _jsx("span", { ...props, "data-grid-handle": "" });
+}
+Widget.Handle = WidgetHandle;

package/package.json

@@ -1,6 +1,71 @@
 {
   "name": "@dash-builder/react",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.1.0",
+  "description": "React bindings for @dash-builder/core: a dashboard grid with draggable, resizable widgets in a fixed number of columns.",
+  "license": "MIT",
+  "author": "Konstantin Penzin",
+  "homepage": "https://constantine-24.github.io/dash-builder/",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Constantine-24/dash-builder.git",
+    "directory": "packages/react"
+  },
+  "bugs": {
+    "url": "https://github.com/Constantine-24/dash-builder/issues"
+  },
+  "keywords": [
+    "dashboard",
+    "grid",
+    "layout",
+    "widgets",
+    "drag-and-drop",
+    "resizable",
+    "draggable",
+    "react"
+  ],
+  "type": "module",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE",
+    "CHANGELOG.md"
+  ],
+  "peerDependencies": {
+    "@dash-builder/core": "0.x",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0"
+  },
+  "devDependencies": {
+    "@dash-builder/core": "0.1.0",
+    "@testing-library/dom": "^10.4.2",
+    "@testing-library/react": "^16.3.3",
+    "@types/react": "^19.3.0",
+    "@types/react-dom": "^19.3.0",
+    "@vitejs/plugin-react": "^6.1.2",
+    "happy-dom": "^21.0.4",
+    "react": "^19.3.1",
+    "react-dom": "^19.3.1",
+    "typescript": "^7.0.2",
+    "vite": "^8.3.5",
+    "vitest": "^5.0.5"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit -p tsconfig.json",
+    "demo": "vite",
+    "build:demo": "vite build",
+    "test:smoke": "pnpm build && node scripts/smoke.mjs"
+  }
 }