nexus-shell 0.1.23 → 0.2.0

package/README.md

@@ -1,147 +1,188 @@
-# 🚀 Nexus Shell Framework
+# Nexus Shell
 
-[![npm version](https://img.shields.io/npm/v/nexus-shell.svg)](https://www.npmjs.com/package/nexus-shell)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-[![Build & Deploy Storybook](https://github.com/techmuch/nexus-shell/actions/workflows/deploy-storybook.yml/badge.svg)](https://github.com/techmuch/nexus-shell/actions/workflows/deploy-storybook.yml)
-[![Live Documentation](https://img.shields.io/badge/docs-live--pages-blueviolet)](https://techmuch.github.io/nexus-shell/?path=/docs/introduction--docs)
+React components for building IDE-style application shells — menu bar, activity
+bar, sidebar, docking layout, terminal, chat pane and status bar.
 
-Nexus Shell is a professional-grade, library-first React 19 / TypeScript frontend framework for building multi-panel **"Workbench"** style applications (resembling VS Code, JupyterLab, or specialized dashboard workstations). 
+**[Documentation and live examples →](https://techmuch.github.io/nexus-shell/)** ·
+[Storybook](https://techmuch.github.io/nexus-shell/storybook/)
 
-Instead of building a rigid layout from scratch, Nexus Shell provides a **fully decoupled, registry-driven workspace engine** powered by `flexlayout-react`, allowing tabs, menus, hotkeys, status bars, and custom sidebars to be dynamically declared and contextually composed.
+```bash
+npm install nexus-shell
+```
 
----
+```ts
+import 'nexus-shell/style.css';
+```
 
-## 📖 Live Interactive Documentation
-Explore the live documentation, interactive component playground, prop definitions, and layout compositions at:
-👉 **[Live Storybook Documentation Site](https://techmuch.github.io/nexus-shell/?path=/docs/introduction--docs)**
+React 19 is a peer dependency.
 
----
+## Two tiers
 
-## 🎨 Visual Showcase & Capabilities
+**Primitives** are pure and prop-driven. No global state, no registry lookups.
+You pass data in, you get callbacks out.
 
-### 1. Tabbed Dialogue Mapping Workbench & Workspace
-A flexible workstation that integrates Compendium-style visual argumentation mapping (React Flow canvas) with external node libraries and logic inspectors as drag-and-drop tabs.
-![Dialogue Mapping Workbench (Dark Theme)](docs/images/dialogue-mapper-library-dark.png)
-*(Above: Dialogue Mapping workspace in Dark Theme showing interactive nodes, custom icons, and Straight connectors)*
+```tsx
+import { StatusBar, ActivityBar, SidebarPane, TreeWidget } from 'nexus-shell';
+
+const [active, setActive] = useState<string | null>('files');
+
+<div className="theme-light flex h-screen flex-col">
+  <div className="flex flex-1">
+    <ActivityBar
+      items={panels}
+      activeId={active}
+      onSelect={(id) => setActive(id === active ? null : id)}
+    />
+    {active && (
+      <SidebarPane title="Explorer" onClose={() => setActive(null)}>
+        <TreeWidget data={files} onToggle={toggle} onActivate={open} />
+      </SidebarPane>
+    )}
+    <main className="flex-1">{children}</main>
+  </div>
+  <StatusBar widgets={[{ id: 'branch', label: 'main', alignment: 'left' }]} />
+</div>;
+```
 
-### 2. Georgia Tech Theme & Theme-Adaptivity
-Fully responsive styling driven by HSL CSS variables, conforming to WCAG contrast standards.
-![Dialogue Mapping Workbench (GT Theme)](docs/images/dialogue-mapper-library-light.png)
-*(Above: Light Theme workspace showing responsive menus, active tab headers, and the account widget)*
+**`ShellLayout`** is the assembled frame — the same components, wired to a set of
+zustand stores and registries so you configure declaratively:
 
-### 3. Workflow Reviews & Mockup Canvas Overlay
-Draw overlay annotations directly onto child mockups and generate implementation plans dynamically using AI nodes.
-![Mockup Reviewer Layout](docs/images/mockup-reviewer-layout.png)
-*(Above: A complex Mockup Reviewer workstation running canvas drawing tools and terminal consoles side-by-side)*
+```tsx
+import { ShellLayout, componentRegistry } from 'nexus-shell';
 
-### 4. Interactive Storybook Workspace
-Reorganized story taxonomy allowing you to build, test, and preview widgets in isolation or combined.
-![Storybook Taxonomy](docs/images/media__storybook_layout.png)
+componentRegistry.register('editor', Editor);
 
----
+<ShellLayout
+  title={<Logo />}
+  panels={[{ id: 'files', label: 'Explorer', icon: Files, component: FileTree }]}
+  menuConfig={{ File: [{ id: 'save', label: 'Save', commandId: 'file.save' }] }}
+  statusBarConfig={[{ id: 'branch', label: 'main', alignment: 'left' }]}
+/>;
+```
 
-## 🤔 Why Choose Nexus Shell?
+Each primitive also has a `Connected*` variant that binds it to the matching
+store. `ShellLayout` is built out of those, and they're exported, so you can mix
+tiers freely.
 
-| If you are building... | Nexus Shell provides... |
-| :--- | :--- |
-| **IDE/Workbench Web Apps** | A complete drag-and-drop tab layout engine with splits, resizing, and sidebars (`flexlayout-react` integration). |
-| **Modular Dashboard Interfaces** | Inversion of Control registries (`componentRegistry`, `commandRegistry`, `menuRegistry`) so features register themselves dynamically. |
-| **Complex Geospatial/Tactical Maps** | High-performance maps (`WargameMap`) combining `react-map-gl`, `deck.gl`, and `h3-js` for hexagonal grid overlays and MIL-STD military icons. |
-| **AI Orchestration Workbenches** | State-driven workflow templates, agent nodes, and drawing canvas mockups built with React Flow. |
+## Components
 
----
+| Primitive | What it is |
+| :-- | :-- |
+| `ActivityBar` | Vertical icon rail for switching sidebar panels |
+| `ChatPane` | Docked chat transcript with slash-command autocomplete |
+| `CommandPalette` | Filterable, keyboard-navigable command list |
+| `ContextMenu` | Floating menu positioned at viewport coordinates |
+| `DataGrid` | Sortable, filterable table with optional virtualisation |
+| `MenuBar` | Application menu bar with submenus and content slots |
+| `Modal` | Alert / confirm / prompt dialog |
+| `QuickSearch` | Compact search field with grouped results, for the menu bar |
+| `SearchWidget` | Full-height search panel with autocomplete, for the sidebar |
+| `SettingsPanel` | Theme picker body for the settings sidebar |
+| `SidebarPane` | Titled, closable container for sidebar content |
+| `StatusBar` | Footer with left / center / right item groups |
+| `TerminalPane` | Bottom-docked terminal log and input |
+| `ThemeSwitcher` | Segmented theme control |
+| `TreeWidget` | Virtualised file tree with drag-to-move and a data-driven menu |
+| `UserProfile` | Avatar and identity widget |
 
-## ✨ Key Features
+`ShellLayout` composes all of them.
 
-- **Advanced Docking Engine**: Full drag-and-drop tab management (dock, split, float, collapse) out-of-the-box.
-- **Inversion of Control (IoC) Registries**: Add new menu items, hotkeys, or tab contents programmatically from anywhere in your code without touching the layout container.
-- **Zustand State Persistence**: Automatically restores the user's workspace structure, theme preference, and pane configurations across page reloads.
-- **Accessibility & Contrast First**: Built to look beautiful and professional under three default themes (`theme-light`, `theme-dark`, and `theme-gt` for Georgia Tech fans) while satisfying AA/AAA color contrast ratios.
-- **Pre-Integrated Widgets**: A library of reusable layout widgets including terminal consoles, chat panels, tree file explorers, virtualized grids, and hex maps.
+## Theming
 
----
+Three themes ship in the stylesheet: `theme-light`, `theme-dark`, `theme-gt`.
+Colors are CSS custom properties scoped to those classes, so switching themes is
+a class on an ancestor — no React context, no provider.
 
-## 🚦 Quick Start
+Add your own by defining a `.theme-yourname` block with the same properties.
 
-### 1. Installation
+## Development
 
 ```bash
-npm install nexus-shell
+npm install
+
+npm run site           # documentation site at :5173
+npm run storybook      # component workbench at :6006
+npm run dev            # showcase app at :5173
+
+npm run typecheck      # library sources
+npm test               # vitest — unit and architecture tests
+npm run site:test      # renders every site route and demo
+npm run build          # library build to dist/
+npm run build-storybook
+npm run site:build     # documentation site to website/dist/
+npm run e2e            # Playwright against the showcase app
 ```
 
-### 2. Basic Setup
-
-In your main entry point (e.g., `main.tsx` or `App.tsx`):
+`npm run typecheck` covers `src/` only. To include the examples:
 
-```tsx
-import React from 'react';
-import ReactDOM from 'react-dom/client';
-import { ShellLayout, initializeShell } from 'nexus-shell';
-import 'nexus-shell/style.css'; // Essential styling properties
-
-// Initialize core registries and default welcome workspace
-initializeShell();
-
-export default function App() {
-  return (
-    <div className="h-screen w-screen bg-background text-foreground">
-      <ShellLayout 
-        title={<div className="font-bold text-lg">My Custom IDE</div>}
-      />
-    </div>
-  );
-}
-
-ReactDOM.createRoot(document.getElementById('root')!).render(<App />);
+```bash
+npx tsc --noEmit -p tsconfig.examples.json
 ```
 
----
-
-## 🏗 Registry-Driven Customization
+CI runs all of the above on every push and pull request.
 
-Nexus Shell lets you register custom features dynamically:
+### Layout
 
-### Register a Keyboard Shortcut (Command)
-```typescript
-import { commandRegistry } from 'nexus-shell';
-
-commandRegistry.registerCommand({
-  id: 'my-app.hello',
-  label: 'Say Hello',
-  keybinding: 'Control+L',
-  execute: () => alert('Hello from Nexus Shell!'),
-});
+```
+src/
+  components/       Primitives — pure, prop-driven, the public API
+  connected/        Store-bound wrappers used by ShellLayout
+  core/             Stores (zustand) and registries
+  lib/              Shared utilities
+  stories/          MDX documentation pages
+examples/
+  showcase/         Demo apps built on the library — not published
+    dialogue-mapper/
+    mockup-reviewer/
+    wiki/
+    wargame/
+    e2e/            Playwright specs for the showcase app
+  basic-app/        Minimal integration example
+website/
+  src/demos/        Live examples — the source shown on the site
+  src/content/      The component gallery, as data
+  scripts/          Generates the props tables from the library's types
 ```
 
-### Register a Tab Component
-```typescript
-import { componentRegistry } from 'nexus-shell';
+### Documentation site
 
-componentRegistry.register('my-custom-widget', () => (
-  <div className="p-4 bg-card text-card-foreground">
-    <h2>Dynamic Custom Tab</h2>
-    <p>This tab can be docked anywhere in the workspace!</p>
-  </div>
-));
-```
+`website/` is a Vite app that imports the library from `../src`, not from
+`dist`. Every example on the site is rendered by the current source, so a demo
+that no longer compiles against the real API fails the build rather than
+quietly documenting an API that no longer exists.
 
----
+Two generation steps keep it honest:
 
-## 🧪 Development & Testing
+- **Props tables** come from `website/scripts/generate-api.mjs`, which parses
+  the component sources for prop names, types, defaults and JSDoc. Nothing is
+  hand-written.
+- **Code samples** are extracted from the demo files by `#region` marker, so the
+  snippet a visitor copies is provably the code that produced the thing they
+  just interacted with.
 
-```bash
-# Start Vite App & local Storybook server
-npm run dev:all
+Adding a component to the site is one entry in `website/src/content/components.ts`
+plus a demo file. There is no per-component page to keep in sync.
 
-# Build package artifacts (ESM, UMD, CSS, and Types)
-npm run build
+The site ships no dependencies of its own — routing, syntax highlighting and the
+copy button are all local, so the docs can't drag the repo's install surface
+around.
 
-# Run Playwright E2E and Visual Regression tests
-npx playwright test
-```
+**Deployment.** `.github/workflows/deploy-pages.yml` builds the site and
+Storybook on every push to `main` and publishes them as one Pages artifact — the
+site at the root, Storybook under `/storybook/`. First-time setup needs your
+credentials: run `./scripts/setup-pages.sh`.
+
+The split between `components/` and `connected/` is the load-bearing one. A
+component that reads a global store can't be configured by its caller, rendered
+twice with different data, or documented — its props table is empty because it
+has no props. Everything in `components/` is therefore forbidden from importing
+`core/services`, and the tests in `components/__tests__` exist to keep it that
+way.
 
----
+Anything under `examples/` is a consumer of the library, not part of it. It's
+built and documented alongside the components to prove the primitives are
+sufficient, but it ships to nobody.
 
-## 📄 License
+## License
 
-MIT © [David/TechMuch]
+MIT

package/dist/components/layout/ShellLayout.d.ts

@@ -1,17 +1,63 @@
+import { ReactNode } from 'react';
 import { Model } from 'flexlayout-react';
+import { IMenuItemConfig } from '../../core/registry/MenuRegistry';
+import { ISlashCommandConfig } from '../../core/services/ChatService';
 import { ISidebarPanel } from '../../core/services/SidebarService';
-import { ISlashCommand } from '../../core/services/ChatService';
-import { IStatusBarWidget } from '../../core/services/StatusBarService';
-import { IMenuItem } from '../../core/registry/MenuRegistry';
+import { IStatusBarWidgetConfig } from '../../core/services/StatusBarService';
 
-interface ShellLayoutProps {
+export interface ShellLayoutProps {
+    /**
+     * Sidebar panels to register. Each becomes an icon in the activity bar and
+     * renders its `component` in the sidebar when selected.
+     */
     panels?: ISidebarPanel[];
-    slashCommands?: ISlashCommand[];
-    menuConfig?: Record<string, IMenuItem[]>;
-    statusBarConfig?: IStatusBarWidget[];
-    rightMenuBarContent?: React.ReactNode;
-    title?: React.ReactNode;
+    /** Slash commands available in the chat pane. */
+    slashCommands?: ISlashCommandConfig[];
+    /** Menu structure, keyed by top-level menu name. Items dispatch by `commandId`. */
+    menuConfig?: Record<string, IMenuItemConfig[]>;
+    /** Items for the status bar, grouped by their `alignment`. */
+    statusBarConfig?: IStatusBarWidgetConfig[];
+    /** Branding shown at the far left of the menu bar. */
+    title?: ReactNode;
+    /** Slot at the far right of the menu bar, for actions or a theme switcher. */
+    rightMenuBarContent?: ReactNode;
+    /** Widget rendered between the menus and the right slot, sized for search. */
+    centerMenuBarContent?: ReactNode;
+    /**
+     * Take control of the docking layout. When provided, the shell renders this
+     * model and stops writing changes to `useLayoutStore` — useful for tests and
+     * stories. Omit it to use the store's persisted model.
+     */
     layoutModel?: Model;
+    disableLocalStorage?: boolean;
+    initialLayoutJson?: any;
+    onLayoutChange?: (layout: any) => void;
 }
-export declare const ShellLayout: ({ panels, slashCommands, menuConfig, statusBarConfig, rightMenuBarContent, title, layoutModel }: ShellLayoutProps) => import("react/jsx-runtime").JSX.Element;
-export {};
+/**
+ * The complete application shell: menu bar, activity bar, sidebar, a
+ * `flexlayout-react` docking area, terminal, chat pane and status bar.
+ *
+ * This is the batteries-included composition. It registers whatever you pass
+ * into the shell stores on mount, then renders the `Connected*` component
+ * variants, which read from those stores. Tab contents come from the
+ * {@link componentRegistry}, so plugins can contribute views without the shell
+ * importing them.
+ *
+ * If you want the pieces without the wiring, import the individual components
+ * and compose them yourself — every one of them is prop-driven and works
+ * standalone.
+ *
+ * Closing a tab marked dirty via `useLayoutStore().setTabDirty` prompts for
+ * confirmation before the tab is removed.
+ *
+ * @example
+ * ```tsx
+ * <ShellLayout
+ *   title={<Logo />}
+ *   panels={[{ id: 'files', label: 'Explorer', icon: Files, component: FileTree }]}
+ *   menuConfig={{ File: [{ id: 'save', label: 'Save', commandId: 'file.save' }] }}
+ *   statusBarConfig={[{ id: 'branch', label: 'main', alignment: 'left' }]}
+ * />
+ * ```
+ */
+export declare const ShellLayout: ({ panels, slashCommands, menuConfig, statusBarConfig, title, rightMenuBarContent, centerMenuBarContent, layoutModel, }: ShellLayoutProps) => import("react/jsx-runtime").JSX.Element;

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

@@ -1 +1,48 @@
-export declare const ActivityBar: () => import("react/jsx-runtime").JSX.Element;
+import { LucideIcon } from 'lucide-react';
+
+/** A single icon button in the {@link ActivityBar}. */
+export interface IActivityBarItem {
+    /** Stable identifier reported to `onSelect`. */
+    id: string;
+    /** Accessible label and tooltip text. */
+    label: string;
+    /** `lucide-react` icon rendered at 20px. */
+    icon: LucideIcon;
+}
+export interface ActivityBarProps {
+    /** Items rendered in the main (top) group, in order. */
+    items?: IActivityBarItem[];
+    /**
+     * Items rendered in the bottom group, below the flex spacer. Defaults to a
+     * single Settings item. Pass `[]` to render no bottom group.
+     */
+    bottomItems?: IActivityBarItem[];
+    /** Id of the currently active item, or `null` when nothing is selected. */
+    activeId?: string | null;
+    /**
+     * Called with the clicked item's id. Toggling — clicking the active item to
+     * deselect it — is the caller's decision, not the component's.
+     */
+    onSelect?: (id: string) => void;
+    /** Extra classes merged onto the root `<aside>`. */
+    className?: string;
+    /** Accessible label for the landmark. Defaults to `"Activity Bar"`. */
+    'aria-label'?: string;
+}
+/**
+ * The narrow vertical icon rail on the left edge of the shell, used to switch
+ * which panel the sidebar shows.
+ *
+ * Controlled — it holds no selection state. For the store-backed variant used
+ * by `ShellLayout`, see `ConnectedActivityBar`.
+ *
+ * @example
+ * ```tsx
+ * <ActivityBar
+ *   items={[{ id: 'files', label: 'Explorer', icon: Files }]}
+ *   activeId={active}
+ *   onSelect={(id) => setActive(id === active ? null : id)}
+ * />
+ * ```
+ */
+export declare const ActivityBar: ({ items, bottomItems, activeId, onSelect, className, "aria-label": ariaLabel, }: ActivityBarProps) => import("react/jsx-runtime").JSX.Element;

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

@@ -0,0 +1,30 @@
+import { default as React } from 'react';
+
+export interface AppTitleProps {
+    /** Primary line. Rendered uppercase in a mono face. */
+    title: string;
+    /** Secondary line beneath the title. Omit to render a single line. */
+    subtitle?: string;
+    /**
+     * Element shown in the leading badge, typically a 16px `lucide-react` icon.
+     * Omit to render no badge at all.
+     */
+    icon?: React.ReactNode;
+    /** Extra classes merged onto the root element. */
+    className?: string;
+}
+/**
+ * A branding lockup — icon badge, title and subtitle — sized for the
+ * {@link MenuBar}'s `title` slot.
+ *
+ * Purely presentational. Pass whatever branding your app needs; the library
+ * supplies no default copy.
+ *
+ * @example
+ * ```tsx
+ * <MenuBar
+ *   title={<AppTitle title="Acme Studio" subtitle="Design System" icon={<Boxes size={16} />} />}
+ * />
+ * ```
+ */
+export declare const AppTitle: ({ title, subtitle, icon, className }: AppTitleProps) => import("react/jsx-runtime").JSX.Element;

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

@@ -1 +1,63 @@
-export declare const ChatPane: () => import("react/jsx-runtime").JSX.Element | null;
+import { default as React } from 'react';
+
+/** A single message in the {@link ChatPane} transcript. */
+export interface IChatMessage {
+    /** Stable identifier. Used as the React key. */
+    id: string;
+    /** Who sent it. `'user'` right-aligns; anything else left-aligns. */
+    role: 'user' | 'assistant';
+    /** Message body. Rendered as plain text with newlines preserved. */
+    text: string;
+    /** Optional display name shown above the bubble. Defaults from `role`. */
+    author?: string;
+}
+/** A `/`-prefixed shortcut offered in the composer's autocomplete. */
+export interface ISlashCommand {
+    /** Command word without the leading slash, e.g. `"clear"`. */
+    command: string;
+    /** One-line description shown beside the command in the suggestion list. */
+    description: string;
+}
+export interface ChatPaneProps {
+    /** Messages to display, oldest first. */
+    messages?: IChatMessage[];
+    /**
+     * Called with the trimmed message text on send. The component clears its
+     * composer but does not append to `messages` — that is the caller's job.
+     */
+    onSend?: (text: string) => void;
+    /** Slash commands offered once the composer starts with `/`. */
+    slashCommands?: ISlashCommand[];
+    /** Called when a slash command is picked from the suggestion list. */
+    onSlashCommand?: (command: ISlashCommand) => void;
+    /** Called when the close button is pressed. Omit to hide the button. */
+    onClose?: () => void;
+    /** Title shown in the pane header. Defaults to `"Chat"`. */
+    title?: string;
+    /** Placeholder for the composer. */
+    placeholder?: string;
+    /** Shown in place of the transcript when `messages` is empty. */
+    emptyState?: React.ReactNode;
+    /** Extra classes merged onto the root element. */
+    className?: string;
+}
+/**
+ * A docked chat panel: a scrolling transcript over a composer with slash-command
+ * autocomplete.
+ *
+ * Fully controlled — it owns only the in-progress input and the suggestion
+ * highlight. Messages, sending and visibility belong to the caller, so the same
+ * component works against a local array, a websocket, or an LLM endpoint. For
+ * the store-backed variant used by `ShellLayout`, see `ConnectedChatPane`.
+ *
+ * @example
+ * ```tsx
+ * <ChatPane
+ *   messages={messages}
+ *   onSend={(text) => send(text)}
+ *   slashCommands={[{ command: 'clear', description: 'Clear the transcript' }]}
+ *   onClose={() => setOpen(false)}
+ * />
+ * ```
+ */
+export declare const ChatPane: ({ messages, onSend, slashCommands, onSlashCommand, onClose, title, placeholder, emptyState, className, }: ChatPaneProps) => import("react/jsx-runtime").JSX.Element;

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;