@geomak/ui 1.2.0 → 1.4.0

package/dist/index.d.cts

@@ -1,4 +1,4 @@
-export { C as COLORS, S as SemanticColorKey, a as SemanticRadiusKey, V as VarColorKey, b as VarRadiusKey, c as VarShadowKey, P as palette, s as semanticTokens, v as vars } from './index-CPCiQllz.cjs';
+export { C as COLORS, S as SemanticColorKey, a as SemanticRadiusKey, V as VarColorKey, b as VarRadiusKey, c as VarShadowKey, P as palette, s as semanticTokens, v as vars } from './index-DLGzTj3K.cjs';
 import * as react_jsx_runtime from 'react/jsx-runtime';
 import React$1 from 'react';
 import * as TooltipPrimitive from '@radix-ui/react-tooltip';
@@ -329,26 +329,31 @@ declare function Drawer({ isOpen, onClose, hasFooter, placement, width, okText,
 
 interface TooltipProps {
     children: React$1.ReactNode;
+    /** The text or node shown inside the tooltip */
     title: React$1.ReactNode;
-    /** 'top' | 'right' | 'bottom' | 'left' */
+    /** Which side of the trigger the tooltip appears on */
     placement?: 'top' | 'right' | 'bottom' | 'left';
-    /** Delay in ms before showing the tooltip */
+    /** Delay before showing, ms (default 300) */
     delayDuration?: number;
+    /** Offset from trigger in px (default 8) */
+    sideOffset?: number;
 }
 /**
  * Tooltip powered by Radix Tooltip.
  *
- * Radix handles keyboard navigation (escape), pointer events, and ARIA.
- * The VesOPS prussian-blue style is preserved.
- *
- * Wrap your app in `<TooltipProvider>` (re-exported below) to batch providers.
+ * Radix handles keyboard navigation (Escape), pointer events, and ARIA.
+ * Each placement animates in from the correct direction.
+ * Wrap your app in `<TooltipProvider>` (re-exported below) to share a
+ * single provider instead of nesting one per tooltip.
  *
  * @example
- * <Tooltip title="Delete record" placement="right">
- *   <IconButton icon={<Icon.Trash />} />
- * </Tooltip>
+ * <TooltipProvider>
+ *   <Tooltip title="Delete record" placement="top">
+ *     <IconButton icon={<TrashIcon />} />
+ *   </Tooltip>
+ * </TooltipProvider>
  */
-declare function Tooltip({ children, title, placement, delayDuration, }: TooltipProps): react_jsx_runtime.JSX.Element;
+declare function Tooltip({ children, title, placement, delayDuration, sideOffset, }: TooltipProps): react_jsx_runtime.JSX.Element;
 
 declare const TooltipProvider: React$1.FC<TooltipPrimitive.TooltipProviderProps>;
 
@@ -452,6 +457,7 @@ declare function ToggleButton({ items, onChange, activeKey }: ToggleButtonProps)
 
 /** ─────────────────── types ─────────────────── */
 type NotificationType = 'info' | 'success' | 'warning' | 'danger';
+type NotificationPosition = 'top-right' | 'top-left' | 'top-center' | 'bottom-right' | 'bottom-left' | 'bottom-center';
 interface NotificationPayload {
     title: React$1.ReactNode;
     description?: React$1.ReactNode;
@@ -461,32 +467,20 @@ interface NotificationPayload {
 }
 /** ─────────────────── provider ─────────────────── */
 /**
- * Wrap your application (or a subtree) in `NotificationProvider` to enable
- * toast notifications. Then call `useNotification()` anywhere inside to
- * trigger them.
+ * Wrap your app in `NotificationProvider`, then call `useNotification()` anywhere inside.
+ *
+ * @param position  One of 6 viewport positions (default: `top-right`)
  *
  * @example
- * // _app.tsx / main.tsx
- * <NotificationProvider>
+ * <NotificationProvider position="bottom-right">
  *   <App />
  * </NotificationProvider>
- *
- * // Inside a component
- * const notify = useNotification()
- * notify.success({ title: 'Saved!', description: 'Your changes were saved.', duration: 3000 })
  */
-declare function NotificationProvider({ children }: {
+declare function NotificationProvider({ children, position, }: {
     children: React$1.ReactNode;
+    position?: NotificationPosition;
 }): react_jsx_runtime.JSX.Element;
 /** ─────────────────── hook ─────────────────── */
-/**
- * Imperative notification API.
- *
- * @example
- * const notify = useNotification()
- * notify.success({ title: 'Done', description: 'Record saved.', duration: 3000 })
- * notify.danger({ title: 'Error', description: err.message })
- */
 declare function useNotification(): {
     info: (props: Omit<NotificationPayload, "type">) => void;
     success: (props: Omit<NotificationPayload, "type">) => void;
@@ -827,38 +821,254 @@ interface ThemeSwitchProps {
             checked: boolean;
         };
     }) => void;
+    /** Optional accessible label (defaults to "Toggle dark mode") */
+    label?: string;
 }
 /**
  * Theme (dark-mode) toggle switch powered by Radix Switch.
  *
- * Displays a red/green dot to indicate the checked state.
- * Used as the dark-mode toggle in the TopBar.
+ * The thumb color indicates mode: green = light, slate = dark.
+ * Layout (position, margin) is the parent's responsibility — this component
+ * renders inline with no external margins.
  *
  * @example
- * <Switch checked={isDarkMode} onChange={({ target }) => setDarkMode(target.checked)} />
+ * <ThemeSwitch checked={isDark} onChange={({ target }) => setDark(target.checked)} />
  */
-declare function Switch$1({ checked, onChange }: ThemeSwitchProps): react_jsx_runtime.JSX.Element;
+declare function ThemeSwitch({ checked, onChange, label }: ThemeSwitchProps): react_jsx_runtime.JSX.Element;
+
+interface TopBarProps {
+    /** Brand area — logo, wordmark, or app name. Rendered on the leading edge. */
+    brand?: React$1.ReactNode;
+    /**
+     * Centre content — primary navigation links, breadcrumb, or page title.
+     * On mobile (< md breakpoint) this moves below the brand row.
+     */
+    center?: React$1.ReactNode;
+    /**
+     * Trailing actions — theme toggle, user avatar, notification bell, etc.
+     * Rendered on the trailing edge.
+     */
+    actions?: React$1.ReactNode;
+    /**
+     * Height in pixels (default 56). Controls the `h-*` style directly so
+     * child scroll-offset calculations can consume it as a CSS var.
+     */
+    height?: number;
+    /** Additional className on the root element */
+    className?: string;
+}
+/**
+ * App-shell top navigation bar.
+ *
+ * Three named slots: brand (leading), center, actions (trailing).
+ * All slots are optional — omit what you don't need.
+ *
+ * The component is sticky by default (`sticky top-0`) with `z-[100]`.
+ * Height is exposed as `--topbar-height` CSS variable on the element so
+ * layout children can reference it for scroll-offset or sticky positioning.
+ *
+ * Light/dark aware via Phase B semantic tokens.
+ *
+ * @example
+ * <TopBar
+ *   brand={<Logo />}
+ *   center={<NavLinks />}
+ *   actions={
+ *     <>
+ *       <ThemeSwitch checked={isDark} onChange={toggleDark} />
+ *       <UserAvatar />
+ *     </>
+ *   }
+ * />
+ */
+declare function TopBar({ brand, center, actions, height, className, }: TopBarProps): react_jsx_runtime.JSX.Element;
+
+/** ─────────────────── types ─────────────────── */
+interface SidebarItem {
+    key: string;
+    icon: React$1.ReactNode;
+    label: string;
+    isActive?: boolean;
+    onClick?: () => void;
+    /** Numeric badge shown on the icon */
+    badge?: number;
+}
+interface SidebarSection {
+    key: string;
+    /** Section title — visible only when expanded */
+    title?: string;
+    items: SidebarItem[];
+}
+interface SidebarProps {
+    sections: SidebarSection[];
+    isExpanded: boolean;
+    onToggle?: () => void;
+    /** Expanded sidebar width in px (default 220) */
+    expandedWidth?: number;
+    /** Collapsed sidebar width in px (default 52) */
+    collapsedWidth?: number;
+    /** Slot rendered at the bottom of the sidebar (theme switch, user avatar…) */
+    footer?: React$1.ReactNode;
+}
+/** ─────────────────── main component ─────────────────── */
+/**
+ * Collapsible application sidebar.
+ *
+ * When collapsed: icon-only with tooltips. When expanded: icon + label.
+ * Width animates with an ease-out-expo curve. The parent (AppShell) is
+ * responsible for shifting the main content by the sidebar width.
+ *
+ * @example
+ * const [open, setOpen] = useState(true)
+ * <Sidebar
+ *   sections={NAV_SECTIONS}
+ *   isExpanded={open}
+ *   onToggle={() => setOpen(o => !o)}
+ * />
+ */
+declare function Sidebar({ sections, isExpanded, onToggle, expandedWidth, collapsedWidth, footer, }: SidebarProps): react_jsx_runtime.JSX.Element;
+
+interface AppShellProps {
+    /**
+     * Top navigation bar.
+     * Typically `<TopBar brand={...} actions={...} />`.
+     */
+    topBar?: React$1.ReactNode;
+    /** Sidebar navigation sections */
+    sidebarSections?: SidebarSection[];
+    /** Expanded width of the sidebar in px (default 220) */
+    sidebarExpandedWidth?: SidebarProps['expandedWidth'];
+    /** Collapsed width of the sidebar in px (default 52) */
+    sidebarCollapsedWidth?: SidebarProps['collapsedWidth'];
+    /** Start expanded (default false) */
+    sidebarDefaultExpanded?: boolean;
+    /** Slot rendered at the bottom of the sidebar */
+    sidebarFooter?: SidebarProps['footer'];
+    /** Main page content */
+    children?: React$1.ReactNode;
+    /** Root element className */
+    className?: string;
+}
+/**
+ * Full-page application layout skeleton.
+ *
+ * Composes a sticky TopBar + collapsible Sidebar + scrollable content area.
+ * The main area shifts with the sidebar width via a Framer Motion margin animation.
+ *
+ * @example
+ * <AppShell
+ *   topBar={<TopBar brand={<Logo />} actions={<ThemeSwitch ... />} />}
+ *   sidebarSections={NAV_SECTIONS}
+ * >
+ *   <PageContent />
+ * </AppShell>
+ */
+declare function AppShell({ topBar, sidebarSections, sidebarExpandedWidth, sidebarCollapsedWidth, sidebarDefaultExpanded, sidebarFooter, children, className, }: AppShellProps): react_jsx_runtime.JSX.Element;
+
+/** ─────────────────── base ─────────────────── */
+interface SkeletonBaseProps {
+    className?: string;
+    /** Override inline styles */
+    style?: React$1.CSSProperties;
+}
+/** ─────────────────── SkeletonBox ─────────────────── */
+interface SkeletonBoxProps extends SkeletonBaseProps {
+    width?: number | string;
+    height?: number | string;
+    /** Override border-radius (defaults to token --radius-md) */
+    radius?: number | string;
+}
+/**
+ * Generic rectangular loading placeholder.
+ * Use for images, cards, headers, or any block element.
+ *
+ * @example
+ * <SkeletonBox width={240} height={160} />
+ * <SkeletonBox width="100%" height={48} radius="var(--radius-lg)" />
+ */
+declare function SkeletonBox({ width, height, radius, className, style }: SkeletonBoxProps): react_jsx_runtime.JSX.Element;
+/** ─────────────────── SkeletonText ─────────────────── */
+interface SkeletonTextProps extends SkeletonBaseProps {
+    /** Number of lines (default 3) */
+    lines?: number;
+    /** Width of the last (shortest) line as a percentage (default 60) */
+    lastLineWidth?: number;
+    /** Line height in px (default 14) */
+    lineHeight?: number;
+    /** Gap between lines in px (default 8) */
+    gap?: number;
+}
+/**
+ * Multi-line text loading placeholder.
+ * Last line is shorter to mimic real paragraph layout.
+ *
+ * @example
+ * <SkeletonText lines={4} lastLineWidth={45} />
+ */
+declare function SkeletonText({ lines, lastLineWidth, lineHeight, gap, className, style, }: SkeletonTextProps): react_jsx_runtime.JSX.Element;
+/** ─────────────────── SkeletonCircle ─────────────────── */
+interface SkeletonCircleProps extends SkeletonBaseProps {
+    /** Diameter in px (default 40) */
+    size?: number;
+}
+/**
+ * Circular loading placeholder — avatars, icons, status indicators.
+ *
+ * @example
+ * <SkeletonCircle size={48} />
+ */
+declare function SkeletonCircle({ size, className, style }: SkeletonCircleProps): react_jsx_runtime.JSX.Element;
+/** ─────────────────── SkeletonCard ─────────────────── */
+interface SkeletonCardProps extends SkeletonBaseProps {
+    /** Include a circular avatar in the header (default true) */
+    hasAvatar?: boolean;
+    /** Number of text lines in the body (default 3) */
+    lines?: number;
+}
+/**
+ * Composite card skeleton — avatar + heading + body text + action strip.
+ * Use as a drop-in while real card data loads.
+ *
+ * @example
+ * <div className="grid grid-cols-3 gap-4">
+ *   {loading && Array.from({ length: 3 }).map((_, i) => <SkeletonCard key={i} />)}
+ * </div>
+ */
+declare function SkeletonCard({ hasAvatar, lines, className, style }: SkeletonCardProps): react_jsx_runtime.JSX.Element;
 
 interface ButtonProps {
     content?: React$1.ReactNode;
-    /** HTML button type attribute */
+    /** Visual style variant */
+    variant?: 'primary' | 'secondary' | 'ghost' | 'danger';
+    /** Size — controls height, padding, and font size */
+    size?: 'sm' | 'md' | 'lg';
+    /** HTML button type */
     buttonType?: 'button' | 'submit' | 'reset';
-    /** Visual variant */
-    type?: string;
     loading?: boolean;
     disabled?: boolean;
+    /** Inline style overrides (width, etc.). Margins/layout belong in the parent. */
     style?: React$1.CSSProperties;
+    /** Leading icon — rendered before content */
     icon?: React$1.ReactNode;
     onClick?: React$1.MouseEventHandler<HTMLButtonElement>;
+    /**
+     * @deprecated Pass `variant` instead. Kept for API compat — currently no-op.
+     * Will be removed in the next major version.
+     */
+    type?: string;
 }
 /**
- * Primary action button.
+ * Primary action button with variant + size system.
+ *
+ * Width is never hardcoded — set `style={{ width }}` or let the parent grid/flex control it.
  *
  * @example
  * <Button content="Save" onClick={handleSave} />
- * <Button content="Submit" buttonType="submit" loading={isPending} />
+ * <Button content="Delete" variant="danger" size="sm" />
+ * <Button content="Cancel" variant="secondary" />
+ * <Button content="Loading…" loading buttonType="submit" />
  */
-declare function Button({ content, buttonType, loading, disabled, style, icon, onClick, }: ButtonProps): react_jsx_runtime.JSX.Element;
+declare function Button({ content, variant, size, buttonType, loading, disabled, style, icon, onClick, }: ButtonProps): react_jsx_runtime.JSX.Element;
 
 interface TextInputProps {
     value?: any;
@@ -964,40 +1174,40 @@ interface DropdownPillProps {
 declare function DropdownPill({ value, hasSiblings }: DropdownPillProps): react_jsx_runtime.JSX.Element;
 
 interface CheckboxProps {
-    /** 'vertical' | 'horizontal' */
-    layout?: string;
-    /** 'left' | 'right' (label side when horizontal) */
-    labelPosition?: string;
-    label?: React$1.ReactNode;
-    name?: string;
-    htmlFor?: string;
-    errorMessage?: React$1.ReactNode;
-    value?: boolean;
+    /** Controlled checked state */
+    checked?: boolean;
     onChange?: (e: {
         target: {
-            value: boolean;
+            checked: boolean;
             id?: string;
             name?: string;
         };
     }) => void;
-    [key: string]: any;
+    label?: React$1.ReactNode;
+    name?: string;
+    /** `id` for the hidden input and the `<label htmlFor>` link */
+    htmlFor?: string;
+    errorMessage?: React$1.ReactNode;
+    disabled?: boolean;
+    /** @deprecated Use `checked` */
+    value?: boolean;
 }
 /**
  * Accessible checkbox powered by Radix Checkbox.
  *
- * Radix handles keyboard activation, focus ring, and ARIA checked state.
- * Emits a synthetic `{ target: { value, id, name } }` event to stay
- * compatible with existing form-change handlers.
+ * Radix handles keyboard activation, focus ring, and `role="checkbox"` ARIA.
+ * The check mark pops in with a spring animation on first check.
  *
  * @example
  * <Checkbox
  *   htmlFor="agree"
  *   label="I agree to the terms"
- *   value={form.agree}
- *   onChange={({ target }) => setField('agree', target.value)}
+ *   checked={form.agree}
+ *   onChange={({ target }) => setField('agree', target.checked)}
  * />
  */
-declare function Checkbox({ layout, labelPosition, label, name, htmlFor, errorMessage, value, onChange, }: CheckboxProps): react_jsx_runtime.JSX.Element;
+declare function Checkbox({ checked, value, // legacy alias
+onChange, label, name, htmlFor, errorMessage, disabled, }: CheckboxProps): react_jsx_runtime.JSX.Element;
 
 interface SwitchInputProps {
     checked?: boolean;
@@ -1237,4 +1447,4 @@ declare const Temporal: {
     TemporalPicker: typeof TemporalPickerBase;
 };
 
-export { 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, DropdownPill, type DropdownPillProps, 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, MenuBar, MenuBarItem, type MenuBarItemConfig, type MenuBarItemProps, type MenuBarProps, Modal, type ModalProps, type NotificationPayload, NotificationProvider, NumberInput, type NumberInputProps, OpaqueGridCard, type OpaqueGridCardProps, type PaginationOptions, Password, type PasswordProps, ScalableContainer, type ScalableContainerProps, SearchInput, type SearchInputProps, Switch, type SwitchInputProps, type TabItem, Table, type TableColumn, type TableProps, Tabs, type TabsProps, Temporal, type TemporalPickerProps, TextInput, type TextInputProps, Switch$1 as ThemeSwitch, type ThemeSwitchProps, ToggleButton, type ToggleButtonProps, type ToggleItem, Tooltip, type TooltipProps, TooltipProvider, Tree, type TreeItemClickPayload, type TreeNode, type TreeProps, TreeSelect, type TreeSelectProps, Wizard, type WizardProps, type WizardStep, useNotification };
+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, DropdownPill, type DropdownPillProps, 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, MenuBar, MenuBarItem, type MenuBarItemConfig, type MenuBarItemProps, type MenuBarProps, Modal, type ModalProps, type NotificationPayload, NotificationProvider, NumberInput, type NumberInputProps, OpaqueGridCard, type OpaqueGridCardProps, type PaginationOptions, Password, type PasswordProps, 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, Temporal, type TemporalPickerProps, TextInput, type TextInputProps, ThemeSwitch, type ThemeSwitchProps, 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 };