@vuu-ui/grid-layout 4.0.0-alpha.1

package/types/GridGeometry.d.ts

@@ -0,0 +1,331 @@
+import type { GridItemId, GridItemResizeable, GridTrackSize } from "./GridSnapshot";
+/**
+ * Pure, immutable grid geometry.
+ *
+ * This module owns every geometry and track transition algorithm used by the
+ * grid layout. It is deliberately free of DOM, React, EventEmitter and mutable
+ * model dependencies; all browser/runtime measurement enters through the
+ * explicit, immutable {@link TrackMetrics} input.
+ *
+ * Callers read an immutable {@link GridGeometry} plus {@link TrackMetrics} from
+ * whatever runtime representation they own, invoke a transition, then hydrate
+ * the result back into that representation.
+ */
+export type GridGeometryTrackType = "column" | "row";
+export type GridGeometryItemType = "content" | "placeholder" | "splitter" | "stacked-content";
+export type GridGeometrySplitDirection = "north" | "south" | "east" | "west";
+export type GridGeometryResizeDirection = "horizontal" | "vertical";
+export type GridGeometryAssignDirection = "bwd" | "fwd";
+export type GridGeometryRemoveReason = "drag" | "close" | "placeholder" | "unstack";
+export type GridGeometryTrackInsertPosition = "after" | "before";
+export interface GridGeometrySpan {
+    readonly end: number;
+    readonly start: number;
+}
+export interface GridGeometryItem {
+    readonly column: GridGeometrySpan;
+    readonly dragging?: boolean;
+    readonly id: GridItemId;
+    readonly resizeable?: GridItemResizeable;
+    readonly row: GridGeometrySpan;
+    readonly stackId?: string;
+    readonly type: GridGeometryItemType;
+}
+export interface GridGeometry {
+    readonly columns: readonly GridTrackSize[];
+    readonly items: readonly GridGeometryItem[];
+    readonly rows: readonly GridTrackSize[];
+}
+/**
+ * Explicit measurement input. `measured[i]` is the measured pixel size of
+ * track `i`, or -1 when that track has not been measured. Geometry functions
+ * never measure; when a transition needs a measurement it does not have, it
+ * fails with MEASUREMENT_REQUIRED and the caller re-measures and retries.
+ */
+export interface TrackMetrics {
+    readonly measured: readonly number[];
+}
+export declare const NO_TRACK_METRICS: TrackMetrics;
+export declare const trackMetrics: (measured: readonly number[]) => TrackMetrics;
+/** Measurement input for both track types. */
+export interface GridMeasurements {
+    readonly column?: TrackMetrics;
+    readonly row?: TrackMetrics;
+}
+export declare const NO_MEASUREMENTS: GridMeasurements;
+/**
+ * The immutable state of a single track: its css size, plus the measured
+ * pixel value carried alongside it (-1 when unmeasured).
+ */
+export interface GridGeometryTrack {
+    readonly measured: number;
+    readonly size: GridTrackSize;
+}
+/**
+ * The result of a track transition. `sources[i]` is the index of the track in
+ * the previous track list that new track `i` derives from, or -1 for a track
+ * that did not previously exist.
+ */
+export interface GridTrackTransition {
+    readonly sources: readonly number[];
+    readonly tracks: readonly GridGeometryTrack[];
+}
+export interface GridGeometryUpdate {
+    readonly column?: GridGeometrySpan;
+    readonly id: GridItemId;
+    readonly row?: GridGeometrySpan;
+}
+export interface GridGeometryRemoval {
+    readonly id: GridItemId;
+    readonly reason: GridGeometryRemoveReason;
+}
+export type GridGeometryErrorCode = "GEOMETRY_ERROR" | "INVALID_ITEM" | "INVALID_TARGET" | "ITEM_NOT_FOUND" | "MEASUREMENT_REQUIRED" | "NON_RESIZABLE" | "TRACK_NOT_FOUND";
+export interface GridGeometryError {
+    readonly code: GridGeometryErrorCode;
+    readonly message: string;
+    readonly trackType?: GridGeometryTrackType;
+}
+export type GridGeometryResult<T> = {
+    readonly ok: true;
+    readonly value: T;
+} | {
+    readonly error: GridGeometryError;
+    readonly ok: false;
+};
+export declare const isFractionTrackSize: (size: GridTrackSize) => boolean;
+export declare const isPixelTrackSize: (size: GridTrackSize) => boolean;
+export declare const readTracks: (sizes: readonly GridTrackSize[], metrics?: TrackMetrics) => readonly GridGeometryTrack[];
+export declare const trackSizes: (tracks: readonly GridGeometryTrack[]) => GridTrackSize[];
+export declare const geometryTracks: (geometry: GridGeometry, trackType: GridGeometryTrackType) => readonly GridTrackSize[];
+/** Split a single track into two equally sized tracks. */
+export declare const splitTrack: (tracks: readonly GridGeometryTrack[], trackIndex: number, trackType: GridGeometryTrackType) => GridGeometryResult<GridTrackTransition>;
+/**
+ * Find an existing grid line that exactly bisects the given track range,
+ * returning -1 when the range cannot be bisected by an existing line.
+ */
+export declare const findBisectingTrack: (tracks: readonly GridGeometryTrack[], startIndex: number, endIndex: number, trackType: GridGeometryTrackType) => GridGeometryResult<number>;
+export interface GridTrackBisection {
+    readonly newTrackIndex: number;
+    readonly transition: GridTrackTransition;
+}
+/**
+ * Create a new grid line that bisects the tracks between two grid lines.
+ */
+export declare const bisectTracks: (tracks: readonly GridGeometryTrack[], fromTrackLine: number, toTrackLine: number, trackType: GridGeometryTrackType) => GridGeometryResult<GridTrackBisection>;
+/**
+ * Insert a new pixel track, reducing the track it displaces by the same
+ * amount. The insertion is a no-op when there is no track to reduce.
+ */
+export declare const insertTrack: (tracks: readonly GridGeometryTrack[], { index, position, }: {
+    index: number;
+    position: GridGeometryTrackInsertPosition;
+}, size: number, trackType: GridGeometryTrackType) => GridGeometryResult<GridTrackTransition | undefined>;
+/**
+ * Remove a track, assigning its size to the adjacent (contra) track.
+ */
+export declare const removeTrack: (tracks: readonly GridGeometryTrack[], index: number, assignDirection?: GridGeometryAssignDirection, trackType?: GridGeometryTrackType) => GridGeometryResult<GridTrackTransition>;
+/** Set an explicit size for a single track. */
+export declare const resizeTrackTo: (tracks: readonly GridGeometryTrack[], trackIndex: number, size: GridTrackSize, trackType?: GridGeometryTrackType) => GridGeometryResult<GridTrackTransition>;
+/** Grow one track by `value`, shrinking its contra track by the same amount. */
+export declare const resizeTracksAdjacent: (tracks: readonly GridGeometryTrack[], { contraTrackIndex, delta, resizedTrackIndex, }: {
+    contraTrackIndex: number;
+    delta: number;
+    resizedTrackIndex: number;
+}, trackType: GridGeometryTrackType) => GridGeometryResult<GridTrackTransition>;
+export interface GridGeometryResizeConstraint {
+    readonly minimum: number;
+    readonly trackIndices: readonly number[];
+}
+export interface GridProportionalResize {
+    readonly afterConstraints?: readonly GridGeometryResizeConstraint[];
+    readonly afterTrackIndices: readonly number[];
+    readonly beforeConstraints?: readonly GridGeometryResizeConstraint[];
+    readonly beforeTrackIndices: readonly number[];
+    readonly delta: number;
+    readonly initialSizes?: readonly number[];
+}
+/**
+ * The total reduction that a group of tracks can absorb without violating
+ * its minimum size constraints.
+ */
+export declare const getProportionalResizeAllowance: (tracks: readonly GridGeometryTrack[], trackIndices: readonly number[], constraints: readonly GridGeometryResizeConstraint[], trackType: GridGeometryTrackType) => GridGeometryResult<number>;
+/**
+ * Move a boundary between two groups of tracks, distributing the change across
+ * each group in proportion to current track sizes and honouring the minimum
+ * size constraints declared for each group.
+ */
+export declare const resizeTracksProportionally: (tracks: readonly GridGeometryTrack[], { afterConstraints, afterTrackIndices, beforeConstraints, beforeTrackIndices, delta, initialSizes, }: GridProportionalResize, trackType: GridGeometryTrackType) => GridGeometryResult<GridTrackTransition>;
+export declare const findGeometryItem: (geometry: GridGeometry, itemId: GridItemId) => GridGeometryItem | undefined;
+/**
+ * Apply position updates to a geometry, returning a new geometry. Updates
+ * applied to a stacked-content item are propagated to its stacked members,
+ * matching the way the legacy model applies child positions.
+ */
+export declare const applyGeometryUpdates: (geometry: GridGeometry, updates: readonly GridGeometryUpdate[]) => GridGeometry;
+export declare const isFixedHeightItem: ({ resizeable }: GridGeometryItem) => boolean;
+export declare const isFixedWidthItem: ({ resizeable }: GridGeometryItem) => boolean;
+export declare const canSplitGridItem: (item: GridGeometryItem, splitDirection: GridGeometrySplitDirection) => boolean;
+export declare const gridResizeDirectionForSplit: (splitDirection: GridGeometrySplitDirection) => GridGeometryResizeDirection;
+export declare const itemsFillColumn: (items: readonly GridGeometryItem[], pos: GridGeometrySpan) => boolean;
+export declare const itemsFillRow: (items: readonly GridGeometryItem[], pos: GridGeometrySpan) => boolean;
+/**
+ * Split a grid area in two along a grid line, returning the position of the
+ * dropped item followed by the position of the split target.
+ */
+export declare const splitGridChildPosition: ({ column, row }: {
+    column: GridGeometrySpan;
+    row: GridGeometrySpan;
+}, splitDirection: GridGeometrySplitDirection, splitTrackIndex: number) => [{
+    column: GridGeometrySpan;
+    row: GridGeometrySpan;
+}, {
+    column: GridGeometrySpan;
+    row: GridGeometrySpan;
+}];
+export interface GridGeometryTransition {
+    readonly columns?: GridTrackTransition;
+    readonly rows?: GridTrackTransition;
+    /** updates applied to the model without notifying position listeners */
+    readonly silentUpdates: readonly GridGeometryUpdate[];
+    /** the geometry that results from applying this transition */
+    readonly geometry: GridGeometry;
+    /** updates applied to the model and broadcast to position listeners */
+    readonly updates: readonly GridGeometryUpdate[];
+}
+/**
+ * Shift items to accommodate a track that has been inserted at `trackIndex`.
+ */
+export declare const shiftItemsForNewTrack: (items: readonly GridGeometryItem[], trackType: GridGeometryTrackType, trackIndex: number) => GridGeometryUpdate[];
+export interface GridSplitItemRequest {
+    readonly droppedItemId: GridItemId;
+    readonly resizeDirection?: GridGeometryResizeDirection;
+    readonly splitDirection: GridGeometrySplitDirection;
+    readonly targetItemId: GridItemId;
+}
+/**
+ * A dragged item has been dropped on a (NESW) quadrant of a target item.
+ * Split the target, adding or reusing a grid line as required.
+ */
+export declare const splitGridItem: (geometry: GridGeometry, { droppedItemId, resizeDirection, splitDirection, targetItemId, }: GridSplitItemRequest, measurements?: GridMeasurements) => GridGeometryResult<GridGeometryTransition>;
+export interface GridReplaceItemRequest {
+    readonly droppedItemId: GridItemId;
+    readonly targetItemId: GridItemId;
+}
+export interface GridReplaceItemTransition extends GridGeometryTransition {
+    readonly removals: readonly GridGeometryRemoval[];
+}
+/**
+ * A dragged item has been dropped on the centre of a target item; the dropped
+ * item takes over the target's grid area and the target is removed.
+ */
+export declare const replaceGridItem: (geometry: GridGeometry, { droppedItemId, targetItemId }: GridReplaceItemRequest) => GridGeometryResult<GridReplaceItemTransition>;
+/**
+ * Identify grid lines that no longer serve as the start of one item and the
+ * end of another, and which can therefore be removed.
+ */
+export declare const findUnusedGridLines: (geometry: GridGeometry) => readonly [number[], number[]];
+/**
+ * Shift items to accommodate a track inserted at `index`. The insert position
+ * describes which of the two neighbouring tracks the new track overlaps.
+ */
+export declare const shiftItemsForInsertedTrack: (items: readonly GridGeometryItem[], trackType: GridGeometryTrackType, index: number, position: GridGeometryTrackInsertPosition) => GridGeometryUpdate[];
+/**
+ * When a grid line is removed, every item bound to a line beyond it must be
+ * rebound one line lower.
+ */
+export declare const shiftItemsForRemovedTrack: (items: readonly GridGeometryItem[], trackType: GridGeometryTrackType, trackIndex: number) => GridGeometryUpdate[];
+export interface GridRemoveItemRequest {
+    readonly itemId: GridItemId;
+    readonly reason: GridGeometryRemoveReason;
+}
+export interface GridRemoveItemTransition extends GridGeometryTransition {
+    /** true when listeners are notified of the position updates */
+    readonly notify: boolean;
+    readonly placeholders?: {
+        readonly added: readonly GridGeometryItem[];
+        readonly removedIds: readonly GridItemId[];
+    };
+    readonly removals: readonly GridGeometryRemoval[];
+    /** true when the removed item was a member of a stack */
+    readonly stackMember: boolean;
+}
+/**
+ * Remove an item, extending contra items to occupy the space it leaves,
+ * normalizing tracks that are no longer referenced and regenerating
+ * placeholders for any space that remains empty.
+ */
+export declare const removeGridItem: (geometry: GridGeometry, { itemId, reason }: GridRemoveItemRequest, { createPlaceholderId, measurements, }: {
+    createPlaceholderId: () => string;
+    measurements?: GridMeasurements;
+}) => GridGeometryResult<GridRemoveItemTransition>;
+export interface GridPlaceholderTransition {
+    readonly added: readonly GridGeometryItem[];
+    readonly geometry: GridGeometry;
+    readonly removedIds: readonly GridItemId[];
+}
+/**
+ * Build the occupancy matrix for a set of items.
+ */
+export declare const getGridMatrix: (items: readonly GridGeometryItem[], rowCount: number, colCount: number) => number[][];
+/**
+ * Placeholders represent every empty area of the grid. They are regenerated
+ * from scratch, so existing placeholders are always replaced.
+ */
+export declare const regeneratePlaceholders: (geometry: GridGeometry, createPlaceholderId: () => string) => GridPlaceholderTransition;
+export interface GridGeometrySplitter {
+    readonly align: "start" | "end";
+    readonly ariaOrientation: "horizontal" | "vertical";
+    readonly column: GridGeometrySpan;
+    readonly controls: string;
+    readonly id: string;
+    readonly orientation: GridGeometryResizeDirection;
+    readonly resizedChildItems: {
+        readonly after: string[];
+        readonly before: string[];
+    };
+    readonly resizedGridTracks: [number, number];
+    readonly row: GridGeometrySpan;
+}
+export interface GridSplitterGeometry {
+    readonly horizontalSplitterItemIds: readonly GridItemId[];
+    readonly splitters: readonly GridGeometrySplitter[];
+    readonly verticalSplitterItemIds: readonly GridItemId[];
+}
+/**
+ * Compute the splitters for a grid, together with the items that carry a
+ * horizontal or vertical splitter.
+ */
+export declare const computeSplitters: (geometry: GridGeometry) => GridSplitterGeometry;
+/**
+ * Resize requires a new track if the splitter being used for the resize sits
+ * on the same track edge as another splitter.
+ */
+export declare const doesResizeRequireNewTrack: (splitters: readonly GridGeometrySplitter[], splitter: GridGeometrySplitter) => boolean;
+export interface GridInsertTrackRequest {
+    readonly contraItemIds: readonly GridItemId[];
+    readonly index: number;
+    readonly position: GridGeometryTrackInsertPosition;
+    readonly resizeItemIds: readonly GridItemId[];
+    readonly size: number;
+    readonly trackType: GridGeometryTrackType;
+}
+export interface GridInsertTrackTransition {
+    readonly anchorUpdates: readonly GridGeometryUpdate[];
+    readonly columns?: GridTrackTransition;
+    readonly geometry: GridGeometry;
+    readonly insertUpdates: readonly GridGeometryUpdate[];
+    readonly rows?: GridTrackTransition;
+}
+/**
+ * Insert a new grid line so that an item sharing a track edge with other items
+ * can be resized independently, and anchor the resized/contra items to it.
+ */
+export declare const insertTrackForResize: (geometry: GridGeometry, { contraItemIds, index, position, resizeItemIds, size, trackType, }: GridInsertTrackRequest, measurements?: GridMeasurements) => GridGeometryResult<GridInsertTrackTransition>;
+export interface GridRemoveTrackRequest {
+    readonly assignDirection?: GridGeometryAssignDirection;
+    readonly trackIndex: number;
+    readonly trackType: GridGeometryTrackType;
+    readonly updateItems?: boolean;
+}
+/** Remove a grid track, rebinding items bound to lines beyond it. */
+export declare const removeGridTrack: (geometry: GridGeometry, { assignDirection, trackIndex, trackType, updateItems, }: GridRemoveTrackRequest, measurements?: GridMeasurements) => GridGeometryResult<GridGeometryTransition>;

