@wordpress/widget-dashboard 0.1.0

package/build-types/context/dashboard-context.d.ts

@@ -0,0 +1,111 @@
+import type { ReactNode } from 'react';
+import type { ResolveWidgetModule, WidgetType } from '@wordpress/widget-primitives';
+import type { WidgetGridModel, WidgetGridSettings, DashboardWidget } from '../types';
+type GridSettingsWithColumns = WidgetGridSettings & {
+    columns: number;
+};
+/**
+ * Rich state distributed to every compound component inside `WidgetDashboard`.
+ * Internal — compounds reach the full state via `useDashboardInternalContext()`.
+ *
+ * `layout`/`onLayoutChange` and `gridSettings`/`onGridSettingsChange` here
+ * operate on the staging layer, not the committed props. Mutations from
+ * compound children stay in staging until `commit` publishes them on the
+ * consumer.
+ */
+interface InternalDashboardContextValue {
+    widgetTypes: WidgetType[];
+    isResolvingWidgetTypes: boolean;
+    layout: DashboardWidget[];
+    onLayoutChange: (layout: DashboardWidget[]) => void;
+    onLayoutReset?: () => void;
+    gridSettings: GridSettingsWithColumns;
+    onGridSettingsChange: (gridSettings: WidgetGridSettings) => void;
+    canEditGridSettings: boolean;
+    /**
+     * Restores the staging copy of `gridSettings` to the package's
+     * built-in defaults. Does not touch the committed slice; the user
+     * must `commit` to publish the reset, or `cancel` to discard it.
+     */
+    resetGridSettings: () => void;
+    /**
+     * Publishes staged slices that differ from their committed
+     * counterparts. By default also exits edit mode; pass
+     * `{ exitEditMode: false }` when committing from the layout
+     * settings drawer so customize mode stays active.
+     */
+    commit: (options?: CommitOptions) => void;
+    /**
+     * Switches the layout model, updates staging, and publishes
+     * immediately — equivalent to changing the model in layout
+     * settings and clicking Save.
+     */
+    commitGridModelChange: (targetModel: WidgetGridModel) => void;
+    /**
+     * Reverts staging slices. By default reverts both layout and grid
+     * settings and exits edit mode. Pass `{ exitEditMode: false }` when
+     * dismissing the layout settings drawer. Pass `{ revertLayout: false }`
+     * to revert only grid settings (preserves in-progress widget layout
+     * edits while customize mode is active).
+     */
+    cancel: (options?: CancelOptions) => void;
+    hasUncommittedChanges: boolean;
+    editMode: boolean;
+    onEditChange?: (next: boolean) => void;
+    resolveWidgetModule: ResolveWidgetModule;
+}
+interface CommitOptions {
+    exitEditMode?: boolean;
+}
+interface CancelOptions {
+    exitEditMode?: boolean;
+    revertLayout?: boolean;
+}
+/**
+ * Compound-internal hook — exposes the full provider state.
+ * Not part of the public API; lives in the same module
+ * so compound components can reach the state directly.
+ */
+export declare function useDashboardInternalContext(): InternalDashboardContextValue;
+interface ProviderProps {
+    widgetTypes: WidgetType[];
+    isResolvingWidgetTypes?: boolean;
+    layout: DashboardWidget[];
+    /**
+     * Fired on commit when the staged layout differs from `layout`.
+     */
+    onLayoutChange: (layout: DashboardWidget[]) => void;
+    /**
+     * Optional reset action surfaced by the bundled `Actions`.
+     */
+    onLayoutReset?: () => void;
+    editMode?: boolean;
+    onEditChange?: (next: boolean) => void;
+    /**
+     * Overrides the default `import()` resolution of
+     * `WidgetType.renderModule`.
+     */
+    resolveWidgetModule?: ResolveWidgetModule;
+    gridSettings?: WidgetGridSettings;
+    /**
+     * Fired on commit when the staged settings differ from
+     * `gridSettings`.
+     */
+    onGridSettingsChange?: (gridSettings: WidgetGridSettings) => void;
+    children: ReactNode;
+}
+/**
+ * Provider for the dashboard's staging layer. Owns staging copies of
+ * `layout` and `gridSettings`; `commit` publishes whichever slice
+ * differs from its committed prop, `cancel` reverts both.
+ *
+ * Staging re-syncs from the committed props on prop change. In-flight
+ * edits are dropped silently when an external update (cross-tab commit,
+ * reset, websocket push) lands. Consumers that cannot tolerate this
+ * loss should mediate the prop updates before forwarding them here.
+ *
+ * @param {ProviderProps} props Component props.
+ */
+export declare function WidgetDashboardProvider({ widgetTypes, isResolvingWidgetTypes, layout: committedLayout, onLayoutChange, onLayoutReset, editMode, onEditChange, resolveWidgetModule, gridSettings: committedGridSettings, onGridSettingsChange, children }: ProviderProps): React.ReactNode;
+export {};
+//# sourceMappingURL=dashboard-context.d.ts.map

