nexus-shell 0.2.0 → 0.2.1

package/README.md

@@ -16,17 +16,74 @@ import 'nexus-shell/style.css';
 
 React 19 is a peer dependency.
 
-## Two tiers
+## Start with the shell
 
-**Primitives** are pure and prop-driven. No global state, no registry lookups.
-You pass data in, you get callbacks out.
+An application built on this library starts with `ShellLayout` and grows by
+registering features into it.
 
 ```tsx
-import { StatusBar, ActivityBar, SidebarPane, TreeWidget } from 'nexus-shell';
+// main.tsx — a complete application
+import { createRoot } from 'react-dom/client';
+import { Boxes, Files } from 'lucide-react';
+import {
+  AppTitle,
+  ShellLayout,
+  componentRegistry,
+  initializeShell,
+  useLayoutStore,
+} from 'nexus-shell';
+import 'nexus-shell/style.css';
+
+// Views register by id, so the shell never has to import them.
+componentRegistry.register('editor', Editor);
+
+initializeShell({
+  panels: [{ id: 'files', label: 'Explorer', icon: Files, component: FileExplorer }],
+  commands: [
+    { id: 'file.save', label: 'File: Save', keybinding: 'Control+s', execute: save },
+  ],
+  menus: { File: [{ id: 'save', label: 'Save', commandId: 'file.save' }] },
+  statusBar: [{ id: 'branch', label: 'main', alignment: 'left' }],
+});
+
+useLayoutStore.getState().addTab('editor', 'App.tsx');
+
+createRoot(document.getElementById('root')!).render(
+  <ShellLayout title={<AppTitle title="Acme Studio" icon={<Boxes size={16} />} />} />,
+);
+```
+
+That is a working IDE: dockable tabs, a command palette on `Cmd/Ctrl+Shift+P`, a
+terminal, a chat pane, and a themable frame.
+
+## Growing an app
+
+You add capability by **registering** it. None of this changes the layout, which
+is what lets plugins and distant code contribute to the shell.
+
+| To add | Do this |
+| :-- | :-- |
+| A view or tab | `componentRegistry.register(id, Component)`, then `useLayoutStore().addTab(id, title)` |
+| An action or hotkey | `commandRegistry.registerCommand({ id, label, keybinding, execute })` — appears in the palette automatically |
+| A menu entry | `menuRegistry.registerMenu('File', { id, label, commandId })` |
+| A sidebar panel | Add it to `panels`; it becomes an activity bar icon |
+| A status bar item | `useStatusBarStore.getState().addWidget(...)` |
+| A dialog from anywhere | `await useModalStore.getState().openConfirm('Sure?')` |
+| An unsaved-changes guard | `useLayoutStore.getState().setTabDirty(tabId, true)` |
+
+## When you need less than the shell
+
+Every component the shell is assembled from is exported on its own — pure and
+prop-driven, with no global state or registry lookups. This is the escape hatch:
+reach for it when you're embedding one piece into an app you already have, or
+building a frame `ShellLayout` can't express.
+
+```tsx
+import { ActivityBar, SidebarPane, StatusBar, TreeWidget } from 'nexus-shell';
 
 const [active, setActive] = useState<string | null>('files');
 
-<div className="theme-light flex h-screen flex-col">
+<div className="theme-dark flex h-screen flex-col">
   <div className="flex flex-1">
     <ActivityBar
       items={panels}
@@ -44,29 +101,18 @@ const [active, setActive] = useState<string | null>('files');
 </div>;
 ```
 
-**`ShellLayout`** is the assembled frame — the same components, wired to a set of
-zustand stores and registries so you configure declaratively:
-
-```tsx
-import { ShellLayout, componentRegistry } from 'nexus-shell';
-
-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' }]}
-/>;
-```
+These are controlled, so state stays in your app — a real cost the shell was
+absorbing for you.
 
-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.
+Between the two sit the `Connected*` variants, each binding one component to its
+store. `ShellLayout` is built entirely out of them, so you can rearrange the
+shell's own frame and keep every registration working.
 
 ## Components
 
-| Primitive | What it is |
+`ShellLayout` assembles all of these. Each is also exported on its own.
+
+| Component | What it is |
 | :-- | :-- |
 | `ActivityBar` | Vertical icon rail for switching sidebar panels |
 | `ChatPane` | Docked chat transcript with slash-command autocomplete |
@@ -85,8 +131,6 @@ tiers freely.
 | `TreeWidget` | Virtualised file tree with drag-to-move and a data-driven menu |
 | `UserProfile` | Avatar and identity widget |
 
