Tile Layout API

Full surface of oge-tile-layout and its declarative oge-tile-layout-item children: inputs, methods, the cancelable events, the serializable state and its validator, the template slots, the keyboard map and the config provider.

Properties Methods Events Types

OgeTileLayout

oge-tile-layout

Properties 10

Name	Type	Default	Description
`items`	`readonly OgeTileLayoutItemData[]`	`[]`	The tiles as data, rendered after the declarative `oge-tile-layout-item` children. Fields: `key`, `title?`, `colSpan?`, `rowSpan?`, `order?`, `minColSpan?` / `maxColSpan?`, `minRowSpan?` / `maxRowSpan?`, `resizable?`, `reorderable?`.
`columns`	`number \| undefined`	`config ?? 4`	Number of grid columns. Column spans are clamped to it; below 480px of container width the layout collapses to one column.
`rowHeight`	`number \| 'auto' \| undefined`	`config ?? 160`	Height of one row track in px, or `auto` to size rows by their content.
`gap`	`number \| undefined`	`config ?? 16`	Gap between tiles in px.
`columnWidth`	`number \| string \| undefined`	—	Fixed column width (`240` px or any CSS length); default equal `1fr` columns.
`resizable`	`boolean \| 'horizontal' \| 'vertical'`	`false`	Default resizability of every tile (the item’s own `resizable` overrides it): a corner handle for the pointer, `Ctrl`+`Shift`+arrows for the keyboard.
`reorderable`	`boolean`	`true`	Default reorderability: drag by the header, `Ctrl`+arrows on the keyboard.
`state`	`OgeTileLayoutState \| undefined`	`undefined`	The committed layout (two-way `[(state)]`). `undefined` lays the tiles out from their own `order` and spans; every move and resize writes a new state.
`ariaLabel`	`string \| undefined`	`messages.layoutLabel ('Dashboard')`	Accessible name of the list.
`locale`	`string \| undefined`	`config ?? LOCALE_ID`	BCP 47 locale of the announcements’ plural rules.

Methods 5

Name	Type	Description
`focus(key?)`	`(key?: OgeTileLayoutKey) => void`	Focuses a tile (default: the current tab stop).
`moveTile(key, toIndex)`	`(key: OgeTileLayoutKey, toIndex: number) => boolean`	Moves a tile through the cancelable pipeline (`source: 'api'`); `false` when nothing moved.
`resizeTile(key, colSpan, rowSpan)`	`(key: OgeTileLayoutKey, colSpan: number, rowSpan: number) => boolean`	Gives a tile new spans, clamped to its bounds, through the cancelable pipeline.
`getState()`	`() => OgeTileLayoutState`	The current layout as a serializable state.
`applyState(state)`	`(state: unknown) => boolean`	Validates (`sanitizeOgeTileLayoutState`) and applies a persisted state; `false` and no change when it is invalid. Emits `layoutChanged`.

Events 6

Name	Type	Description
`reordering`	`OgeTileLayoutReorderingEvent`	A tile is about to move — set `cancel` to keep it.
`reordered`	`OgeTileLayoutReorderedEvent`	A tile moved.
`resizing`	`OgeTileLayoutResizingEvent`	A tile is about to change its spans — set `cancel` to keep them.
`resized`	`OgeTileLayoutResizedEvent`	A tile changed its spans.
`layoutChanged`	`OgeTileLayoutChangedEvent`	The layout changed (move, resize, `applyState`) — persist `state`.
`stateChange`	`OgeTileLayoutState \| undefined`	The `[(state)]` model’s change half.

Types 21

Template slots

Name	Type	Description
`OgeTileLayoutHeaderTemplate`	`[ogeTileLayoutHeaderTemplate]`	Replaces the title in the header of every `items` tile. The header stays the drag handle; buttons inside it are real controls that never start a drag.
`OgeTileLayoutContentTemplate`	`[ogeTileLayoutContentTemplate]`	The body of every `items` tile. Ordinary flow content in the normal Tab order.
`OgeTileLayoutTemplateContext`	`{ $implicit: OgeTileLayoutItemData; key; index; colSpan; rowSpan }`	Context of both slots; the spans are the live preview while a resize is in progress.

Events & state

Name	Type	Description
`OgeTileLayoutReorderingEvent`	`{ item; key; fromIndex; toIndex; source: 'pointer' \| 'keyboard' \| 'api'; event?; cancel }`	A tile is about to move — set `cancel` to keep it where it is. The pointer drop and the keyboard emit the same payload.
`OgeTileLayoutReorderedEvent`	`Omit<OgeTileLayoutReorderingEvent, 'cancel'>`	A tile moved.
`OgeTileLayoutResizingEvent`	`{ item; key; previous: OgeTileLayoutSpan; next: OgeTileLayoutSpan; source; event?; cancel }`	A tile is about to change its spans (already clamped to its bounds) — set `cancel` to keep them.
`OgeTileLayoutResizedEvent`	`Omit<OgeTileLayoutResizingEvent, 'cancel'>`	A tile changed its spans.
`OgeTileLayoutChangedEvent`	`{ state: OgeTileLayoutState; source }`	The layout changed through a move, a resize or `applyState()` — the state to persist.
`OgeTileLayoutState`	`{ version: 1; tiles: { key; order; colSpan; rowSpan }[] }`	The serializable layout. `order` is the 0-based display position. Tiles the state does not list are placed after the known ones; entries whose key no longer exists are ignored.
`sanitizeOgeTileLayoutState(input, knownKeys?)`	`(input: unknown, knownKeys?: Iterable<OgeTileLayoutKey>) => OgeTileLayoutState \| null`	Validates persisted / imported state (untrusted input): never throws, rejects prototype keys at any depth, drops unknown fields, duplicate and unknown keys, keeps integer spans ≥ 1 and renumbers the order. `applyState()` runs it for you.