package/build-types/context/dashboard-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dashboard-context.d.ts","sourceRoot":"","sources":["../../src/context/dashboard-context.tsx"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAavC,OAAO,KAAK,EACX,mBAAmB,EACnB,UAAU,EACV,MAAM,8BAA8B,CAAC;AAStC,OAAO,KAAK,EACX,eAAe,EACf,kBAAkB,EAClB,eAAe,EACf,MAAM,UAAU,CAAC;AAGlB,KAAK,uBAAuB,GAAG,kBAAkB,GAAG;IAAE,OAAO,EAAE,MAAM,CAAA;CAAE,CAAC;AA0CxE;;;;;;;;GAQG;AACH,UAAU,6BAA6B;IACtC,WAAW,EAAE,UAAU,EAAE,CAAC;IAC1B,sBAAsB,EAAE,OAAO,CAAC;IAChC,MAAM,EAAE,eAAe,EAAE,CAAC;IAC1B,cAAc,EAAE,CAAE,MAAM,EAAE,eAAe,EAAE,KAAM,IAAI,CAAC;IACtD,aAAa,CAAC,EAAE,MAAM,IAAI,CAAC;IAC3B,YAAY,EAAE,uBAAuB,CAAC;IACtC,oBAAoB,EAAE,CAAE,YAAY,EAAE,kBAAkB,KAAM,IAAI,CAAC;IACnE,mBAAmB,EAAE,OAAO,CAAC;IAE7B;;;;OAIG;IACH,iBAAiB,EAAE,MAAM,IAAI,CAAC;IAE9B;;;;;OAKG;IACH,MAAM,EAAE,CAAE,OAAO,CAAC,EAAE,aAAa,KAAM,IAAI,CAAC;IAE5C;;;;OAIG;IACH,qBAAqB,EAAE,CAAE,WAAW,EAAE,eAAe,KAAM,IAAI,CAAC;IAEhE;;;;;;OAMG;IACH,MAAM,EAAE,CAAE,OAAO,CAAC,EAAE,aAAa,KAAM,IAAI,CAAC;IAE5C,qBAAqB,EAAE,OAAO,CAAC;IAC/B,QAAQ,EAAE,OAAO,CAAC;IAClB,YAAY,CAAC,EAAE,CAAE,IAAI,EAAE,OAAO,KAAM,IAAI,CAAC;IACzC,mBAAmB,EAAE,mBAAmB,CAAC;CACzC;AAED,UAAU,aAAa;IACtB,YAAY,CAAC,EAAE,OAAO,CAAC;CACvB;AAED,UAAU,aAAa;IACtB,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,YAAY,CAAC,EAAE,OAAO,CAAC;CACvB;AAID;;;;GAIG;AACH,wBAAgB,2BAA2B,IAAI,6BAA6B,CAQ3E;AAED,UAAU,aAAa;IACtB,WAAW,EAAE,UAAU,EAAE,CAAC;IAC1B,sBAAsB,CAAC,EAAE,OAAO,CAAC;IACjC,MAAM,EAAE,eAAe,EAAE,CAAC;IAE1B;;OAEG;IACH,cAAc,EAAE,CAAE,MAAM,EAAE,eAAe,EAAE,KAAM,IAAI,CAAC;IAEtD;;OAEG;IACH,aAAa,CAAC,EAAE,MAAM,IAAI,CAAC;IAE3B,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,YAAY,CAAC,EAAE,CAAE,IAAI,EAAE,OAAO,KAAM,IAAI,CAAC;IAEzC;;;OAGG;IACH,mBAAmB,CAAC,EAAE,mBAAmB,CAAC;IAE1C,YAAY,CAAC,EAAE,kBAAkB,CAAC;IAElC;;;OAGG;IACH,oBAAoB,CAAC,EAAE,CAAE,YAAY,EAAE,kBAAkB,KAAM,IAAI,CAAC;IAEpE,QAAQ,EAAE,SAAS,CAAC;CACpB;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,uBAAuB,CAAE,EACxC,WAAW,EACX,sBAA8B,EAC9B,MAAM,EAAE,eAAe,EACvB,cAAc,EACd,aAAa,EACb,QAAgB,EAChB,YAAY,EACZ,mBAAmD,EACnD,YAAY,EAAE,qBAAoC,EAClD,oBAAoB,EACpB,QAAQ,EACR,EAAE,aAAa,GAAI,KAAK,CAAC,SAAS,CAsKlC"}

package/build-types/context/ui-context.d.ts

