nexus-shell 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 David
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,223 @@
+# Nexus-Shell Framework
+
+Nexus-Shell is a professional-grade, library-first frontend framework for building "Workbench" style applications (like VS Code or JupyterLab). Built with **React 19**, **TypeScript**, and **FlexLayout**, it provides a modular foundation for complex, multi-panel web tools.
+
+## ✨ Key Features
+
+- **Advanced Tab Docking:** Complete drag-and-drop window management with splits, tabs, and sidebars.
+- **Modular Registry System:** Decouple commands, menus, and plugins from the core UI.
+- **Persistence:** Automatic workspace restoration via `localStorage`.
+- **Command Palette:** `Ctrl+Shift+P` searchable command interface.
+- **Theming:** First-class support for Light, Dark, and custom themes (includes a Georgia Tech theme).
+- **Library Ready:** ESM and UMD bundles with full TypeScript type definitions.
+
+---
+
+## 🚦 Quick Start
+
+### 1. Installation
+
+```bash
+npm install nexus-shell
+```
+
+### 2. Basic Setup
+
+In your main entry point (e.g., `App.tsx`):
+
+```tsx
+import { ShellLayout, initializeShell } from 'nexus-shell';
+import 'nexus-shell/style.css';
+
+// Initialize core shell services
+initializeShell();
+
+export default function App() {
+  return (
+    <div className="h-screen w-screen">
+      <ShellLayout />
+    </div>
+  );
+}
+```
+
+---
+
+## 🏗 Core Concepts
+
+### 1. Registries (The Brains)
+Nexus-Shell uses registries to manage global state without component coupling.
+
+- **`commandRegistry`**: Register global actions with IDs, labels, and optional keybindings.
+- **`menuRegistry`**: Map commands to the top Menu Bar.
+- **`pluginRegistry`**: Manage the lifecycle (`activate`/`deactivate`) of modular features.
+
+### 2. Commands & Menus
+```typescript
+import { commandRegistry, menuRegistry } from 'nexus-shell';
+
+// Register a command
+commandRegistry.registerCommand({
+  id: 'my-app.hello',
+  label: 'Say Hello',
+  keybinding: 'Control+L',
+  execute: () => alert('Hello World!'),
+});
+
+// Add it to the Help menu
+menuRegistry.registerMenu('Help', {
+  id: 'help.hello',
+  label: 'Say Hello',
+  commandId: 'my-app.hello',
+});
+```
+
+### 3. Layout Management
+The layout is powered by `flexlayout-react`. You can dynamically add tabs from anywhere in your app:
+
+```typescript
+import { useLayoutStore } from 'nexus-shell';
+
+const addMyTab = () => {
+  useLayoutStore.getState().addTab('my-component', 'My Tab Title');
+};
+```
+
+---
+
+## 🛠 Step-by-Step: Creating a Custom Application
+
+Follow these steps to build a feature-rich application using Nexus-Shell:
+
+### Step 1: Initialize the Shell
+Call `initializeShell()` before your app renders. This sets up the default "Welcome" tab, core menus, and global keyboard listeners.
+
+### Step 2: Define your Components
+Create React components that you want to appear as tabs. You must register these in the `factory` of the `ShellLayout` or provide a custom factory.
+
+### Step 3: Register Commands and Menus
+Define the actions your users can take. By using `commandRegistry`, your actions automatically show up in the **Command Palette** (`Ctrl+Shift+P`) and can be triggered by **Keyboard Shortcuts**.
+
+### Step 4: Implement Plugins
+For larger apps, encapsulate features into Plugins:
+```typescript
+import { IPlugin, commandRegistry } from 'nexus-shell';
+
+export const MyFeaturePlugin: IPlugin = {
+  id: 'my-feature',
+  name: 'My Feature',
+  activate: () => {
+    // Register commands, menus, and sidebars here
+  },
+  deactivate: () => {
+    // Cleanup
+  }
+};
+```
+
+### Step 5: Choose a Theme
+Users can switch themes in the Settings sidebar. You can also set the theme programmatically:
+```typescript
+import { useThemeStore } from 'nexus-shell';
+
+useThemeStore.getState().setTheme('gt'); // Go Jackets!
+```
+
+---
+
+## 🎨 Customization API
+
+Nexus-Shell is highly configurable via props on the `ShellLayout` component. This allows you to repurpose the workbench for different application needs.
+
+### 1. Menu Bar Configuration (`menuConfig`)
+Define hierarchical menus with nested submenus and commands.
+```tsx
+const myMenus = {
+  'File': [
+    { id: 'new', label: 'New File', commandId: 'nexus.new-tab' },
+    { id: 'recent', label: 'Open Recent', submenu: [
+      { id: 'r1', label: 'Project Alpha' },
+      { id: 'r2', label: 'Project Beta' }
+    ]}
+  ]
+};
+```
+
+### 2. Status Bar Widgets (`statusBarConfig`)
+Add info widgets to the bottom bar with specific alignments.
+```tsx
+const myStatusBar = [
+  { id: 'info', label: 'System OK', alignment: 'left', icon: Activity },
+  { id: 'v', label: 'v1.0.0', alignment: 'center' },
+  { id: 'user', label: 'Admin', alignment: 'right', onClick: () => alert('Admin Clicked') }
+];
+```
+
+### 3. Sidebar Panels (`panels`)
+Inject custom tools into the left Activity Bar.
+```tsx
+const myPanels = [
+  { id: 'home', label: 'Home', icon: Home, component: MyHomeComponent },
+  { id: 'db', label: 'Database', icon: Database, component: <DbExplorer /> }
+];
+```
+
+### 4. Chat Slash Commands (`slashCommands`)
+Extend the chat interface with custom functional commands.
+```tsx
+const myChatCommands = [
+  { command: 'ping', description: 'Test latency', execute: () => console.log('Pong!') },
+  { command: 'clear', description: 'Reset chat', execute: (args) => resetLogic() }
+];
+```
+
+### 5. Search Integration (`SearchWidget`)
+A reusable component for implementing project-wide search.
+```tsx
+<SearchWidget 
+  placeholder="Filter objects..."
+  onSearch={(query) => doFilter(query)}
+  results={filteredResults}
+  suggestions={['recent-1.txt', 'recent-2.txt']}
+  onSelect={(result) => openItem(result)}
+  loading={isSearching}
+/>
+```
+
+**Usage Example:**
+```tsx
+<ShellLayout 
+  menuConfig={myMenus}
+  statusBarConfig={myStatusBar}
+  panels={myPanels}
+  slashCommands={myChatCommands}
+/>
+```
+
+---
+
+## 📂 Project Structure (Library)
+
+```text
+/dist               <-- Compiled library artifacts (ESM, UMD, CSS, Types)
+/src
+  /components       <-- UI Components (Layout, Widgets)
+  /core
+    /registry       <-- Registry logic (Commands, Menus, Plugins)
+    /services       <-- State Management (Zustand)
+  /index.ts         <-- Public API Entry Point
+```
+
+---
+
+## 🧪 Development & Testing
+
+- **Run Dev App:** `npm run dev`
+- **Build Library:** `npm run build`
+- **Run Tests:** `npx playwright test`
+
+---
+
+## 📄 License
+
+MIT © [David/TechMuch]

