@petrarca/sonnet-shell 0.2.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).