nexus-shell 0.2.1 → 0.2.3

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,7 +128,7 @@ 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

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/index.d.ts

@@ -22,7 +22,7 @@
  * you need a layout the shell cannot express. Most applications should not need
  * to.
  */
-export { ShellLayout, type ShellLayoutProps } from './components/layout/ShellLayout';
+export { ShellLayout, ShellLayout as NexusWorkspaceShell, 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';