nexus-shell 0.1.23 → 0.2.1

package/dist/components/widgets/CommandPalette.d.ts

@@ -1,8 +1,56 @@
-import { ICommand } from '../../core/registry/CommandRegistry';
-
-interface CommandPaletteProps {
-    commands?: ICommand[];
-    forcedOpen?: boolean;
+/** An entry in the {@link CommandPalette} list. */
+export interface ICommandItem {
+    /** Stable identifier. Also matched against the query. */
+    id: string;
+    /** Human-readable name shown in the list and matched against the query. */
+    label: string;
+    /** Optional keybinding hint rendered on the right, e.g. `"⌘K"`. */
+    keybinding?: string;
 }
-export declare const CommandPalette: ({ commands: customCommands, forcedOpen }: CommandPaletteProps) => import("react/jsx-runtime").JSX.Element | null;
-export {};
+export interface CommandPaletteProps<T extends ICommandItem = ICommandItem> {
+    /** Whether the palette is showing. */
+    open: boolean;
+    /** Commands to offer. Filtered against the query by `label` and `id`. */
+    commands: T[];
+    /** Called with the chosen command on click or Enter. */
+    onSelect: (command: T) => void;
+    /** Called on Escape and on backdrop click. */
+    onClose?: () => void;
+    /**
+     * Render inline instead of as a fixed overlay. Useful for documenting the
+     * palette in Storybook, or embedding it in a page. Defaults to `false`.
+     */
+    inline?: boolean;
+    /** Placeholder for the query input. */
+    placeholder?: string;
+    /**
+     * Custom filter. Receives every command and the current query; return `true`
+     * to keep. Defaults to a case-insensitive substring match on `label` and `id`.
+     */
+    filter?: (command: T, query: string) => boolean;
+    /** Extra classes merged onto the palette surface. */
+    className?: string;
+}
+/**
+ * A VS Code-style command palette: a fuzzy-filtered, keyboard-navigable list of
+ * commands over a dimmed backdrop.
+ *
+ * Fully controlled — it owns only the query text and the highlighted row.
+ * Visibility, the command list and execution are the caller's. It also binds no
+ * global keyboard shortcut; for the store-backed variant that reads the
+ * {@link commandRegistry} and binds `Cmd/Ctrl+Shift+P`, see
+ * `ConnectedCommandPalette`.
+ *
+ * Arrow keys move the highlight, Enter selects, Escape closes.
+ *
+ * @example
+ * ```tsx
+ * <CommandPalette
+ *   open={open}
+ *   commands={[{ id: 'file.save', label: 'Save File', keybinding: '⌘S' }]}
+ *   onSelect={(cmd) => { run(cmd.id); setOpen(false); }}
+ *   onClose={() => setOpen(false)}
+ * />
+ * ```
+ */
+export declare const CommandPalette: <T extends ICommandItem = ICommandItem>({ open, commands, onSelect, onClose, inline, placeholder, filter, className, }: CommandPaletteProps<T>) => import("react/jsx-runtime").JSX.Element | null;

package/dist/components/widgets/ContextMenu.d.ts

@@ -1,16 +1,47 @@
 import { default as React } from 'react';
 
+/** An entry in a {@link ContextMenu}. */
 export interface IContextMenuItem {
+    /** Label shown for the entry. */
     label: string;
+    /** Optional element rendered before the label, e.g. `<Plus size={14} />`. */
     icon?: React.ReactNode;
+    /** Runs on click. The menu closes afterwards. */
     onClick: () => void;
+    /** Draw a separator above this entry. */
     divider?: boolean;
+    /** Render the entry greyed out and non-interactive. */
+    disabled?: boolean;
 }
-interface ContextMenuProps {
+export interface ContextMenuProps {
+    /** Viewport x coordinate, typically `event.clientX`. */
     x: number;
+    /** Viewport y coordinate, typically `event.clientY`. */
     y: number;
+    /** Entries to show, in order. */
     items: IContextMenuItem[];
+    /** Called on outside click, on Escape, and after any entry is chosen. */
     onClose: () => void;
+    /** Extra classes merged onto the menu surface. */
+    className?: string;
 }
-export declare const ContextMenu: React.FC<ContextMenuProps>;
-export {};
+/**
+ * A floating menu positioned at viewport coordinates, for right-click menus.
+ *
+ * Renders `position: fixed` at the given point and closes on outside click or
+ * Escape. It does not decide when to appear — mount it conditionally from your
+ * own `onContextMenu` handler and store the coordinates yourself.
+ *
+ * @example
+ * ```tsx
+ * {menu && (
+ *   <ContextMenu
+ *     x={menu.x}
+ *     y={menu.y}
+ *     items={[{ label: 'Delete', onClick: () => remove(menu.id) }]}
+ *     onClose={() => setMenu(null)}
+ *   />
+ * )}
+ * ```
+ */
+export declare const ContextMenu: ({ x, y, items, onClose, className }: ContextMenuProps) => import("react/jsx-runtime").JSX.Element;

package/dist/components/widgets/DataGrid.d.ts

@@ -1,22 +1,66 @@
 import { default as React } from 'react';
 
+/** A column definition for {@link DataGrid}. */
 export interface IDataGridColumn<T = any> {
+    /** Property on the row object to read. Also used as the React key. */
     key: string;
+    /** Header text. */
     header: string;
+    /** Fixed column width as a CSS length or px number. Omit to size flexibly. */
     width?: string | number;
+    /** Allow clicking the header to sort by this column. Defaults to `false`. */
     sortable?: boolean;
+    /**
+     * Custom cell renderer. Receives the cell value and the whole row, so you can
+     * render badges, links or derived values. Defaults to the raw value.
+     */
     render?: (value: any, row: T) => React.ReactNode;
 }
 export interface DataGridProps<T = any> {
+    /** Columns, in display order. */
     columns: IDataGridColumn<T>[];
+    /** Rows to display. Sorting and filtering are applied on top of this array. */
     data: T[];
+    /** Called with the clicked row. */
     onRowClick?: (row: T) => void;
+    /** Value of `rowKey` on the row to highlight as selected. */
     selectedRowId?: string | number;
+    /** Property used as each row's identity. Defaults to `"id"`. */
     rowKey?: keyof T;
+    /**
+     * Virtualise rows with `react-virtuoso`. Leave on for large datasets; turn it
+     * off when the grid must print or be fully present in the DOM. Defaults to
+     * `true`.
+     */
     virtualized?: boolean;
+    /** Show the built-in filter box above the grid. Defaults to `true`. */
     showFilter?: boolean;
+    /** Show a loading indicator in place of rows. Defaults to `false`. */
     loading?: boolean;
+    /** Message shown when there are no rows. */
     placeholder?: string;
+    /** Extra classes merged onto the root element. */
     className?: string;
 }
+/**
+ * A sortable, filterable data table with optional row virtualisation.
+ *
+ * Filtering and sorting are handled internally against the `data` you pass — a
+ * case-insensitive match across all values, and click-to-sort on columns marked
+ * `sortable`. For server-side paging or sorting, filter upstream and set
+ * `showFilter={false}`.
+ *
+ * @example
+ * ```tsx
+ * <DataGrid
+ *   columns={[
+ *     { key: 'name', header: 'Name', sortable: true },
+ *     { key: 'status', header: 'Status', width: 120,
+ *       render: (v) => <Badge>{v}</Badge> },
+ *   ]}
+ *   data={rows}
+ *   onRowClick={(row) => select(row.id)}
+ * />
+ * ```
+ */
 export declare const DataGrid: <T extends Record<string, any>>({ columns, data, onRowClick, selectedRowId, rowKey, virtualized, showFilter, loading, placeholder, className, }: DataGridProps<T>) => import("react/jsx-runtime").JSX.Element;

package/dist/components/widgets/MenuBar.d.ts

@@ -1,6 +1,56 @@
-interface MenuBarProps {
-    title?: React.ReactNode;
-    rightContent?: React.ReactNode;
+import { ReactNode } from 'react';
+
+/** An entry in a {@link MenuBar} dropdown. */
+export interface IMenuItem {
+    /** Stable identifier reported to `onSelect`. */
+    id: string;
+    /** Label shown in the dropdown. */
+    label: string;
+    /** Keybinding hint shown right-aligned, e.g. `"⌘S"`. */
+    keybinding?: string;
+    /** Nested items. An item with a submenu is not itself selectable. */
+    submenu?: IMenuItem[];
 }
-export declare const MenuBar: ({ title, rightContent }: MenuBarProps) => import("react/jsx-runtime").JSX.Element;
-export {};
+export interface MenuBarProps {
+    /**
+     * Menus keyed by top-level label, e.g. `{ File: [...], Edit: [...] }`.
+     * Insertion order determines display order.
+     */
+    menus?: Record<string, IMenuItem[]>;
+    /** Called with the chosen leaf item. Items with a `submenu` never fire this. */
+    onSelect?: (item: IMenuItem) => void;
+    /**
+     * Branding shown at the far left. Pass a string, a logo element, or omit it
+     * for the default wordmark. Providing a `title` switches the bar to its
+     * taller, translucent variant.
+     */
+    title?: ReactNode;
+    /**
+     * Slot between the menus and the right edge, sized for a search input. The
+     * bar renders whatever you pass — it does not embed a search component.
+     */
+    center?: ReactNode;
+    /** Slot at the far right, for a theme switcher, avatar, or actions. */
+    right?: ReactNode;
+    /** Extra classes merged onto the root `<header>`. */
+    className?: string;
+}
+/**
+ * The application menu bar: a row of hover-activated dropdowns with optional
+ * one-level submenus, plus slots for branding, a centre widget and right-hand
+ * actions.
+ *
+ * Presentational and fully controlled — menus come in as data and selections go
+ * out through `onSelect`. It reads no registry. For the variant wired to the
+ * {@link menuRegistry} and {@link commandRegistry}, see `ConnectedMenuBar`.
+ *
+ * @example
+ * ```tsx
+ * <MenuBar
+ *   menus={{ File: [{ id: 'save', label: 'Save', keybinding: '⌘S' }] }}
+ *   onSelect={(item) => run(item.id)}
+ *   right={<ThemeSwitcher value={theme} onChange={setTheme} />}
+ * />
+ * ```
+ */
+export declare const MenuBar: ({ menus, onSelect, title, center, right, className, }: MenuBarProps) => import("react/jsx-runtime").JSX.Element;

package/dist/components/widgets/Modal.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Which of the three dialog shapes to render.
+ *
+ * - `alert` — a single OK button.
+ * - `confirm` — Cancel and Confirm.
+ * - `prompt` — Cancel and Confirm, plus a text input.
+ */
+export type ModalType = 'alert' | 'confirm' | 'prompt';
+export interface ModalProps {
+    /** Whether the dialog is mounted. Nothing renders when `false`. */
+    open: boolean;
+    /** Dialog shape. Defaults to `"alert"`. */
+    type?: ModalType;
+    /** Heading text. */
+    title: string;
+    /** Body text. Newlines are preserved. */
+    message?: string;
+    /** Initial value of the input when `type` is `"prompt"`. */
+    defaultValue?: string;
+    /**
+     * Called on Confirm/OK and on Enter. Receives the input text for `prompt`,
+     * and `undefined` for `alert` and `confirm`.
+     */
+    onConfirm?: (value?: string) => void;
+    /** Called on Cancel, on the close button, on Escape, and on backdrop click. */
+    onCancel?: () => void;
+    /** Label for the confirm button. Defaults to `"OK"` / `"Confirm"` by `type`. */
+    confirmLabel?: string;
+    /** Label for the cancel button. Defaults to `"Cancel"`. */
+    cancelLabel?: string;
+    /** Placeholder for the prompt input. */
+    placeholder?: string;
+    /** Extra classes merged onto the dialog surface. */
+    className?: string;
+}
+/**
+ * A centered modal dialog covering the three common blocking interactions:
+ * alert, confirm and prompt.
+ *
+ * Fully controlled — it owns only the prompt's draft text. Escape, backdrop
+ * click and the close button all route to `onCancel`; Enter routes to
+ * `onConfirm`. For the promise-based variant driven by `useModalStore` (so you
+ * can `await openConfirm(...)` from anywhere), see `ConnectedModal`.
+ *
+ * @example
+ * ```tsx
+ * <Modal
+ *   open={open}
+ *   type="prompt"
+ *   title="Rename file"
+ *   message="Enter a new name."
+ *   defaultValue="untitled.ts"
+ *   onConfirm={(name) => rename(name)}
+ *   onCancel={() => setOpen(false)}
+ * />
+ * ```
+ */
+export declare const Modal: ({ open, type, title, message, defaultValue, onConfirm, onCancel, confirmLabel, cancelLabel, placeholder, className, }: ModalProps) => import("react/jsx-runtime").JSX.Element | null;

package/dist/components/widgets/QuickSearch.d.ts

@@ -0,0 +1,66 @@
+import { default as React } from 'react';
+
+/** A single row in the {@link QuickSearch} dropdown. */
+export interface IQuickSearchResult {
+    /** Identifier, unique within its category. */
+    id: string;
+    /** Primary line. */
+    title: string;
+    /** Secondary line, truncated to one line. Often a path or shortcut hint. */
+    description?: string;
+    /**
+     * Group heading this result appears under. Groups render in the order given
+     * by the `categories` prop, or in first-seen order when that is omitted.
+     */
+    category: string;
+    /** Icon component rendered at 12px in the row's leading badge. */
+    icon?: React.ComponentType<{
+        size?: number;
+        className?: string;
+    }>;
+}
+export interface QuickSearchProps<T extends IQuickSearchResult = IQuickSearchResult> {
+    /**
+     * Results for the current query. `QuickSearch` does no filtering — it renders
+     * exactly what you give it, so you control matching, ranking and async
+     * loading.
+     */
+    results: T[];
+    /** Called on every keystroke, debounced by `debounceMs`. */
+    onQueryChange?: (query: string) => void;
+    /** Called when a row is clicked or chosen with Enter. */
+    onSelect: (result: T) => void;
+    /**
+     * Explicit category order. Categories absent from this list are dropped, so
+     * it doubles as a whitelist. Defaults to first-seen order.
+     */
+    categories?: string[];
+    /** Placeholder for the input. Defaults to `"Search…"`. */
+    placeholder?: string;
+    /** Delay before `onQueryChange` fires, in ms. Defaults to `200`. */
+    debounceMs?: number;
+    /** Extra classes merged onto the root element. */
+    className?: string;
+}
+/**
+ * A compact search field with a grouped results dropdown, sized to sit inside a
+ * {@link MenuBar}.
+ *
+ * Presentational and fully controlled — it owns the query text, the open state
+ * and the keyboard highlight, and nothing else. Searching is entirely yours:
+ * results are pushed in via `results`, so the same component backs a local
+ * array, a registry lookup, or a remote index.
+ *
+ * Arrow keys move the highlight across groups, Enter selects, Escape closes.
+ *
+ * @example
+ * ```tsx
+ * <QuickSearch
+ *   results={hits}
+ *   categories={['Actions', 'Files']}
+ *   onQueryChange={setQuery}
+ *   onSelect={(hit) => open(hit.id)}
+ * />
+ * ```
+ */
+export declare const QuickSearch: <T extends IQuickSearchResult = IQuickSearchResult>({ results, onQueryChange, onSelect, categories, placeholder, debounceMs, className, }: QuickSearchProps<T>) => import("react/jsx-runtime").JSX.Element;

package/dist/components/widgets/SearchWidget.d.ts

@@ -1,19 +1,55 @@
 import { default as React } from 'react';
 
+/** A result row in {@link SearchWidget}. */
 export interface ISearchResult {
+    /** Stable identifier. Used as the React key. */
     id: string;
+    /** Primary line. */
     title: string;
+    /** Secondary line, truncated to one line. */
     description?: string;
+    /** Icon component rendered at 14px in the leading badge. */
     icon?: React.ComponentType<any>;
+    /** Short tag rendered right-aligned on the title row, e.g. `"FILE"`. */
     category?: string;
 }
 export interface SearchWidgetProps {
+    /** Placeholder for the input. Defaults to `"Search..."`. */
     placeholder?: string;
+    /**
+     * Called with the current query, debounced by 300ms. Do your matching here
+     * and feed the outcome back through `results`.
+     */
     onSearch: (query: string) => void;
+    /** Results for the current query. The widget renders them as given. */
     results: ISearchResult[];
+    /** Called with the clicked result. */
     onSelect: (result: ISearchResult) => void;
+    /** Past or suggested queries offered as autocomplete below the input. */
     suggestions?: string[];
+    /** Swap the search icon for a spinner while a query is in flight. */
     loading?: boolean;
+    /** Extra classes merged onto the root element. */
     className?: string;
 }
+/**
+ * A full-height search panel: an input with autocomplete over a scrolling
+ * result list. Sized for the sidebar, unlike the compact {@link QuickSearch}
+ * that sits in the menu bar.
+ *
+ * Controlled with respect to results — it owns the query text and debounces it
+ * to `onSearch`, but never filters `results` itself. That keeps async and
+ * remote search straightforward.
+ *
+ * @example
+ * ```tsx
+ * <SearchWidget
+ *   onSearch={setQuery}
+ *   results={hits}
+ *   loading={isFetching}
+ *   suggestions={recentQueries}
+ *   onSelect={(hit) => open(hit.id)}
+ * />
+ * ```
+ */
 export declare const SearchWidget: React.FC<SearchWidgetProps>;

package/dist/components/widgets/SettingsPanel.d.ts

@@ -0,0 +1,33 @@
+import { LucideIcon } from 'lucide-react';
+
+/** A theme choice offered by {@link SettingsPanel}. */
+export interface ISettingsThemeOption<T extends string = string> {
+    id: T;
+    label: string;
+    icon: LucideIcon;
+}
+export declare const DEFAULT_SETTINGS_THEMES: ISettingsThemeOption[];
+export interface SettingsPanelProps<T extends string = string> {
+    /** Currently selected theme id. */
+    theme: T;
+    /** Called with the newly selected theme id. */
+    onThemeChange: (theme: T) => void;
+    /** Theme choices to offer. Defaults to the three bundled themes. */
+    themes?: ISettingsThemeOption<T>[];
+    /** Extra classes merged onto the root element. */
+    className?: string;
+}
+/**
+ * Sidebar body for the Settings panel: a vertical list of theme choices.
+ *
+ * Split out of {@link SidebarPane} so the pane stays a generic container. Pass
+ * this (or your own component) as the sidebar's `children`.
+ *
+ * @example
+ * ```tsx
+ * <SidebarPane title="Settings" onClose={close}>
+ *   <SettingsPanel theme={theme} onThemeChange={setTheme} />
+ * </SidebarPane>
+ * ```
+ */
+export declare const SettingsPanel: <T extends string = string>({ theme, onThemeChange, themes, className, }: SettingsPanelProps<T>) => import("react/jsx-runtime").JSX.Element;

package/dist/components/widgets/SidebarPane.d.ts

@@ -1 +1,37 @@
-export declare const SidebarPane: () => import("react/jsx-runtime").JSX.Element | null;
+import { ReactNode } from 'react';
+
+export interface SidebarPaneProps {
+    /**
+     * Heading text. Rendered uppercase with letter-spacing; pass it in natural
+     * case and let the component style it.
+     */
+    title: string;
+    /** Panel body. Scrolls independently of the header. */
+    children?: ReactNode;
+    /**
+     * Called when the close button is pressed. Omit it to hide the close button
+     * entirely — useful when the pane is always visible.
+     */
+    onClose?: () => void;
+    /** Fixed pane width, as a CSS length. Defaults to `"300px"`. */
+    width?: string;
+    /** Extra classes merged onto the root `<aside>`. */
+    className?: string;
+}
+/**
+ * The collapsible panel beside the {@link ActivityBar}: a titled header with an
+ * optional close button, over a scrolling body.
+ *
+ * A pure container — it decides nothing about which panel is showing and holds
+ * no state. Render whatever you like as `children`. For the store-backed
+ * variant that resolves the active panel from `useSidebarStore`, see
+ * `ConnectedSidebarPane`.
+ *
+ * @example
+ * ```tsx
+ * <SidebarPane title="Explorer" onClose={() => setActive(null)}>
+ *   <TreeWidget data={files} />
+ * </SidebarPane>
+ * ```
+ */
+export declare const SidebarPane: ({ title, children, onClose, width, className, }: SidebarPaneProps) => import("react/jsx-runtime").JSX.Element;

package/dist/components/widgets/StatusBar.d.ts

@@ -1 +1,51 @@
-export declare const StatusBar: () => import("react/jsx-runtime").JSX.Element;
+import { LucideIcon } from 'lucide-react';
+
+/**
+ * A single item rendered into one of the status bar's three alignment groups.
+ */
+export interface IStatusBarWidget {
+    /** Stable unique identifier. Used as the React key. */
+    id: string;
+    /** Text shown next to the icon. Pass an empty string for an icon-only item. */
+    label: string;
+    /** Optional `lucide-react` icon rendered before the label at 12px. */
+    icon?: LucideIcon;
+    /** Which of the three groups the item belongs to. */
+    alignment: 'left' | 'center' | 'right';
+    /** Invoked on click and on Enter/Space. Providing it makes the item interactive. */
+    onClick?: () => void;
+    /** Extra classes merged onto the item, e.g. `"text-green-500"`. */
+    className?: string;
+    /** Higher values sort earlier within the group. Defaults to `0`. */
+    priority?: number;
+}
+export interface StatusBarProps {
+    /**
+     * Items to display. They are grouped by `alignment` and sorted by descending
+     * `priority` within each group.
+     */
+    widgets?: IStatusBarWidget[];
+    /** Accessible label for the landmark. Defaults to `"Status Bar"`. */
+    'aria-label'?: string;
+    /** Extra classes merged onto the root `<footer>`. */
+    className?: string;
+}
+/**
+ * A VS Code-style status bar: a fixed-height footer with left, center and right
+ * item groups. Items may be static labels or interactive buttons.
+ *
+ * This component is fully controlled — it holds no state and reads no global
+ * store. For the store-backed variant used by `ShellLayout`, see
+ * {@link ConnectedStatusBar}.
+ *
+ * @example
+ * ```tsx
+ * <StatusBar
+ *   widgets={[
+ *     { id: 'branch', label: 'main', icon: GitBranch, alignment: 'left', onClick: openBranches },
+ *     { id: 'ln', label: 'Ln 12, Col 4', alignment: 'right' },
+ *   ]}
+ * />
+ * ```
+ */
+export declare const StatusBar: ({ widgets, className, "aria-label": ariaLabel, }: StatusBarProps) => import("react/jsx-runtime").JSX.Element;

package/dist/components/widgets/TerminalPane.d.ts

@@ -1 +1,43 @@
-export declare const TerminalPane: () => import("react/jsx-runtime").JSX.Element | null;
+export interface TerminalPaneProps {
+    /** Lines already written to the terminal, oldest first. */
+    history?: string[];
+    /**
+     * Called with the trimmed command text when the user presses Enter. Empty
+     * input is swallowed and never reaches this handler.
+     *
+     * The component does not echo the command or interpret it — append the echo
+     * and any output to `history` yourself. This keeps command semantics
+     * (`clear`, `help`, anything app-specific) entirely in your hands.
+     */
+    onCommand?: (command: string) => void;
+    /** Called when the collapse or close button is pressed. */
+    onClose?: () => void;
+    /** Height of the pane, as a CSS length. Defaults to `"250px"`. */
+    height?: string;
+    /** Prompt string shown before the input. Defaults to `"$"`. */
+    prompt?: string;
+    /** Title shown in the pane header. Defaults to `"Terminal"`. */
+    title?: string;
+    /** Extra classes merged onto the root element. */
+    className?: string;
+}
+/**
+ * A bottom-docked terminal pane: a scrolling output log over a single-line
+ * input.
+ *
+ * Presentational and fully controlled — it owns only the in-progress input
+ * text. Visibility, history and command execution all belong to the caller.
+ * For the store-backed variant with built-in `clear`/`help` handling, see
+ * `ConnectedTerminalPane`.
+ *
+ * @example
+ * ```tsx
+ * const [history, setHistory] = useState<string[]>([]);
+ * <TerminalPane
+ *   history={history}
+ *   onCommand={(cmd) => setHistory((h) => [...h, `$ ${cmd}`, run(cmd)])}
+ *   onClose={() => setOpen(false)}
+ * />
+ * ```
+ */
+export declare const TerminalPane: ({ history, onCommand, onClose, height, prompt, title, className, }: TerminalPaneProps) => import("react/jsx-runtime").JSX.Element;

package/dist/components/widgets/ThemeSwitcher.d.ts

@@ -1,7 +1,37 @@
-import { default as React } from 'react';
-
-export interface ThemeSwitcherProps {
+/** An option in the {@link ThemeSwitcher} segmented control. */
+export interface IThemeOption<T extends string = string> {
+    /** Value reported to `onChange`. Also used as the React key. */
+    id: T;
+    /** Short label shown on the segment. Kept terse — segments are compact. */
+    label: string;
+}
+export declare const DEFAULT_THEME_OPTIONS: IThemeOption[];
+export interface ThemeSwitcherProps<T extends string = string> {
+    /** Currently selected theme id. */
+    value: T;
+    /** Called with the newly selected theme id. */
+    onChange: (theme: T) => void;
+    /**
+     * Selectable themes. Defaults to Light / Dark / Georgia Tech, matching the
+     * themes shipped in the library's stylesheet.
+     */
+    options?: IThemeOption<T>[];
+    /** Extra classes merged onto the root element. */
     className?: string;
+    /** Accessible label for the group. Defaults to `"Theme"`. */
+    'aria-label'?: string;
 }
-export declare const ThemeSwitcher: React.FC<ThemeSwitcherProps>;
-export default ThemeSwitcher;
+/**
+ * A compact segmented control for switching themes.
+ *
+ * Controlled — it renders `value` and reports changes through `onChange`, and
+ * applies no classes to the document itself. For the store-backed variant that
+ * also sets the theme class on `<html>`, see `ConnectedThemeSwitcher`.
+ *
+ * @example
+ * ```tsx
+ * const [theme, setTheme] = useState('light');
+ * <ThemeSwitcher value={theme} onChange={setTheme} />
+ * ```
+ */
+export declare const ThemeSwitcher: <T extends string = string>({ value, onChange, options, className, "aria-label": ariaLabel, }: ThemeSwitcherProps<T>) => import("react/jsx-runtime").JSX.Element;