-`ShellLayout` composes all of them.
-
 ## Theming
 
 Three themes ship in the stylesheet: `theme-light`, `theme-dark`, `theme-gt`.
@@ -125,9 +169,9 @@ CI runs all of the above on every push and pull request.
 
 ```
 src/
-  components/       Primitives — pure, prop-driven, the public API
+  components/       Pure, prop-driven components — what the shell is made of
   connected/        Store-bound wrappers used by ShellLayout
-  core/             Stores (zustand) and registries
+  core/             Stores (zustand), registries, and initializeShell
   lib/              Shared utilities
   stories/          MDX documentation pages
 examples/

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

@@ -1,5 +1,5 @@
 import { ReactNode } from 'react';
-import { Model } from 'flexlayout-react';
+import { Model, IJsonModel } from 'flexlayout-react';
 import { IMenuItemConfig } from '../../core/registry/MenuRegistry';
 import { ISlashCommandConfig } from '../../core/services/ChatService';
 import { ISidebarPanel } from '../../core/services/SidebarService';
@@ -29,35 +29,67 @@ export interface ShellLayoutProps {
      * stories. Omit it to use the store's persisted model.
      */
     layoutModel?: Model;
+    /**
+     * Starting workspace, as a `flexlayout-react` JSON model. Applied once on
+     * mount and only when nothing has been restored from storage, so it seeds a
+     * first run without overwriting a layout the user has since arranged.
+     *
+     * Ignored when `layoutModel` is provided, which takes control outright.
+     */
+    initialLayoutJson?: IJsonModel;
+    /**
+     * Stop persisting the layout to `localStorage`. The workspace then resets to
+     * `initialLayoutJson` on every load — useful for embedded or multi-tenant
+     * shells where a per-browser layout would be wrong. Defaults to `false`.
+     */
     disableLocalStorage?: boolean;
-    initialLayoutJson?: any;
-    onLayoutChange?: (layout: any) => void;
+    /**
+     * Called with the serialised model whenever the user moves, splits, opens or
+     * closes a tab. Use it to persist the layout somewhere of your own — a user
+     * profile on the server, say — instead of, or alongside, `localStorage`.
+     */
+    onLayoutChange?: (layout: IJsonModel) => void;
 }
 /**
  * The complete application shell: menu bar, activity bar, sidebar, a
- * `flexlayout-react` docking area, terminal, chat pane and status bar.
+ * `flexlayout-react` docking workspace, terminal, chat pane and status bar.
+ *
+ * **This is where an application starts.** Call {@link initializeShell} once to
+ * register your commands, menus and panels, render this component, and add
+ * features by registering them rather than by restructuring the layout. Tab
+ * contents resolve through the {@link componentRegistry}, so a new view is a
+ * registration and a menu entry — the shell never needs to import it.
  *
- * 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.
+ * Configuration can arrive either way. Props are convenient for values that
+ * change with your app's state; {@link initializeShell} is better for the fixed
+ * set, since it runs once and works outside React. Props passed here are
+ * written into the same stores on mount, so the two are interchangeable.
  *
- * 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.
+ * Internally this composes the `Connected*` component variants, which read from
+ * the shell stores. Those components — and the pure ones beneath them — are
+ * exported too, for the cases where you need to rearrange the frame itself.
  *
  * 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' }]}
- * />
+ * // main.tsx — a complete application
+ * import { initializeShell, ShellLayout, componentRegistry, AppTitle } from 'nexus-shell';
+ * import 'nexus-shell/style.css';
+ *
+ * componentRegistry.register('editor', Editor);
+ *
+ * initializeShell({
+ *   panels: [{ id: 'files', label: 'Explorer', icon: Files, component: FileTree }],
+ *   commands: [{ id: 'file.save', label: 'File: Save', keybinding: 'Control+s', execute: save }],
+ *   menus: { File: [{ id: 'save', label: 'Save', commandId: 'file.save' }] },
+ *   statusBar: [{ id: 'branch', label: 'main', alignment: 'left' }],
+ * });
+ *
+ * createRoot(document.getElementById('root')!).render(
+ *   <ShellLayout title={<AppTitle title="Acme Studio" icon={<Boxes size={16} />} />} />,
+ * );
  * ```
  */
-export declare const ShellLayout: ({ panels, slashCommands, menuConfig, statusBarConfig, title, rightMenuBarContent, centerMenuBarContent, layoutModel, }: ShellLayoutProps) => import("react/jsx-runtime").JSX.Element;
+export declare const ShellLayout: ({ panels, slashCommands, menuConfig, statusBarConfig, title, rightMenuBarContent, centerMenuBarContent, layoutModel, initialLayoutJson, disableLocalStorage, onLayoutChange, }: ShellLayoutProps) => import("react/jsx-runtime").JSX.Element;