@@ -0,0 +1,54 @@
+/**
+ * External dependencies
+ */
+import type { ReactNode } from 'react';
+type DrawerSide = 'left' | 'right';
+interface DashboardUIContextValue {
+    inserterOpen: boolean;
+    setInserterOpen: (next: boolean) => void;
+    layoutSettingsOpen: boolean;
+    setLayoutSettingsOpen: (next: boolean) => void;
+    resetDialogOpen: boolean;
+    setResetDialogOpen: (next: boolean) => void;
+    /**
+     * `uuid` of the instance whose settings drawer is open, or `null`
+     * when no settings drawer is showing. The per-instance gear in the
+     * chrome sets it; the single `WidgetSettings` at the root reads
+     * it.
+     */
+    settingsWidgetUuid: string | null;
+    setSettingsWidgetUuid: (next: string | null) => void;
+    /**
+     * Edge the settings drawer slides in from. The gear sets it from the
+     * widget's on-screen position so the drawer opens on the side away
+     * from the widget, trying not to cover it.
+     */
+    settingsDrawerSide: DrawerSide;
+    setSettingsDrawerSide: (next: DrawerSide) => void;
+    /**
+     * Inline-start inset (px) the settings drawer is offset by when it
+     * opens from the left, so it clears fixed page chrome (the WordPress
+     * admin menu) instead of sliding over it. `0` when there's nothing to
+     * clear.
+     */
+    settingsDrawerInset: number;
+    setSettingsDrawerInset: (next: number) => void;
+}
+/**
+ * Accesses the shared UI state: overlay open flags and the active settings
+ * instance with its placement. Throws when called outside `WidgetDashboard`.
+ */
+export declare function useDashboardUIContext(): DashboardUIContextValue;
+interface ProviderProps {
+    children: ReactNode;
+}
+/**
+ * Holds transient UI state shared across compounds (the inserter modal and
+ * the per-instance settings drawer). Kept separate from the data context so
+ * that data mutations don't churn the UI state and vice-versa.
+ *
+ * @param {ProviderProps} props Component props.
+ */
+export declare function WidgetDashboardUIProvider({ children }: ProviderProps): import("react").JSX.Element;
+export {};
+//# sourceMappingURL=ui-context.d.ts.map

package/build-types/context/ui-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ui-context.d.ts","sourceRoot":"","sources":["../../src/context/ui-context.tsx"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAYvC,KAAK,UAAU,GAAG,MAAM,GAAG,OAAO,CAAC;AAEnC,UAAU,uBAAuB;IAChC,YAAY,EAAE,OAAO,CAAC;IACtB,eAAe,EAAE,CAAE,IAAI,EAAE,OAAO,KAAM,IAAI,CAAC;IAE3C,kBAAkB,EAAE,OAAO,CAAC;IAC5B,qBAAqB,EAAE,CAAE,IAAI,EAAE,OAAO,KAAM,IAAI,CAAC;IACjD,eAAe,EAAE,OAAO,CAAC;IACzB,kBAAkB,EAAE,CAAE,IAAI,EAAE,OAAO,KAAM,IAAI,CAAC;IAE9C;;;;;OAKG;IACH,kBAAkB,EAAE,MAAM,GAAG,IAAI,CAAC;IAClC,qBAAqB,EAAE,CAAE,IAAI,EAAE,MAAM,GAAG,IAAI,KAAM,IAAI,CAAC;IAEvD;;;;OAIG;IACH,kBAAkB,EAAE,UAAU,CAAC;IAC/B,qBAAqB,EAAE,CAAE,IAAI,EAAE,UAAU,KAAM,IAAI,CAAC;IAEpD;;;;;OAKG;IACH,mBAAmB,EAAE,MAAM,CAAC;IAC5B,sBAAsB,EAAE,CAAE,IAAI,EAAE,MAAM,KAAM,IAAI,CAAC;CACjD;AAID;;;GAGG;AACH,wBAAgB,qBAAqB,IAAI,uBAAuB,CAQ/D;AAED,UAAU,aAAa;IACtB,QAAQ,EAAE,SAAS,CAAC;CACpB;AAED;;;;;;GAMG;AACH,wBAAgB,yBAAyB,CAAE,EAAE,QAAQ,EAAE,EAAE,aAAa,+BAqCrE"}

package/build-types/context/widget-context.d.ts

@@ -0,0 +1,25 @@
+/**
+ * External dependencies
+ */
+import type { ReactNode } from 'react';
+/**
+ * Internal dependencies
+ */
+import type { WidgetContextValue } from '../types';
+interface ProviderProps {
+    value: WidgetContextValue;
+    children: ReactNode;
+}
+/**
+ * Provides the current widget's identity to its render subtree.
+ *
+ * @param {ProviderProps} props Component props.
+ */
+export declare function WidgetContextProvider({ value, children }: ProviderProps): React.ReactNode;
+/**
+ * Returns the current widget's identity (`uuid`, `name`, `index`). Returns
+ * `null` when called outside a widget render subtree.
+ */
+export declare function useWidgetContext(): WidgetContextValue | null;
+export {};
+//# sourceMappingURL=widget-context.d.ts.map

