@vertly/dashboard-grid 0.1.0 → 0.2.0

package/README.md

@@ -43,6 +43,60 @@ 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.
 
+## Adding or removing a widget
+
+`DashboardGrid` only manages layout state (row order, row heights, each
+widget's colSpan) internally — it seeds that state from `rows`/`widgets`
+once on mount, then owns it itself as the user drags/resizes/reorders,
+notifying you via `onUpdateLayout`/`onDeleteWidget` rather than re-reading
+it back from your props. That means **updating `rows`/`widgets` alone,
+after the initial mount, does not make an added or removed widget appear**
+— the mounted instance never re-seeds from new props.
+
+To make an add/remove show up, change the component's `key` (e.g. the
+widget-id set) whenever your data's widget membership changes, so React
+remounts it with a fresh seed:
+
+```tsx
+<DashboardGrid<MyWidget> key={Object.keys(widgets).join(',')} rows={rows} widgets={widgets} ... />
+```
+
+Don't key it on anything that changes on every drag/resize (like colSpan or
+row order) — that would remount mid-interaction and drop the user's
+in-progress drag.
+
+## Adding a widget by dragging it in
+
+To let users drag a widget in from outside the grid (e.g. a palette of
+widget kinds), give your palette items' `useDrag` the exported
+`EXTERNAL_ITEM_TYPE` as their `type`, and pass `onDropExternalItem` (dropped
+into an existing row) and/or `onCreateRowExternalItem` (dropped on the
+"start a new row" zone) — the grid's own drop zones accept that type
+alongside its internal widget drags once either prop is provided, and hand
+you back the raw dragged item plus where it landed:
+
+```tsx
+import { DashboardGrid, EXTERNAL_ITEM_TYPE } from '@vertly/dashboard-grid';
+import { useDrag } from 'react-dnd';
+
+function PaletteItem({ kind }: { kind: string }) {
+  const [, dragRef] = useDrag(() => ({ type: EXTERNAL_ITEM_TYPE, item: { kind } }));
+  return <div ref={dragRef}>{kind}</div>;
+}
+
+<DashboardGrid<MyWidget>
+  rows={rows}
+  widgets={widgets}
+  onDropExternalItem={(item, rowId, index) => spawnWidget(item as { kind: string }, rowId, index)}
+  onCreateRowExternalItem={(item) => spawnWidgetInNewRow(item as { kind: string })}
+/>;
+```
+
+This component never inspects the dragged item's shape — it's whatever
+your palette's `useDrag` supplied, passed straight through. As with any
+other add, remember to re-key the component once the new widget lands in
+your `rows`/`widgets` data (see above).
+
 ## Layout math
 
 The row/column layout functions the component is built on
@@ -68,5 +122,5 @@ relevant selectors in your own global CSS.
 
 See `DashboardGridProps` in the package's type definitions for the full
 list: `rows`, `widgets`, `readOnly`, `saveDebounceMs`, `onUpdateLayout`,
-`onDeleteWidget`, `renderRowEdgeAdd`, `renderWidgetMenu`,
-`renderWidgetConfigDialog`.
+`onDeleteWidget`, `onDropExternalItem`, `onCreateRowExternalItem`,
+`renderRowEdgeAdd`, `renderWidgetMenu`, `renderWidgetConfigDialog`.

package/dist/cn.cjs

@@ -0,0 +1,33 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var cn_exports = {};
+__export(cn_exports, {
+  cn: () => cn
+});
+module.exports = __toCommonJS(cn_exports);
+var import_clsx = require("clsx");
+var import_tailwind_merge = require("tailwind-merge");
+function cn(...inputs) {
+  return (0, import_tailwind_merge.twMerge)((0, import_clsx.clsx)(inputs));
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  cn
+});
+//# sourceMappingURL=cn.cjs.map

package/dist/cn.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/cn.ts"],"sourcesContent":["import { clsx, type ClassValue } from 'clsx';\nimport { twMerge } from 'tailwind-merge';\n\nexport function cn(...inputs: ClassValue[]) {\n  return twMerge(clsx(inputs));\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA,kBAAsC;AACtC,4BAAwB;AAEjB,SAAS,MAAM,QAAsB;AAC1C,aAAO,mCAAQ,kBAAK,MAAM,CAAC;AAC7B;","names":[]}

package/dist/cn.d.cts

@@ -0,0 +1,5 @@
+import { ClassValue } from 'clsx';
+
+declare function cn(...inputs: ClassValue[]): string;
+
+export { cn };

package/dist/cn.d.ts

@@ -0,0 +1,5 @@
+import { ClassValue } from 'clsx';
+
+declare function cn(...inputs: ClassValue[]): string;
+
+export { cn };

package/dist/cn.js

@@ -0,0 +1,9 @@
+import { clsx } from "clsx";
+import { twMerge } from "tailwind-merge";
+function cn(...inputs) {
+  return twMerge(clsx(inputs));
+}
+export {
+  cn
+};
+//# sourceMappingURL=cn.js.map

package/dist/cn.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/cn.ts"],"sourcesContent":["import { clsx, type ClassValue } from 'clsx';\nimport { twMerge } from 'tailwind-merge';\n\nexport function cn(...inputs: ClassValue[]) {\n  return twMerge(clsx(inputs));\n}\n"],"mappings":"AAAA,SAAS,YAA6B;AACtC,SAAS,eAAe;AAEjB,SAAS,MAAM,QAAsB;AAC1C,SAAO,QAAQ,KAAK,MAAM,CAAC;AAC7B;","names":[]}