feat: add F0GridStack component

packages/react/package.json

@@ -236,6 +236,7 @@
     "embla-carousel-autoplay": "^8.5.2",
     "embla-carousel-react": "^8.6.0",
     "embla-carousel-wheel-gestures": "^8.0.1",
+    "gridstack": "^12.3.3",
     "prosemirror-state": "^1.4.3",
     "prosemirror-view": "^1.38.1",
     "react-remove-scroll": "^2.7.1",

packages/react/src/components/Utilities/F0GridStack/F0GridStack.tsx

@@ -0,0 +1,166 @@
+import {
+  GridItemHTMLElement,
+  GridStackOptions,
+  GridStackWidget,
+} from "gridstack"
+import "gridstack/dist/gridstack.css"
+import { forwardRef, useImperativeHandle, useMemo } from "react"
+import { useGridStackContext } from "./components/grid-stack-context"
+import { GridStackProvider } from "./components/grid-stack-provider"
+import { GridStackRender } from "./components/grid-stack-render"
+import { GridStackRenderProvider } from "./components/grid-stack-render-provider"
+
+export type GridStackReactOptions = Omit<GridStackOptions, "children">
+
+export type GridStackReactSize = { w: number; h: number }
+
+export interface GridStackReactWidget extends GridStackWidget {
+  id: Required<GridStackWidget>["id"]
+  allowedSizes?: GridStackReactSize[]
+  renderFn?: () => React.ReactElement
+}
+
+/**
+ * Represents a node in the grid layout.
+ */
+export interface GridStackWidgetPosition {
+  id: string
+  w: number
+  h: number
+  x: number
+  y: number
+  meta?: Record<string, unknown>
+}
+
+export interface F0GridStackProps {
+  options: GridStackReactOptions
+  widgets: GridStackReactWidget[]
+  onChange?: (layout: GridStackWidgetPosition[]) => void
+}
+
+/**
+ * Methods exposed via ref to control the grid programmatically.
+ * @example
+ * ```tsx
+ * const gridRef = useRef<F0GridStackRef>(null)
+ *
+ * // Add a widget
+ * gridRef.current?.addWidget({
+ *   id: 'new-widget',
+ *   w: 2,
+ *   h: 2,
+ *   renderFn: () => <div>Content</div>
+ *   meta: {
+ *     // Your metadata associated with the widget
+ *   }
+ * })
+ *
+ * // Remove a widget
+ * gridRef.current?.removeWidget('widget-id')
+ *
+ * // Remove all widgets
+ * gridRef.current?.removeAll()
+ *
+ * // Save current layout
+ * const layout = gridRef.current?.saveOptions()
+ * ```
+ */
+export interface F0GridStackRef {
+  addWidget: (widget: GridStackReactWidget) => void
+  removeWidget: (id: string) => void
+  addSubGrid: (
+    subGrid: GridStackReactWidget & {
+      id: Required<GridStackWidget>["id"]
+      subGridOpts: Required<GridStackWidget>["subGridOpts"] & {
+        children: Array<
+          GridStackWidget & { id: Required<GridStackWidget>["id"] }
+        >
+      }
+    }
+  ) => void
+  removeAll: () => void
+}
+
+const RefHandler = forwardRef<F0GridStackRef, object>((_, ref) => {
+  const context = useGridStackContext()
+
+  useImperativeHandle(
+    ref,
+    () => ({
+      addWidget: context.addWidget,
+      removeWidget: context.removeWidget,
+      addSubGrid: context.addSubGrid,
+      removeAll: context.removeAll,
+    }),
+    [context]
+  )
+
+  return null
+})
+
+RefHandler.displayName = "RefHandler"
+
+export const F0GridStack = forwardRef<F0GridStackRef, F0GridStackProps>(
+  ({ options, widgets, onChange }, ref) => {
+    const gridOptions = useMemo(
+      () => ({
+        ...options,
+        children: widgets,
+      }),
+      // eslint-disable-next-line react-hooks/exhaustive-deps
+      [widgets]
+    )
+
+    const closestAllowed = (
+      w: number,
+      h: number,
+      allowed: { w: number; h: number }[]
+    ) => {
+      let best = allowed[0],
+        bestDist = Infinity
+      for (const a of allowed) {
+        const dx = a.w - w,
+          dy = a.h - h
+        const dist = dx * dx + dy * dy
+        if (dist < bestDist) {
+          bestDist = dist
+          best = a
+        }
+      }
+      return best
+    }
+
+    const onResizeStop = (_: Event, el: GridItemHTMLElement) => {
+      // el is the DOM element of the grid item
+      const node = el.gridstackNode // node contains w,h,x,y
+      if (!node) return
+
+      const allowed = el.gridstackNode?.allowedSizes ?? []
+      if (allowed.length === 0) {
+        return
+      }
+
+      const target = closestAllowed(node.w ?? 1, node.h ?? 1, allowed)
+
+      if (node.w !== target.w || node.h !== target.h) {
+        // update will reposition if necessary
+        node.grid?.update(el, { w: target.w, h: target.h })
+      }
+    }
+
+    return (
+      <GridStackProvider
+        initialOptions={gridOptions}
+        onResizeStop={onResizeStop}
+        onChange={onChange}
+      >
+        <RefHandler ref={ref} />
+        <GridStackRenderProvider>
+          <GridStackRender />
+        </GridStackRenderProvider>
+      </GridStackProvider>
+    )
+  }
+)
+
+F0GridStack.displayName = "F0GridStack"

