@aginies/ui 0.1.0 → 0.3.0

package/dist/index.d.cts

@@ -763,8 +763,12 @@ export interface DataColumn<T = any> {
   sortValue?: (row: T) => any;
   /** right for numbers and amounts */
   align?: 'left' | 'right' | 'center';
+  /** Column width; also the room it needs when `minWidth` is absent (px numbers count for priority hiding) */
   width?: number | string;
+  /** Narrowest width the column may take; priority hiding sums these (default 120px) */
   minWidth?: number | string;
+  /** DataTable only: 1 = always shown (default), higher numbers hide first when the table's own width cannot fit every column */
+  priority?: number;
   /** Custom cell; receives (value, row, index) */
   render?: (value: any, row: T, index: number) => React.ReactNode;
   /** Inline edit on double-click, F2 or the pencil (needs onCellEdit) */
@@ -778,8 +782,8 @@ export interface DataColumn<T = any> {
   className?: string;
 }
 /** Visible strings of a DataTable, overridable per locale. */
-export interface DataTableLabels { empty?: string; emptyHint?: string; loading?: string; error?: string; errorHint?: string; retry?: string; selectAll?: string; selectRow?: string; actions?: string; sortedAsc?: string; sortedDesc?: string; edit?: string; }
-/** Dense record grid for agents, runs, approvals and tenants: sortable columns, selection with select-all, inline cell edit, row actions, sticky header, and the states error → loading → empty → rows. Rows are 32px compact and 44px comfortable. */
+export interface DataTableLabels { empty?: string; emptyHint?: string; loading?: string; error?: string; errorHint?: string; retry?: string; selectAll?: string; selectRow?: string; actions?: string; sortedAsc?: string; sortedDesc?: string; edit?: string; /** aria-label of the row-detail toggle while closed */ expandRow?: string; /** aria-label of the row-detail toggle while open */ collapseRow?: string; }
+/** Dense record grid for agents, runs, approvals and tenants: sortable columns, selection with select-all, inline cell edit, row actions, sticky header, and the states error → loading → empty → rows. Rows are 32px compact and 44px comfortable. At narrow widths it hides columns by `priority` against its own measured width and can pin the first column (`stickyFirst`). */
 export interface DataTableProps<T = any> extends Omit<React.HTMLAttributes<HTMLDivElement>, 'onChange' | 'selected' | 'value'> {
   columns: DataColumn<T>[];
   rows: T[];
@@ -824,6 +828,10 @@ export interface DataTableProps<T = any> extends Omit<React.HTMLAttributes<HTMLD
   rowClassName?: (row: T, index: number) => string | false | undefined;
   /** Key of the row whose detail is open (side panel, split view): aria-current, --selection ground and a --signal edge. Independent of `selected` */
   activeKey?: string | number | null;
+  /** First data column (and the selection column) stays put while the table scrolls sideways, with a hairline shadow once scrolled */
+  stickyFirst?: boolean;
+  /** Called with the keys of the columns hidden by `priority` whenever that set changes ([] when all fit) */
+  onHiddenColumnsChange?: (keys: string[]) => void;
 }
 export declare function DataTable<T = any>(props: DataTableProps<T>): JSX.Element;
 
@@ -1320,24 +1328,103 @@ export declare function Toolbar(props: ToolbarProps): JSX.Element;
 /** Vertical hairline between toolbar groups. */
 export declare function ToolbarSeparator(props: React.HTMLAttributes<HTMLSpanElement>): JSX.Element;
 
-/** The console frame: optional GlobalHeader on top, VerticalNavigation on the left, a scrolling main area with the console gutter, optional SidePanel on the right. */
+/** The console frame: optional GlobalHeader on top, VerticalNavigation on the left, a scrolling main area with the console gutter, optional side panel on the right. It measures its own width: ≥ 1280 everything docked; 1024–1279 the sidebar on its 56px rail; < 1024 the sidebar is a drawer and the side panel a sheet from the right, both opened from a 48px page bar; < 768 the gutter is 16px. */
 export interface PageLayoutProps extends React.HTMLAttributes<HTMLDivElement> {
   /** A GlobalHeader (brand screens) — consoles usually omit it */
   header?: React.ReactNode;
-  /** A VerticalNavigation */
+  /** A VerticalNavigation; it reads its state (docked, rail, drawer) from the PageLayout */
   navigation?: React.ReactNode;
-  /** A side panel: inspector, artifact, conversation */
+  /** A side panel: inspector, artifact, conversation. A SidePanel passed without a mode is docked in the frame */
   sidePanel?: React.ReactNode;
   /** Defaults to --panel-w (288) */
   sidePanelWidth?: number | string;
-  /** Content max width (default --content-max 1440) */
+  /** Content width preset: reading (--content-reading 960: settings, documents, wizards) · default (--content-max 1440) · wide (--content-wide 1920: dashboards that add columns) · full (no cap: tables and canvases) */
+  width?: 'reading' | 'default' | 'wide' | 'full';
+  /** Content max width; overrides width */
   maxWidth?: number | string;
   /** No gutter or max width, and the content fills the main area's height (canvas, split views) */
   flush?: boolean;
+  /** Sidebar state: auto (default, from the measured width), or forced docked / rail / overlay */
+  sidebarMode?: 'auto' | 'docked' | 'rail' | 'overlay';
+  /** Side panel state: auto (default: docked ≥ 1024, overlay below), or forced docked / overlay */
+  panelMode?: 'auto' | 'docked' | 'overlay';
+  /** Overlay drawer open (controlled); uncontrolled it opens from the page bar */
+  sidebarOpen?: boolean;
+  onSidebarOpenChange?: (open: boolean) => void;
+  /** Overlay sheet open (controlled); uncontrolled it opens from the page bar and when a side panel appears while the page is narrow */
+  panelOpen?: boolean;
+  onPanelOpenChange?: (open: boolean) => void;
+  /** The 48px page bar shown while the sidebar or panel is an overlay: false hides it (open them through usePageLayout), a node replaces the mark in its middle */
+  bar?: boolean | React.ReactNode;
+  labels?: { openNav?: string; closeNav?: string; openPanel?: string; closePanel?: string; navigation?: string; details?: string };
   as?: any;
 }
 export declare function PageLayout(props: PageLayoutProps): JSX.Element;
 
+/** State of the enclosing PageLayout, for a page that needs to adapt (drop table columns, put the menu button in its own header). */
+export interface PageLayoutState {
+  /** Breakpoint of the page's own width */
+  bp: Breakpoint;
+  sidebar: 'docked' | 'rail' | 'overlay' | null;
+  panel: 'docked' | 'overlay' | null;
+  railExpanded: boolean;
+  setRailExpanded: (expanded: boolean) => void;
+  sidebarOpen: boolean;
+  openSidebar: () => void;
+  closeSidebar: () => void;
+  panelOpen: boolean;
+  openPanel: () => void;
+  closePanel: () => void;
+}
+/** The enclosing PageLayout's state; null outside one. */
+export declare function usePageLayout(): PageLayoutState | null;
+export declare const PageLayoutContext: React.Context<PageLayoutState | null>;
+
+/** Breakpoint names: base < 640 ≤ sm < 768 ≤ md < 1024 ≤ lg < 1280 ≤ xl < 1536 ≤ 2xl (tokens bp-sm … bp-2xl). */
+export type Breakpoint = 'base' | 'sm' | 'md' | 'lg' | 'xl' | '2xl';
+/** A value per breakpoint, mobile first: each one holds until a larger breakpoint sets another. */
+export type Responsive<T> = T | Partial<Record<Breakpoint, T>>;
+
+/** 12-column grid (--grid-columns, --grid-gap) laid out by its own width through a container query, so it responds to its pane, not the window. Dashboards, record bodies, card galleries. */
+export interface GridProps extends React.HTMLAttributes<HTMLElement> {
+  /** Gallery mode: auto-fill columns at least this wide (number = px), e.g. 280 for cards. GridItem spans are ignored */
+  min?: number | string;
+  /** Column count (default --grid-columns, 12) */
+  columns?: number;
+  /** Gap: lg (default, --grid-gap 24), md 16, sm 12, none, or any length */
+  gap?: 'none' | 'sm' | 'md' | 'lg' | number | string;
+  /** Row gap when it differs from gap */
+  rowGap?: 'none' | 'sm' | 'md' | 'lg' | number | string;
+  /** Vertical alignment of items in a row (default stretch) */
+  align?: 'start' | 'center' | 'end';
+  /** Back-fills holes left by wide items */
+  dense?: boolean;
+  as?: any;
+}
+export declare function Grid(props: GridProps): JSX.Element;
+/** One cell of a Grid. */
+export interface GridItemProps extends React.HTMLAttributes<HTMLElement> {
+  /** Columns to span: a number, 'full', or per breakpoint of the Grid's width ({ base: 12, lg: 6, xl: 4 }). Default 12 */
+  span?: Responsive<number | 'full'>;
+  /** Starting column line */
+  start?: number;
+  /** Rows to span */
+  rowSpan?: number;
+  as?: any;
+}
+export declare function GridItem(props: GridItemProps): JSX.Element;
+
+/** Breakpoint values in px (= tokens): { sm: 640, md: 768, lg: 1024, xl: 1280, '2xl': 1536 }. */
+export declare const BREAKPOINTS: Record<Exclude<Breakpoint, 'base'>, number>;
+/** Name of the largest breakpoint a width reaches. */
+export declare function breakpointFor(width: number): Breakpoint;
+/** Width (px) of an element, kept current with a ResizeObserver; null until measured. */
+export declare function useElementWidth(ref: React.RefObject<Element>): number | null;
+/** Breakpoint of an element's own width; null until measured. Use it to drop low-priority table columns in a narrow pane. */
+export declare function useBreakpoint(ref: React.RefObject<Element>): Breakpoint | null;
+/** Drawer/sheet focus handling: focus moves into the container on open, Tab stays inside, Esc calls onClose, focus returns on close. */
+export declare function useOverlayFocus(ref: React.RefObject<HTMLElement>, open: boolean, onClose?: () => void): void;
+
 /** The website's .room: a section that inverts the theme inside — sets data-theme opposite to its ancestor and paints --bg. */
 export interface RoomProps extends React.HTMLAttributes<HTMLElement> {
   /** Force a theme instead of inverting the ancestor's */
@@ -1412,7 +1499,9 @@ export interface VerticalNavigationProps extends Omit<React.HTMLAttributes<HTMLE
   /** Each new width while resizing; persist it and pass it back as width */
   onResize?: (width: number) => void;
   logoHref?: string;
-  labels?: { search?: string; collapse?: string; expand?: string; navigation?: string; resize?: string };
+  /** Layout state. Omit it inside PageLayout, which sets it from its width: docked ≥ 1280, rail 1024–1279 (collapsed to 56px until the user expands it), overlay < 1024 (a drawer with a close button that closes when an item is chosen). Standalone default: docked */
+  mode?: 'docked' | 'rail' | 'overlay';
+  labels?: { search?: string; collapse?: string; expand?: string; navigation?: string; resize?: string; close?: string };
 }
 export declare function VerticalNavigation(props: VerticalNavigationProps): JSX.Element;
 
@@ -1511,7 +1600,15 @@ export interface SplitViewProps extends Omit<React.HTMLAttributes<HTMLDivElement
   resizable?: boolean;
   /** Shows a toggle that hides the list */
   collapsible?: boolean;
-  labels?: { resize?: string; empty?: string; collapse?: string; expand?: string };
+  /** Width of the SplitView itself (a breakpoint name or px) below which list and detail stack: the list fills the pane and a picked record opens as a full pane with a back button. Default 'md' (768); false never stacks. Below 'lg' (1024) the list narrows to --panel-w */
+  stackBelow?: 'sm' | 'md' | 'lg' | 'xl' | number | false;
+  /** Pane shown first when stacked (default 'list') */
+  defaultStackedView?: 'list' | 'detail';
+  /** Called when the stacked pane changes */
+  onStackedViewChange?: (view: 'list' | 'detail') => void;
+  /** Called by the stacked detail's back button (after it returns to the list) */
+  onBack?: () => void;
+  labels?: { resize?: string; empty?: string; collapse?: string; expand?: string; back?: string };
 }
 export declare function SplitView(props: SplitViewProps): JSX.Element;
 