Vocabulary

Name	Type	Description
`OgeTileLayoutItemData`	`interface`	One tile as data: `key`, `title?`, `colSpan?`, `rowSpan?`, `order?`, `minColSpan?` / `maxColSpan?`, `minRowSpan?` / `maxRowSpan?`, `resizable?`, `reorderable?`.
`OgeTileLayoutResizable`	`boolean \| 'horizontal' \| 'vertical'`	Which spans the user may change.
`OgeTileLayoutSpan`	`{ colSpan: number; rowSpan: number }`	Column and row span of a tile.
`OgeTileLayoutKey`	`string \| number`	Identity of a tile.
`OgeTileLayoutChangeSource`	`'pointer' \| 'keyboard' \| 'api'`	What started a change; `api` is a method call.

Keyboard

Name	Type	Description
`Arrow keys / Home / End`	`focus`	Move focus between tiles (one roving tab stop; ↑/↓ go to the closest tile in the row above / below). Content inside a tile keeps its own Tab order, and the tile keys only act while the tile itself is focused.
`Ctrl+← / Ctrl+→`	`move`	Move the focused tile one position earlier / later (mirrored in RTL). `⌘` works as `Ctrl`.
`Ctrl+↑ / Ctrl+↓`	`move`	Move the focused tile to the position of the tile above / below.
`Ctrl+Shift+← / Ctrl+Shift+→`	`resize`	Shrink / grow the column span (mirrored in RTL), within the tile’s bounds.
`Ctrl+Shift+↑ / Ctrl+Shift+↓`	`resize`	Shrink / grow the row span.
`Escape`	`cancel`	Cancels a pointer drag or resize in progress.

OgeTileLayoutItem

oge-tile-layout-item

Properties 8

Name	Type	Default	Description
`key`	`string \| number \| undefined`	`auto id`	Identity reported by every event and stored in the state. Set it when the layout is persisted — the auto id is per page load.
`title`	`string \| undefined`	—	Header text; also the tile’s accessible name.
`colSpan / rowSpan`	`number \| undefined`	`1`	Columns and rows the tile spans.
`order`	`number \| undefined`	—	Initial position; tiles without one keep document order.
`minColSpan / maxColSpan`	`number \| undefined`	`1 / columns`	Bounds of a column-span resize.
`minRowSpan / maxRowSpan`	`number \| undefined`	`1 / unbounded`	Bounds of a row-span resize.
`resizable`	`boolean \| 'horizontal' \| 'vertical' \| undefined`	—	Overrides the layout’s `resizable`.
`reorderable`	`boolean \| undefined`	—	Overrides the layout’s `reorderable`.

Types 1

Slots

Name	Type	Description
`OgeTileLayoutItemHeader`	`[ogeTileLayoutItemHeader]`	Attribute slot: the projected element replaces the header title. Everything else projected is the tile body.

Configuration

Properties 2

Name	Type	Description
`provideOgeTileLayoutConfig(config)`	`(config: OgeTileLayoutConfigInput \| (() => OgeTileLayoutConfigInput)) => Provider`	Application- or component-scoped defaults for `columns`, `rowHeight`, `gap`, `locale` and the `messages` (a function makes it live).
`OGE_TILE_LAYOUT_CONFIG`	`InjectionToken<OgeTileLayoutConfig>`	The token behind `provideOgeTileLayoutConfig()`, with `OGE_DEFAULT_TILE_LAYOUT_CONFIG` as its factory default.

Types 2

Messages

Name	Type	Description
`OgeTileLayoutMessages`	`interface`	`layoutLabel`, `tileRoleDescription`, `untitledTile` (`{position}`), `keyboardHint`, `dragHint`, `moved` (`{title}`, `{position}`, `{count}`), `resized` (ICU plurals over `{colSpan}` / `{rowSpan}`), `unchanged`, `dragCancelled`. Translated in every `@oge-ui/locales` pack (`layout.tileLayout`).
`OgeTileLayoutConfig / OgeTileLayoutConfigInput`	`interface`	The config shape (`messages`, `columns?`, `rowHeight?`, `gap?`, `locale?`) and its partial input; `OGE_DEFAULT_TILE_LAYOUT_CONFIG` / `OGE_DEFAULT_TILE_LAYOUT_MESSAGES` are the resolved defaults.