packages/react/src/components/Utilities/F0GridStack/__stories__/F0GridStack.mdx

@@ -0,0 +1,212 @@
+import { Canvas, Meta, Controls } from "@storybook/addon-docs/blocks"
+
+import * as GridStackStories from "./GridStackReact.stories"
+
+<Meta of={GridStackStories} />
+
+# GridStack
+
+## Introduction
+
+### Definition
+
+F0GridStack is a React wrapper for the GridStack library that enables the
+creation of resizable and draggable grid layouts. It provides a flexible,
+interactive grid system where widgets can be dynamically arranged, resized, and
+repositioned by users or programmatically through ref methods.
+
+### Purpose
+
+The purpose of F0GridStack in our design system is as follows:
+
+- **Interactive Layouts**: Enables users to customize their dashboard or
+  workspace layouts by dragging and resizing widgets
+- **Dynamic Content Management**: Allows programmatic addition and removal of
+  widgets at runtime
+- **Responsive Grid System**: Provides a flexible grid that adapts to different
+  screen sizes and widget configurations
+- **Layout Persistence**: Supports saving and restoring widget positions and
+  sizes through the onChange callback
+- **Nested Grids**: Supports sub-grids for complex, hierarchical layouts
+
+## Basic Usage
+
+The default GridStack configuration demonstrates a simple grid layout with
+multiple widgets that can be dragged and resized.
+
+<Canvas of={GridStackStories.Default} />
+<Controls of={GridStackStories.Default} />
+
+## Programmatic Control with Ref Methods
+
+F0GridStack exposes several methods through a ref that allow you to
+programmatically control the grid layout. This is useful for dynamic widget
+management, such as adding or removing widgets based on user actions or
+application state.
+
+### Accessing Ref Methods
+
+To use the ref methods, create a ref using `useRef<F0GridStackRef>(null)` and
+attach it to the `F0GridStack` component:
+
+```tsx
+import { useRef } from "react"
+import { F0GridStack, type F0GridStackRef } from "@/components/Utilities/F0GridStack"
+
+const gridRef = useRef<F0GridStackRef>(null)
+
+<F0GridStack ref={gridRef} options={{ column: 12 }} widgets={[]} />
+```
+
+### Available Methods
+
+#### `addWidget`
+
+Adds a new widget to the grid programmatically.
+
+**Parameters:**
+
+- `widget`: A `GridStackReactWidget` object with the following properties:
+  - `id`: Unique identifier for the widget (required)
+  - `w`: Width in grid columns
+  - `h`: Height in grid rows
+  - `x`: X position in grid columns (optional, will auto-place if not provided)
+  - `y`: Y position in grid rows (optional, will auto-place if not provided)
+  - `renderFn`: Function that returns the React element to render
+  - `meta`: Optional metadata object associated with the widget
+  - `allowedSizes`: Optional array of allowed size combinations
+  - `allowResize`: Whether the widget can be resized (default: true)
+  - `allowMove`: Whether the widget can be moved (default: true)
+
+**Example:**
+
+```tsx
+gridRef.current?.addWidget({
+  id: "new-widget-1",
+  w: 2,
+  h: 2,
+  meta: {
+    title: "New Widget",
+    type: "chart",
+  },
+  renderFn: () => (
+    <div className="h-full rounded-md bg-f1-background-secondary p-4">
+      New Widget Content
+    </div>
+  ),
+})
+```
+
+#### `removeWidget`
+
+Removes a widget from the grid by its ID.
+
+**Parameters:**
+
+- `id`: The unique identifier of the widget to remove (string)
+
+**Example:**
+
+```tsx
+gridRef.current?.removeWidget("widget-1")
+```
+
+#### `addSubGrid`
+
+Adds a nested grid (sub-grid) to the main grid. This is useful for creating
+hierarchical layouts where widgets can be grouped within a parent widget.
+
+**Parameters:**
+
+- `subGrid`: A `GridStackReactWidget` with additional `subGridOpts` property
+  containing:
+  - `children`: Array of widgets that will be placed inside the sub-grid
+
+**Example:**
+
+```tsx
+gridRef.current?.addSubGrid({
+  id: "subgrid-1",
+  w: 4,
+  h: 4,
+  subGridOpts: {
+    column: 6,
+    children: [
+      {
+        id: "nested-widget-1",
+        w: 2,
+        h: 2,
+        renderFn: () => <div>Nested Widget 1</div>,
+      },
+      {
+        id: "nested-widget-2",
+        w: 2,
+        h: 2,
+        renderFn: () => <div>Nested Widget 2</div>,
+      },
+    ],
+  },
+  renderFn: () => <div>Sub-grid Container</div>,
+})
+```
+
+#### `removeAll`
+
+Removes all widgets from the grid at once.
+
+**Example:**
+
+```tsx
+gridRef.current?.removeAll()
+```
+
+### Complete Example
+
+The following example demonstrates all ref methods in action:
+
+<Canvas of={GridStackStories.WithRefMethods} />
+
+This example shows:
+
+- **Add Widget**: Dynamically adds new widgets to the grid
+- **Remove Last Widget**: Removes the most recently added widget
+- **Remove All**: Clears all widgets from the grid
+
+## Best Practices
+
+1. **Widget IDs**: Always use unique, stable IDs for widgets to ensure proper
+   tracking and removal
+2. **Layout Persistence**: Use the `onChange` callback to save widget positions
+   and restore them on component mount
+3. **Performance**: For large numbers of widgets, consider debouncing the
+   `onChange` callback
+4. **Responsive Design**: Configure appropriate column counts for different
+   screen sizes using the `options.column` property
+5. **Widget Constraints**: Use `allowedSizes` to restrict widget dimensions to
+   specific size combinations
+6. **Metadata**: Store widget-specific data in the `meta` property for easy
+   retrieval and persistence
+
+## Props
+
+### `options`
+
+Configuration object for the grid layout.
+
+- `column`: Number of columns in the grid (default: 12)
+- `row`: Number of rows in the grid (optional)
+- `margin`: Margin between widgets in pixels (optional)
+- `draggable`: Whether widgets can be dragged (default: true)
+- `acceptWidgets`: Whether the grid can accept widgets from other grids
+  (default: false)
+
+### `widgets`
+
+Array of initial widgets to render in the grid. Each widget follows the
+`GridStackReactWidget` interface.
+
+### `onChange`
+
+Callback function that is called whenever the layout changes (widget moved,
+resized, added, or removed). Receives an array of `GridStackWidgetPosition`
+objects containing the current state of all widgets.