package/types/GridLayout.d.ts

@@ -0,0 +1,20 @@
+import { type HTMLAttributes, type ReactElement, type ReactNode } from "react";
+import type { GridLayoutItemProps } from "./GridLayoutItem";
+import type { GridColumnsAndRows, GridLayoutChangeHandler } from "./GridModel";
+export type GridResizeable = "h" | "v" | "hv";
+export type GridResizeDistribution = "adjacent" | "proportional";
+export interface GridLayoutProps extends Omit<HTMLAttributes<HTMLDivElement>, "onChange"> {
+    children?: ReactElement<GridLayoutItemProps> | ReactElement<GridLayoutItemProps>[];
+    "full-page"?: boolean;
+    colsAndRows?: GridColumnsAndRows;
+    /** @deprecated Use GridLayoutProvider onDocumentChange. */
+    onChange?: GridLayoutChangeHandler;
+    /** Content rendered inside canonical placeholders without obscuring their drop target. */
+    placeholderContent?: ReactNode;
+    /** Coupled boundaries with partial cross-group spans retain adjacent resizing. */
+    rowResizeDistribution?: GridResizeDistribution;
+}
+export declare function GridLayout({ id: idProp, children: childrenProp, className, "full-page": fullPage, colsAndRows, onClick, onChange, placeholderContent, rowResizeDistribution, style: styleProp, ...htmlAttributes }: GridLayoutProps): import("react").JSX.Element;
+export declare namespace GridLayout {
+    var displayName: string;
+}

