@geomak/ui 5.0.3 → 5.2.0

package/dist/index.d.ts

@@ -339,6 +339,268 @@ interface PortalProps {
  */
 declare function Portal({ children, target }: PortalProps): React$1.ReactPortal;
 
+type Spacing = 'none' | 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl';
+type BoxBackground = 'none' | 'background' | 'surface' | 'surface-raised' | 'accent';
+type BoxBorder = 'none' | 'border' | 'border-strong' | 'accent' | 'status-error';
+type BoxRadius = 'none' | 'sm' | 'md' | 'lg' | 'xl' | '2xl' | 'full';
+type BoxShadow = 'none' | 'sm' | 'md' | 'lg' | 'xl';
+interface BoxProps {
+    as?: keyof React$1.JSX.IntrinsicElements;
+    /** Padding shorthand — applies to all sides. */
+    p?: Spacing;
+    /** Horizontal padding (left + right). */
+    px?: Spacing;
+    /** Vertical padding (top + bottom). */
+    py?: Spacing;
+    pt?: Spacing;
+    pr?: Spacing;
+    pb?: Spacing;
+    pl?: Spacing;
+    /** Margin shorthand. */
+    m?: Spacing;
+    mx?: Spacing;
+    my?: Spacing;
+    mt?: Spacing;
+    mr?: Spacing;
+    mb?: Spacing;
+    ml?: Spacing;
+    background?: BoxBackground;
+    border?: BoxBorder;
+    radius?: BoxRadius;
+    shadow?: BoxShadow;
+    /** Width via Tailwind class or CSS value. */
+    width?: string | number;
+    /** Height via Tailwind class or CSS value. */
+    height?: string | number;
+    /** Click handler — accepts any element-typed handler. */
+    onClick?: React$1.MouseEventHandler<HTMLElement>;
+    className?: string;
+    style?: React$1.CSSProperties;
+    children?: React$1.ReactNode;
+}
+/**
+ * A polymorphic layout primitive — a `<div>` (by default) styled via prop
+ * shortcuts to the design system's tokenised spacing, surface, border,
+ * radius, and shadow scales. Use it when you'd otherwise reach for a
+ * className-only `<div>` with `p-4 bg-surface border border-border rounded-lg`.
+ *
+ * The token shortcuts map straight to Tailwind classes under the hood, so
+ * Tailwind's content scanner sees the classes and JIT-emits the CSS. There
+ * is no runtime style cost beyond the className concatenation.
+ *
+ * Use `as` when the semantic element should differ (`<section>`, `<article>`).
+ *
+ * @example Padded card surface
+ * ```tsx
+ * <Box p="lg" background="surface" border="border" radius="lg" shadow="sm">
+ *   <Typography variant="h3">Card title</Typography>
+ * </Box>
+ * ```
+ *
+ * @example Semantic section
+ * ```tsx
+ * <Box as="section" px="md" py="lg" background="background">
+ *   <PageContent />
+ * </Box>
+ * ```
+ */
+declare function Box({ as, p, px, py, pt, pr, pb, pl, m, mx, my, mt, mr, mb, ml, background, border, radius, shadow, width, height, onClick, className, style, children, }: BoxProps): react_jsx_runtime.JSX.Element;
+
+type FlexDirection = 'row' | 'row-reverse' | 'col' | 'col-reverse';
+type FlexAlign = 'start' | 'center' | 'end' | 'stretch' | 'baseline';
+type FlexJustify = 'start' | 'center' | 'end' | 'between' | 'around' | 'evenly';
+type FlexWrap = 'nowrap' | 'wrap' | 'wrap-reverse';
+interface FlexProps extends BoxProps {
+    direction?: FlexDirection;
+    align?: FlexAlign;
+    justify?: FlexJustify;
+    wrap?: FlexWrap;
+    /** Gap between children — uses the same spacing token scale as Box. */
+    gap?: Spacing;
+    inline?: boolean;
+}
+/**
+ * `Box` with `display: flex` baked in. All Box props are accepted (padding,
+ * margin, background, border, etc.) plus flex-specific controls.
+ *
+ * @example Horizontal row, centred, with gap
+ * ```tsx
+ * <Flex direction="row" align="center" gap="md">
+ *   <Avatar src={user.photo} alt={user.name} />
+ *   <Typography variant="body">{user.name}</Typography>
+ * </Flex>
+ * ```
+ *
+ * @example Vertical stack
+ * ```tsx
+ * <Flex direction="col" gap="sm">
+ *   <Typography variant="h3">Title</Typography>
+ *   <Typography variant="body">Body text</Typography>
+ * </Flex>
+ * ```
+ */
+declare function Flex({ direction, align, justify, wrap, gap, inline, className, ...boxProps }: FlexProps): react_jsx_runtime.JSX.Element;
+
+interface GridProps extends BoxProps {
+    /**
+     * Number of columns (1–12) for the most common case, OR an explicit
+     * CSS grid-template-columns string for arbitrary layouts
+     * (e.g. `"200px 1fr"` or `"repeat(auto-fit, minmax(180px, 1fr))"`).
+     */
+    cols?: number | string;
+    /** Same as `cols` but for rows. */
+    rows?: number | string;
+    /** Uniform gap. Token scale, like Box's padding. */
+    gap?: Spacing;
+    /** Horizontal-only gap (overrides `gap`). */
+    gapX?: Spacing;
+    /** Vertical-only gap (overrides `gap`). */
+    gapY?: Spacing;
+    /** Cross-axis alignment of items within their cell. */
+    align?: 'start' | 'center' | 'end' | 'stretch';
+    /** Main-axis alignment of items within their cell. */
+    justify?: 'start' | 'center' | 'end' | 'stretch';
+}
+/**
+ * `Box` with `display: grid` baked in. Use `cols` / `rows` as numbers for
+ * the common "N equal tracks" case, or pass any CSS grid-template-* string
+ * for arbitrary layouts (auto-fit grids, fixed-width sidebars, etc.).
+ *
+ * @example 3-column grid with medium gap
+ * ```tsx
+ * <Grid cols={3} gap="md">
+ *   <Card />
+ *   <Card />
+ *   <Card />
+ * </Grid>
+ * ```
+ *
+ * @example Auto-fit responsive grid
+ * ```tsx
+ * <Grid cols="repeat(auto-fit, minmax(220px, 1fr))" gap="lg">
+ *   {items.map((it) => <Card key={it.id} {...it} />)}
+ * </Grid>
+ * ```
+ */
+declare function Grid({ cols, rows, gap, gapX, gapY, align, justify, className, style, ...boxProps }: GridProps): react_jsx_runtime.JSX.Element;
+
+type AvatarSize = 'xs' | 'sm' | 'md' | 'lg' | 'xl';
+type AvatarShape = 'circle' | 'square';
+type AvatarStatus = 'online' | 'offline' | 'away' | 'busy';
+interface AvatarProps {
+    /** Image URL. If missing or fails to load, `fallback` renders instead. */
+    src?: string;
+    /** Alt text — required when `src` is provided for screen readers. */
+    alt?: string;
+    /**
+     * Fallback rendered when the image is unavailable. Pass either:
+     * - a string (e.g. user initials like "JD") — rendered with semi-bold weight
+     * - any ReactNode (icon, emoji)
+     * - omit entirely — a generic "person" silhouette is used
+     */
+    fallback?: React$1.ReactNode;
+    /** Size preset. Default `'md'`. */
+    size?: AvatarSize;
+    /** Circle (default) or rounded square. */
+    shape?: AvatarShape;
+    /**
+     * Optional presence indicator dot in the bottom-right corner.
+     * `'online' | 'offline' | 'away' | 'busy'`.
+     */
+    status?: AvatarStatus;
+    className?: string;
+}
+/**
+ * Circular (or rounded-square) user avatar built on `@radix-ui/react-avatar`.
+ * Radix handles the image-load lifecycle: it tries to load `src`, falls back
+ * to the `fallback` slot after a short delay if the image is missing or fails
+ * to decode, and re-attempts on `src` change.
+ *
+ * **Fallback strategy** (in order):
+ * 1. `fallback` prop if provided (string or ReactNode)
+ * 2. Two-character initials extracted from `alt` if `alt` is provided
+ * 3. A generic "person" silhouette SVG
+ *
+ * **Status dot** is an optional presence indicator in the bottom-right —
+ * online (green), away (amber), busy (red), offline (grey).
+ *
+ * @example Basic with image
+ * ```tsx
+ * <Avatar src="/users/jd.jpg" alt="Jane Doe" />
+ * ```
+ *
+ * @example Fallback to initials
+ * ```tsx
+ * <Avatar alt="Jane Doe" size="lg" />
+ * ```
+ *
+ * @example Online presence + square shape
+ * ```tsx
+ * <Avatar src={user.photo} alt={user.name} status="online" shape="square" />
+ * ```
+ */
+declare function Avatar({ src, alt, fallback, size, shape, status, className, }: AvatarProps): react_jsx_runtime.JSX.Element;
+
+type TypographyVariant = 'display' | 'h1' | 'h2' | 'h3' | 'h4' | 'subtitle' | 'body' | 'caption' | 'overline' | 'code';
+type TypographyColor = 'foreground' | 'foreground-secondary' | 'foreground-muted' | 'accent' | 'status-error' | 'status-warning' | 'status-success' | 'status-info' | 'inherit';
+type TypographyWeight = 'normal' | 'medium' | 'semibold' | 'bold';
+type TypographyAlign = 'left' | 'center' | 'right' | 'justify';
+interface TypographyProps {
+    /** Visual scale variant. */
+    variant?: TypographyVariant;
+    /**
+     * Element to render. Defaults are sensible per variant
+     * (e.g. h1 → `<h1>`, body → `<p>`, code → `<code>`). Override
+     * with `as` when the semantic element should differ from the visual
+     * style (e.g. a styled-as-h1 product card heading rendered as `<div>`).
+     */
+    as?: keyof React$1.JSX.IntrinsicElements;
+    color?: TypographyColor;
+    weight?: TypographyWeight;
+    align?: TypographyAlign;
+    /** Truncate to one line with ellipsis. */
+    truncate?: boolean;
+    /** Render the text with reduced opacity (useful for disabled states). */
+    muted?: boolean;
+    className?: string;
+    style?: React$1.CSSProperties;
+    children?: React$1.ReactNode;
+}
+/**
+ * Polymorphic typography primitive. `variant` picks a visual scale; `as`
+ * controls the rendered element when it should differ from the default
+ * for that variant (e.g. a styled-as-h2 card title rendered as `<div>`).
+ *
+ * **Variants** map to the design-system text scale:
+ * - `display`: hero headlines
+ * - `h1` – `h4`: section / subsection headings
+ * - `subtitle`: emphasised lead text
+ * - `body` (default): paragraph text
+ * - `caption`: small label / hint text
+ * - `overline`: uppercase eyebrow text
+ * - `code`: inline code samples
+ *
+ * **Colour** accepts any semantic token; defaults to `inherit` so the
+ * parent's text colour flows through (useful when nesting Typography
+ * inside a coloured surface like an accent badge).
+ *
+ * @example Section heading
+ * ```tsx
+ * <Typography variant="h2">Vessel performance</Typography>
+ * ```
+ *
+ * @example Styled as h1 but rendered as div (for SEO-neutral cards)
+ * ```tsx
+ * <Typography variant="h1" as="div">Card title</Typography>
+ * ```
+ *
+ * @example Error message
+ * ```tsx
+ * <Typography variant="caption" color="status-error">{errorText}</Typography>
+ * ```
+ */
+declare function Typography({ variant, as, color, weight, align, truncate, muted, className, style, children, }: TypographyProps): react_jsx_runtime.JSX.Element;
+
 type IconButtonVariant = 'primary' | 'bordered';
 interface IconButtonProps {
     icon?: React.ReactNode;
@@ -699,25 +961,71 @@ interface FadingBaseProps {
 declare function FadingBase({ className, isMounted, children, }: FadingBaseProps): react_jsx_runtime.JSX.Element;
 
 interface ListItem {
+    /** Stable key for React reconciliation + active-key matching. */
     key: string | number;
+    /** Main item text (title). Required. */
     label: React$1.ReactNode;
+    /** Optional description rendered below the label, in foreground-secondary. */
+    description?: React$1.ReactNode;
+    /**
+     * Optional leading slot, typically an Avatar. Anything React-renderable
+     * is accepted (icon, image, status badge…).
+     */
+    avatar?: React$1.ReactNode;
+    /** Optional trailing slot, e.g. a badge, count, or action icon. */
+    trailing?: React$1.ReactNode;
+    /** Disable interaction for this item only. */
+    disabled?: boolean;
 }
 interface ListProps {
     items: ListItem[];
     onItemClick: (item: ListItem) => void;
     activeKey?: string | number;
+    /**
+     * Visual density. `'compact'` for dense reference lists,
+     * `'comfortable'` (default) for typical UI, `'spacious'` for hero rows.
+     */
+    density?: 'compact' | 'comfortable' | 'spacious';
 }
 /**
- * Vertical clickable list with active-item highlight.
+ * Vertical clickable list with optional avatar / description / trailing
+ * slots per item. Built on `role="listbox"` + `role="option"` so screen
+ * readers announce it as a selectable list. Keyboard activation works on
+ * Enter and Space.
  *
- * @example
+ * **When to use this** over a Table:
+ * - When the dataset is a simple sequence of records that the user
+ *   browses + picks one of (sidebar nav, contact list, vessel chooser).
+ * - When each row's primary signal is a 1–2-line summary, not a tabular
+ *   breakdown.
+ *
+ * Use Table when comparing rows across multiple columns matters more than
+ * picking one.
+ *
+ * @example Plain
+ * ```tsx
+ * <List
+ *   items={[{ key: 1, label: 'Aurora' }, { key: 2, label: 'Beacon' }]}
+ *   activeKey={2}
+ *   onItemClick={(it) => setSelected(it.key)}
+ * />
+ * ```
+ *
+ * @example With avatars + descriptions
+ * ```tsx
  * <List
- *   items={vessels.map(v => ({ key: v.imo, label: v.name }))}
- *   activeKey={selectedImo}
- *   onItemClick={(item) => setSelected(item.key)}
+ *   items={crew.map((c) => ({
+ *     key: c.id,
+ *     label: c.name,
+ *     description: c.rank,
+ *     avatar: <Avatar src={c.photo} alt={c.name} status={c.status} />,
+ *     trailing: <Badge count={c.unread} />,
+ *   }))}
+ *   onItemClick={(it) => navigate(`/crew/${it.key}`)}
  * />
+ * ```
  */
-declare function List({ items, onItemClick, activeKey }: ListProps): react_jsx_runtime.JSX.Element;
+declare function List({ items, onItemClick, activeKey, density, }: ListProps): react_jsx_runtime.JSX.Element;
 
 interface ScalableContainerProps {
     /** Resting width. Any CSS length / percent. Default `'100%'`. */
@@ -1076,6 +1384,16 @@ interface TableProps<T extends Record<string, any> = Record<string, any>> {
     hasSearch?: boolean;
     footer?: React$1.ReactNode;
     header?: React$1.ReactNode;
+    /**
+     * When `true`, the body renders skeleton rows (one per column with the
+     * shared shimmer animation) instead of data. Use during initial data
+     * fetch, server-side pagination transitions, or any time the dataset is
+     * not yet ready. Combine with `pagination.serverSide` for the canonical
+     * "loading next page" pattern.
+     */
+    loading?: boolean;
+    /** Number of skeleton rows to render when `loading` is true. Default `8`. */
+    loadingRowCount?: number;
 }
 /** ─────────────────── main component ─────────────────── */
 /**
@@ -1118,7 +1436,7 @@ interface TableProps<T extends Record<string, any> = Record<string, any>> {
  * />
  * ```
  */
-declare function Table<T extends Record<string, any> = Record<string, any>>({ columns, rows, getRowKey, pagination, expandRow, hasSearch, footer, header, }: TableProps<T>): react_jsx_runtime.JSX.Element;
+declare function Table<T extends Record<string, any> = Record<string, any>>({ columns, rows, getRowKey, pagination, expandRow, hasSearch, footer, header, loading, loadingRowCount, }: TableProps<T>): react_jsx_runtime.JSX.Element;
 
 interface ThemeSwitchProps {
     checked: boolean;
@@ -1786,25 +2104,67 @@ interface AutoCompleteProps {
     style?: React$1.CSSProperties;
     /** Label/input orientation. Defaults to `'vertical'`. */
     layout?: 'horizontal' | 'vertical';
+    /**
+     * Static list — when provided, the component does its own substring
+     * filtering on `label` and `key`. Mutually exclusive with `onSearch`.
+     */
     items?: AutoCompleteItem[];
+    /**
+     * Async resolver — when provided, `items` is ignored and `onSearch(term)`
+     * is called (debounced) every time the user pauses typing. Its returned
+     * promise drives the option list. The component manages an internal
+     * `loading` state and shows an `xs` LoadingSpinner where the search icon
+     * normally lives while a query is in flight.
+     */
+    onSearch?: (term: string) => Promise<AutoCompleteItem[]>;
+    /**
+     * Debounce delay (ms) before `onSearch` fires after the user stops
+     * typing. Default `250`. Ignored when `items` is used.
+     */
+    debounce?: number;
     onItemClick?: (value: string) => void;
     /** Custom "empty" message */
     emptyText?: string;
+    /** Custom "loading" message — shown in async mode while a query is in flight. */
+    loadingText?: string;
 }
 /**
- * Search-as-you-type autocomplete powered by Radix Popover.
+ * Search-as-you-type autocomplete powered by Radix Popover. Supports two
+ * modes:
+ *
+ * - **Static**: pass `items` — the component substring-filters locally.
+ *   Best for small fixed lists (≤ 200 entries).
+ * - **Async**: pass `onSearch(term) => Promise<Item[]>` — the component
+ *   debounces input and drives the option list from the resolver. Shows
+ *   an `xs` LoadingSpinner while the query is in flight.
  *
  * The popover opens when the input is focused and closes when an item is
- * selected or the user clicks away. Radix handles portal-based z-stacking.
+ * selected or the user clicks away.
  *
- * @example
+ * @example Static (small fixed list)
+ * ```tsx
  * <AutoComplete
  *   label="Vessel"
- *   items={vessels.map(v => ({ key: v.imo, value: v.imo, label: v.name }))}
+ *   items={vessels.map((v) => ({ key: v.imo, value: v.imo, label: v.name }))}
  *   onItemClick={(imo) => setVessel(imo)}
  * />
+ * ```
+ *
+ * @example Async (server-backed)
+ * ```tsx
+ * <AutoComplete
+ *   label="Port"
+ *   debounce={300}
+ *   onSearch={async (term) => {
+ *     const res = await fetch(`/api/ports?q=${encodeURIComponent(term)}`)
+ *     const data = await res.json()
+ *     return data.map((p) => ({ key: p.unlocode, value: p.unlocode, label: p.name }))
+ *   }}
+ *   onItemClick={(unlocode) => setPort(unlocode)}
+ * />
+ * ```
  */
-declare function AutoComplete({ disabled, label, placeholder, name, inputStyle, style, layout, items, onItemClick, emptyText, }: AutoCompleteProps): react_jsx_runtime.JSX.Element;
+declare function AutoComplete({ disabled, label, placeholder, name, inputStyle, style, layout, items, onSearch, debounce, onItemClick, emptyText, loadingText, }: AutoCompleteProps): react_jsx_runtime.JSX.Element;
 
 interface TreeSelectNode {
     key: string | number;
@@ -1980,4 +2340,4 @@ type TemporalPickerProps = DatePickerProps;
  */
 declare function DatePicker({ value, onChange, label, placeholder, htmlFor, name: _name, layout, disabled, errorMessage, min, max, style, format, weekStartsOn, clearable, }: DatePickerProps): react_jsx_runtime.JSX.Element;
 
-export { AppShell, type AppShellProps, AutoComplete, type AutoCompleteProps, Button, type ButtonProps, Catalog, CatalogCarousel, type CatalogCarouselProps, CatalogGrid, type CatalogGridProps, type CatalogProps, Checkbox, type CheckboxProps, ContextMenu, type ContextMenuActionItem, type ContextMenuPosition, type ContextMenuProps, type DatePickerProps, Drawer, type DrawerProps, Dropdown, type DropdownItem, type DropdownProps, type ExpandRowOptions, FadingBase, type FadingBaseProps, FileInput, type FileInputProps, GridCard, type GridCardItem, type GridCardProps, Icon, IconButton, type IconButtonProps, List, type ListItem, type ListProps, LoadingSpinner, type LoadingSpinnerProps, Modal, type ModalProps, type NotificationPayload, NotificationProvider, NumberInput, type NumberInputProps, OpaqueGridCard, type OpaqueGridCardProps, type PaginationOptions, Password, type PasswordProps, Portal, type PortalProps, ScalableContainer, type ScalableContainerProps, SearchInput, type SearchInputProps, Sidebar, type SidebarItem, type SidebarProps, type SidebarSection, SkeletonBox, type SkeletonBoxProps, SkeletonCard, type SkeletonCardProps, SkeletonCircle, type SkeletonCircleProps, SkeletonText, type SkeletonTextProps, Switch, type SwitchInputProps, type TabItem, Table, type TableColumn, type TableProps, Tabs, type TabsProps, DatePicker as Temporal, type TemporalPickerProps, TextInput, type TextInputProps, type ThemeColors, type ThemeConfig, type ThemeDensity, type ThemeMotion, ThemeProvider, type ThemeProviderProps, type ThemeRadius, type ThemeShadows, ThemeSwitch, type ThemeSwitchProps, type ThemeTypography, ToggleButton, type ToggleButtonProps, type ToggleItem, Tooltip, type TooltipProps, TooltipProvider, TopBar, type TopBarProps, Tree, type TreeItemClickPayload, type TreeNode, type TreeProps, TreeSelect, type TreeSelectProps, Wizard, type WizardProps, type WizardStep, useNotification };
+export { AppShell, type AppShellProps, AutoComplete, type AutoCompleteProps, Avatar, type AvatarProps, type AvatarShape, type AvatarSize, type AvatarStatus, Box, type BoxBackground, type BoxBorder, type BoxProps, type BoxRadius, type BoxShadow, Button, type ButtonProps, Catalog, CatalogCarousel, type CatalogCarouselProps, CatalogGrid, type CatalogGridProps, type CatalogProps, Checkbox, type CheckboxProps, ContextMenu, type ContextMenuActionItem, type ContextMenuPosition, type ContextMenuProps, type DatePickerProps, Drawer, type DrawerProps, Dropdown, type DropdownItem, type DropdownProps, type ExpandRowOptions, FadingBase, type FadingBaseProps, FileInput, type FileInputProps, Flex, type FlexAlign, type FlexDirection, type FlexJustify, type FlexProps, type FlexWrap, Grid, GridCard, type GridCardItem, type GridCardProps, type GridProps, Icon, IconButton, type IconButtonProps, List, type ListItem, type ListProps, LoadingSpinner, type LoadingSpinnerProps, Modal, type ModalProps, type NotificationPayload, NotificationProvider, NumberInput, type NumberInputProps, OpaqueGridCard, type OpaqueGridCardProps, type PaginationOptions, Password, type PasswordProps, Portal, type PortalProps, ScalableContainer, type ScalableContainerProps, SearchInput, type SearchInputProps, Sidebar, type SidebarItem, type SidebarProps, type SidebarSection, SkeletonBox, type SkeletonBoxProps, SkeletonCard, type SkeletonCardProps, SkeletonCircle, type SkeletonCircleProps, SkeletonText, type SkeletonTextProps, type Spacing, Switch, type SwitchInputProps, type TabItem, Table, type TableColumn, type TableProps, Tabs, type TabsProps, DatePicker as Temporal, type TemporalPickerProps, TextInput, type TextInputProps, type ThemeColors, type ThemeConfig, type ThemeDensity, type ThemeMotion, ThemeProvider, type ThemeProviderProps, type ThemeRadius, type ThemeShadows, ThemeSwitch, type ThemeSwitchProps, type ThemeTypography, ToggleButton, type ToggleButtonProps, type ToggleItem, Tooltip, type TooltipProps, TooltipProvider, TopBar, type TopBarProps, Tree, type TreeItemClickPayload, type TreeNode, type TreeProps, TreeSelect, type TreeSelectProps, Typography, type TypographyAlign, type TypographyColor, type TypographyProps, type TypographyVariant, type TypographyWeight, Wizard, type WizardProps, type WizardStep, useNotification };