@petrarca/sonnet-shell 0.3.0 → 0.4.0

package/README.md

@@ -4,13 +4,28 @@ Application shell, layout, and navigation for the Petrarca Sonnet component libr
 
 ## What's included
 
-**AppShell** -- Full application shell with icon rail, top bar, side pane, sub-navigation, command menu, and confirm dialogs.
+**RootLayout / AppShell** — Full application shell: TopBar, navigation
+(icon-rail or sidebar), SidePane, content area, overlays, command menu.
 
-**Imperative API** -- Shell capabilities exposed as simple function calls: `notification.success()`, `panel.open()`, `navigation.go()`, `dialog.confirm()`, `fullscreen.enter()`.
+**Navigation layouts** — Two built-in layouts driven by the same module metadata:
+- `ShellRail` — narrow icon strip + contextual sub-nav panel (default)
+- `ShellSidebar` — single-column sidebar with icons, labels, and collapsible sections
 
-**Module registry** -- Register application modules with navigation, routes, and search providers. The shell renders the navigation and routes automatically.
+**Navigation primitives** — Compose custom layouts from `IconRail`, `RailIcon`,
+`RailSeparator`, `Sidebar`, `SidebarGroup`, `SidebarItem`, `SubNavPanel`.
 
-**Auth components** (subpath: `@petrarca/sonnet-shell/auth`) -- Login, ProtectedRoute, and TenantSelection components with prop-driven auth configuration. No auth logic baked in -- the host app provides the auth state.
+**Shell chrome** — `TopBar`, `ShellFooter`, `ShellVersion` for header/footer slots.
+
+**Imperative API** — Shell capabilities as simple function calls from any module:
+`notification`, `dialog`, `navigation`, `panel`, `sidePane`, `fullscreen`, `events`.
+
+**Module system** — Register app modules (`ShellModule`) with routes, navigation,
+Cmd+K commands, and side pane config. `createModuleRegistry()` aggregates them.
+
+**Auth components** (`@petrarca/sonnet-shell/auth`) — `Login`, `ProtectedRoute`,
+`TenantSelection`. Prop-driven — no auth logic baked in.
+
+---
 
 ## Install
 
