DashboardGridCommands

comins-grid-layout@0.3.0React

20 React state commands for widget CRUD, layout changes, reset, and serialization.

Access and shared contract

Call these methods on grid.commands returned by useDashboardGrid(). Mutations request a React reducer transition and do not return promises. A serializer called immediately after a setter in the same event may read the previous render. Read the next render or the snapshot in onLayoutMutation. Do not retain a commands object from an old render.

Some commands targeting a missing ID can create a new state object and event without a visible change. Mutation events follow reducer state identity; they are not persistence acknowledgements or proof of geometry changes.

Hook options and result · Engine ref methods

All 20 methods

addWidget

addWidget: (widget: DashboardWidget<TData>) => void;

Adds a complete widget, finding free space for a new ID. An existing ID is replaced with the supplied complete definition; use updateWidget for a partial edit. Returns void; mutation kind: widget:add.

insertWidgetAt

insertWidgetAt: (widget: DashboardWidget<TData>, targetLayout: DashboardWidgetLayout, targetSnapshot: DashboardLayoutSnapshot) => void;

Applies a dropped widget together with its target geometry and complete target snapshot. Duplicate IDs or an invalid target leave state unchanged. Returns void, so it is not an acceptance result; use the public core function insertDashboardWidgetAtLayout when a result object is needed. Accepted transitions use widget:add.

updateWidget

updateWidget: (id: DashboardWidgetId, patch: Partial<DashboardWidget<TData>>) => void;

Shallow-merges patch into the widget matching id, preserving its ID. data is not deeply merged; patch.layout must be a complete layout. A missing ID does not insert a widget. Returns void; kind: widget:update.

updateWidgetLayout

updateWidgetLayout: (id: DashboardWidgetId, patch: Partial<Omit<DashboardWidgetLayout, "id">>) => void;

Merges geometry fields such as x, y, w, and h into the existing layout and normalizes it for the current column count. The ID is preserved; a missing ID does not insert a widget. Returns void; kind: widget:update.

removeWidget

removeWidget: (id: DashboardWidgetId) => void;

Removes the widget and its previous-layout and per-column cache entries. Removing a missing ID does not remove other widgets. Returns void; kind: widget:remove.

clearWidgets

clearWidgets: () => void;

Clears all widgets and previous layouts while retaining the column count. Returns void; kind: widgets:clear.

maximizeWidget

maximizeWidget: (id: DashboardWidgetId) => void;

Remembers the restorable geometry and sets the maximized state. Starts from (0, 0), full column width, and height at least 3, then applies constraints. A missing ID leaves state unchanged. Returns void; kind: widget:update.

minimizeWidget

minimizeWidget: (id: DashboardWidgetId) => void;

Remembers the restorable geometry and requests minimized state with height 1, subject to layout constraints. A missing ID leaves state unchanged. Returns void; kind: widget:update.

restoreWidget

restoreWidget: (id: DashboardWidgetId) => void;

Clears maximized/minimized flags, restores remembered geometry, and removes that previous-layout entry. Without an entry, it keeps the current geometry and clears the flags. A missing ID leaves state unchanged. Returns void; kind: widget:update.

autoArrangeWidgets

autoArrangeWidgets: () => void;

Packs widgets left to right in array order, moving to a new row when needed. Its placement rule differs from the engine’s compact(). Returns void; kind: layout:arrange.

fitWidgetsToColumns

fitWidgetsToColumns: () => void;

Groups widgets by equal y. Rows with empty column space redistribute widths to fill the columns; already full rows are retained. Returns void; kind: layout:fill.

fitWidgetToColumns

fitWidgetToColumns: (id: DashboardWidgetId) => void;

Gives the remaining width in the target’s row (same y) to that widget and repacks that row’s x positions. A missing ID or no remaining width leaves state unchanged. Returns void; kind: layout:fill.

setColumns

setColumns: (columns: number) => void;

Changes column count. Finite values are rounded and clamped to 1–12; non-finite values become 12. Saves the source-column layout and restores a cached target-column layout when available. The same count leaves state unchanged. Returns void; kind: columns:change.

applyLayoutSnapshot

applyLayoutSnapshot: (snapshot: DashboardLayoutSnapshot) => void;

Applies snapshot.columns and per-ID geometry to existing widgets. Keeps their titles, data, and membership; IDs present only in the snapshot are not inserted. Connect to onLayoutCommit to reflect engine geometry in React state. Returns void; kind: layout:commit.

resetLayout

resetLayout: (snapshot?: DashboardLayoutSnapshot | DashboardStateSnapshotInput<TData>) => void;

Recreates the entire state from the initial mount inputs when omitted, or from the supplied snapshot. A geometry-only snapshot cannot restore titles or data; use a state snapshot for full restoration. Resets refreshVersion to 0. Returns void; kind: layout:reset.

restoreLayout

restoreLayout: (snapshot: DashboardStateSnapshotInput<TData>) => void;

Recreates widgets, columns, previous layouts, and per-column caches from the required state snapshot. The argument is required; this does not mean “return to initial state.” Returns void; kind: layout:restore.

