nexus-shell 0.2.2 → 0.2.4

package/README.md

@@ -92,7 +92,7 @@ const [active, setActive] = useState<string | null>('files');
     />
     {active && (
       <SidebarPane title="Explorer" onClose={() => setActive(null)}>
-        <TreeWidget data={files} onToggle={toggle} onActivate={open} />
+        <TreeWidget data={nodes} onToggle={toggle} onActivate={open} />
       </SidebarPane>
     )}
     <main className="flex-1">{children}</main>
@@ -128,12 +128,13 @@ shell's own frame and keep every registration working.
 | `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 |
+| `TreeWidget` | Virtualised tree for any hierarchy, with drag-to-move and a data-driven menu |
 | `UserProfile` | Avatar and identity widget |
 
 ## Theming
 
-Three themes ship in the stylesheet: `theme-light`, `theme-dark`, `theme-gt`.
+Four themes ship in the stylesheet: `theme-light`, `theme-dark`, `theme-gt`
+(Georgia Tech) and `theme-tamu` (Texas A&M).
 Colors are CSS custom properties scoped to those classes, so switching themes is
 a class on an ancestor — no React context, no provider.
 

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

@@ -6,13 +6,18 @@ export interface ISettingsThemeOption<T extends string = string> {
     label: string;
     icon: LucideIcon;
 }
+/**
+ * The themes bundled in the library stylesheet, with their full labels.
+ * Derived from the theme registry, so a new bundled theme appears here without
+ * a code change.
+ */
 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. */
+    /** Theme choices to offer. Defaults to every bundled theme. */
     themes?: ISettingsThemeOption<T>[];
     /** Extra classes merged onto the root element. */
     className?: string;

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

@@ -5,6 +5,11 @@ export interface IThemeOption<T extends string = string> {
     /** Short label shown on the segment. Kept terse — segments are compact. */
     label: string;
 }
+/**
+ * The themes bundled in the library stylesheet, using their abbreviated labels
+ * because the segments are narrow. Derived from the theme registry, so a new
+ * bundled theme appears here without a code change.
+ */
 export declare const DEFAULT_THEME_OPTIONS: IThemeOption[];
 export interface ThemeSwitcherProps<T extends string = string> {
     /** Currently selected theme id. */
@@ -12,8 +17,8 @@ export interface ThemeSwitcherProps<T extends string = string> {
     /** 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.
+     * Selectable themes. Defaults to every theme bundled in the library's
+     * stylesheet. Supply your own to offer a different set.
      */
     options?: IThemeOption<T>[];
     /** Extra classes merged onto the root element. */

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

@@ -1,31 +1,60 @@
 import { default as React } from 'react';
 
-/** A node in the {@link TreeWidget} hierarchy. */
+/**
+ * A node in the {@link TreeWidget} hierarchy.
+ *
+ * The model is deliberately domain-neutral: the component knows about branches
+ * and leaves, and nothing else. A file explorer, an org chart, a scene graph and
+ * a category picker are all the same shape here — what differs is your `kind`
+ * and your `icon`.
+ */
 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';
+    /**
+     * Whether this node can contain children — a folder, a department, a group.
+     * Branches expand on click and accept drops; leaves do neither.
+     *
+     * Defaults to `false`. Set it explicitly for a branch whose children haven't
+     * been loaded yet, so it still renders as expandable.
+     */
+    isBranch?: boolean;
+    /**
+     * Your own classification for this node, e.g. `"folder"`, `"department"`,
+     * `"question"`. The component never interprets it — it exists so context-menu
+     * actions can target node types through {@link ITreeAction.showFor}.
+     */
+    kind?: string;
     /** Child nodes. Only rendered while `isOpen` is `true`. */
     children?: ITreeNode[];
-    /** Whether a folder is expanded. Controlled by you — see `onToggle`. */
+    /** Whether a branch is expanded. Controlled by you — see `onToggle`. */
     isOpen?: boolean;
+    /**
+     * Icon rendered before the label. Any node works — a `lucide-react` icon, an
+     * avatar, a coloured dot. Omit it for a label-only row.
+     */
+    icon?: React.ReactNode;
+    /** Extra classes merged onto this row. */
+    className?: string;
 }
-/**
- * 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".
- */
+/** Where a context-menu action applies. */
 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. */
+/**
+ * Where a context-menu entry is offered.
+ *
+ * `'branch'` and `'leaf'` match structurally; `'background'` is a right-click on
+ * empty space. Any other string is matched against the node's `kind`, so you can
+ * scope an action to your own node types.
+ */
+export type TreeActionScope = 'branch' | 'leaf' | 'background' | (string & {});
+/** An entry in the tree's right-click menu. */
 export interface ITreeAction {
     /** Stable identifier. Used as the React key. */
     id: string;
@@ -38,39 +67,38 @@ export interface ITreeAction {
     /** 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.
+     * Restrict where the entry appears. Defaults to everywhere.
+     *
+     * @example
+     * ```ts
+     * showFor: ['branch', 'background']   // structural
+     * showFor: ['department']             // matches node.kind
+     * ```
      */
-    showFor?: ('file' | 'folder' | 'background')[];
+    showFor?: TreeActionScope[];
 }
 export interface TreeWidgetProps {
     /** Root nodes. Expansion state lives on the nodes themselves via `isOpen`. */
     data: ITreeNode[];
     /**
-     * Called when a folder is clicked. Flip that node's `isOpen` in your own
+     * Called when a branch 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. */
+    /** Called when a node is double-clicked or Enter is pressed on a leaf. */
     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.
+     * Called after a node is dragged onto a branch. Only branches accept drops.
+     * Reparenting is yours to perform — the tree does not mutate `data`.
+     */
+    onMoveNode?: (draggedId: string, targetBranchId: string) => void;
+    /**
+     * Entries for the right-click menu. Empty by default: the component ships no
+     * actions of its own, because "New File" means nothing to an org chart.
      *
-     * Pass your own array to replace that set entirely — this is the extension
-     * point for app-specific commands, so the tree itself stays generic.
+     * With no entries, no menu appears.
      */
     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;
-    /** Handler for the built-in "Rename" action. */
-    onRename?: (nodeId: string) => void;
-    /** Handler for the built-in "Delete" action. */
-    onDelete?: (nodeId: string) => void;
     /** Indentation added per depth level, in px. Defaults to `12`. */
     indent?: number;
     /**
@@ -79,32 +107,49 @@ export interface TreeWidgetProps {
      * search, or a test environment that can't measure layout. Defaults to `true`.
      */
     virtualized?: boolean;
+    /** Accessible label for the tree. Defaults to `"Tree"`. */
+    'aria-label'?: string;
     /** Extra classes merged onto the root element. */
     className?: string;
 }
 /**
- * A virtualised file-explorer tree with drag-to-move and a right-click menu.
+ * A virtualised, domain-neutral tree with drag-to-move and a data-driven
+ * 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.
+ * It renders any hierarchy — files, an org chart, a scene graph, nested
+ * categories, an argument map. The component's only structural concept is
+ * `isBranch`: branches expand and accept drops, leaves do neither. Everything
+ * else — what a node *is*, what icon it carries, what actions it offers — is
+ * yours to supply.
  *
- * 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.
+ * Rows are virtualised via `react-virtuoso`, so large trees stay responsive.
+ *
+ * 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.
  *
  * @example
  * ```tsx
