@petrarca/sonnet-shell 0.2.0 → 0.4.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[];
@@ -188,12 +199,55 @@ interface ServiceModule {
      *   canvases, or any route that manages its own scroll and height.
      */
     layout?: "default" | "full";
+    /**
+     * Optional module-owned effect hook, invoked once by the shell inside the
+     * shell tree (so it has Router / QueryClient / provider context available).
+     *
+     * Use this for app-state reactions that belong to the module rather than to
+     * central app code — e.g. subscribing to a shell event and invalidating the
+     * module's own caches. The shell calls it unconditionally on every render, so
+     * it MUST obey the Rules of Hooks (call hooks unconditionally, no early
+     * returns) and the set of modules MUST be stable for the app's lifetime.
+     *
+     * It renders no UI; return nothing.
+     */
+    useEffects?: () => void;
+    /**
+     * Capabilities this module requires to be available, as "domain:name" strings
+     * (e.g. "state:graph.selected", "auth:templates.read"). Combined with implicit
+     * AND. Absent ⇒ the module is always available.
+     *
+     * The shell does not interpret these — the app's `resolveCapability` evaluates
+     * each one. See docs/design/module-capabilities.md.
+     */
+    requires?: string[];
+}
+/** Semantic reason a capability is unmet. Drives the presentation matrix. */
+type UnmetKind = "missing-state" | "not-authorized" | "not-authorized-soft" | "feature-off" | "error";
+/** Result of evaluating a single capability. Decision only — never presentation. */
+interface CapabilityResult {
+    met: boolean;
+    /** Why the capability is unmet (only when met === false). */
+    kind?: UnmetKind;
+    /** Optional human-readable hint, surfaced in tooltips / adjacent text. */
+    reason?: string;
 }
+/** App-provided function that evaluates a single capability string. */
+type CapabilityResolver = (capability: string) => CapabilityResult;
+/** A shell surface that gates modules. */
+type Surface = "rail" | "command" | "route";
+/** How an unavailable module renders on a surface. */
+type Effect = "visible" | "disabled" | "hidden" | "redirect";
+/**
+ * Maps (unmet reason kind, surface) → effect. Sparse overrides are merged over
+ * the shell defaults (`DEFAULT_CAPABILITY_POLICY`).
+ */
+type CapabilityPolicy = Partial<Record<UnmetKind, Partial<Record<Surface, Effect>>>>;
 
 /**
  * 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 +255,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 +290,27 @@ 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;
+    /**
+     * Evaluates a module capability (from `ShellModule.requires`) for gating the
+     * icon rail / command menu / routes. Absent ⇒ no gating (all modules
+     * available). See docs/design/module-capabilities.md.
+     */
+    resolveCapability?: CapabilityResolver;
+    /**
+     * Sparse overrides for the (unmet reason kind, surface) → effect matrix,
+     * merged over the shell defaults. Lets the app tune hide-vs-disable per
+     * reason kind and surface without touching modules.
+     */
+    capabilityPolicy?: CapabilityPolicy;
 }
 /**
  * Read the shell configuration from context.
@@ -243,8 +325,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 +342,43 @@ 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;
+    /** Render greyed and non-interactive (e.g. a capability requirement is unmet). */
+    disabled?: boolean;
+    /** Optional tooltip override (e.g. why the item is disabled). Defaults to `label`. */
+    tooltip?: string;
+}
+/** Single icon button with tooltip inside an IconRail. */
+declare function RailIcon({ icon: Icon, label, active, onClick, disabled, tooltip, }: 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 +446,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;
@@ -383,6 +569,25 @@ interface UserMenuProps {
 }
 declare function UserMenu({ user, onSignOut }: UserMenuProps): react_jsx_runtime.JSX.Element;
 
+/** Default (kind, surface) → effect matrix. App overrides are merged over this. */
+declare const DEFAULT_CAPABILITY_POLICY: Record<UnmetKind, Record<Surface, Effect>>;
+/** Merge a sparse app override over the default matrix. */
+declare function resolveCapabilityPolicy(override?: CapabilityPolicy): Record<UnmetKind, Record<Surface, Effect>>;
+interface ModuleEffect {
+    effect: Effect;
+    /** Hint from the first most-restrictive unmet capability (for tooltips). */
+    reason?: string;
+}
+/**
+ * Evaluate a module's requirements for a given surface.
+ *
+ * Returns `visible` when there are no requirements or all are met. Otherwise
+ * each unmet capability maps (kind, surface) → effect and the most restrictive
+ * wins (hidden > redirect > disabled > visible). When capabilities share the
+ * same effect rank, the first one with a non-empty reason provides the tooltip.
+ */
+declare function evaluateModule(module: ShellModule, surface: Surface, resolve: CapabilityResolver | undefined, policy: Record<UnmetKind, Record<Surface, Effect>>): ModuleEffect;
+
 /**
  * Shell API -- imperative domain capabilities for modules.
  *
@@ -431,11 +636,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;
@@ -480,6 +692,22 @@ interface PanelOptions {
      * - "full": panel covers the full viewport height including the TopBar.
      */
     coverage?: "below-header" | "full";
+    /**
+     * Allow the user to drag the left edge of the panel to resize it.
+     * Defaults to false. When true, the fixed `width` token is used as the
+     * initial width and the panel width is controlled dynamically.
+     */
+    resizable?: boolean;
+    /**
+     * Minimum width in pixels when resizable. Defaults to 240.
+     * Ignored when resizable is false.
+     */
+    minWidth?: number;
+    /**
+     * Maximum width in pixels when resizable. Defaults to 90% of viewport width.
+     * Ignored when resizable is false.
+     */
+    maxWidth?: number;
     /** Called after the panel finishes closing. Use to restore focus to the triggering element. */
     onClose?: () => void;
 }
@@ -537,6 +765,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 +794,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 +867,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 +883,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, type CapabilityPolicy, type CapabilityResolver, type CapabilityResult, CommandMenu, ConfirmDialog, type ConfirmDialogProps, type ConfirmOptions, type Contribution, DEFAULT_CAPABILITY_POLICY, type Effect, FeatureLink, type FullscreenOptions, IconRail, type IconRailProps, type ModuleCommand, type ModuleEffect, 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, type Surface, TopBar, type UnmetKind, UserMenu, type UserMenuUser, createModuleRegistry, dialog, evaluateModule, events, fullscreen, initDialog, initFeatureNav, initFullscreen, initNavigation, initPanel, initSidePane, navigation, notification, panel, resolveCapabilityPolicy, sidePane, useExtensionPoint, useMainModules, useShellConfig, useShellEvent, useShellModules, useShellNavigation, useSidePaneState };