@petrarca/sonnet-shell 0.2.0 → 0.3.0

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 import * as react_jsx_runtime from 'react/jsx-runtime';
-import { RouteObject } from 'react-router-dom';
 import * as React from 'react';
 import React__default, { ReactNode } from 'react';
+import { RouteObject } from 'react-router-dom';
 import { LucideIcon } from 'lucide-react';
 
 interface SidePaneOptions {
@@ -50,7 +50,7 @@ declare function useSidePaneState(): SidePaneState;
  * Shell type definitions.
  *
  * These types define the contract between the shell and modules.
- * Modules implement ServiceModule; the shell consumes it.
+ * Modules implement ShellModule; the shell consumes it.
  */
 
 interface NavLink {
@@ -62,17 +62,21 @@ interface NavLink {
     id?: string;
     label: string;
     path: string;
+    /** Optional trailing badge (count or status text) for sidebar display. */
+    badge?: string | number;
 }
 interface NavGroup {
     /** Stable identifier used as React key. Defaults to heading if omitted. */
     id: string;
     heading?: string;
     links: NavLink[];
+    /** Whether this group can be collapsed in sidebar mode. */
+    collapsible?: boolean;
 }
 /**
  * An action contributed by a module to the CommandMenu.
  *
- * Modules declare commands in ServiceModule.commands[]. The CommandMenu
+ * Modules declare commands in ShellModule.commands[]. The CommandMenu
  * renders them in a dedicated group so users can trigger module actions
  * (open side pane, trigger a workflow, etc.) directly from Cmd+K without
  * navigating to a route first.
@@ -123,7 +127,7 @@ interface Contribution {
 interface ShellEventMap {
     [custom: string]: unknown;
 }
-interface ServiceModule {
+interface ShellModule {
     /** Unique identifier for this module */
     id: string;
     /** Display name (icon rail tooltip, sub-nav header, command menu) */
@@ -134,7 +138,14 @@ interface ServiceModule {
     icon: LucideIcon;
     /** URL prefix used to match this module to the current route */
     basePath: string;
-    /** Navigation groups for the sub-nav panel */
+    /**
+     * Fixed top-level navigation links shown in the sidebar's top zone
+     * (no group heading, separator below). Not shown in the icon-rail
+     * sub-nav panel — they are sidebar-specific shortcuts.
+     * Optional — omit if all navigation belongs in grouped sections.
+     */
+    topNav?: NavLink[];
+    /** Navigation groups for the sub-nav panel and sidebar grouped sections */
     navigation: NavGroup[];
     /** React Router route definitions owned by this module */
     routes: RouteObject[];
@@ -193,7 +204,7 @@ interface ServiceModule {
 /**
  * Module registry factory.
  *
- * Accepts a list of ServiceModules and returns derived data structures
+ * Accepts a list of ShellModules and returns derived data structures
  * consumed by the shell (icon rail groups, flattened routes, extension
  * point lookup). This is the reusable core; the app-specific module
  * list lives in the consumer (e.g. modules/registry.ts).
@@ -201,22 +212,29 @@ interface ServiceModule {
 
 interface ModuleRegistry {
     /** All modules in registration order. */
-    modules: ServiceModule[];
+    modules: ShellModule[];
     /** Visible modules shown in the main area of the icon rail. */
-    mainModules: ServiceModule[];
+    mainModules: ShellModule[];
     /** Modules pinned to the bottom of the icon rail. */
-    bottomModules: ServiceModule[];
+    bottomModules: ShellModule[];
     /** All routes from all modules, flattened. */
     allRoutes: RouteObject[];
     /** Get contributions for a named extension point, sorted by order. */
     getExtensionPoint: (name: string) => Contribution[];
 }
-declare function createModuleRegistry(modules: ServiceModule[]): ModuleRegistry;
+declare function createModuleRegistry(modules: ShellModule[]): ModuleRegistry;
 
 interface AppShellProps {
     registry: ModuleRegistry;
+    /**
+     * Optional custom sidebar replacing the default IconRail + SubNavPanel.
+     * When provided, the shell renders this element in place of the two-column
+     * navigation chrome. Use the Sidebar / SidebarGroup / SidebarItem components
+     * from this package to build a single-column navigation layout.
+     */
+    sidebar?: React__default.ReactNode;
 }
-declare function AppShell({ registry }: AppShellProps): react_jsx_runtime.JSX.Element;
+declare function AppShell({ registry, sidebar }: AppShellProps): react_jsx_runtime.JSX.Element;
 
 interface ShellConfig {
     /**
@@ -229,6 +247,15 @@ interface ShellConfig {
      * components.
      */
     topBar?: ReactNode;
+    /**
+     * Content rendered inside the ShellFooter. The shell provides the
+     * `<footer>` element with its sizing and border; the consumer owns
+     * everything inside it.
+     *
+     * Common uses: status bar, sync indicators, version info, quick actions.
+     * Omit to render no footer.
+     */
+    footer?: ReactNode;
 }
 /**
  * Read the shell configuration from context.
@@ -243,8 +270,10 @@ declare function useShellConfig(): ShellConfig;
 interface RootLayoutProps {
     config: ShellConfig;
     registry: ModuleRegistry;
+    /** Optional custom sidebar replacing the default IconRail + SubNavPanel. */
+    sidebar?: React__default.ReactNode;
 }
-declare function RootLayout({ config, registry }: RootLayoutProps): react_jsx_runtime.JSX.Element;
+declare function RootLayout({ config, registry, sidebar, }: RootLayoutProps): react_jsx_runtime.JSX.Element;
 
 /**
  * TopBar -- persistent header across the entire application.
@@ -258,32 +287,39 @@ interface TopBarProps {
 }
 declare function TopBar({ children }: TopBarProps): react_jsx_runtime.JSX.Element;
 
-interface IconRailProps {
-    activeServiceId: string | null;
-    /** moduleId of the module whose side pane is currently open, or null. */
-    activeSidePaneModuleId: string | null;
-    onServiceSelect: (serviceId: string) => void;
-}
 /**
- * IconRail -- narrow vertical bar with service domain icons.
+ * IconRail primitives — composable building blocks for the narrow
+ * vertical icon strip.
+ *
+ * - IconRail: the container (<nav> with flex column, border, bg)
+ * - RailIcon: a single icon button with tooltip
+ * - RailSeparator: divider between groups
  *
- * Main services scroll in the center, settings/playground pinned at bottom.
- * Tooltips show service labels on hover.
+ * For the auto-wired layout, use ShellRail instead.
  */
-declare function IconRail({ activeServiceId, activeSidePaneModuleId, onServiceSelect, }: IconRailProps): react_jsx_runtime.JSX.Element;
+
+interface IconRailProps {
+    children: React__default.ReactNode;
+    className?: string;
+}
+/** Narrow vertical nav container for RailIcon items. */
+declare function IconRail({ children, className, }: IconRailProps): React__default.ReactElement;
+interface RailIconProps {
+    icon: LucideIcon;
+    label: string;
+    active?: boolean;
+    onClick?: () => void;
+}
+/** Single icon button with tooltip inside an IconRail. */
+declare function RailIcon({ icon: Icon, label, active, onClick, }: RailIconProps): React__default.ReactElement;
+/** Visual divider between icon groups inside an IconRail. */
+declare function RailSeparator(): React__default.ReactElement;
 
 interface SubNavPanelProps {
-    service: ServiceModule;
+    service: ShellModule;
     collapsed: boolean;
     onToggleCollapse: () => void;
 }
-/**
- * SubNavPanel -- contextual secondary navigation for the selected service domain.
- *
- * Shows the service label at top, then grouped nav links. If other modules
- * contribute links via the "<moduleId>.nav" extension point, they are
- * appended as an additional group.
- */
 declare function SubNavPanel({ service, collapsed, onToggleCollapse, }: SubNavPanelProps): react_jsx_runtime.JSX.Element;
 
 /**
@@ -351,6 +387,97 @@ interface ConfirmDialogProps {
  */
 declare function ConfirmDialog({ open, title, description, confirmLabel, cancelLabel, variant, onConfirm, onCancel, }: ConfirmDialogProps): React__default.ReactElement;
 
+/**
+ * Sidebar — single-column navigation layout.
+ *
+ * Alternative to the IconRail + SubNavPanel two-column pattern.
+ * Renders an optional header, a scrollable body with SidebarGroup /
+ * SidebarItem children, and takes its full height from the shell.
+ */
+
+interface SidebarProps {
+    children: React__default.ReactNode;
+    /** Optional header rendered above the scrollable nav (e.g. app name, collapse button). */
+    header?: React__default.ReactNode;
+    width?: number;
+    className?: string;
+}
+declare function Sidebar({ children, header, width, className, }: SidebarProps): React__default.ReactElement;
+
+/** Labeled, optionally collapsible section within a Sidebar. */
+
+interface SidebarGroupProps {
+    heading?: string;
+    collapsible?: boolean;
+    defaultOpen?: boolean;
+    /** Render a border separator below this group. */
+    separator?: boolean;
+    children: React__default.ReactNode;
+}
+declare function SidebarGroup({ heading, collapsible, defaultOpen, separator, children, }: SidebarGroupProps): React__default.ReactElement;
+
+/** Single navigation row inside a Sidebar — icon + label + optional trailing slot. */
+
+interface SidebarItemProps {
+    icon?: LucideIcon;
+    label: string;
+    path: string;
+    badge?: string | number;
+    indent?: number;
+    expandable?: boolean;
+    expanded?: boolean;
+    onToggle?: () => void;
+    onClick?: () => void;
+}
+declare function SidebarItem({ icon: Icon, label, path, badge, indent, expandable, expanded, onToggle, onClick, }: SidebarItemProps): React__default.ReactElement;
+
+/**
+ * ShellRail — icon-rail + sub-nav-panel layout, auto-wired from the
+ * module registry and shell navigation context.
+ *
+ * Reads active service state from ShellNavigationContext (provided by
+ * AppShell) and module list from ShellModulesContext. No props required.
+ *
+ * For custom layouts, compose IconRail, RailIcon, RailSeparator, and
+ * SubNavPanel directly.
+ */
+
+declare function ShellRail(): React__default.ReactElement;
+
+/**
+ * ShellSidebar — single-column sidebar layout, auto-wired from the
+ * module registry.
+ *
+ * Reads module list from ShellModulesContext (provided by AppShell).
+ * For custom layouts, compose Sidebar / SidebarGroup / SidebarItem directly.
+ */
+
+type ShellSidebarProps = Omit<SidebarProps, "children"> & {
+    /** Label for the bottom-pinned modules group. Default: "Tools". */
+    bottomGroupLabel?: string;
+};
+declare function ShellSidebar({ bottomGroupLabel, ...sidebarProps }: ShellSidebarProps): React__default.ReactElement;
+
+interface ShellFooterProps {
+    children?: ReactNode;
+}
+declare function ShellFooter({ children }: ShellFooterProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * ShellVersion — displays the app name and optional version in the footer.
+ *
+ * Typically used as ShellConfig.footer content alongside ShellFooter.
+ * The consumer provides name and version from their own package.json.
+ */
+
+interface ShellVersionProps {
+    /** Application name. */
+    name: string;
+    /** Version string (e.g. from package.json). Omit to show name only. */
+    version?: string;
+}
+declare function ShellVersion({ name, version, }: ShellVersionProps): React__default.ReactElement;
+
 interface ShellConfigProviderProps {
     config: ShellConfig;
     children: ReactNode;
@@ -431,11 +558,18 @@ declare const dialog: {
 };
 type NavigateFn = (path: string) => void;
 type CommandMenuFn = () => void;
+type FeatureLookupFn = (featureId: string) => string | null;
 /**
  * Called by the shell during initialization to inject router + command menu.
  * Not part of the public module API -- only the shell calls this.
  */
 declare function initNavigation(navigateFn: NavigateFn, openCommandMenuFn: CommandMenuFn): void;
+/**
+ * Called by the shell during initialization to inject the feature lookup.
+ * Resolves a stable feature id (e.g. "auditing.audit-events") to a path.
+ * Not part of the public module API -- only the shell calls this.
+ */
+declare function initFeatureNav(lookupFn: FeatureLookupFn): void;
 declare const navigation: {
     /** Navigate to a path within the shell. */
     goTo(path: string): void;
@@ -537,6 +671,13 @@ interface FullscreenOptions {
     /** React content to render inside the fullscreen overlay. */
     content: ReactNode;
 }
+type FullscreenEnterFn = (opts: FullscreenOptions) => void;
+type FullscreenExitFn = () => void;
+/**
+ * Called by the shell during initialization to inject fullscreen controls.
+ * Not part of the public module API -- only the shell calls this.
+ */
+declare function initFullscreen(enterFn: FullscreenEnterFn, exitFn: FullscreenExitFn): void;
 declare const fullscreen: {
     /** Enter fullscreen mode, rendering content over all shell chrome. */
     enter(opts: FullscreenOptions): void;
@@ -559,6 +700,16 @@ declare const events: {
  */
 declare function useShellModules(): ModuleRegistry;
 
+interface ShellNavigationState {
+    activeService: ShellModule | null;
+    sidePaneModuleId: string | null;
+    subNavCollapsed: boolean;
+    onToggleSubNav: () => void;
+    onServiceSelect: (id: string) => void;
+}
+/** Read shell navigation state. Must be used within AppShell. */
+declare function useShellNavigation(): ShellNavigationState;
+
 /**
  * OverviewCard and FeatureLink -- building blocks for module overview pages.
  *
@@ -622,7 +773,7 @@ declare function useExtensionPoint(name: string): Contribution[];
  *
  * Useful for building overviews like the home page.
  */
-declare function useMainModules(): ServiceModule[];
+declare function useMainModules(): ShellModule[];
 /**
  * Subscribe to a shell event, auto-unsubscribing on unmount.
  *
@@ -638,4 +789,4 @@ declare function useMainModules(): ServiceModule[];
  */
 declare function useShellEvent<K extends keyof ShellEventMap>(key: K, handler: (payload: ShellEventMap[K]) => void): void;
 
-export { AppShell, CommandMenu, ConfirmDialog, type ConfirmDialogProps, type ConfirmOptions, type Contribution, FeatureLink, type FullscreenOptions, IconRail, type ModuleCommand, type ModuleRegistry, type NavGroup, type NavLink, OverviewCard, type PanelOptions, PlaceholderPage, RootLayout, SearchTrigger, type ServiceModule, type ShellConfig, ShellConfigProvider, type ShellEventMap, SidePane, type SidePaneOptions as SidePaneApiOptions, SidePaneContext, type SidePaneOptions, type SidePaneState, SubNavPanel, TopBar, UserMenu, type UserMenuUser, createModuleRegistry, dialog, events, fullscreen, initDialog, initNavigation, initPanel, initSidePane, navigation, notification, panel, sidePane, useExtensionPoint, useMainModules, useShellConfig, useShellEvent, useShellModules, useSidePaneState };
+export { AppShell, CommandMenu, ConfirmDialog, type ConfirmDialogProps, type ConfirmOptions, type Contribution, FeatureLink, type FullscreenOptions, IconRail, type IconRailProps, type ModuleCommand, type ModuleRegistry, type NavGroup, type NavLink, OverviewCard, type PanelOptions, PlaceholderPage, RailIcon, type RailIconProps, RailSeparator, RootLayout, SearchTrigger, type ShellConfig, ShellConfigProvider, type ShellEventMap, ShellFooter, type ShellFooterProps, type ShellModule, type ShellNavigationState, ShellRail, ShellSidebar, type ShellSidebarProps, ShellVersion, type ShellVersionProps, SidePane, type SidePaneOptions as SidePaneApiOptions, SidePaneContext, type SidePaneOptions, type SidePaneState, Sidebar, SidebarGroup, type SidebarGroupProps, SidebarItem, type SidebarItemProps, type SidebarProps, SubNavPanel, type SubNavPanelProps, TopBar, UserMenu, type UserMenuUser, createModuleRegistry, dialog, events, fullscreen, initDialog, initFeatureNav, initFullscreen, initNavigation, initPanel, initSidePane, navigation, notification, panel, sidePane, useExtensionPoint, useMainModules, useShellConfig, useShellEvent, useShellModules, useShellNavigation, useSidePaneState };