+ * // An org chart — no files in sight.
  * <TreeWidget
- *   data={nodes}
- *   onToggle={(n) => setNodes(toggle(nodes, n.id))}
- *   onActivate={(n) => open(n.id)}
+ *   data={[
+ *     {
+ *       id: 'eng',
+ *       label: 'Engineering',
+ *       isBranch: true,
+ *       kind: 'department',
+ *       isOpen: true,
+ *       icon: <Building2 size={14} />,
+ *       children: [
+ *         { id: 'ada', label: 'Ada Lovelace', kind: 'person', icon: <User size={14} /> },
+ *       ],
+ *     },
+ *   ]}
+ *   onToggle={(node) => setNodes(toggle(nodes, node.id))}
  *   actions={[
- *     { id: 'new-map', label: 'New Map', icon: <Map size={14} />,
- *       showFor: ['folder', 'background'], onSelect: (ctx) => createMap(ctx.nodeId) },
+ *     { id: 'hire', label: 'Add report', showFor: ['department'], onSelect: addReport },
  *   ]}
  * />
  * ```
  */
-export declare const TreeWidget: ({ data, onToggle, onActivate, onMoveNode, actions, onNewFile, onNewFolder, onRename, onDelete, indent, virtualized, className, }: TreeWidgetProps) => import("react/jsx-runtime").JSX.Element;
+export declare const TreeWidget: ({ data, onToggle, onActivate, onMoveNode, actions, indent, virtualized, "aria-label": ariaLabel, className, }: TreeWidgetProps) => import("react/jsx-runtime").JSX.Element;

package/dist/core/Boot.d.ts

@@ -31,7 +31,7 @@ export interface InitializeShellOptions {
     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"];
+export declare const DEFAULT_COMMAND_IDS: readonly ["view.toggleTerminal", "view.toggleChat", "view.toggleSidebar", ...string[]];
 /**
  * Boot the shell: register commands, menus, panels and status bar items into
  * the shell registries and stores.

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

@@ -1,4 +1,13 @@
-export type ThemeType = 'light' | 'dark' | 'gt';
+import { BundledThemeId } from '../../lib/themes';
+
+/**
+ * A theme id.
+ *
+ * The bundled ids are suggested by autocomplete, but any string is accepted:
+ * define a `.theme-yourname` block with the same custom properties and it works
+ * exactly like the built-ins.
+ */
+export type ThemeType = BundledThemeId | (string & {});
 interface ThemeState {
     theme: ThemeType;
     setTheme: (theme: ThemeType) => void;

package/dist/index.d.ts

@@ -57,3 +57,4 @@ export { ThemeSwitcher, type ThemeSwitcherProps, type IThemeOption, DEFAULT_THEM
 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 { cn } from './lib/cn';
+export { BUNDLED_THEMES, BUNDLED_THEME_CLASSES, themeClass, type IBundledTheme, type BundledThemeId, } from './lib/themes';

package/dist/lib/themes.d.ts

@@ -0,0 +1,57 @@
+/**
+ * The themes bundled in the library's stylesheet.
+ *
+ * This is the single source of truth. `ThemeService` derives its union type and
+ * its class-swapping from it, `ThemeSwitcher` and `SettingsPanel` derive their
+ * default options, `initializeShell` derives its theme commands and View menu,
+ * and Storybook derives its toolbar. Adding a theme is a block in `index.css`
+ * plus one entry here.
+ *
+ * It lives in `lib/` rather than `core/services/` because the presentational
+ * components need it, and they are forbidden from importing stores.
+ *
+ * Themes are not a closed set — see {@link ThemeSwitcher}'s `options` prop and
+ * {@link SettingsPanel}'s `themes` prop for supplying your own.
+ */
+export interface IBundledTheme {
+    /** Matches the `.theme-<id>` class in the stylesheet. */
+    id: string;
+    /** Full name, for menus and the settings panel. */
+    label: string;
+    /** Abbreviated name, for the compact segmented switcher. */
+    shortLabel: string;
+    /** One line on what the theme is, used in documentation. */
+    description: string;
+}
+export declare const BUNDLED_THEMES: readonly [{
+    readonly id: "light";
+    readonly label: "Light";
+    readonly shortLabel: "Light";
+    readonly description: "Neutral light theme. The default.";
+}, {
+    readonly id: "dark";
+    readonly label: "Dark";
+    readonly shortLabel: "Dark";
+    readonly description: "Low-glare dark theme on a soft grey base.";
+}, {
+    readonly id: "gt";
+    readonly label: "Georgia Tech";
+    readonly shortLabel: "GT";
+    readonly description: "Buzz Gold (#EAAA00) on Tech Tower White.";
+}, {
+    readonly id: "tamu";
+    readonly label: "Texas A&M";
+    readonly shortLabel: "TAMU";
+    readonly description: "Aggie Maroon (#500000) on white.";
+}];
+/** Ids of the themes that ship in the stylesheet. */
+export type BundledThemeId = (typeof BUNDLED_THEMES)[number]['id'];
+/** Every bundled theme's class name, e.g. `["theme-light", …]`. */
+export declare const BUNDLED_THEME_CLASSES: string[];
+/**
+ * The class name for a theme id.
+ *
+ * Accepts any string, not just a bundled id, so an app that defines its own
+ * `.theme-*` block can use it too.
+ */
+export declare const themeClass: (id: string) => string;