package/dist/App.d.ts

@@ -0,0 +1,2 @@
+declare function App(): import("react/jsx-runtime").JSX.Element;
+export default App;

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

@@ -0,0 +1,14 @@
+import { ISidebarPanel } from '../../core/services/SidebarService';
+import { ISlashCommand } from '../../core/services/ChatService';
+import { IStatusBarWidget } from '../../core/services/StatusBarService';
+import { IMenuItem } from '../../core/registry/MenuRegistry';
+
+interface ShellLayoutProps {
+    panels?: ISidebarPanel[];
+    slashCommands?: ISlashCommand[];
+    menuConfig?: Record<string, IMenuItem[]>;
+    statusBarConfig?: IStatusBarWidget[];
+    rightMenuBarContent?: React.ReactNode;
+}
+export declare const ShellLayout: ({ panels, slashCommands, menuConfig, statusBarConfig, rightMenuBarContent }: ShellLayoutProps) => import("react/jsx-runtime").JSX.Element;
+export {};

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

@@ -0,0 +1 @@
+export declare const ActivityBar: () => import("react/jsx-runtime").JSX.Element;

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

@@ -0,0 +1 @@
+export declare const ChatPane: () => import("react/jsx-runtime").JSX.Element | null;

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

@@ -0,0 +1,8 @@
+import { ICommand } from '../../core/registry/CommandRegistry';
+
+interface CommandPaletteProps {
+    commands?: ICommand[];
+    forcedOpen?: boolean;
+}
+export declare const CommandPalette: ({ commands: customCommands, forcedOpen }: CommandPaletteProps) => import("react/jsx-runtime").JSX.Element | null;
+export {};

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