@@ -1720,6 +1817,40 @@ export interface StepperProps extends Omit<React.HTMLAttributes<HTMLOListElement
 }
 export declare function Stepper(props: StepperProps): JSX.Element;
 
+/** One view in an ActivityBar. */
+export interface ActivityBarItem {
+  /** Value passed to onSelect and matched against `active` */
+  id: string;
+  /** Lucide icon name (kebab-case), or a node such as <ProductIcon product="code" size={20} /> */
+  icon: string | React.ReactNode;
+  /** Accessible name and tooltip text */
+  label: string;
+  /** Small count Badge on the icon (a number, or a short word) */
+  badge?: number | string;
+  /** Shown dimmed, skipped by the arrow keys, not selectable */
+  disabled?: boolean;
+  /** id of the view panel this item opens (sets aria-controls) */
+  controls?: string;
+  /** id for the tab button, so the panel can point back with aria-labelledby */
+  tabId?: string;
+}
+/** Vertical 48px icon strip that switches the view beside it, like VS Code's activity bar or IntelliJ's tool-window bar: use it in IDE mocks and the web build of the Code panel. A vertical tablist with roving focus (↑ ↓ Home End, Enter or Space selects), tooltips with each label, a 2px --signal bar on the edge facing the view. */
+export interface ActivityBarProps extends Omit<React.HTMLAttributes<HTMLDivElement>, 'onSelect'> {
+  /** Top group of views */
+  items: ActivityBarItem[];
+  /** Bottom group (accounts, settings), pushed to the foot of the bar */
+  footerItems?: ActivityBarItem[];
+  /** id of the selected item */
+  active?: string;
+  /** Called with the id and item when an item is clicked or chosen with Enter / Space */
+  onSelect?: (id: string, item: ActivityBarItem) => void;
+  /** Which side of the view the bar sits on; the active bar and the --line edge face the view (default left) */
+  side?: 'left' | 'right';
+  /** aria-label of the tablist (default "Views") */
+  labels?: { navigation?: string };
+}
+export declare function ActivityBar(props: ActivityBarProps): JSX.Element;
+
 // --- feedback ---
 /** The brand loader: the Aginies mark animated with CSS keyframes only. Use it wherever the product itself is working (boot, page data, an agent run); use Spinner for a single control. */
 export interface AginiesLoaderProps extends Omit<React.HTMLAttributes<HTMLElement>, 'label'> {
@@ -1994,7 +2125,10 @@ export interface SidePanelProps extends Omit<React.HTMLAttributes<HTMLElement>,
   size?: 'md' | 'lg';
   /** Any width (number = px), overriding size: a 600px trace inspector, "40vw" */
   width?: number | string;
+  /** docked sits in the layout (inside PageLayout, a SidePanel with no mode is docked); overlay (default) is a modal sheet from the right: scrim, focus moved in and kept inside, Esc and scrim click call onClose, focus restored */
   mode?: 'overlay' | 'docked';
+  /** Overlay only: the --overlay scrim behind the sheet (default true) */
+  scrim?: boolean;
   children?: React.ReactNode;
   labels?: { close?: string };
 }