package/build-types/context/widget-context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"widget-context.d.ts","sourceRoot":"","sources":["../../src/context/widget-context.tsx"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAOvC;;GAEG;AACH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,UAAU,CAAC;AAInD,UAAU,aAAa;IACtB,KAAK,EAAE,kBAAkB,CAAC;IAC1B,QAAQ,EAAE,SAAS,CAAC;CACpB;AAED;;;;GAIG;AACH,wBAAgB,qBAAqB,CAAE,EACtC,KAAK,EACL,QAAQ,EACR,EAAE,aAAa,GAAI,KAAK,CAAC,SAAS,CAMlC;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,IAAI,kBAAkB,GAAG,IAAI,CAE5D"}

package/build-types/hooks/use-dashboard-container-column-count.d.ts

@@ -0,0 +1,15 @@
+import { type Ref } from '@wordpress/element';
+interface UseDashboardContainerColumnCountResult {
+    containerRef: Ref<HTMLDivElement>;
+    columnCount: number;
+}
+/**
+ * Tracks the dashboard grid container width and maps it to an opinionated
+ * column count (4 → 2 → 1). Measurement is container-based via
+ * `ResizeObserver`, not viewport media queries.
+ *
+ * @param {Ref< HTMLDivElement >} [forwardedRef] Ref forwarded from the grid wrapper.
+ */
+export declare function useDashboardContainerColumnCount(forwardedRef?: Ref<HTMLDivElement>): UseDashboardContainerColumnCountResult;
+export {};
+//# sourceMappingURL=use-dashboard-container-column-count.d.ts.map

package/build-types/hooks/use-dashboard-container-column-count.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"use-dashboard-container-column-count.d.ts","sourceRoot":"","sources":["../../src/hooks/use-dashboard-container-column-count.ts"],"names":[],"mappings":"AAIA,OAAO,EAIN,KAAK,GAAG,EACR,MAAM,oBAAoB,CAAC;AAO5B,UAAU,sCAAsC;IAC/C,YAAY,EAAE,GAAG,CAAE,cAAc,CAAE,CAAC;IACpC,WAAW,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;GAMG;AACH,wBAAgB,gCAAgC,CAC/C,YAAY,CAAC,EAAE,GAAG,CAAE,cAAc,CAAE,GAClC,sCAAsC,CAgCxC"}

package/build-types/index.d.ts

@@ -0,0 +1,7 @@
+export { WidgetDashboard } from './widget-dashboard';
+export type { DashboardWidget, WidgetGridSettings } from './types';
+export { WIDGET_DASHBOARD_COLUMN_COUNT } from './types';
+export { DEFAULT_GRID } from './utils/default-grid';
+export { normalizeGridSettings } from './utils/normalize-grid-settings';
+export { ROW_HEIGHT_PRESETS, DEFAULT_ROW_HEIGHT, } from './utils/row-height-presets';
+//# sourceMappingURL=index.d.ts.map

package/build-types/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AACrD,YAAY,EAAE,eAAe,EAAE,kBAAkB,EAAE,MAAM,SAAS,CAAC;AACnE,OAAO,EAAE,6BAA6B,EAAE,MAAM,SAAS,CAAC;AACxD,OAAO,EAAE,YAAY,EAAE,MAAM,sBAAsB,CAAC;AACpD,OAAO,EAAE,qBAAqB,EAAE,MAAM,iCAAiC,CAAC;AACxE,OAAO,EACN,kBAAkB,EAClB,kBAAkB,GAClB,MAAM,4BAA4B,CAAC"}

package/build-types/lock-unlock.d.ts

@@ -0,0 +1,2 @@
+export declare const lock: (object: unknown, privateData: unknown) => void, unlock: <T = any>(object: unknown) => T;
+//# sourceMappingURL=lock-unlock.d.ts.map

package/build-types/lock-unlock.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"lock-unlock.d.ts","sourceRoot":"","sources":["../src/lock-unlock.ts"],"names":[],"mappings":"AAKA,eAAO,MAAQ,IAAI,mDAAE,MAAM,iCAIzB,CAAC"}

package/build-types/types.d.ts