@@ -0,0 +1,16 @@
+import { default as React } from 'react';
+
+export interface IContextMenuItem {
+    label: string;
+    icon?: React.ReactNode;
+    onClick: () => void;
+    divider?: boolean;
+}
+interface ContextMenuProps {
+    x: number;
+    y: number;
+    items: IContextMenuItem[];
+    onClose: () => void;
+}
+export declare const ContextMenu: React.FC<ContextMenuProps>;
+export {};

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

@@ -0,0 +1 @@
+export declare const FilesSidebar: () => import("react/jsx-runtime").JSX.Element;

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

@@ -0,0 +1,5 @@
+interface MenuBarProps {
+    rightContent?: React.ReactNode;
+}
+export declare const MenuBar: ({ rightContent }: MenuBarProps) => import("react/jsx-runtime").JSX.Element;
+export {};

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

@@ -0,0 +1,19 @@
+import { default as React } from 'react';
+
+export interface ISearchResult {
+    id: string;
+    title: string;
+    description?: string;
+    icon?: React.ComponentType<any>;
+    category?: string;
+}
+export interface SearchWidgetProps {
+    placeholder?: string;
+    onSearch: (query: string) => void;
+    results: ISearchResult[];
+    onSelect: (result: ISearchResult) => void;
+    suggestions?: string[];
+    loading?: boolean;
+    className?: string;
+}
+export declare const SearchWidget: React.FC<SearchWidgetProps>;

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

@@ -0,0 +1 @@
+export declare const SidebarPane: () => import("react/jsx-runtime").JSX.Element | null;

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

@@ -0,0 +1 @@
+export declare const StatusBar: () => import("react/jsx-runtime").JSX.Element;

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

@@ -0,0 +1 @@
+export declare const TerminalPane: () => import("react/jsx-runtime").JSX.Element | null;

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

@@ -0,0 +1,19 @@
+import { default as React } from 'react';
+
+export interface ITreeNode {
+    id: string;
+    label: string;
+    type: 'file' | 'folder';
+    children?: ITreeNode[];
+    isOpen?: boolean;
+    level?: number;
+}
+export interface TreeWidgetProps {
+    data: ITreeNode[];
+    onMoveNode?: (draggedId: string, targetId: string) => void;
+    onNewFile?: (parentId: string) => void;
+    onNewFolder?: (parentId: string) => void;
+    onRename?: (nodeId: string) => void;
+    onDelete?: (nodeId: string) => void;
+}
+export declare const TreeWidget: React.FC<TreeWidgetProps>;

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

@@ -0,0 +1,11 @@
+import { default as React } from 'react';
+
+export interface UserProfileProps {
+    name: string;
+    avatarUrl?: string;
+    role?: string;
+    onClick?: () => void;
+    className?: string;
+    showName?: boolean;
+}
+export declare const UserProfile: React.FC<UserProfileProps>;

