#Elements

Generated by website/scripts/generate-api.ts from packages/gridla/src. Do not edit by hand; run bun run generate in website/.

Custom elements over gridla/dom: <gridla-canvas>, <gridla-item>, <gridla-preview>, and <gridla-transfer-scope>, registered with defineGridlaElements. No shadow DOM; your styles apply.

import { createTransferScope, defineGridlaElements, GridlaCanvasElement, GridlaItemElement, GridlaPreviewElement, GridlaTransferScopeElement } from 'gridla/elements'
import type { GridlaCanvasEventMap, GridlaLayoutChangeDetail, TransferScope } from 'gridla/elements'

#Functions

#createTransferScope

Create a TransferScope. Pass it to every createGridController whose items may move between each other (option scope); the controllers register themselves and unregister on destroy().

export function createTransferScope(): TransferScope

#defineGridlaElements

Register \<prefix-canvas\>, \<prefix-item\>, \<prefix-preview\>, and \<prefix-transfer-scope\> (default prefix gridla). Safe to call more than once and with several prefixes; a name that is already defined is skipped. Does nothing where customElements is unavailable (server rendering).

export function defineGridlaElements(prefix = 'gridla'): void

#Classes

#GridlaCanvasElement

A canvas over mountGrid. Set the layout property (or listen for layout-change and set it back for controlled use); children are \<gridla-item item-id\> elements and an optional \<gridla-preview\>.

Attributes: responsive ("false" sizes the element to the layout), gap, snap-distance, drag-threshold, keyboard-step, resize-edges (built-in handles for every item, for example "e s se"), resize-handle-class, positioning (transform | absolute), selected-id.

export class GridlaCanvasElement<TData = unknown> extends BaseElement

#GridlaItemElement

One item of a \<gridla-canvas\>. Its light-DOM children are the content; the canvas positions the element and sets the data-gridla-* attributes. The only attribute is item-id. An element without a matching layout item is hidden; a layout item without an element gets one created.

export class GridlaItemElement extends BaseElement

#GridlaPreviewElement

The drop outline. Place one inside a \<gridla-canvas\>; the canvas shows it (data-gridla-preview) while a gesture has an accepted preview and hides it otherwise.

export class GridlaPreviewElement extends BaseElement

#GridlaTransferScopeElement

Shares one transfer scope with every \<gridla-canvas\> inside it, so items can be dragged between them. Nest canvases inside items for nested layouts.

export class GridlaTransferScopeElement extends BaseElement

#Types

#GridlaCanvasEventMap

Events dispatched by \<gridla-canvas\>. layout-change fires after every accepted change, commit after every interactive commit (with the solver strategy), select when the selection changes, item-click when a press ends without a drag, transfer-out and transfer-in when an item crosses canvases inside a \<gridla-transfer-scope\>. None of them bubble.

export type GridlaCanvasEventMap<TData = unknown> = {
  'layout-change': CustomEvent<GridlaLayoutChangeDetail<TData>>
  commit: CustomEvent<GridChangeDetail>
  select: CustomEvent<{ itemId: string | null }>
  'item-click': CustomEvent<{ itemId: string }>
  'transfer-out': CustomEvent<{ itemId: string; targetId: string }>
  'transfer-in': CustomEvent<{ item: GridItem<TData>; sourceId: string }>
}

#GridlaLayoutChangeDetail

Detail of the layout-change event: the next layout and what changed.

export type GridlaLayoutChangeDetail<TData = unknown> = {
  layout: GridLayout<TData>
  change: GridChangeDetail
}

#TransferScope

Coordinates item moves between canvases. The pointer decides the target: the deepest registered canvas under the pointer that accepts the item previews the drop; releasing there commits it.

export type TransferScope = {
  /** Add a canvas. Returns a function that removes it again. */
  register: (registration: TransferRegistration) => () => void
  /** Called by the source canvas on every pointer move during a drag (client coordinates). */
  track: (sourceId: string, itemId: string, client: GridPoint) => void
  /** Called by the source canvas on release. Returns `true` when a transfer happened. */
  drop: (sourceId: string) => boolean
  /** Abandon the current transfer session and clear any target preview. */
  cancel: () => void
}