@@ -18,8 +33,228 @@ Application shell, layout, and navigation for the Petrarca Sonnet component libr
 pnpm add @petrarca/sonnet-shell @petrarca/sonnet-ui @petrarca/sonnet-core
 ```
 
-Peer dependencies: `react`, `react-dom`, `react-router-dom`, `tailwindcss`.
+Peer dependencies: `react >=19`, `react-dom >=19`, `react-router-dom`, `tailwindcss`.
+
+---
+
+## Setup
+
+### 1. Define modules
+
+Each feature area is a `ShellModule`:
+
+```ts
+// src/modules/home/index.ts
+import { Home } from "lucide-react";
+import type { ShellModule } from "@petrarca/sonnet-shell";
+import { routes } from "./routes";
+
+const homeModule: ShellModule = {
+  id: "home",
+  label: "Home",
+  icon: Home,
+  basePath: "/home",
+  navigation: [
+    {
+      id: "main",
+      links: [
+        { id: "home.overview", label: "Overview", path: "/home" },
+        { id: "home.settings", label: "Settings", path: "/home/settings" },
+      ],
+    },
+  ],
+  // Optional: fixed top-zone links in sidebar mode (no heading, separator below)
+  topNav: [
+    { id: "home.overview", label: "Overview", path: "/home" },
+  ],
+  routes,
+};
+
+export default homeModule;
+```
+
+### 2. Create the registry
+
+```ts
+// src/modules/registry.ts
+import { createModuleRegistry } from "@petrarca/sonnet-shell";
+import home from "./home";
+import settings from "./settings";
+
+const registry = createModuleRegistry([home, settings]);
+
+export const { allRoutes } = registry;
+export default registry;
+```
+
+### 3. Wire the shell
+
+```tsx
+// src/routes/AppRouter.tsx
+import { createBrowserRouter, RouterProvider, Navigate } from "react-router-dom";
+import {
+  RootLayout,
+  SearchTrigger,
+  UserMenu,
+  ShellVersion,
+  type ShellConfig,
+} from "@petrarca/sonnet-shell";
+import pkg from "../../package.json";
+import registry from "@/modules/registry";
+
+function TopBarContent() {
+  return (
+    <>
+      <div className="flex items-center gap-3">
+        <span className="text-sm font-semibold">MY APP</span>
+      </div>
+      <div className="flex items-center gap-2">
+        <SearchTrigger />
+        <UserMenu user={...} onSignOut={...} />
+      </div>
+    </>
+  );
+}
+
+const shellConfig: ShellConfig = {
+  topBar: <TopBarContent />,
+  footer: <ShellVersion name="My App" version={pkg.version} />,
+};
+
+const router = createBrowserRouter([
+  {
+    element: <RootLayout config={shellConfig} registry={registry} />,
+    children: [
+      { index: true, element: <Navigate to="/home" replace /> },
+      ...registry.allRoutes,
+    ],
+  },
+]);
+
+export function AppRouter() {
+  return <RouterProvider router={router} />;
+}
+```
+
+### 4. CSS and Tailwind
+
+```css
+/* index.css */
+@import "@petrarca/sonnet-ui/styles.css";
+
+/* Shell layout — app-level, not provided by the library */
+html, body, #root { height: 100%; }
+#root { display: flex; flex-direction: column; overflow: hidden; }
+body { min-height: 100vh; overflow: hidden; }
+```
+
+```js
+// tailwind.config.js
+module.exports = {
+  presets: [require("@petrarca/sonnet-ui/tailwind-preset")],
+  content: [
+    "./src/**/*.{ts,tsx}",
+    "./node_modules/@petrarca/sonnet-*/dist/**/*.js",
+  ],
+  plugins: [require("tailwindcss-animate"), require("@tailwindcss/typography")],
+};
+```
+
+---
+
+## Sidebar layout
+
+Pass a `sidebar` prop to `RootLayout` to replace the default icon-rail with a
+single-column sidebar:
+
+```tsx
+import { ShellSidebar } from "@petrarca/sonnet-shell";
+
+// Auto-wired from registry metadata:
+<RootLayout config={shellConfig} registry={registry} sidebar={<ShellSidebar />} />
+
+// Or fully custom:
+import { Sidebar, SidebarGroup, SidebarItem } from "@petrarca/sonnet-shell";
+
+<RootLayout
+  config={shellConfig}
+  registry={registry}
+  sidebar={
+    <Sidebar>
+      <SidebarGroup separator>
+        <SidebarItem icon={Home} label="Overview" path="/home" />
+      </SidebarGroup>
+      <SidebarGroup heading="PROJECTS" collapsible>
+        <SidebarItem icon={Folder} label="Alpha" path="/projects/alpha" />
+      </SidebarGroup>
+    </Sidebar>
+  }
+/>
+```
+
+`topNav` on a `ShellModule` populates the top separator zone automatically
+when using `ShellSidebar`.
+
+---
+
+## Imperative API
+
+Any module can call the shell API without prop drilling:
+
+```ts
+import { notification, dialog, navigation, panel, sidePane } from "@petrarca/sonnet-shell";
+
+notification.success("Saved.");
+notification.error("Failed to save.");
+
+const confirmed = await dialog.confirm({
+  title: "Delete item?",
+  confirmLabel: "Delete",
+  variant: "destructive",
+});
+
+navigation.goTo("/home");
+navigation.goToFeature("home.settings");  // stable id, path-independent
+
+panel.open({
+  title: "Details",
+  content: <MyPanel />,
+  width: "default",
+});
+
+sidePane.toggle({ moduleId: "my-module", content: <MySidePane /> });
+```
+
+---
+
+## ShellModule reference
+
+```ts
+interface ShellModule {
+  id: string;                    // unique, e.g. "terminology"
+  label: string;                 // shown in rail tooltip, sub-nav header
+  description?: string;          // shown in Cmd+K
+  icon: LucideIcon;
+
+  basePath: string;              // URL prefix, e.g. "/terminology"
+  routes: RouteObject[];         // React Router routes
+
+  topNav?: NavLink[];            // fixed top-zone links (sidebar only)
+  navigation: NavGroup[];        // grouped nav links (rail + sidebar)
+
+  pinBottom?: boolean;           // pin to bottom of rail / sidebar tools group
+  hidden?: boolean;              // hide from navigation entirely
+
+  contributions?: Contribution[]; // inject links into other modules' nav
+  commands?: ModuleCommand[];     // Cmd+K actions
+
+  sidePane?: { ... };            // inline resizable panel config
+  layout?: "default" | "full";   // "full" removes scroll wrapper and padding
+}
+```
+
+---
 
 ## License
 
-Apache 2.0
+See [LICENSE.md](../../LICENSE.md).

package/dist/index.d.ts

@@ -199,7 +199,50 @@ interface ShellModule {
      *   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.
@@ -256,6 +299,18 @@ interface ShellConfig {
      * 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.
@@ -309,9 +364,13 @@ interface RailIconProps {
     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, }: RailIconProps): React__default.ReactElement;
+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;
 
@@ -510,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.
  *
@@ -614,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;
 }
@@ -789,4 +883,4 @@ declare function useMainModules(): ShellModule[];
  */
 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 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 };
+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 };