@@ -0,0 +1,222 @@
+/**
+ * Dashboard-specific types: `DashboardWidget`, grid settings, and the
+ * `WidgetDashboard` prop bag.
+ *
+ * The widget contract types (`WidgetName`, `WidgetType`, `WidgetRenderProps`,
+ * `ResolveWidgetModule`) live in `@wordpress/widget-primitives` and are
+ * imported from there directly; this module does not re-export them.
+ */
+/**
+ * External dependencies
+ */
+import type { ReactNode } from 'react';
+/**
+ * WordPress dependencies
+ */
+import type { DashboardGridLayoutItem, DashboardLanesLayoutItem } from '@wordpress/grid';
+import type { WidgetName, WidgetType, ResolveWidgetModule } from '@wordpress/widget-primitives';
+export type GridTilePlacement = Omit<DashboardGridLayoutItem, 'key'>;
+export type MasonryTilePlacement = Omit<DashboardLanesLayoutItem, 'key'>;
+/**
+ * Storage shape for a widget's placement.
+ *
+ * Structurally a union of every supported per-model shape, but the
+ * intended invariant is stronger than the type suggests: every
+ * placement in a given layout must match the shape of the currently
+ * active `gridSettings.model`. `migrateLayout` is the only correct
+ * way to transition placements across model changes; the render
+ * layer is allowed to trust the active model and treat each
+ * placement as the matching shape.
+ *
+ * The type system cannot enforce that invariant on its own (there is
+ * no discriminator on the placement itself), so consider this union a
+ * declaration of which shapes are *valid*, not which shape any given
+ * placement happens to be at runtime.
+ */
+export type DashboardTilePlacement = GridTilePlacement | MasonryTilePlacement;
+/**
+ * A widget placed on the dashboard.
+ *
+ * A `WidgetType` describes the blueprint. A `DashboardWidget` is a
+ * concrete placement of that type on a specific dashboard: its unique
+ * id, the type it references, user-configured attributes, and its
+ * `placement` in the grid.
+ */
+export interface DashboardWidget<Item = unknown> {
+    /**
+     * Unique instance identifier.
+     */
+    uuid: string;
+    /**
+     * Widget type name — must match a `WidgetType.name` in `widgetTypes`.
+     */
+    type: WidgetName;
+    /**
+     * User-configured attributes for this instance.
+     */
+    attributes?: Item;
+    /**
+     * Grid-model-specific placement (column/row spans, ordering,
+     * etc.). Must match the shape implied by the dashboard's active
+     * `gridSettings.model`; see `DashboardTilePlacement` for the
+     * invariant and `migrateLayout` for the transition mechanism.
+     */
+    placement?: DashboardTilePlacement;
+}
+/**
+ * Identity of a widget within the rendering tree. Returned by
+ * `useWidgetContext()`; `null` when called outside a widget render subtree.
+ */
+export interface WidgetContextValue {
+    /**
+     * Widget instance id.
+     */
+    uuid: string;
+    /**
+     * Widget type name.
+     */
+    name: WidgetName;
+    /**
+     * Index of the widget in the `layout` array.
+     */
+    index: number;
+}
+/**
+ * Identifier for the active grid model. Drives which `@wordpress/grid`
+ * surface the dashboard mounts and which per-model settings the
+ * `WidgetGridSettings` union admits.
+ *
+ * Model names describe user-facing concepts. The mapping to the
+ * underlying `@wordpress/grid` component is an implementation detail
+ * resolved in the render layer; `'masonry'` is rendered today through
+ * `DashboardLanes` (skyline placement) but could swap to a future
+ * native `display: grid-lanes` path without affecting the model name.
+ */
+export type WidgetGridModel = 'grid' | 'masonry';
+/**
+ * Maximum column count for the widget dashboard on wide containers.
+ * Not exposed in layout settings; container width steps the count down
+ * to two and one column at fixed breakpoints.
+ */
+export declare const WIDGET_DASHBOARD_COLUMN_COUNT = 4;
+/**
+ * Settings common to every grid model. Column count is resolved from
+ * the dashboard container width (see
+ * `utils/resolve-dashboard-column-count`). `columns` and `minColumnWidth`
+ * on this type remain for persisted payloads and `@wordpress/grid`
+ * compatibility; the dashboard ignores user-facing values for both.
+ *
+ * `spacing` is intentionally absent: the gap between tiles is
+ * presentational and lives with the design-system theme/density, not
+ * with per-dashboard settings. The grid surface keeps the prop for
+ * programmatic overrides, but the dashboard does not propagate it.
+ */
+interface BaseWidgetGridSettings {
+    /**
+     * Target column count (cap). The dashboard always uses
+     * {@link WIDGET_DASHBOARD_COLUMN_COUNT}; persisted values are ignored.
+     */
+    columns?: number;
+    /**
+     * Per-tile minimum width in pixels. Unused by the dashboard; column
+     * count is derived from container width instead.
+     */
+    minColumnWidth?: number;
+}
+/**
+ * 2D packed grid settings. Items declare explicit width and height
+ * spans; rows use a uniform track height via `rowHeight`.
+ */
+export interface WidgetGridLayoutSettings extends BaseWidgetGridSettings {
+    model?: 'grid';
+    /**
+     * Row height in pixels (`200` small, `300` medium, `400` large). Every
+     * tile in a row fills the row vertically.
+     */
+    rowHeight?: number;
+}
+/**
+ * Masonry settings. Heights are content-driven; resize is
+ * horizontal-only. `flowTolerance` tunes how aggressively the placer
+ * preserves source order vs. minimizing empty regions.
+ */
+export interface WidgetMasonryLayoutSettings extends BaseWidgetGridSettings {
+    model: 'masonry';
+    /**
+     * Pixel tolerance for source-order tiebreaking when two candidate
+     * columns have similar baselines.
+     */
+    flowTolerance?: number;
+}
+/**
+ * Discriminated union of supported grid-model configurations.
+ *
+ * When `model` is omitted the dashboard treats the settings as the
+ * 2D packed grid (`'grid'`) for backwards compatibility with the
+ * pre-union shape.
+ */
+export type WidgetGridSettings = WidgetGridLayoutSettings | WidgetMasonryLayoutSettings;
+/**
+ * Props for `WidgetDashboard`.
+ *
+ * The consumer owns the committed layout state; the dashboard maintains
+ * a staging copy internally for in-progress edits, and `onLayoutChange`
+ * fires only when the user commits via the Done action.
+ */
+export interface WidgetDashboardProps {
+    /**
+     * Widget instances to render. Consumer owns this state.
+     */
+    layout: DashboardWidget[];
+    /**
+     * Called when the user commits in-progress edits via the Done action.
+     * Receives the full layout array as it should be persisted. In-progress
+     * mutations (reorder, resize, add, remove, attribute edits) accumulate
+     * in the dashboard's internal staging layer and do not fire this
+     * callback until commit.
+     */
+    onLayoutChange: (layout: DashboardWidget[]) => void;
+    /**
+     * Called when the layout is reset to the default.
+     */
+    onLayoutReset?: () => void;
+    /**
+     * Widget types available for rendering. The dashboard never queries a
+     * store directly — consumers scope and filter via this prop.
+     */
+    widgetTypes: WidgetType[];
+    /**
+     * When true, widget types are still loading. Instances whose type is
+     * not yet in `widgetTypes` show a loading state instead of missing.
+     */
+    isResolvingWidgetTypes?: boolean;
+    /**
+     * Whether the dashboard is in edit mode (enables drag/resize).
+     */
+    editMode?: boolean;
+    /**
+     * Called when edit mode toggles via `WidgetDashboard.Actions`.
+     */
+    onEditChange?: (next: boolean) => void;
+    /**
+     * Overrides the default `import()` resolution of
+     * `WidgetType.renderModule`. Useful for tests, Storybook, or future
+     * remote-URL loading.
+     */
+    resolveWidgetModule?: ResolveWidgetModule;
+    /**
+     * Grid model configuration. See `WidgetGridSettings` for the shape.
+     */
+    gridSettings?: WidgetGridSettings;
+    /**
+     * Called when the user commits in-progress grid-settings edits via
+     * the Done action. The dashboard maintains a staging copy of
+     * settings internally; mutations stay local until commit. When
+     * omitted, the `Layout settings` button in the customize toolbar is
+     * hidden, since there is nowhere to persist the change.
+     */
+    onGridSettingsChange?: (gridSettings: WidgetGridSettings) => void;
+    children?: ReactNode;
+}
+export {};
+//# sourceMappingURL=types.d.ts.map

