Fragiola

Concepts

The primitive contract

How every GridLayout part renders, takes your props and exposes its state, so you can style and compose it freely.

Every part follows the same rules.

  • render, never asChild. render={<section />} merges the part's props into your element; render={(props, state) => …} hands you both.
  • ref is a plain prop, merged with the part's own.
  • Your props are forwarded, and your handlers run after the part's own. On Root, the grid's pointer and key handling runs after yours: preventDefault vetoes a gesture or replaces a key.
  • className and style take a value or a function of the state. Your style sits under the part's structural style.
  • Structural inline style only: a position, a size, a transform, the held item above the others, touch-action: none on handles and drag sources, and a placeholder and drag preview that never take the pointer. Nothing cosmetic.
  • State through data-* and ARIA, present or absent, never "false". See State attributes.
  • No text and no names. Give every item, handle and button its accessible name.
  • You own the recursion. GridLayout.Items is a children function over the layout's items.

The parts

parthookwhat it is
GridLayout.RootuseGridLayout, useGridLayoutViewthe positioned box the items are placed in
GridLayout.ItemsuseItemsa children function over the items, keyed by id
GridLayout.ItemuseIteman item, placed at its box; a tab stop
GridLayout.DragHandleuseDragHandlethe only place its item drags from, and its tab stop
GridLayout.ResizeHandleuseResizeHandlea side or corner the item is resized from
GridLayout.PlaceholderusePlaceholderwhere the held item would land, during a gesture
GridLayout.DragSourceuseDragSourceanything on the page that brings a new item in; a tab stop
GridLayout.DragPreviewuseDragPreviewwhat follows the pointer while it brings an item in

A part hook returns { state, props }: spread props onto any element to make it that part.

Outside the root, parts and hooks reach the grid through a gridLayoutRef (useGridLayoutRef(), or createGridLayoutRef() outside a component), given to the root too.

In Vue

@fragiola/grid-layout-vue keeps the same contract, written the Vue way (Vue components):

  • render is as (a tag or a component) or the render scoped slot, which receives the props to bind and the state.
  • Attributes and listeners fall through onto the part's element, under its structural style; a part's own listeners compose with yours.
  • class and style take a value, not a function of the state: style the state through the data-* attributes (data-dragging:shadow-lg, [data-dragging] in CSS), or read it from the render slot.
  • GridLayout.Items is a scoped slot over the layout's items (v-slot="{ item }"): you still own what each item renders.
  • A composable returns { state, props } as computed refs: bind props with v-bind.

In Angular

@fragiola/grid-layout-angular keeps the same contract, written the Angular way (Angular directives):

  • render is the element you write: each part is a directive on it (gridLayoutRoot, [gridLayoutItem]="item.id", gridLayoutDragHandle, [gridLayoutDragSource]="{ w, h }"), which keeps your attributes, classes, styles and listeners; the structural style keys win.
  • className and style as a function of the state are your own bindings, reading the part's state() signal through exportAs (#part="gridLayoutItem", [class.held]="part.state().dragging"), or a data-* selector.
  • The recursion, and the parts present only at times, are template directives: <ng-template gridLayoutItems let-item>, *gridLayoutCells="let cell", *gridLayoutPlaceholder, *gridLayoutResizeHandle="'bottom-end'", *gridLayoutDragPreview.
  • Callbacks are outputs ((layoutChange), (dragStart), (dropped), …); [(layout)] binds the layout both ways, once per committed change.
  • Hooks are injection functions that return signals (injectGridLayout(), injectItems(), …); a part's function (injectItem()) gives the enclosing directive's { state }.
Unstyled
Gallery