package/dist/core/Boot.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Initializes the shell's core commands and menus.
+ */
+export declare const initializeShell: () => Promise<void>;

package/dist/core/registry/CommandRegistry.d.ts

@@ -0,0 +1,15 @@
+export interface ICommand {
+    id: string;
+    label: string;
+    execute: (...args: any[]) => void;
+    icon?: string;
+    keybinding?: string;
+}
+export declare class CommandRegistry {
+    private commands;
+    registerCommand(command: ICommand): void;
+    executeCommand(id: string, ...args: any[]): void;
+    getCommand(id: string): ICommand | undefined;
+    getCommands(): ICommand[];
+}
+export declare const commandRegistry: CommandRegistry;

package/dist/core/registry/MenuRegistry.d.ts

@@ -0,0 +1,15 @@
+export interface IMenuItem {
+    id: string;
+    label: string;
+    commandId?: string;
+    keybinding?: string;
+    submenu?: IMenuItem[];
+}
+export declare class MenuRegistry {
+    private menus;
+    registerMenu(menuId: string, item: IMenuItem): void;
+    setMenus(menuConfig: Record<string, IMenuItem[]>): void;
+    getMenu(menuId: string): IMenuItem[];
+    getAllMenus(): Record<string, IMenuItem[]>;
+}
+export declare const menuRegistry: MenuRegistry;

package/dist/core/registry/PluginRegistry.d.ts

@@ -0,0 +1,17 @@
+export interface IPlugin {
+    id: string;
+    name: string;
+    activate: () => void;
+    deactivate: () => void;
+}
+export type PluginLoader = () => Promise<IPlugin>;
+export declare class PluginRegistry {
+    private plugins;
+    private loaders;
+    registerPlugin(plugin: IPlugin): void;
+    registerLazyPlugin(id: string, loader: PluginLoader): void;
+    activatePlugin(id: string): Promise<void>;
+    getPlugin(id: string): IPlugin | undefined;
+    getAllPlugins(): IPlugin[];
+}
+export declare const pluginRegistry: PluginRegistry;

package/dist/core/services/ChatService.d.ts

@@ -0,0 +1,12 @@
+export interface ISlashCommand {
+    command: string;
+    description: string;
+    execute: (args: string[]) => void;
+}
+interface ChatState {
+    slashCommands: ISlashCommand[];
+    setSlashCommands: (commands: ISlashCommand[]) => void;
+    registerSlashCommand: (command: ISlashCommand) => void;
+}
+export declare const useChatStore: import('zustand').UseBoundStore<import('zustand').StoreApi<ChatState>>;
+export {};

package/dist/core/services/KeyboardService.d.ts

@@ -0,0 +1 @@
+export declare const useKeyboardShortcuts: () => void;

package/dist/core/services/LayoutService.d.ts

@@ -0,0 +1,12 @@
+import { Model } from 'flexlayout-react';
+
+interface LayoutState {
+    model: Model;
+    dirtyTabs: Set<string>;
+    setModel: (model: Model) => void;
+    addTab: (componentName: string, title?: string) => void;
+    setTabDirty: (tabId: string, dirty: boolean) => void;
+    isTabDirty: (tabId: string) => boolean;
+}
+export declare const useLayoutStore: import('zustand').UseBoundStore<import('zustand').StoreApi<LayoutState>>;
+export {};

package/dist/core/services/RightSidebarService.d.ts

@@ -0,0 +1,7 @@
+interface RightSidebarState {
+    isChatOpen: boolean;
+    setChatOpen: (open: boolean) => void;
+    toggleChat: () => void;
+}
+export declare const useRightSidebarStore: import('zustand').UseBoundStore<import('zustand').StoreApi<RightSidebarState>>;
+export {};

package/dist/core/services/SidebarService.d.ts

