nexus-shell 0.1.23 → 0.2.0

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;

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

@@ -1,21 +1,110 @@
 import { default as React } from 'react';
 
+/** A node in the {@link TreeWidget} hierarchy. */
 export interface ITreeNode {
+    /** Stable identifier, unique across the whole tree. */
     id: string;
+    /** Text shown for the node. */
     label: string;
+    /** `folder` nodes expand on click; `file` nodes do not. */
     type: 'file' | 'folder';
+    /** Child nodes. Only rendered while `isOpen` is `true`. */
     children?: ITreeNode[];
+    /** Whether a folder is expanded. Controlled by you — see `onToggle`. */
     isOpen?: boolean;
-    level?: number;
+}
+/**
+ * Where a context-menu action applies.
+ *
+ * `nodeId` is `null` when the menu was opened on empty background, which is how
+ * you distinguish "new file here" from "new file at the root".
+ */
+export interface ITreeContext {
+    /** The right-clicked node's id, or `null` for the background. */
+    nodeId: string | null;
+    /** The right-clicked node, or `null` for the background. */
+    node: ITreeNode | null;
+}
+/** A custom entry in the tree's right-click menu. */
+export interface ITreeAction {
+    /** Stable identifier. Used as the React key. */
+    id: string;
+    /** Label shown in the menu. */
+    label: string;
+    /** Optional icon element, rendered before the label. */
+    icon?: React.ReactNode;
+    /** Runs with the right-clicked target. */
+    onSelect: (context: ITreeContext) => void;
+    /** Draw a separator above this entry. */
+    divider?: boolean;
+    /**
+     * Restrict where the entry appears. Defaults to everywhere. Use this for
+     * actions that only make sense on a folder, or only on the background.
+     */
+    showFor?: ('file' | 'folder' | 'background')[];
 }
 export interface TreeWidgetProps {
+    /** Root nodes. Expansion state lives on the nodes themselves via `isOpen`. */
     data: ITreeNode[];
-    onMoveNode?: (draggedId: string, targetId: string) => void;
+    /**
+     * Called when a folder is clicked. Flip that node's `isOpen` in your own
+     * state — the tree renders expansion but does not own it.
+     */
+    onToggle?: (node: ITreeNode) => void;
+    /** Called when a node is double-clicked. Typically opens the item. */
+    onActivate?: (node: ITreeNode) => void;
+    /** Called after a node is dragged onto a folder. */
+    onMoveNode?: (draggedId: string, targetFolderId: string) => void;
+    /**
+     * Entries for the right-click menu. Defaults to New File, New Folder, Rename
+     * and Delete, which map to the `onNew*` / `onRename` / `onDelete` props.
+     *
+     * Pass your own array to replace that set entirely — this is the extension
+     * point for app-specific commands, so the tree itself stays generic.
+     */
+    actions?: ITreeAction[];
+    /** Handler for the built-in "New File" action. */
     onNewFile?: (parentId: string | null) => void;
+    /** Handler for the built-in "New Folder" action. */
     onNewFolder?: (parentId: string | null) => void;
-    onNewDialogueMap?: (parentId: string | null) => void;
+    /** Handler for the built-in "Rename" action. */
     onRename?: (nodeId: string) => void;
+    /** Handler for the built-in "Delete" action. */
     onDelete?: (nodeId: string) => void;
-    onDoubleClick?: (node: ITreeNode) => void;
+    /** Indentation added per depth level, in px. Defaults to `12`. */
+    indent?: number;
+    /**
+     * Virtualise rows with `react-virtuoso`. Leave on for large trees; turn it
+     * off when every row must be present in the DOM — printing, full-text browser
+     * search, or a test environment that can't measure layout. Defaults to `true`.
+     */
+    virtualized?: boolean;
+    /** Extra classes merged onto the root element. */
+    className?: string;
 }
-export declare const TreeWidget: React.FC<TreeWidgetProps>;
+/**
+ * A virtualised file-explorer tree with drag-to-move and a right-click menu.
+ *
+ * Rows are virtualised via `react-virtuoso`, so very large trees stay
+ * responsive. The component is controlled: expansion lives on your nodes as
+ * `isOpen` and changes are reported through `onToggle`, so the tree never holds
+ * a second copy of your data.
+ *
+ * The context menu is data-driven. The defaults cover the usual file
+ * operations; pass `actions` to replace them with your own commands rather than
+ * adding one-off props.
+ *
+ * @example
+ * ```tsx
+ * <TreeWidget
+ *   data={nodes}
+ *   onToggle={(n) => setNodes(toggle(nodes, n.id))}
+ *   onActivate={(n) => open(n.id)}
+ *   actions={[
+ *     { id: 'new-map', label: 'New Map', icon: <Map size={14} />,
+ *       showFor: ['folder', 'background'], onSelect: (ctx) => createMap(ctx.nodeId) },
+ *   ]}
+ * />
+ * ```
+ */
+export declare const TreeWidget: ({ data, onToggle, onActivate, onMoveNode, actions, onNewFile, onNewFolder, onRename, onDelete, indent, virtualized, className, }: TreeWidgetProps) => import("react/jsx-runtime").JSX.Element;