package/build-types/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH;;GAEG;AACH,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAEvC;;GAEG;AACH,OAAO,KAAK,EACX,uBAAuB,EACvB,wBAAwB,EACxB,MAAM,iBAAiB,CAAC;AACzB,OAAO,KAAK,EACX,UAAU,EACV,UAAU,EACV,mBAAmB,EACnB,MAAM,8BAA8B,CAAC;AAEtC,MAAM,MAAM,iBAAiB,GAAG,IAAI,CAAE,uBAAuB,EAAE,KAAK,CAAE,CAAC;AACvE,MAAM,MAAM,oBAAoB,GAAG,IAAI,CAAE,wBAAwB,EAAE,KAAK,CAAE,CAAC;AAE3E;;;;;;;;;;;;;;;GAeG;AACH,MAAM,MAAM,sBAAsB,GAAG,iBAAiB,GAAG,oBAAoB,CAAC;AAE9E;;;;;;;GAOG;AACH,MAAM,WAAW,eAAe,CAAE,IAAI,GAAG,OAAO;IAC/C;;OAEG;IACH,IAAI,EAAE,MAAM,CAAC;IAEb;;OAEG;IACH,IAAI,EAAE,UAAU,CAAC;IAEjB;;OAEG;IACH,UAAU,CAAC,EAAE,IAAI,CAAC;IAElB;;;;;OAKG;IACH,SAAS,CAAC,EAAE,sBAAsB,CAAC;CACnC;AAED;;;GAGG;AACH,MAAM,WAAW,kBAAkB;IAClC;;OAEG;IACH,IAAI,EAAE,MAAM,CAAC;IAEb;;OAEG;IACH,IAAI,EAAE,UAAU,CAAC;IAEjB;;OAEG;IACH,KAAK,EAAE,MAAM,CAAC;CACd;AAED;;;;;;;;;;GAUG;AACH,MAAM,MAAM,eAAe,GAAG,MAAM,GAAG,SAAS,CAAC;AAEjD;;;;GAIG;AACH,eAAO,MAAM,6BAA6B,IAAI,CAAC;AAE/C;;;;;;;;;;;GAWG;AACH,UAAU,sBAAsB;IAC/B;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IAEjB;;;OAGG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;CACxB;AAED;;;GAGG;AACH,MAAM,WAAW,wBAAyB,SAAQ,sBAAsB;IACvE,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;CACnB;AAED;;;;GAIG;AACH,MAAM,WAAW,2BAA4B,SAAQ,sBAAsB;IAC1E,KAAK,EAAE,SAAS,CAAC;IAEjB;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,CAAC;CACvB;AAED;;;;;;GAMG;AACH,MAAM,MAAM,kBAAkB,GAC3B,wBAAwB,GACxB,2BAA2B,CAAC;AAE/B;;;;;;GAMG;AACH,MAAM,WAAW,oBAAoB;IACpC;;OAEG;IACH,MAAM,EAAE,eAAe,EAAE,CAAC;IAE1B;;;;;;OAMG;IACH,cAAc,EAAE,CAAE,MAAM,EAAE,eAAe,EAAE,KAAM,IAAI,CAAC;IAEtD;;OAEG;IACH,aAAa,CAAC,EAAE,MAAM,IAAI,CAAC;IAE3B;;;OAGG;IACH,WAAW,EAAE,UAAU,EAAE,CAAC;IAE1B;;;OAGG;IACH,sBAAsB,CAAC,EAAE,OAAO,CAAC;IAEjC;;OAEG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAC;IAEnB;;OAEG;IACH,YAAY,CAAC,EAAE,CAAE,IAAI,EAAE,OAAO,KAAM,IAAI,CAAC;IAEzC;;;;OAIG;IACH,mBAAmB,CAAC,EAAE,mBAAmB,CAAC;IAE1C;;OAEG;IACH,YAAY,CAAC,EAAE,kBAAkB,CAAC;IAElC;;;;;;OAMG;IACH,oBAAoB,CAAC,EAAE,CAAE,YAAY,EAAE,kBAAkB,KAAM,IAAI,CAAC;IAEpE,QAAQ,CAAC,EAAE,SAAS,CAAC;CACrB"}