package/dist/core/Boot.d.ts

@@ -0,0 +1,66 @@
+import { ICommand } from './registry/CommandRegistry';
+import { IMenuItemConfig } from './registry/MenuRegistry';
+import { ISlashCommandConfig } from './services/ChatService';
+import { ISidebarPanel } from './services/SidebarService';
+import { IStatusBarWidgetConfig } from './services/StatusBarService';
+
+export interface InitializeShellOptions {
+    /**
+     * Sidebar panels to register. Each becomes an icon in the activity bar and
+     * renders its `component` in the sidebar when selected.
+     */
+    panels?: ISidebarPanel[];
+    /** Menus keyed by top-level name. Items dispatch through their `commandId`. */
+    menus?: Record<string, IMenuItemConfig[]>;
+    /** Commands available to the palette, menus and keybindings. */
+    commands?: ICommand[];
+    /** Items for the status bar, grouped by their `alignment`. */
+    statusBar?: IStatusBarWidgetConfig[];
+    /** Slash commands offered in the chat pane. */
+    slashCommands?: ISlashCommandConfig[];
+    /**
+     * Register the built-in view and theme commands listed in
+     * {@link DEFAULT_COMMAND_IDS}. Defaults to `true`. Turn it off if your app
+     * wants to own every command id.
+     */
+    defaultCommands?: boolean;
+    /**
+     * Register a default **View** menu exposing the built-in commands. Defaults
+     * to `true`, and is ignored when `defaultCommands` is `false`.
+     */
+    defaultMenus?: boolean;
+}
+/** The command ids `initializeShell` registers unless told not to. */
+export declare const DEFAULT_COMMAND_IDS: readonly ["view.toggleTerminal", "view.toggleChat", "view.toggleSidebar", "theme.light", "theme.dark", "theme.gt"];
+/**
+ * Boot the shell: register commands, menus, panels and status bar items into
+ * the shell registries and stores.
+ *
+ * This is the usual first call in a Nexus Shell application. `ShellLayout` can
+ * take the same configuration as props, but doing it here has two advantages:
+ * it runs once rather than on every render, and it happens outside React, so
+ * plugins and other non-component code can contribute in exactly the same way.
+ *
+ * Call it once, before rendering. It is safe to call again — the registries
+ * warn on duplicate ids rather than throwing — but it is not a reset: nothing
+ * previously registered is removed.
+ *
+ * @example
+ * ```ts
+ * // main.tsx
+ * import { initializeShell, componentRegistry } from 'nexus-shell';
+ * import 'nexus-shell/style.css';
+ *
+ * componentRegistry.register('editor', Editor);
+ *
+ * initializeShell({
+ *   panels: [{ id: 'files', label: 'Explorer', icon: Files, component: FileTree }],
+ *   commands: [{ id: 'file.save', label: 'File: Save', keybinding: 'Control+s', execute: save }],
+ *   menus: { File: [{ id: 'save', label: 'Save', commandId: 'file.save' }] },
+ *   statusBar: [{ id: 'branch', label: 'main', alignment: 'left' }],
+ * });
+ *
+ * createRoot(el).render(<ShellLayout title={<AppTitle title="Acme" />} />);
+ * ```
+ */
+export declare const initializeShell: (options?: InitializeShellOptions) => void;

package/dist/index.d.ts

@@ -2,19 +2,45 @@
  * Nexus Shell — a React component library for building IDE-style application
  * shells.
  *
- * The surface is deliberately two-tier:
+ * **Start with {@link ShellLayout}.** It is the whole application frame — menu
+ * bar, activity bar, sidebar, docking workspace, terminal, chat pane and status
+ * bar — and the intended starting point for an app built on this library. Call
+ * {@link initializeShell} once to register your commands, menus and panels,
+ * render `ShellLayout`, and grow from there.
  *
- * 1. **Primitives** — pure, prop-driven components with no global state. Use
- *    these to build your own layout. They are the supported public API.
- * 2. **Shell** — `ShellLayout` plus the stores and registries behind it, for
- *    when you want the whole assembled application frame.
- *
- * Import the stylesheet once in your app entry:
  * ```ts
+ * import { initializeShell, ShellLayout } from 'nexus-shell';
  * import 'nexus-shell/style.css';
+ *
+ * initializeShell({ panels, menus, commands });
+ * createRoot(el).render(<ShellLayout title={<AppTitle title="Acme" />} />);
  * ```