refreshLayout

refreshLayout: () => void;

Increments refreshVersion. Connect it to the component’s refreshKey to trigger engine refresh. Returns void; this command does not emit a layout mutation event.

serializeLayout

serializeLayout: () => DashboardLayoutSnapshot;

Returns new objects and an array containing the current render’s column count and widget geometry. Omits titles, data, and maximization restore history. Reading does not change state.

serializeState

serializeState: () => DashboardStateSnapshot<TData>;

Returns the current render’s widget definitions, columns, previous layouts, and per-column caches. Layout structures are copied, but nested data objects are not deep-cloned. This is neither a JSON string nor a persistence result; serialization and storage belong to the consumer.

Try the example

Add a widget or remove A, then inspect the rendered React state. compact runs through the ref and flows back to commands through onLayoutCommit. See persistence for saving and restoring.

Live example

Preview

Code

GridApiDemo.tsx

import { useRef, useState } from 'react';
import { DashboardGrid, useDashboardGrid, type DashboardGridHandle } from 'comins-grid-layout';
import 'gridstack/dist/gridstack.min.css';
import 'comins-grid-layout/styles.css';

export default function GridApiDemo({ lang = 'ko' }: { lang?: string }) {
  const ko = lang === 'ko';
  const handle = useRef<DashboardGridHandle>(null);
  const sequence = useRef(0);
  const [inspection, setInspection] = useState('');
  const grid = useDashboardGrid({ initialColumns: 12, initialWidgets: [
    { id: 'first', title: 'A', layout: { id: 'first', x: 0, y: 0, w: 4, h: 2 } },
    { id: 'second', title: 'B', layout: { id: 'second', x: 6, y: 0, w: 4, h: 2 } },
  ] });
  return <div className="demo grid-demo" data-demo="grid-api">
    <div className="demo-toolbar">
      <button onClick={() => {
        const id = `added-${++sequence.current}`;
        grid.commands.addWidget({ id, title: id, layout: { id, x: 0, y: 0, w: 3, h: 2 } });
      }}>{ko ? '위젯 추가' : 'Add widget'}</button>
      <button onClick={() => grid.commands.resizeWidget('first', { w: 8, h: 3 })}>{ko ? 'A 크기 8×3' : 'Resize A to 8×3'}</button>
      <button onClick={() => grid.commands.restoreWidget('first')}>{ko ? 'A 크기 복원' : 'Restore A size'}</button>
      <button onClick={() => grid.commands.removeWidget('first')}>{ko ? 'A 삭제' : 'Remove A'}</button>
      <button onClick={() => {
        const snapshot = handle.current?.compact('list');
        setInspection(snapshot ? JSON.stringify(snapshot, null, 2) : (ko ? '그리드 준비 중' : 'Grid is initializing'));
      }}>compact('list')</button>
      <button onClick={() => {
        const ref = handle.current;
        const probe = { x: 0, y: 20, w: 2, h: 1 };
        setInspection(JSON.stringify({ columns: ref?.getColumnCount() ?? null, rows: ref?.getRowCount() ?? null,
          float: ref?.getFloat() ?? null, empty: ref?.isAreaEmpty(probe) ?? null,
          fits: ref?.willItFit(probe) ?? null }, null, 2));
      }}>{ko ? '그리드 조회' : 'Inspect grid'}</button>
      <button onClick={() => { grid.commands.resetLayout(); setInspection(''); }}>{ko ? '초기화' : 'Reset'}</button>
    </div>
    <DashboardGrid ref={handle} widgets={grid.widgets} columns={grid.columns}
      refreshKey={grid.refreshVersion} onLayoutCommit={grid.commands.applyLayoutSnapshot}
      editable movable resizable showControls={false}
      engineOptions={{ cellHeight: 60, margin: 6, animate: false }}
      renderWidget={widget => <div className="widget-content">{widget.title}</div>}
    />
    <p role="status">{ko ? '위젯 수' : 'Widget count'}: <span data-widget-count>{grid.widgets.length}</span></p>
    <details open><summary>{ko ? '현재 React 상태' : 'Current React state'}</summary>
      <pre data-grid-state>{JSON.stringify(grid.commands.serializeLayout(), null, 2)}</pre>
    </details>
    {inspection && <pre data-grid-inspection aria-live="polite">{inspection}</pre>}
  </div>;
}

Evidence

The npm declarations below were compared with a fixed source snapshot. The snapshot is the commit recorded in the public artifact provenance.

• comins-grid-layout/dist/core/controller-types.d.ts
• npm 0.3.0 · Source snapshot

resizeWidget

resizeWidget: (id: DashboardWidgetId, size: Pick<DashboardWidgetLayout, "w" | "h">) => void;

Specify W/H in grid units. Column and min/max constraints apply; the geometry before the first resize is retained. restoreWidget restores that geometry after repeated resizes. Legacy maximize/minimize commands remain deprecated compatibility APIs; default buttons are no longer provided.