package/build-types/utils/create-dashboard-widget/create-dashboard-widget.d.ts

@@ -0,0 +1,20 @@
+/**
+ * WordPress dependencies
+ */
+import type { WidgetType } from '@wordpress/widget-primitives';
+/**
+ * Internal dependencies
+ */
+import type { DashboardWidget } from '../../types';
+/**
+ * Create a new dashboard widget from a widget type.
+ *
+ * Generates a unique id and applies default placement. If no initial
+ * attributes are provided, falls back to the type's `example.attributes`
+ * (matching the `widget.json` schema).
+ *
+ * @param widgetType        Source widget type.
+ * @param initialAttributes Initial attributes; default to the type's example.
+ */
+export declare function createDashboardWidget<T>(widgetType: WidgetType, initialAttributes?: T): DashboardWidget<T>;
+//# sourceMappingURL=create-dashboard-widget.d.ts.map

package/build-types/utils/create-dashboard-widget/create-dashboard-widget.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"create-dashboard-widget.d.ts","sourceRoot":"","sources":["../../../src/utils/create-dashboard-widget/create-dashboard-widget.ts"],"names":[],"mappings":"AAKA;;GAEG;AACH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,8BAA8B,CAAC;AAE/D;;GAEG;AACH,OAAO,KAAK,EAAE,eAAe,EAAqB,MAAM,aAAa,CAAC;AAQtE;;;;;;;;;GASG;AACH,wBAAgB,qBAAqB,CAAE,CAAC,EACvC,UAAU,EAAE,UAAU,EACtB,iBAAiB,CAAC,EAAE,CAAC,GACnB,eAAe,CAAE,CAAC,CAAE,CAQtB"}

package/build-types/utils/create-dashboard-widget/index.d.ts

@@ -0,0 +1,2 @@
+export { createDashboardWidget } from './create-dashboard-widget';
+//# sourceMappingURL=index.d.ts.map

package/build-types/utils/create-dashboard-widget/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/utils/create-dashboard-widget/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAC"}

package/build-types/utils/default-grid/default-grid.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Internal dependencies
+ */
+import type { WidgetGridSettings } from '../../types';
+/**
+ * Canonical default grid settings. Applied by the dashboard when the
+ * consumer omits `gridSettings`, and the baseline hosts should treat as
+ * the factory default when persisting their own copy.
+ */
+export declare const DEFAULT_GRID: WidgetGridSettings;
+//# sourceMappingURL=default-grid.d.ts.map

package/build-types/utils/default-grid/default-grid.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"default-grid.d.ts","sourceRoot":"","sources":["../../../src/utils/default-grid/default-grid.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAItD;;;;GAIG;AACH,eAAO,MAAM,YAAY,EAAE,kBAI1B,CAAC"}

package/build-types/utils/default-grid/index.d.ts

@@ -0,0 +1,2 @@
+export { DEFAULT_GRID } from './default-grid';
+//# sourceMappingURL=index.d.ts.map

package/build-types/utils/default-grid/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/utils/default-grid/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC"}

package/build-types/utils/grid-model-change/grid-model-change.d.ts

@@ -0,0 +1,20 @@
+import type { DashboardWidget, WidgetGridModel, WidgetGridSettings } from '../../types';
+export declare function getGridModel(settings: WidgetGridSettings): WidgetGridModel;
+type ComputeGridModelChangeProps = {
+    layout: DashboardWidget[];
+    gridSettings: WidgetGridSettings;
+    targetModel: WidgetGridModel;
+};
+type ComputeGridModelChangeResult = {
+    layout: DashboardWidget[];
+    gridSettings: WidgetGridSettings;
+} | null;
+/**
+ * Computes the staged layout and grid settings after a layout-model change.
+ *
+ * @param {ComputeGridModelChangeProps} params Layout, current settings, and target model.
+ * @return {ComputeGridModelChangeResult} Migrated layout and settings, or `null` when the model is unchanged.
+ */
+export declare function computeGridModelChange({ layout, gridSettings, targetModel }: ComputeGridModelChangeProps): ComputeGridModelChangeResult;
+export {};
+//# sourceMappingURL=grid-model-change.d.ts.map

package/build-types/utils/grid-model-change/grid-model-change.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"grid-model-change.d.ts","sourceRoot":"","sources":["../../../src/utils/grid-model-change/grid-model-change.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EACX,eAAe,EACf,eAAe,EACf,kBAAkB,EAClB,MAAM,aAAa,CAAC;AAGrB,wBAAgB,YAAY,CAAE,QAAQ,EAAE,kBAAkB,GAAI,eAAe,CAE5E;AAED,KAAK,2BAA2B,GAAG;IAClC,MAAM,EAAE,eAAe,EAAE,CAAC;IAC1B,YAAY,EAAE,kBAAkB,CAAC;IACjC,WAAW,EAAE,eAAe,CAAC;CAC7B,CAAC;AAEF,KAAK,4BAA4B,GAAG;IACnC,MAAM,EAAE,eAAe,EAAE,CAAC;IAC1B,YAAY,EAAE,kBAAkB,CAAC;CACjC,GAAG,IAAI,CAAC;AAET;;;;;GAKG;AACH,wBAAgB,sBAAsB,CAAE,EACvC,MAAM,EACN,YAAY,EACZ,WAAW,EACX,EAAE,2BAA2B,GAAI,4BAA4B,CAgB7D"}