package/types/GridLayoutContext.d.ts

@@ -0,0 +1,141 @@
+import { type Dispatch, type DragEvent } from "react";
+import type { GridLayoutDragEndHandler } from "./GridLayoutProvider";
+import type { GridModel, TabStateTab, TrackSize } from "./GridModel";
+import type { GridLayoutDragStartHandler } from "./useDraggable";
+import type { GridLayoutModel } from "./GridLayoutModel";
+import type { GridLayoutDropPosition } from "@vuu-ui/vuu-utils";
+import type { GridController } from "./GridController";
+import type { GridSnapshot } from "./GridSnapshot";
+import type { JsonValue } from "./json-value";
+export type GridLayoutActionType = "close";
+export type GridLayoutCloseAction = {
+    type: "close";
+    id: string;
+};
+export type GridLayoutRenameTabAction = {
+    type: "rename-tab";
+    id: string;
+    title: string;
+};
+export type GridLayoutAddTabbedChildAction = {
+    title: string;
+    type: "add-tabbed-child";
+    componentTemplate: ComponentTemplate;
+    stackId: string;
+};
+export type GridLayoutSwitchTabAction = {
+    type: "switch-tab";
+    fromId: string;
+    toId: string;
+};
+export type GridLayoutSelectTabAction = {
+    type: "select-tab";
+    itemId: string;
+    stackId: string;
+};
+export type GridLayoutTrackAction = {
+    type: "resize-grid-column" | "resize-grid-row";
+    trackIndex: number;
+    value: TrackSize;
+};
+export type GridLayoutAction = GridLayoutCloseAction | GridLayoutAddTabbedChildAction | GridLayoutSwitchTabAction | GridLayoutSelectTabAction | GridLayoutTrackAction | GridLayoutRenameTabAction;
+export type GridLayoutDispatch = Dispatch<GridLayoutAction>;
+/**
+ * provides details of a dragged component within a stack
+ */
+export interface TabbedComponentDragSource {
+    element: HTMLElement;
+    isSelectedTab: boolean;
+    label: string;
+    layoutId: string;
+    tab: TabStateTab;
+    /** deprecated */
+    tabIndex: number;
+    tabsId: string;
+    type: "tabbed-component";
+}
+/**
+ * provides details of a dragged component
+ */
+export interface ComponentDragSource {
+    element: HTMLElement;
+    dragElement?: HTMLElement;
+    id: string;
+    label: string;
+    layoutId: string;
+    type: "component";
+}
+export interface TypedComponentTemplate {
+    readonly component: {
+        readonly settings: JsonValue;
+        readonly type: string;
+        readonly version: number;
+    };
+    /**
+     * Can the component act as a drop target. Note: false does not
+     * preclude children of the component from acting as drop targets.
+     */
+    readonly dropTarget?: boolean;
+    /** Primarily intended for display in a palette. */
+    readonly label: string;
+}
+/** @deprecated Use TypedComponentTemplate. */
+export interface LegacyComponentTemplate {
+    /**
+     * Stringified JSON - the serialized layoutJSON from which
+     * component can be reconstituted
+     */
+    componentJson: string;
+    /**
+     * Can the component act as a drop target. Note: false does not
+     * preclude children of the component from acting as drop targets.
+     */
+    dropTarget?: boolean;
+    /**
+     * Primarily intended for display in Palette etc.
+     */
+    label: string;
+}
+export type ComponentTemplate = TypedComponentTemplate | LegacyComponentTemplate;
+export type ComponentTemplateWithoutLabel = Omit<TypedComponentTemplate, "label"> | Omit<LegacyComponentTemplate, "label">;
+export declare const isTypedComponentTemplate: (template: ComponentTemplate) => template is TypedComponentTemplate;
+/**
+ * provides details of a template, to be used on drop to instantiate  a new component
+ */
+export type TemplateSource = ComponentTemplate & {
+    element: HTMLElement;
+    layoutId: string;
+    type: "template";
+};
+export type DragSourceProvider = (evt: DragEvent<Element>) => DragSource;
+export type DragSource = ComponentDragSource | TemplateSource | TabbedComponentDragSource;
+export declare const sourceIsComponent: (source: DragSource | undefined) => source is ComponentDragSource;
+export declare const sourceIsTabbedComponent: (source: DragSource | undefined) => source is TabbedComponentDragSource;
+export declare const sourceIsTemplate: (source: DragSource | undefined) => source is TemplateSource;
+export type GridLayoutDropHandler = (targetId: string, dragSource: DragSource, position: GridLayoutDropPosition) => boolean;
+export type GridLayoutDragLeaveHandler = () => void;
+export interface GridLayoutContextProps {
+    dispatchGridLayoutAction: GridLayoutDispatch;
+    gridController?: GridController;
+    gridLayoutModel?: GridLayoutModel;
+    gridModel?: GridModel;
+    gridSnapshot?: GridSnapshot;
+    id: string;
+    onDragEnd?: GridLayoutDragEndHandler;
+    onDragLeave: GridLayoutDragLeaveHandler;
+    onDragPreview: GridLayoutDropHandler;
+    onDragStart: GridLayoutDragStartHandler;
+    onDrop: GridLayoutDropHandler;
+}
+export declare const GridLayoutContext: import("react").Context<GridLayoutContextProps>;
+export declare const useGridLayoutDispatch: () => GridLayoutDispatch;
+export declare const useGridLayoutDropHandler: () => GridLayoutDropHandler;
+export declare const useGridLayoutDragPreviewHandler: () => GridLayoutDropHandler;
+export declare const useGridLayoutDragLeaveHandler: () => GridLayoutDragLeaveHandler;
+export declare const useGridLayoutDragEndHandler: () => GridLayoutDragEndHandler | undefined;
+export declare const useGridLayoutDragStartHandler: () => GridLayoutDragStartHandler;
+/** @deprecated Mutable GridModel is an internal compatibility engine. */
+export declare const useGridModel: () => GridModel;
+export declare const useGridController: () => GridController;
+export declare const useGridSnapshot: () => GridSnapshot;
+export declare const useGridLayoutId: () => string;

