@aginies/ui 0.1.0 → 0.2.0

package/dist/index.d.cts

@@ -1320,24 +1320,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 +1491,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 +1592,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;
 
@@ -1994,7 +2083,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

@@ -1320,24 +1320,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 +1491,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 +1592,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;
 
@@ -1994,7 +2083,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 };
 }