package/build-types/utils/grid-model-change/index.d.ts

@@ -0,0 +1,2 @@
+export { computeGridModelChange, getGridModel } from './grid-model-change';
+//# sourceMappingURL=index.d.ts.map

package/build-types/utils/grid-model-change/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/utils/grid-model-change/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,sBAAsB,EAAE,YAAY,EAAE,MAAM,qBAAqB,CAAC"}

package/build-types/utils/index.d.ts

@@ -0,0 +1,3 @@
+export { createDashboardWidget } from './create-dashboard-widget';
+export { migrateLayout } from './migrate-layout';
+//# sourceMappingURL=index.d.ts.map

package/build-types/utils/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAC;AAClE,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC"}

package/build-types/utils/migrate-layout/index.d.ts

@@ -0,0 +1,2 @@
+export { migrateLayout } from './migrate-layout';
+//# sourceMappingURL=index.d.ts.map

package/build-types/utils/migrate-layout/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/utils/migrate-layout/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC"}

package/build-types/utils/migrate-layout/migrate-layout.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Internal dependencies
+ */
+import type { DashboardWidget, WidgetGridModel } from '../../types';
+interface MigrationContext {
+    /**
+     * Column count of the currently-mounted grid surface. Used to
+     * resolve `'full'` widths to a concrete numeric span when going
+     * from the 2D grid model to masonry. When the surface is in
+     * responsive mode and the runtime column count is unknown,
+     * callers should pass a sensible fallback (e.g., the default of
+     * 6 used by `@wordpress/grid`).
+     */
+    columns: number;
+}
+/**
+ * Migrates every widget's `placement` between grid models.
+ *
+ * The two storage shapes overlap on `width` and `order` but diverge
+ * on the rest: 2D grid carries `height` and discriminated string
+ * widths (`'fill'`/`'full'`), lanes carries `lane` and only numeric
+ * widths. Each conversion loses information that the target model
+ * cannot represent. The caller is responsible for surfacing the
+ * result to the user in a way that lets them correct visually.
+ *
+ * When `from === to`, the input is returned unchanged.
+ *
+ * @param widgets Widgets to migrate.
+ * @param from    Source model. `undefined` is treated as `'grid'`.
+ * @param to      Target model.
+ * @param context Information that depends on the live render (today
+ *                only `columns`).
+ */
+export declare function migrateLayout(widgets: DashboardWidget[], from: WidgetGridModel | undefined, to: WidgetGridModel, context?: Partial<MigrationContext>): DashboardWidget[];
+export {};
+//# sourceMappingURL=migrate-layout.d.ts.map

package/build-types/utils/migrate-layout/migrate-layout.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"migrate-layout.d.ts","sourceRoot":"","sources":["../../../src/utils/migrate-layout/migrate-layout.ts"],"names":[],"mappings":"AAAA;;GAEG;AACH,OAAO,KAAK,EACX,eAAe,EAGf,eAAe,EACf,MAAM,aAAa,CAAC;AAErB,UAAU,gBAAgB;IACzB;;;;;;;OAOG;IACH,OAAO,EAAE,MAAM,CAAC;CAChB;AAkFD;;;;;;;;;;;;;;;;;GAiBG;AACH,wBAAgB,aAAa,CAC5B,OAAO,EAAE,eAAe,EAAE,EAC1B,IAAI,EAAE,eAAe,GAAG,SAAS,EACjC,EAAE,EAAE,eAAe,EACnB,OAAO,GAAE,OAAO,CAAE,gBAAgB,CAAO,GACvC,eAAe,EAAE,CA8BnB"}

package/build-types/utils/normalize-grid-settings/index.d.ts

@@ -0,0 +1,2 @@
+export { normalizeGridSettings } from './normalize-grid-settings';
+//# sourceMappingURL=index.d.ts.map

package/build-types/utils/normalize-grid-settings/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/utils/normalize-grid-settings/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,qBAAqB,EAAE,MAAM,2BAA2B,CAAC"}

package/build-types/utils/normalize-grid-settings/normalize-grid-settings.d.ts

@@ -0,0 +1,11 @@
+import type { WidgetGridSettings } from '../../types';
+/**
+ * Coerces legacy grid row heights to a dashboard preset. Standard grid
+ * rows always use uniform track sizing so tiles align with the masonry
+ * model boundary.
+ *
+ * @param settings         Grid settings to normalize.
+ * @param defaultRowHeight Fallback row height when none is set.
+ */
+export declare function normalizeGridSettings(settings: WidgetGridSettings, defaultRowHeight: number): WidgetGridSettings;
+//# sourceMappingURL=normalize-grid-settings.d.ts.map

package/build-types/utils/normalize-grid-settings/normalize-grid-settings.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"normalize-grid-settings.d.ts","sourceRoot":"","sources":["../../../src/utils/normalize-grid-settings/normalize-grid-settings.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAA4B,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAGhF;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CACpC,QAAQ,EAAE,kBAAkB,EAC5B,gBAAgB,EAAE,MAAM,GACtB,kBAAkB,CAuBpB"}