package/types/GridLayoutDocument.d.ts

@@ -0,0 +1,61 @@
+import type { DecodedGridComponentSettings, EncodedGridComponentSettings, GridComponentSettingsError, GridComponentSettingsInput, GridComponentSettingsRegistry } from "./GridComponentSettings";
+import type { GridItemSnapshot, GridSnapshot, GridStackSnapshot } from "./GridSnapshot";
+export declare const GRID_LAYOUT_DOCUMENT_KIND = "grid-layout";
+export declare const GRID_LAYOUT_DOCUMENT_VERSION = 2;
+export interface PersistedGridLayout {
+    readonly columns: readonly string[];
+    readonly id: string;
+    readonly items: readonly GridItemSnapshot[];
+    readonly placeholderIds: readonly string[];
+    readonly rows: readonly string[];
+    readonly stacks: readonly GridStackSnapshot[];
+}
+export interface GridLayoutDocument {
+    readonly components: readonly EncodedGridComponentSettings[];
+    readonly kind: typeof GRID_LAYOUT_DOCUMENT_KIND;
+    readonly layout: PersistedGridLayout;
+    readonly version: typeof GRID_LAYOUT_DOCUMENT_VERSION;
+}
+export declare const immutableGridLayoutDocument: (document: GridLayoutDocument) => GridLayoutDocument;
+export interface GridLayoutDocumentV1 {
+    readonly components: readonly EncodedGridComponentSettings[];
+    readonly kind: typeof GRID_LAYOUT_DOCUMENT_KIND;
+    readonly layout: {
+        readonly columns: readonly string[];
+        readonly gridId: string;
+        readonly items: readonly GridItemSnapshot[];
+        readonly rows: readonly string[];
+        readonly stacks?: readonly GridStackSnapshot[];
+    };
+    readonly version: 1;
+}
+export interface DecodedGridLayoutDocument {
+    readonly components: readonly DecodedGridComponentSettings[];
+    readonly document: GridLayoutDocument;
+    readonly snapshot: GridSnapshot;
+}
+export type GridLayoutDocumentErrorCode = "COMPONENT_SETTINGS_ERROR" | "COMPONENT_RENDERER_ERROR" | "DOCUMENT_MIGRATION_FAILED" | "DUPLICATE_COMPONENT_ID" | "INVALID_DISCRIMINATOR" | "INVALID_DOCUMENT" | "MISSING_COMPONENT_SETTINGS" | "UNEXPECTED_COMPONENT_SETTINGS" | "UNSUPPORTED_DOCUMENT_VERSION";
+export interface GridLayoutDocumentError {
+    readonly code: GridLayoutDocumentErrorCode;
+    readonly componentError?: GridComponentSettingsError;
+    readonly message: string;
+    readonly path: string;
+    readonly version?: number;
+}
+export declare class GridLayoutDocumentCodecError extends Error {
+    readonly issue: GridLayoutDocumentError;
+    constructor(issue: GridLayoutDocumentError);
+}
+export type GridLayoutDocumentResult<T> = {
+    readonly ok: true;
+    readonly value: T;
+} | {
+    readonly error: GridLayoutDocumentError;
+    readonly ok: false;
+};
+export interface EncodeGridLayoutDocumentOptions {
+    readonly componentSettings: readonly GridComponentSettingsInput[];
+    readonly placeholderIds?: readonly string[];
+}
+export declare const encodeGridLayoutDocument: (snapshot: GridSnapshot, registry: GridComponentSettingsRegistry, { componentSettings, placeholderIds }: EncodeGridLayoutDocumentOptions) => GridLayoutDocumentResult<GridLayoutDocument>;
+export declare const decodeGridLayoutDocument: (input: unknown, registry: GridComponentSettingsRegistry) => GridLayoutDocumentResult<DecodedGridLayoutDocument>;

