@sovereignfs/ui 0.45.0 → 0.54.0

package/dist/index.d.ts

@@ -1,5 +1,35 @@
 import * as react from 'react';
-import { ReactNode, ButtonHTMLAttributes, SelectHTMLAttributes, ReactElement, CSSProperties, InputHTMLAttributes, TextareaHTMLAttributes, HTMLAttributes, TdHTMLAttributes, ThHTMLAttributes, LabelHTMLAttributes, ElementType, PointerEvent, KeyboardEvent, MouseEvent } from 'react';
+import { ReactNode, ButtonHTMLAttributes, SelectHTMLAttributes, ReactElement, CSSProperties, InputHTMLAttributes, TextareaHTMLAttributes, HTMLAttributes, TdHTMLAttributes, ThHTMLAttributes, LabelHTMLAttributes, ElementType, PointerEvent, KeyboardEvent, MouseEvent, RefObject } from 'react';
+
+interface LegalLinksProps {
+    privacyHref?: string;
+    tosHref?: string;
+    /** Renders a linked item. Defaults to a plain `<a href>`, which causes a
+     * full page reload — pass Next's `<Link>` (or equivalent) to keep
+     * navigation client-side. Not needed for a full-reload navigation away
+     * from a standalone auth page, but matters if this is ever mounted inside
+     * an SPA-like shell. */
+    renderLink?: (href: string, label: string) => ReactNode;
+    className?: string;
+}
+declare function LegalLinks({ privacyHref, tosHref, renderLink, className, }: LegalLinksProps): react.JSX.Element;
+
+interface MarkdownProps {
+    /** Raw markdown source. Supports the subset used by Sovereign's own
+     * long-form content pages: headings (#/##/###), paragraphs, **bold**,
+     * *italic*, `code`, [links](url), unordered lists (-), and blockquotes
+     * (>), including soft-wrapped continuation lines within a paragraph or
+     * list item. Not a general-purpose CommonMark parser — no tables,
+     * images, ordered lists, or nested blocks. */
+    content: string;
+    className?: string;
+}
+/** Renders a constrained markdown subset (see MarkdownProps) as styled React
+ * elements built from Typography — no HTML string injection. Meant for
+ * long-form, first-party content pages (privacy policy, terms of service)
+ * sourced from a single markdown file, not for rendering arbitrary or
+ * user-supplied markdown. */
+declare function Markdown({ content, className }: MarkdownProps): react.JSX.Element;
 
 type BadgeVariant = 'role' | 'status' | 'mono';
 type BadgeSize = 'sm' | 'md' | 'lg';
