Programmatic Control

Imperative control exposed through the Tilery ref, panel objects, and tab objects.

Controller Ref

The Tilery ref exposes a TileryController. Use it when the application, not a direct drag gesture, needs to change the workspace.

Common workflows

Controller methods

Tab Workflow APIs

Use openOrActivateTab() when app resources have stable ids, such as file paths, issue ids, or routes. If the id already exists, Tilery activates that tab and does not update its data or create a duplicate. If the id is missing, Tilery inserts the tab at the supplied target and activates it.

Edge panels are normal tab targets once they exist in the root layout. Move a tab into a pinned sidebar with { panel: edgePanelId }, or inspect panel.kind === 'edge' when the app needs to treat sidebars differently from main tiled panels.

Use changeTabId() when a temporary tab receives a durable id later, for example after saving a draft file. The rename updates panel tab order and active tab references; it returns null when the old id is missing or the new id is already in use.

tilery.openOrActivateTab(
  {
    id: filePath,
    data: { title: basename(filePath), filePath },
  },
  { afterTab: relatedTabId },
);

tilery.changeTabId('untitled-1', savedFilePath)?.activate();

Panel Objects

TileryPanel objects are returned by getPanel() and getPanels().

Tab Objects

TileryTab objects are returned by getTab(), getTabs(), and panel tab properties.

TileryMoveTarget

Used with moveTab() and tab.moveTo():

type TileryMoveTarget =
  | { panel: TileryPanelId; index?: number }
  | { beforeTab: TileryTabId }
  | { afterTab: TileryTabId }
  | ({
      splitPanel: TileryPanelId;
      direction: TileryDirection;
      size?: number;
      minSize?: TilerySize;
      maxSize?: TilerySize;
    } & TileryLayoutBehaviorConfig)
  | ({
      splitRoot: true;
      direction: TileryDirection;
      size?: number;
      minSize?: TilerySize;
      maxSize?: TilerySize;
    } & TileryLayoutBehaviorConfig);

Use splitPanel when the new panel should sit beside one existing panel. Use splitRoot when the new panel should become a full-width or full-height row/column around the whole main tiled layout. If splitRoot omits size, Tilery gives the new panel an equal share of the resulting root rows or columns.

TileryPanelMoveTarget

Used with movePanel() and panel.moveTo():

type TileryPanelMoveTarget =
  | ({
      splitPanel: TileryPanelId;
      direction: TileryDirection;
      size?: number;
      minSize?: TilerySize;
      maxSize?: TilerySize;
    } & TileryLayoutBehaviorConfig)
  | ({
      splitRoot: true;
      direction: TileryDirection;
      size?: number;
      minSize?: TilerySize;
      maxSize?: TilerySize;
    } & TileryLayoutBehaviorConfig);

Use movePanel() when the panel's runtime content should stay mounted while its position changes. Unlike moving each tab into a new split, this keeps the original panel id.

TileryOpenTabTarget

Used with openOrActivateTab() for the insertion path:

type TileryOpenTabTarget =
  | { panel: TileryPanelId; index?: number }
  | { beforeTab: TileryTabId }
  | { afterTab: TileryTabId };

TileryFloatPanelOptions

Used with floatPanel() and panel.float():

type TileryFloatPanelOptions = TileryFloatingPanelBoundsInit &
  TileryLayoutBehaviorConfig;

TileryPopoutPanelOptions

Used with popoutPanel() and panel.popout():

type TileryPopoutPanelOptions = {
  floatingBounds?: TileryFloatingPanelBoundsInit;
  windowBounds?: TileryPopoutWindowBoundsInit;
} & TileryLayoutBehaviorConfig;

TileryFloatTabOptions

Used with floatTab() and tab.float():

type TileryFloatTabOptions = {
  panelId?: TileryPanelId;
  bounds?: TileryFloatingPanelBoundsInit;
} & TileryLayoutBehaviorConfig;

TileryPopoutTabOptions

Used with popoutTab() and tab.popout():

type TileryPopoutTabOptions = {
  panelId?: TileryPanelId;
  floatingBounds?: TileryFloatingPanelBoundsInit;
  windowBounds?: TileryPopoutWindowBoundsInit;
} & TileryLayoutBehaviorConfig;

TileryDockPanelTarget

Used with dockPanel() and panel.dock():

type TileryDockPanelTarget = {
  splitPanel?: TileryPanelId;
  direction?: TileryDirection;
  size?: number;
  minSize?: TilerySize;
  maxSize?: TilerySize;
} & TileryLayoutBehaviorConfig;

TileryDirection

type TileryDirection = 'left' | 'right' | 'top' | 'bottom';