vue-grid-layout

KO | EN

gitlite — search

#javascript #typescript #go #docker #nodejs #windows #awesome #cli #awesome-list #vue #security #mcp #openai #open-source

vue-grid-layout

(★ 9)

A draggable and resizable grid layout with responsive breakpoints, for vue3.

vue-grid-layout 최신버젼 다운로드

최종 버전 다운로드 (.zip)

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Vue Grid Layout

Vue-Grid-Layout is responsive and supports breakpoints. Breakpoint layouts can be provided by the user
or autogenerated, it supports Vue3, with compatibility for both web and mobile platforms.

VGL is Vue3-only and does not require jQuery.
![lQHPJwoeFsrrm2PNAaXNAyCwnrwXf3Au-Y4GmhEurCB8AA_800_421](https://github.com/user-attachments/assets/1e8b4fcc-e4cc-4cce-a2b2-2213594128e6)

[**[Demo](https://marsio.top/vue-grid-layout/) | [Changelog](/CHANGELOG.md) | [View Response Layout](/example/example.js)**]

## Table of Contents

- [Demos](#demos)
- [Features](#features)
- [MCP Integration](#mcp-integration)
- [Installation](#installation)
- [Which Entry Should I Use?](#which-entry-should-i-use)
- [Usage](#usage)
- [Interaction State and Drag Activation](#interaction-state-and-drag-activation)
- [History (Pinia-powered undo/redo)](#history-pinia-powered-undoredo)
- [Layout Persistence](#layout-persistence)
- [Height Modes and Render Precision](#height-modes-and-render-precision)
- [Professional Dashboard Editor](#professional-dashboard-editor)
- [Dashboard Editor Shell Integration](#dashboard-editor-shell-integration)
- [Widget Registry Protocol](#widget-registry-protocol)
- [Dashboard Layout Document Adapter](#dashboard-layout-document-adapter)
- [Dashboard Responsive Profiles](#dashboard-responsive-profiles)
- [Layout Settings Migration and Repair](#layout-settings-migration-and-repair)
- [Layout Engine Performance](#layout-engine-performance)
- [Responsive Usage](#responsive-usage)
- [Providing Grid Width](#providing-grid-width)
- [Grid Layout Props](#grid-layout-props)
- [Responsive Grid Layout Props](#responsive-grid-layout-props)
- [Grid Item Props](#grid-item-props)

## Demos

The Vite demo app is in [`example/main.ts`](./example/main.ts). Each demo is tagged by capability:

1. Basic — `basic`, `core`
1. Responsive — `responsive`
1. Persistence — `persistence`
1. Headless Editor — `editor`
1. Dashboard Runtime — `dashboard runtime`
1. Dashboard Editor Shell — `dashboard shell`
1. Placement — `placement`
1. Migration — `migration`
1. Worker — `worker`, `layout engine`

## Features

- 100% Vue - no jQuery
- Draggable widgets
- Resizable widgets
- Static widgets
- Configurable packing: horizontal, vertical, or off
- Bounds checking for dragging and resizing
- Widgets may be added or removed without rebuilding grid
- Layout can be serialized and restored
- Responsive breakpoints
- Separate layouts per responsive breakpoint
- Grid Items placed using CSS Transforms
  - Performance with CSS Transforms

## MCP Integration

Vue Grid Layout provides an MCP (Model Context Protocol) server for AI IDEs like Cursor and Claude Desktop. It offers component documentation, props, types, and usage examples.

### Configuration (Cursor / Claude Desktop)

```json
{
  "mcpServers": {
    "vue-grid-layout": {
      "command": "npx",
      "args": ["@marsio/vue-grid-layout-mcp"]
    }
  }
}
```

### Available Tools

| Tool | Description |
|------|-------------|
| `get_vue_grid_layout_docs` | Get complete documentation (Markdown) |
| `list_vue_grid_layout_props` | List component props (JSON) |
| `get_vue_grid_layout_prop` | Query a specific prop |
| `get_vue_grid_layout_type` | Get TypeScript type definitions |
| `get_vue_grid_layout_example` | Get code examples for scenarios (basic / responsive / drag-from-outside) |
| `search_vue_grid_layout_docs` | Full-text search in documentation |

For more details, see [mcp/README.md](./mcp/README.md).

## Installation

Install the Vue-Grid-Layout [package](https://www.npmjs.com/package/@marsio/vue-grid-layout) using [npm](https://www.npmjs.com/):

```bash
npm install @marsio/vue-grid-layout
```

`vue` is a peer dependency. Install `pinia` only when using the history entry:

```bash
npm install vue
npm install pinia
```

## Which Entry Should I Use?

The root entry is lean core and is equivalent to `@marsio/vue-grid-layout/core`. Responsive and advanced capabilities live behind explicit subpaths.

| Capability | Import entry | Notes |
| --- | --- | --- |
| Core Grid | `@marsio/vue-grid-layout` or `@marsio/vue-grid-layout/core` | Root default export remains `VueGridLayout`; root named exports include common core utilities. |
| Responsive Grid | `@marsio/vue-grid-layout/responsive` | Lean responsive component; root no longer exports `Responsive` / `ResponsiveVueGridLayout`. |
| Layout Engine | `@marsio/vue-grid-layout/layout-engine` | Engine, scheduler, executor and migration helpers. |
| Persistence | `@marsio/vue-grid-layout/persistence` | Durable layout document adapters; does not require Pinia. |
| Headless Editor | `@marsio/vue-grid-layout/editor` | Controller, commands, metadata, placement and keyboard helpers. No bundled toolbar, inspector, palette or command UI. |
| Dashboard Runtime | `@marsio/vue-grid-layout/dashboard` | Dashboard document adapter, responsive runtime and migration helpers. |
| Dashboard Editor Shell | `@marsio/vue-grid-layout/dashboard-editor-shell` | Headless shell actions, menus, transactions and shell-managed dashboard document write-back. Render UI in your app. |
| Widget Registry | `@marsio/vue-grid-layout/widget-registry` | Optional API-first widget type, template, settings, sidecar and shell adapter protocol. No renderer or UI kit runtime. |
| History | `@marsio/vue-grid-layout/history` | Optional Pinia-powered layout-only undo/redo. Requires `pinia`. |
| Worker | `@marsio/vue-grid-layout/worker` | Layout engine worker runtime entry. |
| CSS | `@marsio/vue-grid-layout/style.css` | Import once in your app or component library entry. |
| MCP / AI Tooling | `@marsio/vue-grid-layout-mcp` | Independent package; the root package does not export `./mcp`. |

Undeclared deep imports are private implementation details. The package `exports` map is the public API boundary.

### Major-version migration notes

- `build/cjs/cjs.js` is replaced by `dist/index.cjs` and subpath CJS entries.
- `build/web/vue-grid-layout.min.js`, CDN/UMD global usage and `window.VueGridLayout` are no longer public release artifacts.
- `build/web/vue-grid-layout.worker.js` is replaced by the `@marsio/vue-grid-layout/worker` export.
- `typings/index.d.ts` is replaced by generated declarations under `dist/types`.
- Advanced root imports should move to the subpaths listed above; only core/responsive root compatibility is retained.
- Dashboard editor migrations should prefer `@marsio/vue-grid-layout/editor` command history plus `@marsio/vue-grid-layout/dashboard-editor-shell` with `documentWriteBack: "shell"`; legacy `historyStore` remains layout-only compatibility.
- Rollback should use the last stable branch or tag. Do not mix new `dist` package exports with old `build` artifacts.

## Usage

> **AI Tip**: Please use the `get_vue_grid_layout_example` tool to get basic usage example code, do not generate it yourself.

The following example below will
produce a grid with three items where:

- users will not be able to drag or resize item `a`
- item `b` will be restricted to a minimum width of 2 grid blocks and a maximum width of 4 grid blocks
- users will be able to freely drag and resize item `c`

```vue
<template>
  <VGL
    class="layout"
    v-model="state.layout"
    :cols="12"
    :rowHeight="30"
    :width="1200"
  >
    <div key="a">a</div>
    <div key="b">b</div>
    <div key="c">c</div>
  </VGL>
</template>

export default defineComponent({
  components: {
    VGL
  },
  setup() {
    const layout = [
      { i: "a", x: 0, y: 0, w: 1, h: 2, static: true },
      { i: "b", x: 1, y: 0, w: 3, h: 2, minW: 2, maxW: 4 },
      { i: "c", x: 4, y: 0, w: 1, h: 2 }
    ];
    const state = reactive({
      layout
    })
    return {
      state
    };
  }
});
</script>
```

## Interaction State and Drag Activation

Pointer interactions are guarded by an internal state machine so click-like item interactions do not start layout drag work. By default, mouse and pen drags activate after `4px` of pointer travel; touch/coarse pointer drags activate after `8px`.

```vue
<VueGridLayout
  v-model="layout"
  :width="1200"
  :cols="12"
  :drag-activation-distance="{ mouse: 4, pen: 4, touch: 8, coarse: 8 }"
/>
```

- `onDragStart`, `onDrag` and `onDragStop` are semantic drag lifecycle events. A normal click, context-menu click or pointer movement below the activation distance does not emit them and does not show editor guides, write preview layout, create history entries or save persistence.
- Set `dragActivationDistance={0}` when you need the closest compatibility with the older immediate `dragStart` timing.
- Resize handle press still starts resize immediately, but no-op resize ticks and no-op resize stops do not preview or commit layout changes.
- External drop enters an active drop state as soon as it is over the grid. Repeated dragover events at the same grid position and size are ignored for guide/layout preview, `dropDragOver` size overrides participate in preview and commit, and drag leave, rejected drop, cancel and commit all clear dropping placeholder state.
- Debug editor guide state remains internal; use existing editor diagnostics and layout-engine diagnostics for operation ids, phases, blocked reasons and stale/fallback status.
- 2.0 lean boundary: root equals core; no `./compat` entry is provided; responsive imports move to `@marsio/vue-grid-layout/responsive`; component-level `editor`, `persistence` and `historyStore` props are removed from lean grid/responsive. Use `EditorGridLayout` / `EditorResponsiveGridLayout` from `./editor`, `PersistentGridLayout` / `PersistentResponsiveGridLayout` from `./persistence`, and history APIs from `./history`.

## History (Pinia-powered undo/redo)

- Install optional peer: `npm i pinia`.
- Create a store from `@marsio/vue-grid-layout/history` and push committed layout snapshots from `layoutChange`.
- Use the store’s `undo` / `redo` / `canUndo` / `canRedo` to drive shortcuts or toolbar buttons.
- For dashboard editors, prefer editor command history through `useDashboardEditorShell({ documentWriteBack: "shell" })`. This Pinia store is a layout snapshot compatibility path and does not track shell adapter transactions, selection/focus, editor metadata or dashboard sidecar state.

```vue
<template>
  <div class="toolbar">
    <button :disabled="!history.canUndo" @click="undo">Undo</button>
    <button :disabled="!history.canRedo" @click="redo">Redo</button>
  </div>
  <VGL v-model="layout" :cols="12" :width="1200" @layoutChange="history.push">
    <div v-for="item in layout" :key="item.i">{{ item.i }}</div>
  </VGL>
</template>

const history = useGridHistoryStore({ maxSize: 200 })

const layout = reactive([
  { i: 'a', x: 0, y: 0, w: 2, h: 2 },
  { i: 'b', x: 2, y: 0, w: 2, h: 2 }
])

const undo = () => {
  const snap = history.undo()
  if (snap) layout.splice(0, layout.length, ...snap)
}

const redo = () => {
  const snap = history.redo()
  if (snap) layout.splice(0, layout.length, ...snap)
}

// Keep store in sync if layout is updated externally
watch(
  () => layout,
  next => history.replacePresent(next),
  { deep: true }
)
</script>
```

## Layout Persistence

Use `PersistentGridLayout`, `PersistentResponsiveGridLayout`, or `useGridLayoutPersistence()` when a layout should survive refreshes. The persistence layer writes a versioned document through an adapter; it does not depend on Pinia.

Built-in adapters:

- `localStorageAdapter()` for durable browser-local storage and cross-tab updates through the `storage` event.
- `sessionStorageAdapter()` for per-tab browser session storage.
- `indexedDBAdapter()` for larger browser-local documents without blocking on string-only Web Storage.
- `remoteHttpAdapter()` for simple REST backends using `GET`, `PUT` and `DELETE`.
- `memoryPersistenceAdapter()` for tests and demos.

```ts
import { localStorageAdapter, useGridLayoutPersistence } from '@marsio/vue-grid-layout/persistence'
```

## Professional Dashboard Editor

The professional editor API is headless-first. Use `useGridEditor()`, `EditorGridLayout`, or `EditorResponsiveGridLayout` from `@marsio/vue-grid-layout/editor` to get mode, selection, commands, metadata, keyboard, clipboard, guides, dirty/conflict state and CSS contracts without adopting a bundled toolbar or product shell.

```ts
import {
  useGridEditor,
  internalGridEditorClipboard
} from "@marsio/vue-grid-layout/editor";
import { memoryPersistenceAdapter } from "@marsio/vue-grid-layout/persistence";

Editor fundamentals:

- `mode` is controlled; `defaultMode` is uncontrolled. If editor is enabled without either value, it fail-safes to `view` and emits `editor-mode-missing`.
- Commands include `select`, `clearSelection`, `move`, `resize`, `add`, `delete`, `duplicate`, `copy`, `paste`, `align`, `distribute`, `tidy`, `lock`, `unlock`, `show`, `hide`, `save`, `discard`, `reset`, `undo`, `redo`, `section-row-collapse`, `section-row-expand`, `section-row-move`, `section-row-delete` and `section-row-reorder`.
- `canExecute()` performs synchronous mode/capability checks for disabled toolbar states. `execute()` enters the Command Kernel: descriptor defaults, synchronous validation, pending guard scope checks, optional async `beforeCommand`, stale revision checks, transaction commit, history policy, and command events.
- `beforeCommand` is the interception point for permissions and confirmation. Its context includes `command`, `source`, `origin`, `targetIds`, `layout`/`layouts`, `editorMetaById`, `sectionRows`, `selection`, `mode`, history availability, optional `preview` and an `AbortSignal`. The core library waits for the returned promise; it does not provide modal, toast or i18n UI.
- Command events (`command-start`, `command-commit`, `command-blocked`, `command-error`) are observational. Throwing inside `onEvent` does not change a completed command result; use `beforeCommand` when business logic must block or cancel.
- Command history accepts `"record"`, `"ignore"`, `"record-preserveRedoStack"`, `"replace"` and `"clear"` or an object with `mergeKey`, `mergeWindowMs`, `preserveRedoStack` and legacy `skip`. Selection/focus default to `"ignore"`; external/programmatic layout updates default to `"ignore"` while preserving redo.
- `selectedIds`, `activeId`, `anchorId` and `selection.mode` support single and multiple selection. Selection/focus commands do not write persistence or layout history.
- Item editor metadata lives in sidecar `editorMetaById`; `locked`, `visible`, `editable`, `deletable`, `duplicatable` and `copyable` are not written into `LayoutItem` by default.
- Multi-selection move is engine-first: dragging a selected item in a multi-selection, using keyboard arrows, or executing a multi-target `move` command submits a layout-engine `groupMove` operation. The operation preserves selected item offsets, returns per-item layout patches/diagnostics, and records one undoable history entry at commit.
- `locked: true` is editor metadata: it blocks direct editing of that item but does not make it a physical obstacle. `static: true` belongs on the `LayoutItem`: it blocks direct movement and acts as a collision obstacle for other moving items, including group moves.
- `resizable: false` and effective `resizeHandles` are resolved through a shared item capability layer in editor/dashboard wrappers. When `preserveAspectRatio` is enabled, edge handles are disabled by default; opt into edge handles explicitly when the product wants the opposite axis inferred during ratio resize.
- `aspectRatio` is a visual pixel ratio (`widthPx / heightPx`), not `w / h`. Resize preview and commit use the same sidecar constraint; missing visual metrics block ratio resize unless the caller explicitly supplies a fallback policy.
- `commandPolicy: "skip-blocked"` moves only allowed selected items and reports skipped ids; the default `"all-or-nothing"` policy blocks the whole command if any target is locked, hidden, static, missing or otherwise not movable.
- Group move follows the same collision and bounds rules as the layout engine. `preventCollision=true` blocks group collisions with external items, `preventCollision=false` may push/compact external non-static items, `allowOverlap=true` permits overlap, and bounds/maxRows violations are reported as structured blocked results.
- Pointer drag, resize and external drop use the same command guard before durable commit when an editor controller is present. If guard blocks, cancels, times out or the command is stale, the visual preview is rolled back to the committed layout and placeholder/guides/auto-scroll state is cleared.
- Legacy/disabled layout-engine paths do not implement a shadow group move. Multi-item group move returns `unsupported`; single-item move keeps the existing behavior.
- `visible: false` preserves the layout item but does not render it. It is not permission isolation.
- `meta.editor` stores `{ version, editorMetaById, sectionRows, updatedAt }` in the same persistence document as layout data. Do not store sensitive permission data in `meta.editor`; enforce permissions on your server or in `beforeCommand`.
- Default copy/paste uses `internalGridEditorClipboard`; `systemClipboardAdapter()` is optional and safely reports unavailable or denied clipboard access. Clipboard payloads are v1/v2 compatible: v2 adds source grid context such as `cols`, `breakpoint`, `layoutId` and `viewFormat`, while v1 payloads continue to paste with the legacy geometry.
- Advanced placement is exposed as a headless transaction on `GridEditorController`: `placementSession`, `beginPlacement()`, `updatePlacement()`, `commitPlacement()` and `cancelPlacement()`. Dashboard shell flows should call `shell.actions.commitPlacement()` so the editor commit, dashboard/profile write-back and widget/reference adapters finish in one awaitable action. Preview updates do not write layout, history, persistence, selection, focus or adapter payloads; commit converts the session back into the existing `add`/`paste` command pipeline.
- Placement sessions default to `collisionPolicy: "block"` so precise ghost placement stays conservative. Set `collisionPolicy: "layout"` to reuse the grid's existing collision semantics: `preventCollision=true` blocks, `preventCollision=false` with a compacting layout can push/compact existing non-static items, and `allowOverlap=true` permits overlap. Existing items may render at predicted coordinates during preview, but layout, history, persistence and business payloads are unchanged until commit.
- Default Cmd/Ctrl+V remains immediate paste. Set `keyboard: { pasteMode: "interactive" }` only when you want the paste shortcut to enter placement mode. Text inputs, textareas, selects, contenteditable targets and configured ignored targets still receive native keyboard behavior.
- Placement paste reads the configured clipboard once at `beginPlacement()`, falls back from system to internal clipboard, and returns `clipboard-unavailable`, `clipboard-permission` or `clipboard-invalid` without creating a half-active ghost when no payload is usable. The resolved payload is reused at commit so preview ids, metadata, responsive geometry and final ids stay aligned.
- Placement ghost and HUD are visual-only: `.vue-grid-editor-placement-ghost`, `.vue-grid-editor-placement-affected*` and `.vue-grid-editor-placement-hud` are rendered by the overlay layer and are not added to slot children, `state.layout`, `droppingDOMNode` or business widget component trees. In layout-collision preview, affected existing grid items receive render-only candidate coordinates plus `.editor-placement-reflowed`; Esc, blur/unmount, readonly mode, external layout replacement and commit cleanup remove the transient state.
- Keyboard editing covers arrows, accelerated arrows, Alt+arrows resize, Delete/Backspace, Cmd/Ctrl+C/V/D/S and Esc. During active placement, Esc cancels, Enter commits the current candidate, and arrow keys nudge the candidate by `placementNudgeStep` / `placementFastNudgeStep`. Input, textarea, select and contenteditable targets are ignored.
- CSS state classes include `.editor-enabled`, `.editor-mode-view`, `.editor-mode-edit`, `.editor-placement-active`, `.editor-selected`, `.editor-active`, `.editor-locked`, `.editor-hidden`, `.editor-readonly`, `.editor-keyboard-editing`, `.editor-drop-target`, placement classes and guide classes.
- Smart guides keep full candidates in `guides` and expose the product-safe subset in `displayGuides`. By default drag/drop renders at most 3 guides, resize renders at most 2, and only one spacing guide receives a distance label. `debug: "layer"` or `debug: "panel"` exposes full candidates separately from the default user-facing guides.
- Background grid lines are optional editing scaffolding, not smart guides. `showGrid` defaults to interaction-only rendering, uses `.editor-guide-grid`, and stays visually below placeholder, active item, snapped guide and candidate guide layers.
- Alignment guides use blue guide styling and endpoint markers to show which edge or center is aligned. Spacing guides use green dashed styling plus a short label such as `2 cols` or `1 row`; non-debug mode should not show full-canvas high-saturation lines or label every candidate.

L3 layout intelligence APIs are stable headless APIs:

```ts
const intelligence = computeGridEditorIntelligence({
  layout,
  activeItem,
  candidateItem,
  selectionIds: editor.selection.value.selectedIds,
  metaById: editor.editorMetaById.value,
  sectionRows: editor.sectionRows.value,
  cols: 12,
  interaction: "toolbar"
});

const toolbar = editor.getToolbarState();

const alignPreview = applyGridEditorAlign(layout, {
  mode: "left",
  target: { type: "selection-bounds" }
}, {
  targetIds: editor.selection.value.selectedIds,
  sectionRows: editor.sectionRows.value,
  cols: 12
});

const distributePreview = applyGridEditorDistribute(layout, {
  mode: "horizontal",
  strategy: "edge-to-edge",
  bounds: "active-item"
}, {
  targetIds: editor.selection.value.selectedIds,
  activeId: editor.selection.value.activeId,
  cols: 12
});

await editor.execute({
  type: "align",
  source: "toolbar",
  payload: { mode: "left", target: { type: "selection-bounds" }, cols: 12 }
});

await editor.execute({
  type: "distribute",
  source: "toolbar",
  payload: { mode: "horizontal", strategy: "edge-to-edge", cols: 12 }
});

await editor.execute({
  type: "section-row-collapse",
  source: "toolbar",
  payload: { id: "executive-row" }
});
```

`applyGridEditorAlign()`, `applyGridEditorDistribute()`, `deriveGridEditorToolbarState()` and `getToolbarState()` are headless state helpers. The toolbar in `example/23-professional-dashboard-editor.js` is demonstration UI only; its DOM, labels and styling are not API. `snap: false` still allows predictive guide calculation, but snapped visual state and preview/commit geometry correction are disabled. Snap candidates include edge, center, spacing and section/row bounds. Legacy guide options such as `thresholdPx`, `showSpacingLabels` and `maxVisibleGuides` continue to map into intelligence options.

Event order for committed layout commands is:

1. `command-start`
1. synchronous capability check
1. optional `beforeCommand`
1. `command-commit`
1. component `layoutChange`
1. `update:modelValue` or `update:layouts`
1. editor history and persistence dirty/save state

Metadata-only commands emit editor command/state events and update editor history/dirty state without emitting `layoutChange`.

Public command-history APIs:

- `editor.subscribe(listener)` registers additional `GridEditorEventListener` callbacks without replacing the listener supplied in `onEvent`; the returned cleanup is idempotent.
- `editor.createRollbackCheckpoint(reason)` captures layout, selection, metadata, section rows and editor history stacks before an app-owned transaction.
- `editor.restoreRollbackCheckpoint(checkpoint, reason)` restores that checkpoint without creating a new user-visible history entry.
- `createGridEditorHistory().checkpoint()` and `.restore(checkpoint)` are public for shells that need to preserve undo/redo stacks across failed external commits.

Known editor limits: group resize and group bounding-box ghosting are not included, section/row metadata is a client editing model rather than a permission boundary, system clipboard depends on browser permission, hidden items are not a security boundary, legacy layout-engine mode does not support multi-item group move, and legacy `historyStore` remains a layout-only compatibility layer. New guard, metadata, selection, section row, transaction preview and pointer command behavior are committed through editor command history, not through the legacy `historyStore` contract.

### localStorage refresh recovery

```vue
<template>
  <PersistentGridLayout
    v-model="layout"
    :cols="12"
    :width="1200"
    :persistence="{ key: 'dashboard-main', adapter }"
  >
    <div v-for="item in layout" :key="item.i">{{ item.i }}</div>
  </PersistentGridLayout>
</template>

const layout = ref([
  { i: 'a', x: 0, y: 0, w: 2, h: 2 },
  { i: 'b', x: 2, y: 0, w: 2, h: 2 }
])

const adapter = localStorageAdapter({ prefix: 'vgl:' })
</script>
```

`autoSave` defaults to `true` and saves committed layout changes after drag/resize/drop commit, debounced by `debounceMs` (default `300`). It does not write drag, resize or drop preview frames. Adapter operations time out after `timeoutMs` (default `10000`) so a stalled remote store leaves the current in-memory layout intact and surfaces an `adapter-timeout` error.

### autosave dirty state

```vue
<script setup>
import { ref } from 'vue'
import {
  localStorageAdapter,
  useGridLayoutPersistence
} from '@marsio/vue-grid-layout/persistence'

const layout = ref([{ i: 'a', x: 0, y: 0, w: 2, h: 2 }])
const persistence = useGridLayoutPersistence({
  key: 'dashboard-editing',
  kind: 'layout',
  target: layout,
  adapter: localStorageAdapter({ prefix: 'vgl:' }),
  debounceMs: 500,
  onError: error => console.warn(error.message)
})

await persistence.load()

// Bind these to toolbar controls when you need manual review.
const save = () => persistence.save()
const discard = () => persistence.discard()
</script>
```

The controller exposes `status`, `dirty`, `lastSavedAt`, `error`, `conflict`, `load()`, `save()`, `discard()`, `reset()`, `remove()`, `resolveConflict()` and `stop()`.

### custom remote adapter

```ts
import type { LayoutPersistenceAdapter } from '@marsio/vue-grid-layout/persistence'

export const remoteAdapter: LayoutPersistenceAdapter = {
  async load(key) {
    const response = await fetch(`/api/layouts/${key}`)
    if (response.status === 404) return null
    return response.json()
  },
  async save(key, document) {
    await fetch(`/api/layouts/${key}`, {
      method: 'PUT',
      headers: { 'content-type': 'application/json' },
      body: JSON.stringify(document)
    })
  },
  async remove(key) {
    await fetch(`/api/layouts/${key}`, { method: 'DELETE' })
  }
}
```

For a standard REST endpoint, use the built-in HTTP adapter:

```ts
import { remoteHttpAdapter } from '@marsio/vue-grid-layout/persistence'

const adapter = remoteHttpAdapter({
  endpoint: key => `/api/layouts/${encodeURIComponent(key)}`
})
```

For larger browser-local layouts, use IndexedDB:

```ts
import { indexedDBAdapter } from '@marsio/vue-grid-layout/persistence'

const adapter = indexedDBAdapter({
  dbName: 'dashboard-layouts',
  storeName: 'layouts',
  prefix: 'vgl:'
})
```

Adapters can also implement `subscribe(key, callback)` for remote or multi-tab updates. If an adapter does not implement `subscribe`, single-tab save/load still works, but external updates will not be observed. If a dirty page receives an external update, the default conflict strategy is `manual`; configure `conflictStrategy: 'newer-wins'` or `'keep-local'` only when that matches your product rules.

For responsive grids, use `<PersistentResponsiveGridLayout>` from `@marsio/vue-grid-layout/persistence`; it stores the full breakpoint layout map.

Migration note: replace old component-level `persistence` props with `PersistentGridLayout`, `PersistentResponsiveGridLayout`, or `useGridLayoutPersistence()`. Use `@marsio/vue-grid-layout/history` explicitly for undo/redo inside the current browser session.

Security note: `localStorage` is not suitable for sensitive data. Do not put credentials, private query keys or confidential business data in layout `meta`. During SSR or when browser storage is unavailable, the default localStorage adapter reports an unavailable/error state instead of touching `window`.

## Height Modes and Render Precision

`VueGridLayout` supports runtime height modes without changing `LayoutItem`. Item `x/y/w/h` values remain integer grid units for drag, resize, collision, compaction, history and persistence.

```vue
<VueGridLayout
  v-model="layout"
  :width="1200"
  :cols="12"
  height-mode="fit"
  :container-height="640"
  :min-row-height="24"
  render-precision="subpixel"
/>
```

Height modes:

- `auto`: preserves the classic content-sized grid behavior.
- `fixed`: uses `containerHeight` and hides overflow.
- `scroll`: uses `containerHeight` and allows scrolling.
- `fit`: derives runtime `rowHeight` from available container height and rendered rows.

When `containerHeight` is not controlled by the parent, opt in to parent measurement:

```vue
<VueGridLayout
  v-model="layout"
  :width="1200"
  height-mode="fit"
  :auto-measure-container-height="true"
/>
```

`containerHeight` always wins over measured height. Measurement observes the grid root parent content box, not the grid root itself, so `fit` does not feed back into its own height.

`renderPrecision="integer"` is the default and keeps the historical rounded CSS output. `renderPrecision="subpixel"` allows decimal CSS `left/top/width/height`; it does not change committed layout units, collision, compaction, history or persistence.

Compatibility notes:

- If `heightMode` is omitted, `autoSize: true` maps to `auto`.
- If `heightMode` is omitted, `autoSize: false` keeps the legacy externally sized container path.
- Dashboard `autoFillHeight` and `mobileAutoFillHeight` act as compatibility aliases for `fit` only when explicit `heightMode` or `mobileHeightMode` is missing.

## Dashboard Editor Shell Integration

`useDashboardEditorShell()` is a headless product-shell layer for dashboard editors. It sits above `DashboardLayoutDocument`, `DashboardResponsiveRuntime` / `useDashboardResponsiveProfileModel()` and `GridEditorController`; it does not add context menu DOM, dialogs, palette UI, business widget schema, reference fields or persistence side effects to `VueGridLayout` or `DashboardResponsiveVueGridLayout`.

```ts
import {
  useDashboardEditorShell,
  type DashboardEditorShellWidgetAdapter,
  type DashboardEditorShellReferenceAdapter
} from "@marsio/vue-grid-layout/dashboard-editor-shell";

const shell = useDashboardEditorShell({
  document: dashboardDocumentRef,
  model: dashboardResponsiveModel,
  gridElement: gridRootRef,
  mode,
  documentWriteBack: "shell",
  controlled: true,
  widgetAdapter,
  referenceAdapter,
  palette: {
    open: async context => pickWidgetTemplate(context)
  },
  confirm: async context => confirmRemove(context.itemIds),
  onDocumentChange: event => {
    // Proposed document only. Persist explicitly through your app/editor flow.
    proposedDocument.value = event.document;
  },
  onEvent: event => auditShellAction(event)
});
```

Shell responsibilities:

- Position helpers map pointer/contextmenu/drop events or keyboard fallback state to grid `{ x, y }`; list/mobile runtimes return insertion context instead of writing list-only ordering fields to `LayoutItem`.
- `pasteAtEvent()`, `pasteWidget()`, `placeClipboard()`, `commitPlacement()`, `addWidgetFromTemplate()`, `pasteWidgetReference()`, `openWidgetPalette()` and `handleExternalDrop()` reuse the editor command pipeline with explicit placement strategies and dashboard/profile write-back. `placeClipboard()` and `placementMode: "interactive"` start a placement session; `commitPlacement()` commits it through the shell transaction so document write-back and adapters are awaitable.
- `selectItem()`, `highlightItem()` and `scrollToItem()` keep selection in the editor and highlight/scroll as transient shell state. Highlight is not written to `DashboardLayoutDocument`, `LayoutItem`, `editorMetaById`, history or persistence.
- `prepareDashboardContextMenu()` and `prepareWidgetContextMenu()` return plain descriptors with ids, label/labelKey, icons, shortcuts, enabled/hidden/reason, metadata and action callbacks. Render them with your own menu/i18n/permission UI.
- `copyWidget()`, `cutWidget()`, `pasteWidget()`, `duplicateWidget()` and `removeWidget()` work without a widget adapter for layout/editor metadata; when an adapter is present it participates in prepare, commit and rollback.
- `undo()` and `redo()` replay editor history through dashboard/profile write-back, so keyboard shortcuts, toolbar buttons, menu actions and API calls keep the runtime layout and `DashboardLayoutDocument` in sync after paste/add/remove.
- `copyWidgetReference()`, `pasteWidgetReference()` and `replaceReferenceWithWidgetCopy()` require a reference adapter. Reference payloads are opaque; diagnostics record status, ids and error codes, not sensitive payload content.
- `openWidgetPalette()` only calls your palette hook. Catalogs, search, categories and widget configuration remain application code.
- `moveAllWidgets(dx, dy)` uses dashboard migration/layout-engine translation for profile-scoped or default-layout movement and reports applied patches/diagnostics.
- Optional keyboard binding maps shortcuts to shell actions, ignores text-editing targets and uses the same action pipeline as menus/toolbars/API calls. Defaults include Cmd/Ctrl+C copy, Cmd/Ctrl+X cut, Cmd/Ctrl+R copy reference, Cmd/Ctrl+V immediate paste, Cmd/Ctrl+I or Cmd/Ctrl+Shift+V paste reference, Ctrl+Enter or Cmd+Enter interactive “place from clipboard”, Delete/Backspace remove, undo/redo, palette and move-all shortcuts. After a keyboard cut, the next Cmd/Ctrl+V starts interactive clipboard placement instead of filling the newly-opened original slot.

Document ownership is controlled-first. If the shell is given controlled `document`/runtime inputs, successful mutations emit `onDocumentChange` and shell events with a proposed document and `persist: false`; the shell does not autosave. With `controlled: false`, the shell may update the supplied local document ref after a successful action, but remote persistence is still caller-owned.

When `documentWriteBack: "shell"` is enabled on the dashboard profile model, shell and `DashboardResponsiveVueGridLayout`, the shell becomes the only dashboard document write-back owner for editor commands. The responsive model still updates its runtime shadow and projection events, but it no longer emits component-owned `documentChange` for the same layout commit.

Adapter transactions follow `prepare -> editor/dashboard mutation -> commit`, with rollback/compensation when prepare succeeds but mutation or commit fails. This avoids reporting layout success when business payload creation failed, and avoids orphan business payloads when placement/write-back is blocked.

### Command-history-first dashboard editing

Use one write-back owner per dashboard editor:

- Recommended editor path: create the dashboard profile model with `documentWriteBack: "shell"`, pass the same value to `useDashboardEditorShell()` and to `DashboardResponsiveVueGridLayout`, then route toolbar, menu, keyboard, pointer drag/resize and external drop through editor command history. Shell `undo()` and `redo()` replay editor history and write the active dashboard profile/document sidecar in the same transaction.
- Component-owned path: omit `documentWriteBack` or use `"component"` when you only need runtime projection and component `documentChange` from `DashboardResponsiveVueGridLayout`. Do not also mirror the same commit through shell actions.
- Compatibility path: `historyStore` from `@marsio/vue-grid-layout/history` is layout-only. It can mirror committed geometry for older integrations, but it does not restore shell adapter transactions, business payload rollback, selection/focus, `editorMetaById`, `sectionRows`, reference payload state or dashboard persistence decisions.

Pointer drag, pointer resize and external drop can originate directly from the grid rather than from an explicit shell button. In shell-managed mode, the shell subscribes to editor `command-commit` events and emits synthetic `pointer-move`, `pointer-resize` and `external-drop` action results with command id, action source, affected ids, write-back status, patches and diagnostics.

### Shell placement strategies

Shell add/paste/drop entry points accept `strategy?: "cursor" | "nearest-fit" | "first-fit" | "insert-top-shift" | "offset"`, `placementIntent?: "auto" | "here" | "selection" | "viewport"`, `placementMode?: "immediate" | "interactive"` and `collisionPolicy?: "block" | "layout"` through the shared placement options. Targetless widget paste uses `placementIntent: "auto"` and can inherit `menu.defaultPasteStrategy` or `menu.defaultAddStrategy`, so keyboard/toolbars can follow the same left-to-right insertion policy as add flows. When a v2 clipboard source has different `cols` than the active target grid, paste and placement sessions scale the copied group’s `x`, `w` and relative horizontal offsets to the target columns before id mapping. Keyboard bindings can provide `placementOptions` globally or per shortcut, and shortcuts support platform `primary` plus explicit `ctrl` / `meta` modifiers, which lets Ctrl+Enter start the same interactive clipboard placement flow as a toolbar button while reusing the app's current collision policy. Event/grid-position actions use `placementIntent: "here"` by default; dashboard context-menu items are labelled “Paste here” / “Add widget here” for immediate commit and may also expose “Place from clipboard” for ghost placement through the public controller API. For `cursor` placements with `placementIntent: "here"`, the default block policy treats the target as the new item’s top-left anchor and blocks collision in placement sessions; `collisionPolicy: "layout"` instead follows `preventCollision`, `allowOverlap` and `compactType` so the preview can show existing widgets being pushed before commit.

- `first-fit` scans the active runtime layout from `{ x: 0, y: 0 }`, left to right and then row by row. Hidden, static, locked, and currently unrendered items still occupy their geometry because they remain part of the active layout.
- `insert-top-shift` places the new item or copied group at the top-left and shifts every existing active-layout item down by the inserted group height. Static or locked items move only for this layout-level reflow; their drag, resize, and remove permissions do not change.
- If item size, collision repair, bounds, `maxRows`, missing profile write-back, guard checks, or adapter stages fail, the shell returns a blocked/error result with placement diagnostics and rolls back prepared adapter work. Adapter diagnostics include stages, ids, codes, and reasons, not opaque business payloads.
- Responsive write-back stays scoped to the current runtime/profile. Editing a default layout does not overwrite profile overrides, and editing a profile does not materialize unrelated inherited items.

See `example/25-dashboard-editor-shell.js` for context menu descriptors, paste at pointer, selection/highlight/scroll, empty dashboard add, palette hook, widget copy/paste, reference copy/paste/replace mocks, remove confirm and move-all wiring. The example menu/palette/buttons are demonstration UI only; their DOM, styles and labels are not public API.

## Widget Registry Protocol

`@marsio/vue-grid-layout/widget-registry` is an optional headless protocol for product dashboards that need stable widget type metadata without pulling a UI kit, renderer, chart library, plugin marketplace or AI assistant into the core grid. It describes widget types, layout defaults, settings descriptors, template materialization, `extensions.widget` sidecar helpers and shell adapters.

```ts
import {
  createWidgetRegistry,
  materializeWidgetTemplate,
  createWidgetRegistryPaletteAdapter,
  createWidgetRegistryWidgetAdapter,
  validateDashboardWidgetInstances
} from "@marsio/vue-grid-layout/widget-registry";

const registry = createWidgetRegistry([
  {
    type: "kpi",
    version: "1.0.0",
    title: "KPI",
    category: "metrics",
    layoutDefaults: { w: 3, h: 2, minW: 2, minH: 1 },
    rendererHint: { rendererKey: "builtin", componentKey: "kpi-card" },
    settings: {
      fields: [
        { id: "title", type: "string", defaultValue: "Revenue", required: true },
        { id: "format", type: "enum", defaultValue: "compact", options: [{ value: "compact" }, { value: "full" }] }
      ]
    }
  }
]);

const widget = materializeWidgetTemplate(registry, {
  type: "kpi",
  id: "revenue-kpi",
  settings: { title: "Revenue" }
});

if (widget.ok) {
  await shell.actions.addWidgetFromTemplate(widget.template, null, { strategy: "first-fit" });
}
```

Registry boundaries:

- Widget definitions are JSON-safe. Functions, DOM nodes, Vue refs, class instances, circular objects, non-finite numbers and reserved keys are rejected or cleaned according to `policy: "strict" | "tolerant"`.
- `rendererHint` is only a string metadata hint such as `rendererKey`, `componentKey` or `slot`; the registry never stores component objects, dynamic import functions or renderer resolvers.
- Layout defaults bridge to the existing item capability/aspect-ratio model through fields such as `static`, `draggable`, `resizable`, `bounded`, `resizeHandles`, `preserveAspectRatio` and `aspectRatio`.
- Settings descriptors intentionally cover common fields only: `string`, `number`, `boolean`, `enum`, `color`, `text`, `json`, `object`, `array` and `ref`. `object`, `array` and `json` are lightweight JSON-safe checks, not a full JSON Schema runtime.
- Widget instance metadata belongs under each dashboard item at `DashboardItemLayout.extensions.widget`. Basic `LayoutItem` geometry stays clean; normal move/resize write-back does not rewrite widget settings, bindings, payload or renderer metadata.
- `createWidgetRegistryPaletteAdapter()` and `createWidgetRegistryWidgetAdapter()` are composable adapters for `useDashboardEditorShell()`. Existing handwritten `DashboardEditorShellWidgetTemplate`, `palette.open` and `widgetAdapter` integrations remain compatible.

The registry entry is separate from `./dashboard`, `./dashboard-editor-shell`, `./editor`, `./core` and `./responsive`. Root/core/responsive users do not pay for widget protocol code unless they import the `./widget-registry` subpath.

## Dashboard Layout Document Adapter

Dashboard products often need more than the generic `LayoutItem` geometry model. Use `DashboardLayoutDocument` when you need a durable product document with widget layout fields, grid settings, breakpoint/profile overrides, editor sidecar metadata, migrations and ThingsBoard-style import/export boundaries.

```ts
import {
  projectDashboardLayoutDocument,
  writeDashboardRuntimeToDocument,
  type DashboardLayoutDocument
} from '@marsio/vue-grid-layout/dashboard'

const dashboardDocument: DashboardLayoutDocument = {
  dashboardSchemaVersion: 1,
  kind: 'dashboard-layout',
  key: 'dashboard:operations',
  revision: 'rev-1',
  sourceId: 'server',
  savedAt: new Date().toISOString(),
  primaryLayoutId: 'default',
  layouts: {
    default: {
      gridSettings: {
        columns: 24,
        rowHeight: 80,
        heightMode: 'fit',
        minRowHeight: 24,
        renderPrecision: 'subpixel'
      },
      widgets: {
        temperature: {
          col: 0,
          row: 0,
          sizeX: 6,
          sizeY: 4,
          resizable: false,
          mobileOrder: 1
        }
      },
      editor: {
        version: 1,
        editorMetaById: {
          temperature: { label: 'Temperature' }
        }
      }
    }
  }
}

const projected = projectDashboardLayoutDocument(dashboardDocument, {
  profileId: 'mobile',
  targetView: 'mobile'
})

if (projected.ok) {
  const layout = projected.projection.layout
  const editorMetaById = projected.projection.editorMetaById
  const gridSettings = projected.projection.gridSettings

// Pass layout to VueGridLayout modelValue, and pass editorMetaById
  // to your headless editor controller or product shell.
  console.log(layout, editorMetaById, gridSettings)
}
```

To persist committed editor changes back into the dashboard document, write runtime geometry and mapped metadata through the adapter:

```ts
const saved = writeDashboardRuntimeToDocument(dashboardDocument, {
  layout: committedLayout,
  editorMetaById: committedEditorMetaById
}, {
  targetView: 'desktop'
})

if (saved.ok) {
  await dashboardAdapter.save(saved.document.key, saved.document)
}
```

The dashboard adapter is framework-independent. It does not add `useDashboardLayoutPersistence()`, component-level dashboard props, collision repair, context menus, widget palettes or business data source models. `LayoutItem` remains the generic grid runtime shape; dashboard-only fields such as `mobileOrder`, `mobileHeight`, `desktopHide`, `mobileHide`, `preserveAspectRatio`, `aspectRatio` and grid settings stay in the dashboard document or runtime sidecars (`capabilitiesById`, `resizeConstraintsById`).

## Dashboard Responsive Profiles

Use the dashboard responsive layer when a `DashboardLayoutDocument` has breakpoint profiles and you want profile fallback, mobile/list projection, visibility metadata and profile-scoped write-back without changing the generic `ResponsiveVueGridLayout` API.

```ts
import {
  resolveDashboardResponsiveProfile,
  writeDashboardResponsiveRuntimeToDocument,
  type DashboardLayoutDocument
} from '@marsio/vue-grid-layout/dashboard'

const result = resolveDashboardResponsiveProfile(dashboardDocument, {
  width: 390,
  breakpoints: { desktop: 960, mobile: 0 },
  targetViewRule: { mobileBreakpointIds: ['mobile'] },
  mode: 'view'
})

if (result.ok) {
  result.runtime.layout        // Layout for VueGridLayout
  result.runtime.renderItemIds // Slot/widget ids to render
  result.runtime.heightOptions // Profile-derived height/precision defaults
  result.runtime.diagnostics   // profile-fallback, unknown-profile-item, etc.
}

const saved = result.ok && writeDashboardResponsiveRuntimeToDocument(
  dashboardDocument,
  result.runtime,
  committedLayout,
  { createMissingProfileOnEdit: false }
)
```

For Vue integrations that want headless state, use the composable:

```ts
import { useDashboardResponsiveProfileModel } from '@marsio/vue-grid-layout/dashboard'

const model = useDashboardResponsiveProfileModel({
  document,
  width,
  breakpoints: { desktop: 960, mobile: 0 },
  targetViewRule: { mobileBreakpointIds: ['mobile'] },
  mode: 'edit',
  documentWriteBack: 'shell',
  onEvent: event => console.log(event.type)
})
```

For a thin component wrapper, key slot children by dashboard widget id:

```vue
<DashboardResponsiveVueGridLayout
  v-model:document="document"
  :width="width"
  :breakpoints="{ desktop: 960, mobile: 0 }"
  :targetViewRule="{ mobileBreakpointIds: ['mobile'] }"
  :container-height="640"
  document-write-back="shell"
>
  <WidgetCard key="temperature" />
  <WidgetCard key="pressure" />
</DashboardResponsiveVueGridLayout>
```

Use `documentWriteBack: 'shell'` only when `useDashboardEditorShell()` owns the editor transaction. Leave it as the default component path for simple runtime demos that want `DashboardResponsiveVueGridLayout` to emit `documentChange` directly.

Legacy responsive layouts can be converted into a dashboard document. Breakpoint ids such as `lg`, `md`, `sm`, `xs` and `xxs` become dashboard profile ids; by default the largest breakpoint width becomes the default dashboard layout.

```ts
import { createDashboardDocumentFromResponsiveLayouts } from '@marsio/vue-grid-layout/dashboard'

const migrated = createDashboardDocumentFromResponsiveLayouts({
  key: 'dashboard:from-responsive',
  layouts,
  breakpoints: { lg: 1200, md: 996, sm: 768, xs: 480, xxs: 0 },
  cols,
  margin,
  containerPadding
})
```

Dashboard profile `gridSettings` can set `heightMode`, `mobileHeightMode`, `minRowHeight`, `rowHeight`, `mobileRowHeight`, `autoFillHeight`, `mobileAutoFillHeight` and `renderPrecision`. The thin component passes those settings to the base grid as defaults; explicit component props such as `height-mode`, `container-height`, `row-height` and `render-precision` take precedence.

This layer intentionally stays thin. It does not implement aspect-ratio resize, dashboard context menus, widget palettes, copy/paste shells or business widget data sources. Future specs can build those features on top of profile resolution, settings projection, mobile/list runtime, height runtime, settings migration and write-back.

## Layout Settings Migration and Repair

Use the layout engine helpers when changing geometric settings such as columns, importing items, repairing collisions, or translating an entire layout. Visual settings such as margin, row height, height mode and render precision do not automatically rewrite committed item geometry.

```ts
import {
  migrateLayoutSettings,
  repairLayoutCollisions
} from '@marsio/vue-grid-layout/layout-engine'
import {
  migrateDashboardLayoutSettings
} from '@marsio/vue-grid-layout/dashboard'

const migrated = migrateLayoutSettings(layout, {
  previousSettings: { columns: 24 },
  nextSettings: { columns: 12 },
  engineOptions: { cols: 24, compactType: null, preventCollision: true }
})

console.log(migrated.status, migrated.patches, migrated.diagnostics?.details)

const repaired = repairLayoutCollisions(migrated.layout, {
  engineOptions: { cols: 12, compactType: null, preventCollision: true },
  policy: { strategy: 'heuristic' }
})

const dashboardResult = migrateDashboardLayoutSettings(document, {
  profileId: 'tablet',
  nextSettings: { columns: 12 },
  policy: { repair: { strategy: 'nearest-then-first' } }
})
```

The default repair implementation is deterministic heuristic repair: static or locked items are preserved first, movable items use nearest-fit with first-fit fallback, and diagnostics identify scaling, clamping, movement, fallback and unresolved constraints. The API is solver-ready through `customRepairSolver`, objective metadata, budget fields and solver diagnostics, but the package does not ship a full constraint solver, ILP/CP-SAT dependency, settings dialog UI, schema rewrite, group resize, nested grids, inter-grid drag, full Editor Kit UI, Widget Registry schema or AI/MCP dashboard assistant as part of this feature.

## Layout Engine Performance

The default interaction path uses the layout engine module. It keeps preview work separate from committed layout changes, uses a row/column occupancy index for collision and fit checks, and reports structured diagnostics through `layoutEngine.onEvent`.

```vue
<VGL
  v-model="layout"
  :cols="12"
  :width="1200"
  :layoutEngine="{
    scheduler: { mode: 'auto' },
    diagnostics: { debug: true, budgetMs: 8 },
    onEvent: event => {
      if (event.type === 'budget-warning') {
        console.warn(event.message, event.diagnostics)
      }
    }
  }"
/>
```

Recommended scheduler modes:

- `auto` for most dashboards. It chooses eager, rAF-coalesced, or commit-only preview based on layout size, density, and recent compute time.
- `eager` for small layouts and deterministic tests.
- `raf` for larger dashboards where pointermove events arrive faster than rendering.
- `commitOnly` when preview should stay lightweight and full solving should happen on drag/resize stop.

For very large compact, drop-fit, responsive breakpoint generation, batch import, or commit validation tasks, use `workerLayoutExecutor({ workerUrl })`, `createLayoutExecutor({ kind: 'worker', workerUrl })`, or pass a custom executor from `@marsio/vue-grid-layout/layout-engine`. Resolve the worker through the public worker export:

```ts
import { workerLayoutExecutor } from '@marsio/vue-grid-layout/layout-engine'

const executor = workerLayoutExecutor({
  workerUrl: new URL('@marsio/vue-grid-layout/worker', import.meta.url).toString()
})
```

If your bundler does not support package subpaths in `new URL()`, import the worker entry with its URL query if supported by that bundler, or pass your own `workerFactory`. If the worker cannot start, the library falls back to the main-thread executor and emits a `fallback` or `worker-error` event. Pointermove preview for drag/resize stays on the main-thread low-latency path; worker-capable execution is used for commits and heavy fit/responsive operations.

Preview frames are not durable state. `layoutChange`, `update:modelValue`, `historyStore`, and `persistence` are updated only from committed drag/resize/drop results. Diagnostics summarize operation id, phase, layout size, affected item count, collision count, scheduler mode, executor kind, index usage, and duration; debug mode adds a compact replay summary without logging the full layout by default. The benchmark matrix can be run with `yarn bench:layout-engine`; set `EXECUTOR=worker` to include worker queue/compute/end-to-end reporting and `SIZES`, `SCENARIOS`, `SEED`, or `BUDGET_FILE` to customize the run.

You may also choose to set layout properties directly on the children:

```vue
<template>
  <GridLayout class="layout" :cols="12" :rowHeight="30" :width="1200">
    <div key="a" :data-grid="{ x: 0, y: 0, w: 1, h: 2, static: true }">
      a
    </div>
    <div key="b" :data-grid="{ x: 1, y: 0, w: 3, h: 2, minW: 2, maxW: 4 }"">
      b
    </div>
    <div key="c" :data-grid="{ x: 4, y: 0, w: 1, h: 2 }">
      c
    </div>
  </GridLayout>
</template>

export default defineComponent({
  components: {
    VGL
  }
});
</script>
```

### Responsive Usage

To make VGL responsive, use the `<ResponsiveVueGridLayout>` element:

```vue
<template>
  <ResponsiveGridLayout
    class="layout"
    :layouts="state.layouts"
    :breakpoints="{ lg: 1200, md: 996, sm: 768, xs: 480, xxs: 0 }"
    :cols="{ lg: 12, md: 10, sm: 6, xs: 4, xxs: 2 }"
  >
    <div v-for="(l, i) in state.layouts.lg" :key="i+1" :class="{ static: l.static }">
      <span v-if="l.static" class="text" title="This item is static and cannot be removed or resized.">
        Static - {{ i }}
      </span>
      <span v-else class="text">{{ i }}</span>
    </div>
  </ResponsiveGridLayout>
</template>

export default defineComponent({
  components: {
    ResponsiveGridLayout
  },
  setup() {
    const generateLayout = () => {
      return Array.from({ length: 10 }, (item, i) => {
        const y = Math.ceil(Math.random() * 4) + 1;
        return {
          x: Math.round(Math.random() * 5) * 2,
          y: Math.floor(i / 6) * y,
          w: 2,
          h: y,
          i: (i + 1).toString(),
          static: Math.random() < 0.05
        };
      });
    }
    const state = {
      layouts: { lg: generateLayout() }
    }
    return {
      state
    }
  }
});
</script>
```

When in responsive mode, you should supply at least one breakpoint via the `layouts` property.

When using `layouts`, it is best to supply as many breakpoints as possible, especially the largest one.
If the largest is provided, VGL will attempt to interpolate the rest.

You will also need to provide a `width`, when using `<ResponsiveVueGridLayout>` it is suggested you use the HOC
`WidthProvider` as per the instructions below.

It is possible to supply default mappings via the `data-grid` property on individual
items, so that they would be taken into account within layout interpolation.

### Providing Grid Width

Both `<ResponsiveVueGridLayout>` and `<VueGridLayout>` take `width` to calculate
positions on drag events. In simple cases a HOC `WidthProvider` can be used to automatically determine
width upon initialization and window resize events.

const ResponsiveGridLayout = WidthProvider(ResponsiveVueGridLayout);

This allows you to easily replace `WidthProvider` with your own Provider HOC if you need more sophisticated logic.

`WidthProvider` accepts a single prop, `measureBeforeMount`. If `true`, `WidthProvider` will measure the
container's width before mounting children. Use this if you'd like to completely eliminate any resizing animation
on application/component mount.

### Grid Layout Props

VGL supports the following properties (see the source for the final word on this):

```js
//
// Basic props
//

// This is required unless using the HOC <WidthProvider> or similar
width: number,

// If true, the container height swells and contracts to fit contents
autoSize?: boolean = true,

// Runtime height mode. Explicit heightMode takes precedence over autoSize.
heightMode?: 'auto' | 'scroll' | 'fit' | 'fixed',

// Controlled container height in px for fixed, scroll and fit modes.
containerHeight?: number,

// Measure the grid root parent content box when containerHeight is omitted.
autoMeasureContainerHeight?: boolean = false,

// Minimum row height for fit mode before falling back to scroll.
minRowHeight?: number,

// Final CSS pixel output; subpixel does not change committed grid units.
renderPrecision?: 'integer' | 'subpixel' = 'integer',

// Number of columns in this layout.
cols?: number = 12,

// A CSS selector for tags that will not be draggable.
// For example: draggableCancel:'.MyNonDraggableAreaClassName'
// If you forget the leading . it will not work.
// .vue-resizable-handle" is always prepended to this value.
draggableCancel?: string = '',

// If true, native interactive descendants such as button, input, select,
// textarea, link, and contenteditable elements will not start a drag.
draggableCancelInteractiveElements?: boolean = true,

// A CSS selector for tags that will act as the draggable handle.
// For example: draggableHandle:'.MyDragHandleClassName'
// If you forget the leading . it will not work.
draggableHandle?: string = '',

// Compaction type.
compactType?: ('vertical' | 'horizontal' | null) = 'vertical';

// Layout is an array of objects with the format:
// The index into the layout must match the key used on each item component.
// If you choose to use custom keys, you can specify that key in the layout
// array objects using the `i` prop.
layout?: Array<{i?: string, x: number, y: number, w: number, h: number}> = null, // If not provided, use data-grid props on children

// Margin between items [x, y] in px.
margin?: [number, number] = [10, 10],

// Padding inside the container [x, y] in px
containerPadding?: [number, number] = margin,

// Rows have a static height, but you can change this based on breakpoints
// if you like.
rowHeight?: number = 150,

// Configuration of a dropping element. Dropping element is a "virtual" element
// which appears when you drag over some element from outside.
// It can be changed by passing specific parameters:
//  i - id of an element
//  w - width of an element
//  h - height of an element
droppingItem?: { i: string, w: number, h: number }

//
// Flags
//
isDraggable?: boolean = true,
isResizable?: boolean = true,
isBounded?: boolean = false,
// Uses CSS3 translate() instead of position top/left.
// This makes about 6x faster paint performance
useCSSTransforms?: boolean = true,
// If parent DOM node of ResponsiveVueGridLayout or VueGridLayout has "transform: scale(n)" css property,
// we should set scale coefficient to avoid render artefacts while dragging.
transformScale?: number = 1,

// Auto-scroll the nearest scroll container when dragging/resizing near an edge.
// If true, uses defaults. Or pass { margin?: number; speed?: number }.
autoScroll?: boolean | { margin?: number; speed?: number } = false,

// Drag activation threshold in px.
// Defaults are mouse/pen: 4, touch/coarse: 8. Set 0 for legacy-style immediate dragStart.
dragActivationDistance?: number | {
  mouse?: number,
  pen?: number,
  touch?: number,
  coarse?: number,
  default?: number
},

// If true, grid can be placed one over the other.
// If set, implies `preventCollision`.
allowOverlap?: boolean = false,

// If true, grid items won't change position when being
// dragged over. If `allowOverlap` is still false,
// this simply won't allow one to drop on an existing object.
preventCollision?: boolean = false,

// If true, droppable elements (with `draggable={true}` attribute)
// can be dropped on the grid. It triggers "onDrop" callback
// with position and event object as parameters.
// It can be useful for dropping an element in a specific position

isDroppable?: boolean = false,

// Determines how an external element is positioned while dragging over the grid.
// - 'cursor': place based on the mouse position (default)
// - 'auto': snap to the nearest existing block adjacent position
dropStrategy?: 'cursor' | 'auto' = 'cursor',
// Defines which resize handles should be rendered.
// Allows for any combination of:
// 's' - South handle (bottom-center)
// 'w' - West handle (left-center)
// 'e' - East handle (right-center)
// 'n' - North handle (top-center)
// 'sw' - Southwest handle (bottom-left)
// 'nw' - Northwest handle (top-left)
// 'se' - Southeast handle (bottom-right)
// 'ne' - Northeast handle (top-right)
//
// Note that changing this property dynamically does not work due to a restriction in @marsio/vue-resizable.
resizeHandles?: Array<'s' | 'w' | 'e' | 'n' | 'sw' | 'nw' | 'se' | 'ne'> = ['se'],

// class to the `draggableCancel` prop.
resizeHandle?: VNode
  | ((
      resizeHandleAxis: ResizeHandleAxis,
      ref: VueRef<HTMLElement>
    ) => VNode)

//
// Callbacks
//

// Callback so you can save the layout.
// Calls back with (currentLayout) after every drag or resize stop.
onLayoutChange: (layout: Layout) => void,

//
// All callbacks below have signature (layout, oldItem, newItem, placeholder, e, element).
// 'start' and 'stop' callbacks pass `undefined` for 'placeholder'.
//
type ItemCallback = (layout: Layout, oldItem: LayoutItem, newItem: LayoutItem,
                     placeholder: LayoutItem, e: MouseEvent, element: HTMLElement) => void,

// Calls when drag starts.
onDragStart: ItemCallback,
// Calls on each drag movement.
onDrag: ItemCallback,
// Calls when drag is complete.
onDragStop: ItemCallback,
// Calls when resize starts.
onResizeStart: ItemCallback,
// Calls when resize movement happens.
onResize: ItemCallback,
// Calls when resize is complete.
onResizeStop: ItemCallback,

// Calls when an element has been dropped into the grid from outside.
onDrop: (layout: Layout, e: Event, item?: LayoutItem) => void,
// Calls when an element is being dragged over the grid from outside as above.
// This callback should return an object to dynamically change the droppingItem size
// Return false to short-circuit the dragover
onDropDragOver: (e: DragEvent) => { w?: number; h?: number } | false;

// Ref for getting a reference for the grid's wrapping div.
innerRef?: Ref<"div">,

// Layout engine configuration. Omit for the default engine path.
// Set false or { mode: 'legacy' } to use the legacy path.
layoutEngine?: false | {
  mode?: 'default' | 'legacy',
  scheduler?: {
    mode?: 'eager' | 'raf' | 'commitOnly' | 'auto',
    maxTaskMs?: number
  },
  executor?: LayoutExecutor | { kind: 'worker', workerUrl?: string, timeoutMs?: number },
  compareLegacy?: boolean,
  legacyFallback?: boolean,
  diagnostics?: boolean | { debug?: boolean, budgetMs?: number },
  onEvent?: (event: LayoutEngineEvent) => void
}
```

### Responsive Grid Layout Props

The responsive grid layout can be used instead. It supports all of the props above, excepting `layout`.
The new properties and changes are:

```js
// {name: pxVal}, e.g. {lg: 1200, md: 996, sm: 768, xs: 480}
// Breakpoint names are arbitrary but must match in the cols and layouts objects.
breakpoints?: Object = {lg: 1200, md: 996, sm: 768, xs: 480, xxs: 0},

// # of cols. This is a breakpoint -> cols map, e.g. {lg: 12, md: 10, ...}
cols?: Object = {lg: 12, md: 10, sm: 6, xs: 4, xxs: 2},

// margin (in pixels). Can be specified either as horizontal and vertical margin, e.g. `[10, 10]` or as a breakpoint -> margin map, e.g. `{lg: [10, 10], md: [10, 10], ...}.
margin: [number, number],

// containerPadding (in pixels). Can be specified either as horizontal and vertical padding, e.g. `[10, 10]` or as a breakpoint -> containerPadding map, e.g. `{lg: [10, 10], md: [10, 10], ...}.
containerPadding: [number, number],

// layouts is an object mapping breakpoints to layouts.
// e.g. {lg: Layout, md: Layout, ...}
layouts,

// Passed to the inner grid and used for responsive layout generation.
layoutEngine?: false | GridLayoutEngineProp,

//
// Emit
//

// Calls back with breakpoint and new # cols
onBreakpointChange: (newBreakpoint: string, newCols: number) => void,

// Callback so you can save the layout.
// AllLayouts are keyed by breakpoint.
onLayoutChange: (currentLayout: Layout, allLayouts) => void,

// Callback when the width changes, so you can modify the layout as needed.
onWidthChange: (containerWidth: number, margin: [number, number], cols: number, containerPadding: [number, number]) => void;

// ResponsiveVueGridLayout forwards inner VueGridLayout interaction events.
// Payloads match the base grid exactly.
onDragStart / onDrag / onDragStop: ItemCallback,
onResizeStart / onResize / onResizeStop: ItemCallback,
onDrop: (layout: Layout, e: Event, item?: LayoutItem) => void,
onDropDragOver: (e: DragEvent) => { w?: number; h?: number } | false,

```

### Grid Item Props

VGL supports the following properties on grid items or layout items. When initializing a grid,
build a layout array (as in the first example above), or attach this object as the `data-grid` property
to each of your child elements (as in the second example).

If `data-grid` is provided on an item, it will take precedence over an item in the `layout` with the same key (`i`).

Note that if a grid item is provided but incomplete (missing one of `x, y, w, or h`), an error
will be thrown so you can correct your layout.

If no properties are provided for a grid item, one will be generated with a width and height of `1`.

You can set minimums and maximums for each dimension. This is for resizing; it of course has no effect if resizing
is disabled. Errors will be thrown if your mins and maxes overlap incorrectly, or your initial dimensions
are out of range.

Any `<GridItem>` properties defined directly will take precedence over globally-set options. For
example, if the layout has the property `isDraggable: false`, but the grid item has the prop `isDraggable: true`, the item
will be draggable, even if the item is marked `static: true`.

```js
{

// A string corresponding to the component key
  i: string,

// These are all in grid units, not pixels
  x: number,
  y: number,
  w: number,
  h: number,
  minW?: number = 0,
  maxW?: number = Infinity,
  minH?: number = 0,
  maxH?: number = Infinity,

// If true, equal to `isDraggable: false, isResizable: false`.
  static?: boolean = false,
  // If false, will not be draggable. Overrides `static`.
  isDraggable?: boolean = true,
  // If false, will not be resizable. Overrides `static`.
  isResizable?: boolean = true,
  // By default, a handle is only shown on the bottom-right (southeast) corner.
  resizeHandles?: Array<'s' | 'w' | 'e' | 'n' | 'sw' | 'nw' | 'se' | 'ne'> = ['se']
  // If true and draggable, item will be moved only within grid.
  isBounded?: boolean = false
}
```

### Grid Item Heights and Widths

Grid item widths are based on container and number of columns. The size of a grid unit's height is based on `rowHeight`.

Note that an item that has `h=2` is _not exactly twice as tall as one with `h=1` unless you have no `margin`_!

In order for the grid to not be ragged, when an item spans grid units, it must also span margins. So you must add the height or width or the margin you are spanning for each unit. So actual pixel height is `(rowHeight * h) + (marginH * (h - 1)`.

For example, with `rowHeight=30`, `margin=[10,10]` and a unit with height 4, the calculation is `(30 * 4) + (10 * 3)`
![image](https://github.com/user-attachments/assets/4d42cd55-44c5-421d-a565-10aab03d80be)

If this is a problem for you, set `margin=[0,0]` and handle visual spacing between your elements inside the elements' content.

vue-grid-layout

vue-grid-layout 최신버젼 다운로드

오늘의 추천 프로젝트

Was this content helpful?

Recent Feedback

vue-grid-layout

vue-grid-layout 최신버젼 다운로드

오늘의 추천 프로젝트

Was this content helpful?

Recent Feedback

Download README