@@ -30,7 +60,7 @@ interface BadgeProps {
  */
 declare function Badge({ variant, size, status, uppercase, children, }: BadgeProps): react.JSX.Element;
 
-type IconName = 'house' | 'settings' | 'log-out' | 'chevron-right' | 'chevron-left' | 'chevron-down' | 'chevron-up' | 'x' | 'check' | 'plus' | 'trash-2' | 'pencil' | 'rotate-ccw' | 'search' | 'user' | 'shield' | 'lock' | 'eye' | 'eye-off' | 'mail' | 'bell' | 'activity' | 'package' | 'grid-2x2' | 'info' | 'alert-triangle' | 'circle-check' | 'circle-x' | 'calendar' | 'sliders-horizontal' | 'ellipsis-vertical' | 'file' | 'upload' | 'external-link' | 'banana' | 'apple' | 'carrot' | 'egg' | 'beef' | 'fish' | 'coffee' | 'wine' | 'beer' | 'cookie' | 'pizza' | 'candy' | 'salad' | 'milk' | 'drumstick' | 'croissant' | 'cup-soda' | 'spray-can' | 'snowflake' | 'shopping-basket';
+type IconName = 'house' | 'settings' | 'log-out' | 'smartphone' | 'chevron-right' | 'chevron-left' | 'chevron-down' | 'chevron-up' | 'menu' | 'x' | 'check' | 'plus' | 'trash-2' | 'pencil' | 'rotate-ccw' | 'search' | 'user' | 'shield' | 'lock' | 'eye' | 'eye-off' | 'mail' | 'bell' | 'activity' | 'package' | 'grid-2x2' | 'info' | 'alert-triangle' | 'circle-check' | 'circle-x' | 'calendar' | 'sliders-horizontal' | 'ellipsis-vertical' | 'file' | 'upload' | 'external-link' | 'banana' | 'apple' | 'carrot' | 'egg' | 'beef' | 'fish' | 'coffee' | 'wine' | 'beer' | 'cookie' | 'pizza' | 'candy' | 'salad' | 'milk' | 'drumstick' | 'croissant' | 'cup-soda' | 'spray-can' | 'snowflake' | 'shopping-basket';
 
 /** Decorative icon — visually meaningful but described by surrounding text. */
 type DecorativeProps = {
@@ -374,6 +404,12 @@ interface DrawerProps {
      *  "half screen or less" convention for Drawer, this is the only other
      *  supported size; taller content should use `Sheet` instead. */
     snapHeight?: 'content' | 'half';
+    /** Renders a built-in `OverlayHeader` (title + close) below the grab
+     *  handle. Omit when the content supplies its own header, or none is
+     *  needed at all — e.g. the mobile shell's Apps drawer, whose grab handle
+     *  and swipe-down/scrim-tap dismissal are enough on their own. Mirrors
+     *  `Sheet`'s identical `title` prop. */
+    title?: string;
     children: ReactNode;
 }
 /**
@@ -398,7 +434,7 @@ interface DrawerProps {
  * scroll, the same reasoning behind the tasks plugin's edge-zone-only
  * swipe-to-reveal technique.
  */
-declare function Drawer({ open, onClose, 'aria-label': ariaLabel, snapHeight, children, }: DrawerProps): react.JSX.Element | null;
+declare function Drawer({ open, onClose, 'aria-label': ariaLabel, snapHeight, title, children, }: DrawerProps): react.JSX.Element | null;
 
 interface OverlayHeaderProps {
     /** Overlay title, shown between the optional back button and the trailing
@@ -656,8 +692,132 @@ interface PageHeaderProps {
     description?: string;
     action?: ReactNode;
     className?: string;
+    /** Heading level for the title. Defaults to `1` for standalone use; pass
+     * `2` or `3` when the page already sits under a shell/plugin `<h1>`, to
+     * avoid a duplicate top-level heading. Visual style is unchanged at every
+     * level — only the rendered tag changes. */
+    headingLevel?: 1 | 2 | 3;
+}
+declare function PageHeader({ title, description, action, className, headingLevel, }: PageHeaderProps): react.JSX.Element;
+
+interface PageContainerProps extends HTMLAttributes<HTMLDivElement> {
+    /** Constrains and centers content width. Adds no padding of its own — the
+     * runtime shell already pads plugin content. Defaults to 'md'. */
+    maxWidth?: 'sm' | 'md' | 'lg' | 'full';
+    children: ReactNode;
+}
+declare function PageContainer({ maxWidth, className, children, ...rest }: PageContainerProps): react.JSX.Element;
+
+interface MobileHeaderProps extends HTMLAttributes<HTMLDivElement> {
+    /** The brand/logo element — already a complete, clickable link home (e.g. an
+     * instance logo wrapped in the consumer's own router `Link`). Always
+     * rendered. `MobileHeader` stays router-agnostic, so this is provided
+     * fully built rather than as a bare icon + href. Optional — omit it to get
+     * a default "S" badge (matching the runtime shell's own fallback brand
+     * icon when no instance logo is configured), sized and styled to the same
+     * 36px/radius-md convention a custom logo is expected to follow. */
+    logo?: ReactNode;
+    /** Optional contextual title rendered beside the logo (e.g. the active
+     * plugin's name). Absent by default — this is the one overridable part of
+     * the header. See RFC 0088. */
+    title?: string;
+    /** Notification bell — always rendered; not overridable.
+     * TODO: this is just an icon slot today (the consumer wires up its own
+     * click handler/content) — it doesn't yet accommodate a full notification
+     * feature (unread badge, dropdown panel, etc. — see the runtime shell's
+     * own NotificationBell). Deferred; revisit once a plugin actually needs
+     * more than a bare bell icon here. */
+    bell: ReactNode;
+    /** Avatar / account menu trigger — always rendered; not overridable. */
+    avatarMenu: ReactNode;
+}
+/**
+ * The mobile header bar: brand/logo (always shown), an optional contextual
+ * title, and a fixed bell + avatar-menu cluster. Owns its own chrome —
+ * background, border-bottom, sticky positioning, safe-area-aware padding,
+ * and a 768px max-width (so it never stretches full-bleed if mounted outside
+ * an actual mobile viewport) — matching the runtime shell's own mobile
+ * header exactly, since this component is meant to replace that hand-rolled
+ * markup. Presentational only — no data fetching; the consumer supplies
+ * `bell`/`avatarMenu` (and, optionally, `logo`) as already-wired components
+ * (their own sizing — 36px logo/avatar, 44px bell tap target — is the
+ * consumer's responsibility, matching the reference implementation in the
+ * runtime shell). See RFC 0088 for the immutable/overridable boundary this
+ * enforces.
+ */
+declare function MobileHeader({ logo, title, bell, avatarMenu, className, ...rest }: MobileHeaderProps): react.JSX.Element;
+
+interface FooterIcon {
+    icon: ReactNode;
+    label: string;
+    href?: string;
+    onClick?: () => void;
+    active?: boolean;
+}
+interface MobileFooterProps extends HTMLAttributes<HTMLElement> {
+    /** Opens the app drawer/launcher. Always rendered as the centered slot;
+     * not overridable. */
+    onOpenApps: () => void;
+    /** Custom launcher icon (e.g. a plugin-supplied image). Defaults to a
+     * generic grid icon. */
+    launcherIcon?: ReactNode;
+    /** Whether the launcher's own drawer is currently open (applies the
+     * pressed/active visual state). */
+    launcherOpen?: boolean;
+    /** 1 or 2 icons rendered to the left of the centered launcher. */
+    leftIcons: FooterIcon[];
+    /** 1 or 2 icons rendered to the right of the centered launcher. Must match
+     * `leftIcons.length` — the launcher stays visually centered, so a mismatch
+     * is flagged (dev-mode only, never thrown) rather than silently allowed. */
+    rightIcons: FooterIcon[];
+}
+/**
+ * The mobile footer bar: a centered, fixed "Apps" launcher flanked by 1 or 2
+ * overridable icons on each side (3 or 5 total, matching standard
+ * iOS/Android bottom-nav conventions). Owns its own chrome — background,
+ * border-top, safe-area-aware bottom padding, and a 768px max-width (so it
+ * never stretches full-bleed if mounted outside an actual mobile viewport)
+ * — matching the runtime shell's own mobile footer (MobileNav) exactly,
+ * since this component is meant to replace that hand-rolled markup.
+ * Presentational only — no data fetching; the consumer owns the
+ * drawer/overlay `onOpenApps` opens. See RFC 0088 for the
+ * immutable/overridable boundary this enforces.
+ */
+declare function MobileFooter({ onOpenApps, launcherIcon, launcherOpen, leftIcons, rightIcons, className, ...rest }: MobileFooterProps): react.JSX.Element;
+
+interface MobileAppsDrawerItem {
+    /** Stable identity for this tile — used as the React key. */
+    key: string;
+    icon: ReactNode;
+    label: string;
+    /** Renders an `<a>` when set; otherwise a `<button>` calling `onClick`. */
+    href?: string;
+    onClick?: () => void;
+}
+interface MobileAppsDrawerProps {
+    open: boolean;
+    onClose: () => void;
+    /** Accessible name for the drawer panel — required since there's no
+     *  visible title to fall back to (Drawer's grab handle plus swipe-down /
+     *  scrim-tap already cover dismissal, so no header row is rendered). */
+    'aria-label': string;
+    /** The grid tiles — supplied by the consumer (e.g. installed plugins,
+     *  a plugin's own sections). MobileAppsDrawer owns only the drawer
+     *  chrome/grid layout, never the item list itself. */
+    items: MobileAppsDrawerItem[];
 }
-declare function PageHeader({ title, description, action, className }: PageHeaderProps): react.JSX.Element;
+/**
+ * The mobile "Apps" drawer: a bottom sheet with a 3-column grid of icon
+ * tiles — same tile size (56px, radius 14px) and grid layout as the runtime
+ * shell's own Apps drawer (MobileNav's Drawer content), generalized so the
+ * tile list comes from the consumer (the shell passes installed plugins; a
+ * plugin composing its own MobileFooter launcher passes whatever its own
+ * "apps" are, e.g. a section index) rather than being hardcoded to plugins
+ * specifically. No header row (title/close button) — Drawer's own grab
+ * handle plus swipe-down/scrim-tap dismissal are enough, and a header ate
+ * into the limited vertical space a launcher grid needs most.
+ */
+declare function MobileAppsDrawer({ open, onClose, items, ...rest }: MobileAppsDrawerProps): react.JSX.Element;
 
 interface EmptyStateProps {
     icon?: IconName;
@@ -668,6 +828,121 @@ interface EmptyStateProps {
 }
 declare function EmptyState({ icon, heading, description, action, className }: EmptyStateProps): react.JSX.Element;
 
+interface OfflineGateProps {
+    children: ReactNode;
+    /** Defaults to a generic "this section" phrasing — pass the surface's own name. */
+    surfaceName?: string;
+    className?: string;
+}
+/**
+ * OfflineGate — blocks administrative/settings surfaces from rendering
+ * (possibly stale) cached content while the device has no network, showing an
+ * explanatory empty state instead (research 0012, epic task 2.32).
+ *
+ * Distinct from `OfflineBanner`: the banner is an informational overlay that
+ * coexists with normal content everywhere in the shell. This is a hard block
+ * for surfaces where operating against stale data is actively wrong — e.g. a
+ * Console user list or an Account billing page reflects a point-in-time
+ * snapshot the moment it's server-rendered, and any cached copy replayed
+ * later has no way to signal that it may already be stale. `OfflineGate`
+ * doesn't try to tell staleness apart from freshness; it removes the
+ * question by not rendering the content at all while offline.
+ *
+ * `children` is rendered unconditionally while online, so this adds no cost
+ * to the common case — it only decides what to show, never how the wrapped
+ * content itself is fetched or cached.
+ */
+declare function OfflineGate({ children, surfaceName, className }: OfflineGateProps): react.JSX.Element;
+
+interface DeviceOnlyGateProps {
+    children: ReactNode;
+    /** Defaults to a generic "this app" phrasing — pass the plugin's own name. */
+    surfaceName?: string;
+    /**
+     * The caller's own `isDeviceOnlyTierAvailable()` result (from
+     * `@sovereignfs/sdk/device-client`) — taken as a plain boolean rather than
+     * computed inside this component, so `@sovereignfs/ui` never depends on
+     * `@sovereignfs/sdk` (this package must stay usable standalone, outside the
+     * plugin runtime — RFC 0073).
+     */
+    available: boolean;
+    className?: string;
+}
+/**
+ * DeviceOnlyGate — blocks a `device-only`-tier plugin's content from
+ * rendering on a surface that cannot provide the durable, encrypted,
+ * device-auth-gated store that tier requires, showing an explanatory empty
+ * state instead of a broken screen (research 0012, epic tasks 2.33 + 3.36).
+ *
+ * A `device-only` plugin wraps its own root content in this the same way
+ * Console and Account wrap theirs in `OfflineGate` — an opt-in pattern each
+ * surface applies to itself, not a platform-level route gate. The launcher
+ * tile's own "Phone only" badge (`useOfflineTileState`) is advisory UI on top
+ * of this; this component is the actual gate, since a user can always reach a
+ * route directly (a bookmark, a deep link) without passing through the
+ * launcher tile at all.
+ *
+ * **Not a security boundary.** Availability here is a capability signal, not
+ * an authorization check — the real protection for `device-only` data is
+ * that it is encrypted and the key requires device auth to release (epic task
+ * 1.22), so it stays inaccessible regardless of whether this gate is present,
+ * bypassed, or simply never reached (e.g. a hand-crafted request against the
+ * plugin's own API routes).
+ */
+declare function DeviceOnlyGate({ children, surfaceName, available, className, }: DeviceOnlyGateProps): react.JSX.Element;
+
+/**
+ * `'checking'` covers the moment before the caller's own async status check
+ * resolves — same transitional-state pattern `EncryptionSection`'s local
+ * `LocalState` uses, so this gate never flashes an empty state before the
+ * real answer is known. `'no-device-auth'` is the hard-block case (RFC 0093
+ * §5, epic task 1.22): the environment supports the tier, but this device
+ * has no passcode, fingerprint, or face unlock configured, so a key cannot
+ * be created here at all — distinct from `'not-set-up'`, where it can.
+ */
+type DeviceStorageKeyGateStatus = 'checking' | 'unsupported' | 'no-device-auth' | 'not-set-up' | 'set-up';
+interface DeviceStorageKeyGateProps {
+    children: ReactNode;
+    /** Defaults to a generic "This app" phrasing — pass the plugin's own name. */
+    surfaceName?: string;
+    /**
+     * The caller's own `getDeviceStorageKeyStatus()` result (from
+     * `@sovereignfs/sdk/device-only-storage`) — taken as a plain status rather
+     * than computed inside this component, so `@sovereignfs/ui` never depends
+     * on `@sovereignfs/sdk` (same boundary `DeviceOnlyGate`'s `available` prop
+     * draws — this package must stay usable standalone, outside the plugin
+     * runtime — RFC 0073).
+     */
+    status: DeviceStorageKeyGateStatus;
+    /**
+     * Rendered under the "not set up" message — typically a link to Account →
+     * Security. Not built in here: this package depends on no router, so the
+     * caller supplies its own navigable element (a plain `<a>`, a framework
+     * `<Link>`, whatever the host app uses).
+     */
+    setupAction?: ReactNode;
+    className?: string;
+}
+/**
+ * DeviceStorageKeyGate — blocks a `device-only`-tier plugin's content until
+ * the user has set up their Device Storage Key (RFC 0093 §2, epic task
+ * 1.22). Distinct from `DeviceOnlyGate`: that one checks whether the *tier
+ * itself* is available on this surface (native shell, secure-storage bridge
+ * present); this one checks whether the user has actually completed the
+ * one-time, per-device enrollment that tier depends on. A `device-only`
+ * plugin typically wants both — `DeviceOnlyGate` outermost (no point
+ * checking enrollment on a surface that cannot offer the tier at all), this
+ * gate inside it.
+ *
+ * Enrollment is centralized and decoupled from any single plugin (RFC 0093
+ * §2): a plugin that finds no key set up does not run its own enrollment
+ * ceremony inline. It stops here and points the user at Account → Security —
+ * the one place enrollment happens for every `device-only` plugin on this
+ * device — via `setupAction`, the same opt-in, self-applied pattern
+ * `OfflineGate`/`DeviceOnlyGate` already use for their own surfaces.
+ */
+declare function DeviceStorageKeyGate({ children, surfaceName, status, setupAction, className, }: DeviceStorageKeyGateProps): react.JSX.Element | null;
+
 interface SpinnerProps {
     size?: 'sm' | 'md' | 'lg';
     label?: string;
@@ -688,12 +963,25 @@ interface NavTabItem {
     href: string;
     active?: boolean;
 }
+/** Props to spread onto a consumer-supplied link element — keeps NavTabs' own
+ * class names and a11y attributes in sync with whatever the consumer renders. */
+interface NavTabLinkProps {
+    href: string;
+    className: string;
+    'aria-current': 'page' | undefined;
+    children: ReactNode;
+}
 interface NavTabsProps {
     items: NavTabItem[];
     className?: string;
     'aria-label'?: string;
+    /** Render a tab as something other than a plain `<a href>` — e.g. Next's
+     * `<Link replace>` inside an overlay-shell plugin, where a full page
+     * navigation would break the dialog's history contract. Receives the item
+     * plus the class name/aria attributes NavTabs would otherwise apply. */
+    renderLink?: (item: NavTabItem, linkProps: NavTabLinkProps) => ReactNode;
 }
-declare function NavTabs({ items, className, 'aria-label': ariaLabel }: NavTabsProps): react.JSX.Element;
+declare function NavTabs({ items, className, 'aria-label': ariaLabel, renderLink }: NavTabsProps): react.JSX.Element;
 
 interface TooltipProps {
     content: string;
@@ -1711,6 +1999,57 @@ declare const MOBILE_BREAKPOINT_PX = 768;
  */
 declare function useIsMobile(breakpointPx?: number): boolean;
 
+/**
+ * useIsOffline — whether the browser currently has no network connection.
+ *
+ * SSR-safe: always initialises to `false` (online) so the server-rendered HTML
+ * matches the first client render, then reads the real `navigator.onLine`
+ * value in `useEffect`. This picks up the case where the page loaded already
+ * offline (e.g. served from the service-worker cache) at the cost of an
+ * imperceptible one-frame delay before the offline state appears — the same
+ * trade-off `OfflineBanner` makes, which this hook was extracted from so every
+ * consumer shares one connectivity source instead of re-deriving it slightly
+ * differently (research 0012, epic task 2.32).
+ *
+ * Reflects only `navigator.onLine` — true whenever the OS reports a network
+ * interface is up, even without real upstream connectivity (e.g. Wi-Fi with no
+ * internet). That is a known limitation of the browser API itself, not of this
+ * hook; there is currently no better cross-browser signal available.
+ */
+declare function useIsOffline(): boolean;
+
+/**
+ * The two reasons an app tile can be non-interactive, kept structurally
+ * distinct because they have different causes and must never read as the same
+ * thing to a user (research 0012, epic task 2.33):
+ *
+ * - `'connectivity-dimmed'` — a no-offline-tier app, dimmed only while the
+ *   device is **actually offline right now**. Reactive and temporary; clears
+ *   the instant connectivity returns.
+ * - `'capability-restricted'` — a `device-only` app on a surface without the
+ *   durable, encrypted, device-auth-gated store it needs. Static and
+ *   unrelated to connectivity — it stays restricted even when fully online,
+ *   and must never say "offline" to a user who plainly isn't.
+ */
+type OfflineTileState = 'connectivity-dimmed' | 'capability-restricted' | null;
+/**
+ * Which of the two states, if any, applies to an app tile given its declared
+ * offline tier.
+ *
+ * `deviceOnlyAvailable` is the caller's own
+ * `isDeviceOnlyTierAvailable()` result (from
+ * `@sovereignfs/sdk/device-client`) — deliberately taken as a plain boolean
+ * parameter rather than computed inside this hook, so `@sovereignfs/ui` never
+ * depends on `@sovereignfs/sdk` (this package must stay usable standalone,
+ * outside the plugin runtime — RFC 0073).
+ *
+ * An `offline-first` app is never restricted by either state: that tier's
+ * whole point is working with no network, so it stays fully interactive both
+ * online and offline. A `device-only` app that *is* available behaves the
+ * same way — the restriction is about availability, not connectivity.
+ */
+declare function useOfflineTileState(offline: 'offline-first' | 'device-only' | undefined, deviceOnlyAvailable: boolean): OfflineTileState;
+
 interface CommitOnEnterOrBlurHandlers {
     onKeyDown: (e: KeyboardEvent<HTMLInputElement | HTMLTextAreaElement>) => void;
     onBlur: () => void;
@@ -1739,4 +2078,313 @@ interface CommitOnEnterOrBlurHandlers {
  */
 declare function useCommitOnEnterOrBlur(onCommit: () => void): CommitOnEnterOrBlurHandlers;
 
-export { Accordion, type AccordionItem, type AccordionProps, Alert, type AlertProps, type AlertVariant, AspectRatio, type AspectRatioProps, Avatar, type AvatarProps, Badge, type BadgeProps, type BadgeStatus, type BadgeVariant, BalanceChip, type BalanceChipProps, type BannerVariant, Breadcrumb, type BreadcrumbItem, type BreadcrumbProps, Button, ButtonGroup, type ButtonGroupProps, type ButtonProps, type ButtonSize, type ButtonVariant, Calendar, type CalendarProps, Card, type CardProps, CheckableListRow, type CheckableListRowProps, Checkbox, type CheckboxProps, CodeTextarea, type CodeTextareaProps, Collapsible, type CollapsibleProps, Combobox, type ComboboxOption, type ComboboxProps, Command, type CommandItem, type CommandProps, type CommitOnEnterOrBlurHandlers, ConfirmDialog, type ConfirmDialogProps, ContextMenu, type ContextMenuProps, CurrencyInput, type CurrencyInputProps, DataTable, type DataTableColumn, type DataTableProps, DatePicker, type DatePickerProps, Dialog, type DialogProps, type DialogSize, DragHandleRow, type DragHandleRowProps, Drawer, type DrawerProps, EmptyState, type EmptyStateProps, FileDropzone, type FileDropzoneProps, FormField, type FormFieldProps, type FormFieldRenderProps, HoverCard, type HoverCardProps, Icon, type IconName, IconPicker, type IconPickerProps, type IconProps, Input, type InputProps, Item, type ItemProps, Kbd, type KbdProps, Label, type LabelProps, type LongPressHandlers, MOBILE_BREAKPOINT_PX, Marker, type MarkerProps, MemberMultiSelect, type MemberMultiSelectOption, type MemberMultiSelectProps, Menu, MenuEntries, type MenuEntry, type MenuItem, type MenuLabel, type MenuProps, type MenuSeparator, Menubar, type MenubarMenu, type MenubarProps, Message, type MessageProps, MessageScroller, type MessageScrollerProps, type MessageSender, type NavTabItem, NavTabs, type NavTabsProps, NavigationMenu, type NavigationMenuItem, type NavigationMenuProps, OverlayHeader, type OverlayHeaderProps, PageHeader, type PageHeaderProps, Pagination, type PaginationProps, Popover, type PopoverProps, Progress, type ProgressProps, QuantityStepper, type QuantityStepperProps, RadioGroup, type RadioGroupItem, type RadioGroupProps, type ResizableDirection, ResizableHandle, type ResizableHandleProps, ResizablePanel, ResizablePanelGroup, type ResizablePanelGroupProps, type ResizablePanelProps, ScrollArea, type ScrollAreaProps, SegmentedControl, type SegmentedControlProps, type SegmentedOption, Select, type SelectProps, Sheet, type SheetProps, Slider, type SliderProps, type SortDirection, Spinner, type SpinnerProps, type SplitMethod, SplitMethodSelector, type SplitMethodSelectorProps, SplitPane, type SplitPaneProps, StatusBadge, type StatusBadgeProps, type StatusBadgeStatus, SuggestionInput, type SuggestionInputProps, type SuggestionOption, SystemBanner, type SystemBannerProps, type TabItem, Table, TableBody, TableCell, TableHead, TableHeaderCell, type TableProps, TableRow, Tabs, type TabsProps, TagInput, type TagInputProps, Textarea, type TextareaProps, type ToastContextValue, type ToastItem, ToastProvider, Toggle, type ToggleProps, Tooltip, type TooltipProps, Typography, type TypographyProps, type TypographyVariant, type UseLongPressOptions, useCommitOnEnterOrBlur, useDoubleTapHandler, useIsMobile, useLongPress, useOverlaySecondRow, useSingleOrDoubleTap, useToast };
+interface UseSwipeRevealOptions {
+    /** Max reveal distance in px — the row translates by `-revealWidth` when open. */
+    revealWidth: number;
+    /** Whether the reveal is currently open. Controlled by the caller so a
+     *  list of rows can coordinate "only one open at a time" — this hook has
+     *  no open state of its own. */
+    open: boolean;
+    /** Called when a drag releases past the halfway point — the caller should
+     *  set `open` to true. */
+    onOpen: () => void;
+    /** Called when a drag releases before the halfway point — the caller
+     *  should set `open` to false. */
+    onClose: () => void;
+    /** Skip entirely (hooks can't be called conditionally). */
+    disabled?: boolean;
+}
+interface UseSwipeRevealHandlers {
+    onPointerDown: (e: PointerEvent) => void;
+    onPointerMove: (e: PointerEvent) => void;
+    onPointerUp: (e: PointerEvent) => void;
+    onPointerCancel: (e: PointerEvent) => void;
+}
+interface UseSwipeRevealResult {
+    /** Attach to the swipeable row element — the hook writes a live transform
+     *  to it directly during the drag (not via React state) so the row tracks
+     *  the finger at 60fps with no re-render per pointermove. */
+    rowRef: RefObject<HTMLDivElement | null>;
+    /** Spread onto the row's pointer event handlers. */
+    handlers: UseSwipeRevealHandlers;
+}
+/**
+ * useSwipeReveal — horizontal swipe-to-reveal (e.g. Done/Delete actions
+ * behind a list row), extracted from `sovereign-tasks`'s `TaskItem`/
+ * `ListSidebar`, which independently hand-rolled the identical gesture twice
+ * with only `revealWidth` differing (RFC 0079, epic task 9.20).
+ *
+ * Axis-locks on the first 8px of movement (so a vertical scroll or the
+ * carousel's own horizontal swipe-between-slides gesture isn't hijacked by a
+ * diagonal drag) and only resolves to open/closed on release, past the
+ * halfway point of `revealWidth`.
+ */
+declare function useSwipeReveal({ revealWidth, open, onOpen, onClose, disabled, }: UseSwipeRevealOptions): UseSwipeRevealResult;
+
+interface UseSnapCarouselOptions {
+    /** Total number of slides — settle detection clamps to this range. */
+    itemCount: number;
+    /** Called when the user's scroll gesture settles on a different slide
+     *  index than the last one reported. */
+    onSettle?: (index: number) => void;
+    /** Debounce delay (ms) after the last `scroll` event before checking where
+     *  the container settled. Default 120 — matches the value this hook was
+     *  extracted from. Debounced rather than keyed to the `scrollend` event,
+     *  which pre-17.4 iOS Safari/WKWebView doesn't support. */
+    debounceMs?: number;
+}
+interface UseSnapCarouselResult {
+    /** Attach to the `scroll-snap-type: x` scroll container. */
+    scrollRef: RefObject<HTMLDivElement | null>;
+    /** Imperatively scrolls the container to a slide index. */
+    scrollToIndex: (index: number, behavior?: ScrollBehavior) => void;
+}
+/**
+ * useSnapCarousel — debounced "settled slide" detection over a native
+ * `scroll-snap-type: x` container, extracted from `sovereign-tasks`'s
+ * `MobileTasksCarousel` and independently reimplemented in
+ * `sovereign-shopper`'s `MobileShopperCarousel` (RFC 0079, epic task 9.20).
+ * Gives swipe-between-slides physics for free via native scroll-snap, with
+ * this hook only handling "which slide did we land on."
+ */
+declare function useSnapCarousel({ itemCount, onSettle, debounceMs, }: UseSnapCarouselOptions): UseSnapCarouselResult;
+
+interface UseResponsiveLayoutOptions<TWeb, TMobile> {
+    web: TWeb;
+    mobile: TMobile;
+    breakpointPx?: number;
+}
+interface UseResponsiveLayoutResult<TWeb, TMobile> {
+    isMobile: boolean;
+    value: TWeb | TMobile;
+}
+/**
+ * useResponsiveLayout — picks between a `web` and `mobile` value for the
+ * current viewport, built on `useIsMobile` (same breakpoint/SSR-safe-default
+ * behavior, not reimplemented here). Generic over the value type so it works
+ * for JSX (the common case — forking an entire component tree, not just a
+ * class name) or any other per-breakpoint value a plugin wants to pick
+ * without repeating the isMobile-ternary boilerplate every call site.
+ *
+ * This formalizes the `if (isMobile) return <mobile/>; return <web/>;` fork
+ * plugins have hand-rolled per-plugin (e.g. a `MobileAwareShell` component
+ * that swaps an entire routed page tree for a client-only mobile one) —
+ * see `ResponsiveSurface` for the equivalent as a plain JSX component.
+ */
+declare function useResponsiveLayout<TWeb, TMobile>({ web, mobile, breakpointPx, }: UseResponsiveLayoutOptions<TWeb, TMobile>): UseResponsiveLayoutResult<TWeb, TMobile>;
+
+interface UseCarouselRouteSyncOptions {
+    /** Maps the current pathname to a slide index — the caller's own routing
+     *  logic (e.g. special-casing a virtual "starred" slide), unchanged from
+     *  whatever a plugin already has today. This hook has no idea what a
+     *  plugin's routes look like, by design — it never imports a router. */
+    indexForPathname: (pathname: string) => number;
+    /** Inverse mapping — given a settled slide index, the path to navigate to. */
+    pathForIndex: (index: number) => string;
+    /** The current pathname. The caller reads this via their own router (e.g.
+     *  `usePathname()` from `next/navigation`) and passes it in every render —
+     *  this package stays framework-generic and has zero runtime dependencies. */
+    pathname: string;
+    /** Called when this hook wants to navigate — typically
+     *  `(path) => router.replace(path, { scroll: false })`. */
+    onNavigate: (path: string) => void;
+}
+interface UseCarouselRouteSyncResult {
+    /** Feed directly into SwipableMobileCarousel's `activeIndex` prop. */
+    activeIndex: number;
+    /** Feed directly into SwipableMobileCarousel's `onSettle` prop. */
+    onSettle: (index: number) => void;
+}
+/**
+ * useCarouselRouteSync — centralizes the pathname↔slide-index mapping and the
+ * "was this pathname change our own settle, or an external navigation"
+ * distinction that carousel-driving plugins otherwise hand-roll per plugin
+ * (a tapped `<Link>`, browser back/forward, vs. this hook's own
+ * `router.replace` after a swipe settles). Router-agnostic on purpose: the
+ * caller owns the actual `usePathname()`/`router.replace()` calls and only
+ * hands this hook plain values/callbacks.
+ *
+ * Deliberately does not own neighbor-prefetch (SwipableMobileCarousel's
+ * `prefetchDistance`/mount-window covers that) or scroll mechanics (the
+ * carousel component reacts to `activeIndex` changes itself) — this hook is
+ * pathname↔index mapping only, keeping routing glue decoupled from
+ * data-fetching and DOM scrolling.
+ */
+declare function useCarouselRouteSync({ indexForPathname, pathForIndex, pathname, onNavigate, }: UseCarouselRouteSyncOptions): UseCarouselRouteSyncResult;
+
+interface ResponsiveSurfaceProps {
+    web: ReactNode;
+    mobile: ReactNode;
+    breakpointPx?: number;
+}
+/**
+ * ResponsiveSurface — thin JSX convenience wrapper around
+ * `useResponsiveLayout` for the common two-tree case: render an entirely
+ * different component tree below the breakpoint, not a CSS squeeze of the
+ * same one. Renders only whichever side is active — the other tree is never
+ * mounted.
+ *
+ * This does not replace a plugin's own shell component (e.g. a
+ * `MobileAwareShell` that also threads plugin-specific props like a refresh
+ * signal) — those stay a thin per-plugin wrapper around this.
+ */
+declare function ResponsiveSurface({ web, mobile, breakpointPx }: ResponsiveSurfaceProps): react.JSX.Element;
+
+interface SwipableMobileCarouselDotsProps {
+    count: number;
+    activeIndex: number;
+    onJump: (index: number) => void;
+    /** Per-dot accessible names, e.g. ["Lists", "Starred", "Groceries"]. Falls
+     *  back to "Slide N of count" for any index without one. */
+    labels?: (string | undefined)[];
+    /** Labels the whole group — required, no generic fallback (mirrors
+     *  SwipableMobileCarousel's own required aria-label). */
+    'aria-label': string;
+    className?: string;
+}
+/**
+ * SwipableMobileCarouselDots — a real, tappable, labeled slide indicator.
+ * Standalone (not carousel-only): reusable anywhere a set of positions needs
+ * a dot indicator (e.g. an image gallery, an onboarding stepper), and is also
+ * SwipableMobileCarousel's default `renderIndicator`.
+ *
+ * Replaces the `aria-hidden`, non-interactive dots pattern both
+ * sovereign-tasks and sovereign-shopper currently hand-roll — every dot here
+ * is a real `role="tab"` button with its own accessible name, reachable by
+ * keyboard. No roving tabIndex/arrow-key handling: `Tabs` (this library's
+ * other `role="tablist"` component) has none either, so this stays
+ * consistent with it rather than gold-plating past its sibling.
+ */
+declare function SwipableMobileCarouselDots({ count, activeIndex, onJump, labels, 'aria-label': ariaLabel, className, }: SwipableMobileCarouselDotsProps): react.JSX.Element;
+
+interface SwipableMobileCarouselIndicatorProps {
+    count: number;
+    activeIndex: number;
+    labels: (string | undefined)[];
+    onJump: (index: number) => void;
+}
+interface SwipableMobileCarouselProps {
+    /** Controlled active slide index — the caller owns this (typically via
+     *  useCarouselRouteSync, or plain useState). */
+    activeIndex: number;
+    /** Called when a swipe gesture settles on a different index, or when the
+     *  reorder-jump fix re-snaps after the active slide's position changes.
+     *  The caller is responsible for updating `activeIndex` in response. */
+    onSettle: (index: number) => void;
+    /** How many slides on each side of the active one stay mounted. Default 1
+     *  matches both sovereign-tasks' and sovereign-shopper's existing "swipe
+     *  never shows a spinner" behavior. Slides outside this window keep their
+     *  DOM slot (so scroll-snap's position-based indexing stays correct) but
+     *  their children are not mounted at all. */
+    prefetchDistance?: number;
+    /** Passed straight through to the internal useSnapCarousel. */
+    settleDebounceMs?: number;
+    /** Required — labels the scroller region for assistive tech. No generic
+     *  fallback, since one would be wrong for every actual consumer. */
+    'aria-label': string;
+    /** Renders the indicator. Defaults to SwipableMobileCarouselDots. Pass
+     *  `null` to render no indicator at all. */
+    renderIndicator?: null | ((props: SwipableMobileCarouselIndicatorProps) => ReactNode);
+    className?: string;
+    /** Must be SwipableMobileCarouselSlide elements (nullish/boolean children
+     *  are safely skipped for conditional slides). A dev-mode warning is
+     *  logged for any other child type — see resolveSlides below. */
+    children: ReactNode;
+}
+/**
+ * SwipableMobileCarousel — a compound component for swiping between full-
+ * width slides (each an independent route/view on mobile), wrapping
+ * useSnapCarousel. This library's first compound component: every other
+ * component here is flat/prop-based, but slide content is large, arbitrary,
+ * per-plugin subtrees that need a header-known/body-loading split an
+ * array-of-objects prop would only express with worse JSX ergonomics.
+ *
+ * Owns rendering and mount-window mechanics only — it has no opinion on
+ * where slide data lives. Do NOT: (a) aggregate cross-slide data inside a
+ * SwipableMobileCarouselSlideBody (that recomputes on every slide render
+ * regardless of which slide is active — belongs in the parent, which
+ * already knows every slide exists); (b) mount a detail overlay (Sheet,
+ * Dialog) inside a Slide's children — mount it as a sibling of
+ * SwipableMobileCarousel instead, controlled by the same state that would
+ * otherwise drive a routed page's overlay. sovereign-tasks' current
+ * hand-rolled carousel does both and is measurably laggier than
+ * sovereign-shopper's equivalent, which keeps its overlay in the routed pane.
+ */
+declare function SwipableMobileCarousel({ activeIndex, onSettle, prefetchDistance, settleDebounceMs, 'aria-label': ariaLabel, renderIndicator, className, children, }: SwipableMobileCarouselProps): react.JSX.Element;
+
+interface SwipableMobileCarouselSlideProps {
+    /** Stable identity for this slide, independent of its position among
+     *  siblings — required. This is what makes SwipableMobileCarousel's
+     *  reorder-jump fix possible: a plain array index can't distinguish "this
+     *  slide moved to position 2" from "this slide was removed and a
+     *  different one is now at position 2." Reuse whatever id the caller
+     *  already keys their `.map()` on (e.g. a list's own id). */
+    slideKey: string;
+    /** Accessible label surfaced to the default dots indicator (e.g.
+     *  "Groceries"). Falls back to "Slide N of count" if omitted — omitting it
+     *  logs a dev-mode warning, since every real slide usually has a title
+     *  available synchronously already. */
+    label?: string;
+    /** SwipableMobileCarouselSlideHeader/Body/Footer, in any order/subset. */
+    children: ReactNode;
+}
+/**
+ * SwipableMobileCarouselSlide — a single slide of a SwipableMobileCarousel.
+ * Renders its children only while within the carousel's mount window (the
+ * active slide ± its configured prefetchDistance); outside that window it
+ * renders nothing, matching both sovereign-tasks and sovereign-shopper's
+ * existing "never fetch/render a non-neighbor slide" behavior, now
+ * centralized instead of hand-rolled per plugin.
+ */
+declare function SwipableMobileCarouselSlide({ children }: SwipableMobileCarouselSlideProps): react.JSX.Element | null;
+
+interface SwipableMobileCarouselSlideHeaderProps {
+    children: ReactNode;
+    className?: string;
+}
+/**
+ * SwipableMobileCarouselSlideHeader — always renders its children, no
+ * loading concept. Meant for content already known synchronously (a list's
+ * title, color, item count from data the caller already has) so it can
+ * render immediately even while SwipableMobileCarouselSlideBody's own
+ * content is still loading — see that component's doc comment.
+ */
+declare function SwipableMobileCarouselSlideHeader({ children, className, }: SwipableMobileCarouselSlideHeaderProps): react.JSX.Element;
+
+interface SwipableMobileCarouselSlideBodyProps {
+    children: ReactNode;
+    /** While true, renders `loadingFallback` INSTEAD OF children — scoped to
+     *  just this region, not the whole slide. This is what fixes the
+     *  "whole slide blanks out, title included, until its own fetch resolves"
+     *  bug: a caller renders `<SwipableMobileCarouselSlideHeader>` from
+     *  already-known metadata unconditionally, and gates only this component's
+     *  `loading` on the slower fetch — the natural way to compose
+     *  Header/Body/Footer as siblings already produces that behavior, instead
+     *  of gating the entire slide behind one boolean. */
+    loading?: boolean;
+    loadingFallback?: ReactNode;
+    className?: string;
+}
+/**
+ * SwipableMobileCarouselSlideBody — the scrollable region of a slide.
+ *
+ * Deliberately does not set `touch-action: pan-y` on its scroll container
+ * (see SwipableMobileCarouselSlideParts.module.css's `.body` rule) — that
+ * would intersect-to-empty against the carousel's own horizontal
+ * touch-action handling (docs/architecture-rules.md's touch-action
+ * intersection rule), breaking both the vertical scroll here and the
+ * horizontal swipe between slides.
+ */
+declare function SwipableMobileCarouselSlideBody({ children, loading, loadingFallback, className, }: SwipableMobileCarouselSlideBodyProps): react.JSX.Element;
+
+interface SwipableMobileCarouselSlideFooterProps {
+    children: ReactNode;
+    className?: string;
+}
+/**
+ * SwipableMobileCarouselSlideFooter — always renders its children, no
+ * loading concept. See SwipableMobileCarouselSlideHeader's doc comment.
+ */
+declare function SwipableMobileCarouselSlideFooter({ children, className, }: SwipableMobileCarouselSlideFooterProps): react.JSX.Element;
+
+export { Accordion, type AccordionItem, type AccordionProps, Alert, type AlertProps, type AlertVariant, AspectRatio, type AspectRatioProps, Avatar, type AvatarProps, Badge, type BadgeProps, type BadgeStatus, type BadgeVariant, BalanceChip, type BalanceChipProps, type BannerVariant, Breadcrumb, type BreadcrumbItem, type BreadcrumbProps, Button, ButtonGroup, type ButtonGroupProps, type ButtonProps, type ButtonSize, type ButtonVariant, Calendar, type CalendarProps, Card, type CardProps, CheckableListRow, type CheckableListRowProps, Checkbox, type CheckboxProps, CodeTextarea, type CodeTextareaProps, Collapsible, type CollapsibleProps, Combobox, type ComboboxOption, type ComboboxProps, Command, type CommandItem, type CommandProps, type CommitOnEnterOrBlurHandlers, ConfirmDialog, type ConfirmDialogProps, ContextMenu, type ContextMenuProps, CurrencyInput, type CurrencyInputProps, DataTable, type DataTableColumn, type DataTableProps, DatePicker, type DatePickerProps, DeviceOnlyGate, type DeviceOnlyGateProps, DeviceStorageKeyGate, type DeviceStorageKeyGateProps, type DeviceStorageKeyGateStatus, Dialog, type DialogProps, type DialogSize, DragHandleRow, type DragHandleRowProps, Drawer, type DrawerProps, EmptyState, type EmptyStateProps, FileDropzone, type FileDropzoneProps, type FooterIcon, FormField, type FormFieldProps, type FormFieldRenderProps, HoverCard, type HoverCardProps, Icon, type IconName, IconPicker, type IconPickerProps, type IconProps, Input, type InputProps, Item, type ItemProps, Kbd, type KbdProps, Label, type LabelProps, LegalLinks, type LegalLinksProps, type LongPressHandlers, MOBILE_BREAKPOINT_PX, Markdown, type MarkdownProps, Marker, type MarkerProps, MemberMultiSelect, type MemberMultiSelectOption, type MemberMultiSelectProps, Menu, MenuEntries, type MenuEntry, type MenuItem, type MenuLabel, type MenuProps, type MenuSeparator, Menubar, type MenubarMenu, type MenubarProps, Message, type MessageProps, MessageScroller, type MessageScrollerProps, type MessageSender, MobileAppsDrawer, type MobileAppsDrawerItem, type MobileAppsDrawerProps, MobileFooter, type MobileFooterProps, MobileHeader, type MobileHeaderProps, type NavTabItem, type NavTabLinkProps, NavTabs, type NavTabsProps, NavigationMenu, type NavigationMenuItem, type NavigationMenuProps, OfflineGate, type OfflineGateProps, type OfflineTileState, OverlayHeader, type OverlayHeaderProps, PageContainer, type PageContainerProps, PageHeader, type PageHeaderProps, Pagination, type PaginationProps, Popover, type PopoverProps, Progress, type ProgressProps, QuantityStepper, type QuantityStepperProps, RadioGroup, type RadioGroupItem, type RadioGroupProps, type ResizableDirection, ResizableHandle, type ResizableHandleProps, ResizablePanel, ResizablePanelGroup, type ResizablePanelGroupProps, type ResizablePanelProps, ResponsiveSurface, type ResponsiveSurfaceProps, ScrollArea, type ScrollAreaProps, SegmentedControl, type SegmentedControlProps, type SegmentedOption, Select, type SelectProps, Sheet, type SheetProps, Slider, type SliderProps, type SortDirection, Spinner, type SpinnerProps, type SplitMethod, SplitMethodSelector, type SplitMethodSelectorProps, SplitPane, type SplitPaneProps, StatusBadge, type StatusBadgeProps, type StatusBadgeStatus, SuggestionInput, type SuggestionInputProps, type SuggestionOption, SwipableMobileCarousel, SwipableMobileCarouselDots, type SwipableMobileCarouselDotsProps, type SwipableMobileCarouselIndicatorProps, type SwipableMobileCarouselProps, SwipableMobileCarouselSlide, SwipableMobileCarouselSlideBody, type SwipableMobileCarouselSlideBodyProps, SwipableMobileCarouselSlideFooter, type SwipableMobileCarouselSlideFooterProps, SwipableMobileCarouselSlideHeader, type SwipableMobileCarouselSlideHeaderProps, type SwipableMobileCarouselSlideProps, SystemBanner, type SystemBannerProps, type TabItem, Table, TableBody, TableCell, TableHead, TableHeaderCell, type TableProps, TableRow, Tabs, type TabsProps, TagInput, type TagInputProps, Textarea, type TextareaProps, type ToastContextValue, type ToastItem, ToastProvider, Toggle, type ToggleProps, Tooltip, type TooltipProps, Typography, type TypographyProps, type TypographyVariant, type UseCarouselRouteSyncOptions, type UseCarouselRouteSyncResult, type UseLongPressOptions, type UseResponsiveLayoutOptions, type UseResponsiveLayoutResult, type UseSnapCarouselOptions, type UseSnapCarouselResult, type UseSwipeRevealHandlers, type UseSwipeRevealOptions, type UseSwipeRevealResult, useCarouselRouteSync, useCommitOnEnterOrBlur, useDoubleTapHandler, useIsMobile, useIsOffline, useLongPress, useOfflineTileState, useOverlaySecondRow, useResponsiveLayout, useSingleOrDoubleTap, useSnapCarousel, useSwipeReveal, useToast };