package/types/GridLayoutDocumentIds.d.ts

@@ -0,0 +1,15 @@
+import { type GridLayoutDocument } from "./GridLayoutDocument";
+export type GridLayoutIdKind = "component" | "grid" | "item" | "stack";
+export interface GridLayoutIdRemapping {
+    readonly kind: GridLayoutIdKind;
+    readonly newId: string;
+    readonly oldId: string;
+    readonly path: string;
+}
+export type GridLayoutIdAllocator = (kind: GridLayoutIdKind, oldId: string, path: string) => string;
+export interface RemappedGridLayoutDocument {
+    readonly document: GridLayoutDocument;
+    readonly mappings: readonly GridLayoutIdRemapping[];
+}
+export declare const createSequentialGridLayoutIdAllocator: (prefix?: string) => GridLayoutIdAllocator;
+export declare const remapGridLayoutDocumentIds: (source: GridLayoutDocument, allocate: GridLayoutIdAllocator) => RemappedGridLayoutDocument;

package/types/GridLayoutItem.d.ts

@@ -0,0 +1,28 @@
+import { type HTMLAttributes, type ReactElement } from "react";
+import { type LayoutJSON } from "./componentToJson";
+import { type GridChildItemStyle, type GridModelChildItemProps } from "./GridModel";
+export interface GridLayoutItemProps extends Omit<GridModelChildItemProps, "contentDetached" | "style" | "type">, Omit<HTMLAttributes<HTMLDivElement>, "id" | "onDragStart" | "onDrop" | "style"> {
+    "data-drop-target"?: boolean | string;
+    header?: boolean;
+    /**
+     * If provided, component is fixed height
+     */
+    height?: number;
+    label?: string;
+    /**
+     * style.gridArea is optional only if stackId is provided and a separate declaration
+     * of a GridLayoutStackedItem child is included within GridLayout
+     */
+    style?: GridChildItemStyle;
+    /**
+     * If provided, component is fixed width
+     */
+    width?: number;
+}
+export declare function GridLayoutItem({ children, className: classNameProp, contentVisible: contentVisibleProp, "data-drop-target": dataDropTarget, header: headerProp, height, id, minHeight, minWidth, stackId, resizeable, style: styleProp, title: titleProp, width, ...htmlAttributes }: GridLayoutItemProps): import("react").JSX.Element | null;
+export declare namespace GridLayoutItem {
+    var toJSON: (element: ReactElement<GridLayoutItemProps, typeof GridLayoutItemType>) => LayoutJSON<object>;
+}
+declare const GridLayoutItemType: import("react").FunctionComponent<GridLayoutItemProps>;
+export declare const isGridLayoutItem: (element: ReactElement) => boolean;
+export {};