+ *
+ * Everything the shell is built from is also exported on its own. Those
+ * components are pure and prop-driven, and they are the escape hatch: reach for
+ * them when you are embedding one piece into an app you already have, or when
+ * you need a layout the shell cannot express. Most applications should not need
+ * to.
  */
+export { ShellLayout, type ShellLayoutProps } from './components/layout/ShellLayout';
+export { initializeShell, DEFAULT_COMMAND_IDS, type InitializeShellOptions, } from './core/Boot';
+export { commandRegistry, CommandRegistry, type ICommand } from './core/registry/CommandRegistry';
+export { menuRegistry, MenuRegistry, type IMenuItemConfig } from './core/registry/MenuRegistry';
+export { pluginRegistry, type IPlugin, type PluginStatus } from './core/registry/PluginRegistry';
+export { componentRegistry, type ComponentConstructor } from './core/registry/ComponentRegistry';
+export { useChatStore, type ISlashCommandConfig } from './core/services/ChatService';
+export { useLayoutStore } from './core/services/LayoutService';
+export { useModalStore, type ModalType as ModalStoreType } from './core/services/ModalStoreService';
+export { useRightSidebarStore } from './core/services/RightSidebarService';
+export { useSidebarStore, type ISidebarPanel } from './core/services/SidebarService';
+export { useStatusBarStore, type IStatusBarWidgetConfig } from './core/services/StatusBarService';
+export { useTerminalStore } from './core/services/TerminalService';
+export { useThemeStore, type ThemeType } from './core/services/ThemeService';
+export { useUserProfileStore, type UserProfileState } from './core/services/UserProfileService';
+export { useKeyboardShortcuts } from './core/services/KeyboardService';
+export * from './connected';
 export { ActivityBar, type ActivityBarProps, type IActivityBarItem } from './components/widgets/ActivityBar';
+export { AppTitle, type AppTitleProps } from './components/widgets/AppTitle';
 export { ChatPane, type ChatPaneProps, type IChatMessage, type ISlashCommand } from './components/widgets/ChatPane';
 export { CommandPalette, type CommandPaletteProps, type ICommandItem } from './components/widgets/CommandPalette';
 export { ContextMenu, type ContextMenuProps, type IContextMenuItem } from './components/widgets/ContextMenu';
@@ -30,22 +56,4 @@ export { TerminalPane, type TerminalPaneProps } from './components/widgets/Termi
 export { ThemeSwitcher, type ThemeSwitcherProps, type IThemeOption, DEFAULT_THEME_OPTIONS } from './components/widgets/ThemeSwitcher';
 export { TreeWidget, type TreeWidgetProps, type ITreeNode, type ITreeAction, type ITreeContext } from './components/widgets/TreeWidget';
 export { UserProfile, type UserProfileProps, type IUserProfile, type IUserProfileAction } from './components/widgets/UserProfile';
-export { AppTitle, type AppTitleProps } from './components/widgets/AppTitle';
 export { cn } from './lib/cn';
-export { ShellLayout, ShellLayout as NexusWorkspaceShell, type ShellLayoutProps } from './components/layout/ShellLayout';
-export declare const initializeShell: (_config?: unknown) => void;
-export * from './connected';
-export { commandRegistry, CommandRegistry, type ICommand } from './core/registry/CommandRegistry';
-export { menuRegistry, MenuRegistry, type IMenuItemConfig } from './core/registry/MenuRegistry';
-export { pluginRegistry, type IPlugin, type PluginStatus } from './core/registry/PluginRegistry';
-export { componentRegistry, type ComponentConstructor } from './core/registry/ComponentRegistry';
-export { useChatStore, type ISlashCommandConfig } from './core/services/ChatService';
-export { useLayoutStore } from './core/services/LayoutService';
-export { useModalStore, type ModalType as ModalStoreType } from './core/services/ModalStoreService';
-export { useRightSidebarStore } from './core/services/RightSidebarService';
-export { useSidebarStore, type ISidebarPanel } from './core/services/SidebarService';
-export { useStatusBarStore, type IStatusBarWidgetConfig } from './core/services/StatusBarService';
-export { useTerminalStore } from './core/services/TerminalService';
-export { useThemeStore, type ThemeType } from './core/services/ThemeService';
-export { useUserProfileStore, type UserProfileState } from './core/services/UserProfileService';
-export { useKeyboardShortcuts } from './core/services/KeyboardService';