@@ -0,0 +1,17 @@
+import { LucideIcon } from 'lucide-react';
+
+export interface ISidebarPanel {
+    id: string;
+    label: string;
+    icon: LucideIcon;
+    component: React.ComponentType<any> | React.ReactNode;
+}
+interface SidebarState {
+    activeSidebar: string | null;
+    panels: ISidebarPanel[];
+    setActiveSidebar: (id: string | null) => void;
+    toggleSidebar: (id: string) => void;
+    setPanels: (panels: ISidebarPanel[]) => void;
+}
+export declare const useSidebarStore: import('zustand').UseBoundStore<import('zustand').StoreApi<SidebarState>>;
+export {};

package/dist/core/services/StatusBarService.d.ts

@@ -0,0 +1,21 @@
+import { LucideIcon } from 'lucide-react';
+
+export interface IStatusBarWidget {
+    id: string;
+    label: string;
+    icon?: LucideIcon;
+    alignment: 'left' | 'center' | 'right';
+    commandId?: string;
+    onClick?: () => void;
+    className?: string;
+    priority?: number;
+}
+interface StatusBarState {
+    widgets: IStatusBarWidget[];
+    setWidgets: (widgets: IStatusBarWidget[]) => void;
+    addWidget: (widget: IStatusBarWidget) => void;
+    removeWidget: (id: string) => void;
+    updateWidget: (id: string, updates: Partial<IStatusBarWidget>) => void;
+}
+export declare const useStatusBarStore: import('zustand').UseBoundStore<import('zustand').StoreApi<StatusBarState>>;
+export {};

package/dist/core/services/TerminalService.d.ts

@@ -0,0 +1,10 @@
+interface TerminalState {
+    isOpen: boolean;
+    history: string[];
+    setOpen: (open: boolean) => void;
+    toggle: () => void;
+    addHistory: (line: string) => void;
+    clearHistory: () => void;
+}
+export declare const useTerminalStore: import('zustand').UseBoundStore<import('zustand').StoreApi<TerminalState>>;
+export {};

package/dist/core/services/ThemeService.d.ts

@@ -0,0 +1,7 @@
+export type ThemeType = 'light' | 'dark' | 'gt';
+interface ThemeState {
+    theme: ThemeType;
+    setTheme: (theme: ThemeType) => void;
+}
+export declare const useThemeStore: import('zustand').UseBoundStore<import('zustand').StoreApi<ThemeState>>;
+export {};

package/dist/index.d.ts

@@ -0,0 +1,23 @@
+export { ShellLayout } from './components/layout/ShellLayout';
+export { MenuBar } from './components/widgets/MenuBar';
+export { StatusBar } from './components/widgets/StatusBar';
+export { ActivityBar } from './components/widgets/ActivityBar';
+export { SidebarPane } from './components/widgets/SidebarPane';
+export { TreeWidget } from './components/widgets/TreeWidget';
+export { SearchWidget, type ISearchResult, type SearchWidgetProps } from './components/widgets/SearchWidget';
+export { CommandPalette } from './components/widgets/CommandPalette';
+export { UserProfile, type UserProfileProps } from './components/widgets/UserProfile';
+export { ChatPane } from './components/widgets/ChatPane';
+export { TerminalPane } from './components/widgets/TerminalPane';
+export { commandRegistry, type ICommand } from './core/registry/CommandRegistry';
+export { menuRegistry, type IMenuItem } from './core/registry/MenuRegistry';
+export { pluginRegistry, type IPlugin } from './core/registry/PluginRegistry';
+export { initializeShell } from './core/Boot';
+export { useLayoutStore } from './core/services/LayoutService';
+export { useThemeStore, type ThemeType } from './core/services/ThemeService';
+export { useSidebarStore, type ISidebarPanel } from './core/services/SidebarService';
+export { useRightSidebarStore } from './core/services/RightSidebarService';
+export { useTerminalStore } from './core/services/TerminalService';
+export { useChatStore, type ISlashCommand } from './core/services/ChatService';
+export { useStatusBarStore, type IStatusBarWidget } from './core/services/StatusBarService';
+export { useKeyboardShortcuts } from './core/services/KeyboardService';

package/dist/main.d.ts

@@ -0,0 +1 @@
+