package/types/GridLayoutLegacyCompatibility.d.ts

@@ -0,0 +1,57 @@
+import type { ReactElement } from "react";
+import type { LayoutJSON } from "./componentToJson";
+import { type GridLayoutItemProps } from "./GridLayoutItem";
+import type { GridLayoutDescriptor } from "./GridModel";
+import type { GridSnapshot } from "./GridSnapshot";
+export type LegacySerializedComponentMap = Record<string, LayoutJSON>;
+/**
+ * Pre-v2 GridLayout persistence envelope.
+ *
+ * @deprecated Read existing data with this type, then save a GridLayoutDocument.
+ */
+export type SerializedGridLayout = {
+    components: LegacySerializedComponentMap;
+    id: string;
+    layout: GridLayoutDescriptor;
+};
+export type LegacyDeserializedGridLayout = {
+    components: Record<string, ReactElement<GridLayoutItemProps>>;
+    id: string;
+    layout: GridLayoutDescriptor;
+    placeholderIds?: readonly string[];
+};
+export interface LegacyGridLayoutDocument {
+    readonly components: LegacySerializedComponentMap;
+    readonly snapshot: GridSnapshot;
+}
+export type LegacyGridLayoutDecodeResult = {
+    readonly ok: true;
+    readonly value: LegacyGridLayoutDocument;
+} | {
+    readonly error: {
+        readonly code: "INVALID_LEGACY_GRID_LAYOUT";
+        readonly message: string;
+        readonly path: string;
+        readonly version: 1;
+    };
+    readonly ok: false;
+};
+/**
+ * Validates and adapts the descriptor portion of a pre-v2 persistence value.
+ * It deliberately does not produce a writable v2 document because legacy
+ * component props are not typed component settings.
+ *
+ * @deprecated Use decodeGridLayoutDocument for all new persistence.
+ */
+export declare const decodeLegacySerializedGridLayout: (value: SerializedGridLayout) => LegacyGridLayoutDecodeResult;
+export interface LegacyGridLayoutReader {
+    getSavedGrid(id: string): LegacyDeserializedGridLayout | undefined;
+}
+/**
+ * Creates the narrow, read-only React compatibility boundary used by the
+ * deprecated provider input. No mutations are written back to the legacy
+ * descriptor or generic React-prop component map.
+ */
+export declare const createLegacyGridLayoutReader: (serializedLayout: SerializedGridLayout) => LegacyGridLayoutReader;
+/** @deprecated Legacy component JSON may contain React-derived props. */
+export type LegacyGridLayoutComponentJson = LayoutJSON;