package/dist/index.d.ts

@@ -763,8 +763,12 @@ export interface DataColumn<T = any> {
   sortValue?: (row: T) => any;
   /** right for numbers and amounts */
   align?: 'left' | 'right' | 'center';
+  /** Column width; also the room it needs when `minWidth` is absent (px numbers count for priority hiding) */
   width?: number | string;
+  /** Narrowest width the column may take; priority hiding sums these (default 120px) */
   minWidth?: number | string;
+  /** DataTable only: 1 = always shown (default), higher numbers hide first when the table's own width cannot fit every column */
+  priority?: number;
   /** Custom cell; receives (value, row, index) */
   render?: (value: any, row: T, index: number) => React.ReactNode;
   /** Inline edit on double-click, F2 or the pencil (needs onCellEdit) */
@@ -778,8 +782,8 @@ export interface DataColumn<T = any> {
   className?: string;
 }
 /** Visible strings of a DataTable, overridable per locale. */
-export interface DataTableLabels { empty?: string; emptyHint?: string; loading?: string; error?: string; errorHint?: string; retry?: string; selectAll?: string; selectRow?: string; actions?: string; sortedAsc?: string; sortedDesc?: string; edit?: string; }
-/** Dense record grid for agents, runs, approvals and tenants: sortable columns, selection with select-all, inline cell edit, row actions, sticky header, and the states error → loading → empty → rows. Rows are 32px compact and 44px comfortable. */
+export interface DataTableLabels { empty?: string; emptyHint?: string; loading?: string; error?: string; errorHint?: string; retry?: string; selectAll?: string; selectRow?: string; actions?: string; sortedAsc?: string; sortedDesc?: string; edit?: string; /** aria-label of the row-detail toggle while closed */ expandRow?: string; /** aria-label of the row-detail toggle while open */ collapseRow?: string; }
+/** Dense record grid for agents, runs, approvals and tenants: sortable columns, selection with select-all, inline cell edit, row actions, sticky header, and the states error → loading → empty → rows. Rows are 32px compact and 44px comfortable. At narrow widths it hides columns by `priority` against its own measured width and can pin the first column (`stickyFirst`). */
 export interface DataTableProps<T = any> extends Omit<React.HTMLAttributes<HTMLDivElement>, 'onChange' | 'selected' | 'value'> {
   columns: DataColumn<T>[];
   rows: T[];
@@ -824,6 +828,10 @@ export interface DataTableProps<T = any> extends Omit<React.HTMLAttributes<HTMLD
   rowClassName?: (row: T, index: number) => string | false | undefined;
   /** Key of the row whose detail is open (side panel, split view): aria-current, --selection ground and a --signal edge. Independent of `selected` */
   activeKey?: string | number | null;
+  /** First data column (and the selection column) stays put while the table scrolls sideways, with a hairline shadow once scrolled */
+  stickyFirst?: boolean;
+  /** Called with the keys of the columns hidden by `priority` whenever that set changes ([] when all fit) */
+  onHiddenColumnsChange?: (keys: string[]) => void;
 }
 export declare function DataTable<T = any>(props: DataTableProps<T>): JSX.Element;
 
@@ -1320,24 +1328,103 @@ export declare function Toolbar(props: ToolbarProps): JSX.Element;
 /** Vertical hairline between toolbar groups. */
 export declare function ToolbarSeparator(props: React.HTMLAttributes<HTMLSpanElement>): JSX.Element;
 
-/** The console frame: optional GlobalHeader on top, VerticalNavigation on the left, a scrolling main area with the console gutter, optional SidePanel on the right. */
+/** The console frame: optional GlobalHeader on top, VerticalNavigation on the left, a scrolling main area with the console gutter, optional side panel on the right. It measures its own width: ≥ 1280 everything docked; 1024–1279 the sidebar on its 56px rail; < 1024 the sidebar is a drawer and the side panel a sheet from the right, both opened from a 48px page bar; < 768 the gutter is 16px. */
 export interface PageLayoutProps extends React.HTMLAttributes<HTMLDivElement> {
   /** A GlobalHeader (brand screens) — consoles usually omit it */
   header?: React.ReactNode;
-  /** A VerticalNavigation */
+  /** A VerticalNavigation; it reads its state (docked, rail, drawer) from the PageLayout */
   navigation?: React.ReactNode;
-  /** A side panel: inspector, artifact, conversation */
+  /** A side panel: inspector, artifact, conversation. A SidePanel passed without a mode is docked in the frame */
   sidePanel?: React.ReactNode;
   /** Defaults to --panel-w (288) */
   sidePanelWidth?: number | string;
-  /** Content max width (default --content-max 1440) */
+  /** Content width preset: reading (--content-reading 960: settings, documents, wizards) · default (--content-max 1440) · wide (--content-wide 1920: dashboards that add columns) · full (no cap: tables and canvases) */
+  width?: 'reading' | 'default' | 'wide' | 'full';
+  /** Content max width; overrides width */
   maxWidth?: number | string;
   /** No gutter or max width, and the content fills the main area's height (canvas, split views) */
   flush?: boolean;
+  /** Sidebar state: auto (default, from the measured width), or forced docked / rail / overlay */
+  sidebarMode?: 'auto' | 'docked' | 'rail' | 'overlay';
+  /** Side panel state: auto (default: docked ≥ 1024, overlay below), or forced docked / overlay */
+  panelMode?: 'auto' | 'docked' | 'overlay';
+  /** Overlay drawer open (controlled); uncontrolled it opens from the page bar */
+  sidebarOpen?: boolean;
+  onSidebarOpenChange?: (open: boolean) => void;
+  /** Overlay sheet open (controlled); uncontrolled it opens from the page bar and when a side panel appears while the page is narrow */
+  panelOpen?: boolean;
+  onPanelOpenChange?: (open: boolean) => void;
+  /** The 48px page bar shown while the sidebar or panel is an overlay: false hides it (open them through usePageLayout), a node replaces the mark in its middle */
+  bar?: boolean | React.ReactNode;
+  labels?: { openNav?: string; closeNav?: string; openPanel?: string; closePanel?: string; navigation?: string; details?: string };
   as?: any;
 }
 export declare function PageLayout(props: PageLayoutProps): JSX.Element;
 
+/** State of the enclosing PageLayout, for a page that needs to adapt (drop table columns, put the menu button in its own header). */
+export interface PageLayoutState {
+  /** Breakpoint of the page's own width */
+  bp: Breakpoint;
+  sidebar: 'docked' | 'rail' | 'overlay' | null;
+  panel: 'docked' | 'overlay' | null;
+  railExpanded: boolean;
+  setRailExpanded: (expanded: boolean) => void;
+  sidebarOpen: boolean;
+  openSidebar: () => void;
+  closeSidebar: () => void;
+  panelOpen: boolean;
+  openPanel: () => void;
+  closePanel: () => void;
+}
+/** The enclosing PageLayout's state; null outside one. */
+export declare function usePageLayout(): PageLayoutState | null;
+export declare const PageLayoutContext: React.Context<PageLayoutState | null>;
+
+/** Breakpoint names: base < 640 ≤ sm < 768 ≤ md < 1024 ≤ lg < 1280 ≤ xl < 1536 ≤ 2xl (tokens bp-sm … bp-2xl). */
+export type Breakpoint = 'base' | 'sm' | 'md' | 'lg' | 'xl' | '2xl';
+/** A value per breakpoint, mobile first: each one holds until a larger breakpoint sets another. */
+export type Responsive<T> = T | Partial<Record<Breakpoint, T>>;
+
+/** 12-column grid (--grid-columns, --grid-gap) laid out by its own width through a container query, so it responds to its pane, not the window. Dashboards, record bodies, card galleries. */
+export interface GridProps extends React.HTMLAttributes<HTMLElement> {
+  /** Gallery mode: auto-fill columns at least this wide (number = px), e.g. 280 for cards. GridItem spans are ignored */
+  min?: number | string;
+  /** Column count (default --grid-columns, 12) */
+  columns?: number;
+  /** Gap: lg (default, --grid-gap 24), md 16, sm 12, none, or any length */
+  gap?: 'none' | 'sm' | 'md' | 'lg' | number | string;
+  /** Row gap when it differs from gap */
+  rowGap?: 'none' | 'sm' | 'md' | 'lg' | number | string;
+  /** Vertical alignment of items in a row (default stretch) */
+  align?: 'start' | 'center' | 'end';
+  /** Back-fills holes left by wide items */
+  dense?: boolean;
+  as?: any;
+}
+export declare function Grid(props: GridProps): JSX.Element;
+/** One cell of a Grid. */
+export interface GridItemProps extends React.HTMLAttributes<HTMLElement> {
+  /** Columns to span: a number, 'full', or per breakpoint of the Grid's width ({ base: 12, lg: 6, xl: 4 }). Default 12 */
+  span?: Responsive<number | 'full'>;
+  /** Starting column line */
+  start?: number;
+  /** Rows to span */
+  rowSpan?: number;
+  as?: any;
+}
+export declare function GridItem(props: GridItemProps): JSX.Element;
+
+/** Breakpoint values in px (= tokens): { sm: 640, md: 768, lg: 1024, xl: 1280, '2xl': 1536 }. */
+export declare const BREAKPOINTS: Record<Exclude<Breakpoint, 'base'>, number>;
+/** Name of the largest breakpoint a width reaches. */
+export declare function breakpointFor(width: number): Breakpoint;
+/** Width (px) of an element, kept current with a ResizeObserver; null until measured. */
+export declare function useElementWidth(ref: React.RefObject<Element>): number | null;
+/** Breakpoint of an element's own width; null until measured. Use it to drop low-priority table columns in a narrow pane. */
+export declare function useBreakpoint(ref: React.RefObject<Element>): Breakpoint | null;
+/** Drawer/sheet focus handling: focus moves into the container on open, Tab stays inside, Esc calls onClose, focus returns on close. */
+export declare function useOverlayFocus(ref: React.RefObject<HTMLElement>, open: boolean, onClose?: () => void): void;
+
 /** The website's .room: a section that inverts the theme inside — sets data-theme opposite to its ancestor and paints --bg. */
 export interface RoomProps extends React.HTMLAttributes<HTMLElement> {
   /** Force a theme instead of inverting the ancestor's */
@@ -1412,7 +1499,9 @@ export interface VerticalNavigationProps extends Omit<React.HTMLAttributes<HTMLE
   /** Each new width while resizing; persist it and pass it back as width */
   onResize?: (width: number) => void;
   logoHref?: string;
-  labels?: { search?: string; collapse?: string; expand?: string; navigation?: string; resize?: string };
+  /** Layout state. Omit it inside PageLayout, which sets it from its width: docked ≥ 1280, rail 1024–1279 (collapsed to 56px until the user expands it), overlay < 1024 (a drawer with a close button that closes when an item is chosen). Standalone default: docked */
+  mode?: 'docked' | 'rail' | 'overlay';
+  labels?: { search?: string; collapse?: string; expand?: string; navigation?: string; resize?: string; close?: string };
 }
 export declare function VerticalNavigation(props: VerticalNavigationProps): JSX.Element;
 
@@ -1511,7 +1600,15 @@ export interface SplitViewProps extends Omit<React.HTMLAttributes<HTMLDivElement
   resizable?: boolean;
   /** Shows a toggle that hides the list */
   collapsible?: boolean;
-  labels?: { resize?: string; empty?: string; collapse?: string; expand?: string };
+  /** Width of the SplitView itself (a breakpoint name or px) below which list and detail stack: the list fills the pane and a picked record opens as a full pane with a back button. Default 'md' (768); false never stacks. Below 'lg' (1024) the list narrows to --panel-w */
+  stackBelow?: 'sm' | 'md' | 'lg' | 'xl' | number | false;
+  /** Pane shown first when stacked (default 'list') */
+  defaultStackedView?: 'list' | 'detail';
+  /** Called when the stacked pane changes */
+  onStackedViewChange?: (view: 'list' | 'detail') => void;
+  /** Called by the stacked detail's back button (after it returns to the list) */
+  onBack?: () => void;
+  labels?: { resize?: string; empty?: string; collapse?: string; expand?: string; back?: string };
 }
 export declare function SplitView(props: SplitViewProps): JSX.Element;
 
