@vertly/dashboard-grid 0.1.0

package/README.md

@@ -0,0 +1,72 @@
+# @vertly/dashboard-grid
+
+A fluid, drag-and-drop dashboard grid component for React, with its
+row/column layout math included. Widgets live in rows, can be reordered,
+dragged between rows, resized against their row neighbor, and rows
+themselves can be reordered and resized. Built on
+[`react-dnd`](https://react-dnd.github.io/react-dnd/).
+
+This package renders layout only — it has no opinion on what a widget's
+content is, how it's persisted, or what your "add widget" / "configure
+widget" flows look like. You supply those via callbacks and render props.
+
+## Usage
+
+```tsx
+import { DashboardGrid, type DashboardGridWidgetData, type RowLike } from '@vertly/dashboard-grid';
+
+interface MyWidget extends DashboardGridWidgetData {
+  title: string;
+}
+
+function MyDashboard({ rows, widgets }: { rows: RowLike[]; widgets: Record<string, MyWidget> }) {
+  return (
+    <DashboardGrid<MyWidget>
+      rows={rows}
+      widgets={widgets}
+      onUpdateLayout={(rows, colSpans) => saveLayout(rows, colSpans)}
+      onDeleteWidget={(widgetId) => deleteWidget(widgetId)}
+      renderRowEdgeAdd={({ rowId, edge }) => <AddWidgetButton rowId={rowId} edge={edge} />}
+      renderWidgetMenu={(widget, { onConfigure, onDelete }) => (
+        <WidgetMenu onConfigure={onConfigure} onDelete={onDelete} />
+      )}
+      renderWidgetConfigDialog={({ widget, open, onOpenChange }) => (
+        <WidgetConfigDialog widget={widget} open={open} onOpenChange={onOpenChange} />
+      )}
+    />
+  );
+}
+```
+
+Each widget's `content` (a `ReactNode`) is rendered as-is — render it
+yourself (e.g. server-side, or in a parent Server Component) and pass the
+result down, rather than having this component fetch or render widget data
+itself.
+
+## Layout math
+
+The row/column layout functions the component is built on
+(`placeItemAt`, `placeItemInNewRow`, `removeItemFromRow`, `resizeItemPair`,
+`resizeRow`, `moveRow`, `rebalanceRow`, `canPlaceInRow`, and the `RowLike`/
+`SizedItem` types and `COLS`/`ZONE_WIDTH_PX`/etc. constants) are also
+exported directly, in case you want to drive the same layout model without
+this component — e.g. computing/validating a layout server-side. They're
+plain functions with no React or DOM dependency.
+
+## Peer dependencies
+
+`react`, `react-dom`, `react-dnd`, `react-dnd-html5-backend`, `lucide-react`.
+
+## Styling
+
+Ships with a small set of Tailwind utility classNames (using shadcn-style
+CSS variable tokens like `border-border`, `bg-muted`, `text-primary`).
+Bring a Tailwind v4 setup with those tokens defined, or override the
+relevant selectors in your own global CSS.
+
+## Props
+
+See `DashboardGridProps` in the package's type definitions for the full
+list: `rows`, `widgets`, `readOnly`, `saveDebounceMs`, `onUpdateLayout`,
+`onDeleteWidget`, `renderRowEdgeAdd`, `renderWidgetMenu`,
+`renderWidgetConfigDialog`.