@@ -1720,6 +1817,40 @@ export interface StepperProps extends Omit<React.HTMLAttributes<HTMLOListElement
 }
 export declare function Stepper(props: StepperProps): JSX.Element;
 
+/** One view in an ActivityBar. */
+export interface ActivityBarItem {
+  /** Value passed to onSelect and matched against `active` */
+  id: string;
+  /** Lucide icon name (kebab-case), or a node such as <ProductIcon product="code" size={20} /> */
+  icon: string | React.ReactNode;
+  /** Accessible name and tooltip text */
+  label: string;
+  /** Small count Badge on the icon (a number, or a short word) */
+  badge?: number | string;
+  /** Shown dimmed, skipped by the arrow keys, not selectable */
+  disabled?: boolean;
+  /** id of the view panel this item opens (sets aria-controls) */
+  controls?: string;
+  /** id for the tab button, so the panel can point back with aria-labelledby */
+  tabId?: string;
+}
+/** Vertical 48px icon strip that switches the view beside it, like VS Code's activity bar or IntelliJ's tool-window bar: use it in IDE mocks and the web build of the Code panel. A vertical tablist with roving focus (↑ ↓ Home End, Enter or Space selects), tooltips with each label, a 2px --signal bar on the edge facing the view. */
+export interface ActivityBarProps extends Omit<React.HTMLAttributes<HTMLDivElement>, 'onSelect'> {
+  /** Top group of views */
+  items: ActivityBarItem[];
+  /** Bottom group (accounts, settings), pushed to the foot of the bar */
+  footerItems?: ActivityBarItem[];
+  /** id of the selected item */
+  active?: string;
+  /** Called with the id and item when an item is clicked or chosen with Enter / Space */
+  onSelect?: (id: string, item: ActivityBarItem) => void;
+  /** Which side of the view the bar sits on; the active bar and the --line edge face the view (default left) */
+  side?: 'left' | 'right';
+  /** aria-label of the tablist (default "Views") */
+  labels?: { navigation?: string };
+}
+export declare function ActivityBar(props: ActivityBarProps): JSX.Element;
+
 // --- feedback ---
 /** The brand loader: the Aginies mark animated with CSS keyframes only. Use it wherever the product itself is working (boot, page data, an agent run); use Spinner for a single control. */
 export interface AginiesLoaderProps extends Omit<React.HTMLAttributes<HTMLElement>, 'label'> {
@@ -1994,7 +2125,10 @@ export interface SidePanelProps extends Omit<React.HTMLAttributes<HTMLElement>,
   size?: 'md' | 'lg';
   /** Any width (number = px), overriding size: a 600px trace inspector, "40vw" */
   width?: number | string;
+  /** docked sits in the layout (inside PageLayout, a SidePanel with no mode is docked); overlay (default) is a modal sheet from the right: scrim, focus moved in and kept inside, Esc and scrim click call onClose, focus restored */
   mode?: 'overlay' | 'docked';
+  /** Overlay only: the --overlay scrim behind the sheet (default true) */
+  scrim?: boolean;
   children?: React.ReactNode;
   labels?: { close?: string };
 }