@petrarca/sonnet-shell 0.5.0 → 0.7.0

package/README.md

@@ -1,31 +1,36 @@
 # @petrarca/sonnet-shell
 
-Application shell, layout, and navigation for the Petrarca Sonnet component library.
+The application frame of the Petrarca Sonnet component library. You write
+feature areas as modules; the shell composes them into navigation, routes, a
+command menu and a set of surfaces any module can reach imperatively.
 
-## What's included
+## What it provides
 
-**RootLayout / AppShell** — Full application shell: TopBar, navigation
-(icon-rail or sidebar), SidePane, content area, overlays, command menu.
+**A module system.** A `ShellModule` declares its routes, navigation, command
+menu entries, side pane and contributions to other modules.
+`createModuleRegistry` aggregates them and derives the navigation zones and the
+flattened route list once.
 
-**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
+**Two navigation layouts.** `ShellRail`, a narrow icon strip with a contextual
+sub-nav panel, and `ShellSidebar`, a single-column sidebar with collapsible
+sections. Both read the same module metadata, and `IconRail`, `Sidebar`,
+`SidebarGroup`, `SidebarItem` and `SubNavPanel` are exported for a custom one.
 
-**Navigation primitives** — Compose custom layouts from `IconRail`, `RailIcon`,
-`RailSeparator`, `Sidebar`, `SidebarGroup`, `SidebarItem`, `SubNavPanel`.
+**Shell chrome.** `RootLayout` and `AppShell`, `TopBar`, `ShellFooter`,
+`ShellVersion`, `SearchTrigger` and `UserMenu`.
 
-**Shell chrome** — `TopBar`, `ShellFooter`, `ShellVersion` for header/footer slots.
+**An imperative API.** `notification`, `dialog`, `navigation`, `panel`,
+`sidePane`, `fullscreen` and `events` are plain function calls, so a page
+reaches a toast, a confirm dialog, a slide-over or another module without prop
+drilling.
 
-**Imperative API** — Shell capabilities as simple function calls from any module:
-`notification`, `dialog`, `navigation`, `panel`, `sidePane`, `fullscreen`, `events`.
+**Capability gating.** A module can declare what it `requires`; the application
+supplies `resolveCapability` and a policy decides whether an unmet module is
+hidden, disabled or shown with an explanation.
 
-**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.
-
----
+**Auth screens** on the `./auth` subpath: `Login`, `ProtectedRoute` and
+`OrgSelection`. Prop-driven, with no auth logic of their own -- organization
+choice is the `orgs` and `onSelectOrg` props of `Login`.
 
 ## Install
 
@@ -33,92 +38,29 @@ Cmd+K commands, and side pane config. `createModuleRegistry()` aggregates them.
 pnpm add @petrarca/sonnet-shell @petrarca/sonnet-ui @petrarca/sonnet-core
 ```
 
-Peer dependencies: `react >=19`, `react-dom >=19`, `react-router-dom`, `tailwindcss`.
-
----
-
-## Setup
+| Peer | Range | Needed for |
+|---|---|---|
+| `react`, `react-dom` | `>=19` | Everything |
+| `react-router-dom` | `>=7` | Routing, `SidebarItem`, `ProtectedRoute`; the shell is built on the router, not adapted to it |
+| `tailwindcss` | `>=3` | The classes the shell renders |
 
-### 1. Define modules
+`lucide-react` and `sonner` arrive as regular dependencies.
 
-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,
-};
+## Usage
 
-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
+Declare modules, build a registry, mount `RootLayout` as a layout route.
 
 ```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";
+import { RootLayout, createModuleRegistry } from "@petrarca/sonnet-shell";
+import type { ShellConfig } from "@petrarca/sonnet-shell";
+import home from "@/modules/home";
+import widgets from "@/modules/widgets";
 
-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 registry = createModuleRegistry([home, widgets]);
 
 const shellConfig: ShellConfig = {
   topBar: <TopBarContent />,
-  footer: <ShellVersion name="My App" version={pkg.version} />,
 };
 
 const router = createBrowserRouter([
@@ -136,125 +78,28 @@ export function AppRouter() {
 }
 ```
 
-### 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")],
-};
-```
-
----
+A module is a plain object with `id`, `label`, `icon`, `basePath`, `navigation`
+and `routes`, plus optional `matchPaths`, `topNav`, `commands`,
+`contributions`, `sidePane`, `layout`, `useEffects`, `requires`, `pinBottom`
+and `hidden`. The full contract is in [modules](docs/usage/modules.md).
 
-## 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";
+The shell sizes itself from the document and the library does not set document
+styles, so the app-level layout CSS in
+[getting started](docs/usage/getting-started.md) is required -- omitting it is
+the most common setup failure.
 
-// 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
-}
-```
+## Documentation
 
----
+- [Usage guides](docs/usage/index.md) -- getting started,
+  [modules](docs/usage/modules.md), [navigation](docs/usage/navigation.md),
+  the [imperative API](docs/usage/imperative-api.md),
+  [events](docs/usage/events.md), [capabilities](docs/usage/capabilities.md)
+  and [auth](docs/usage/auth.md).
+- [Design docs](docs/design/index.md) -- the navigation layout model and
+  module capabilities.
+- [Workspace documentation](../../docs/README.md) -- how the packages layer and
+  the architecture decision records.
 
 ## License
 
-See [LICENSE.md](../../LICENSE.md).
+Apache 2.0. See [LICENSE.md](../../LICENSE.md).

package/dist/auth/index.d.ts

@@ -1,43 +1,60 @@
 import { ReactNode } from 'react';
 
 /**
- * TenantSelection -- shown after authentication when the user has
- * multiple tenants and no default is set. The user must pick a tenant
- * before the app loads.
+ * OrgSelection -- shown after authentication when the user belongs to
+ * multiple organizations and no default is set. The user selects which
+ * organization context to act in before the app loads.
+ *
+ * "Organization" is used generically: an app might map it to an org-unit,
+ * tenant, workspace, team, or company. The consumer maps its domain type to
+ * OrgOption.
  *
  * Fully props-driven with no app-specific imports.
  * Target package: @petrarca/sonnet-shell
  */
-/** Minimal tenant descriptor. Consumers map their domain type to this shape. */
-interface TenantOption {
+/** Minimal organization descriptor. Consumers map their domain type to this shape. */
+interface OrgOption {
     id: string;
     name: string;
 }
-interface TenantSelectionProps {
-    tenants: TenantOption[];
+interface OrgSelectionProps {
+    orgs: OrgOption[];
     isLoading: boolean;
     error: string | null;
     onSelect: (id: string) => void;
+    /**
+     * Rendered in place of the picker when `orgs` is empty. The library states
+     * the fact ("No organizations assigned") but cannot know why the list is
+     * empty -- pending provisioning, filtered memberships, or none at all -- so
+     * the escape (sign out, retry, contact support) is the consumer's to supply.
+     * Omitted, the message stands alone.
+     */
+    emptyAction?: React.ReactNode;
 }
-declare function TenantSelection({ tenants, isLoading, error, onSelect, }: TenantSelectionProps): React.ReactElement;
+declare function OrgSelection({ orgs, isLoading, error, onSelect, emptyAction, }: OrgSelectionProps): React.ReactElement;
 
 /**
  * Login -- multi-step authentication flow.
  *
- * Step 1: Credentials (local auth form or OIDC redirect)
- * Step 2: Tenant selection (if user has multiple tenants and no default)
+ * Steps:
+ *   identifier    -- email/username entry (when onDiscover is provided)
+ *   auth          -- resolved providers: password form first, SSO buttons below
+ *   credentials   -- single-screen login (no onDiscover)
+ *   org-selection -- organization picker after successful auth
+ *
+ * When onDiscover is NOT provided, the identifier and password sit on one
+ * screen instead of the identifier-first two-step flow.
  *
- * Steps are shown conditionally. If the user has a default tenant,
- * step 2 is skipped and the app loads immediately.
+ * All async operations are injected via props. The component knows nothing
+ * about OIDC, PKCE, or discover endpoints.
  *
- * ProtectedRoute passes a `step` hint in location.state so this
- * component always opens on the correct step when redirected.
+ * Design: a centred card on a quiet page, in the spirit of Auth0 Universal
+ * Login / WorkOS AuthKit. Every colour comes from a design token, so the screen
+ * follows the consumer's theme -- the distinct composition is deliberate, the
+ * palette is not a private one.
  *
- * All auth state and operations are injected via props -- no direct
- * store or context imports.
  * Target package: @petrarca/sonnet-shell
  */
-/** Auth feature flags and provider configuration. Consumer-supplied. */
 interface AuthConfig {
     enabled: boolean;
     features: {
@@ -55,30 +72,58 @@ interface AuthConfig {
         direct_redirect: string | null;
     };
 }
+interface LoginProvider {
+    type: "local" | "external";
+    name: string;
+    label: string;
+    /**
+     * Opaque per-provider data the app's discover step attaches and its
+     * `onExternalLogin` reads back -- e.g. an OIDC authorize URL and target id.
+     * The shell never inspects it; it only carries it through. This keeps Login
+     * domain-agnostic (it "knows nothing about OIDC, PKCE, or discover
+     * endpoints") while sparing the consumer an `as any` cast on the provider.
+     */
+    metadata?: Record<string, unknown>;
+}
 interface LoginProps {
-    /** Auth feature flags and OAuth provider config. */
     config: AuthConfig | null;
-    /** Whether the user is currently authenticated (token present). */
     isAuthenticated: boolean;
-    /** Active tenant id, null when not yet selected. */
     activeTenantId: string | null;
-    /** Whether an async operation is in flight. */
     isLoading: boolean;
-    /** Auth error message to display, null when none. */
     error: string | null;
-    /** The authenticated user's available tenants. */
-    tenants: TenantOption[] | null;
-    /** Perform credential login. Throws on failure. */
+    orgs: OrgOption[] | null;
     onLogin: (credentials: {
         identifier: string;
         password: string;
     }) => Promise<void>;
-    /** Fetch the current user after login to resolve tenant state. */
     onFetchCurrentUser: () => Promise<void>;
-    /** Switch to the given tenant. Throws on failure. */
-    onSwitchTenant: (id: string) => Promise<void>;
-    /** Clear the current auth error. */
+    onSelectOrg: (id: string) => Promise<void>;
     onClearError: () => void;
+    /** Application name shown above the card as a brand label. */
+    appName?: string;
+    /** Logo URL shown above the card. If provided, appName is used as alt text. */
+    logoUrl?: string;
+    /** Enables identifier-first flow. App calls discover endpoint and returns providers. */
+    onDiscover?: (identifier: string) => Promise<LoginProvider[]>;
+    /** Called when user clicks an external provider button. App handles PKCE + redirect. */
+    onExternalLogin?: (provider: LoginProvider) => Promise<void> | void;
+    /** Whether discovery is in flight. */
+    isDiscovering?: boolean;
+    /**
+     * Rendered on the organization step when the user has no organizations to
+     * select. The library cannot know why the list is empty, so the escape --
+     * sign out, retry, contact support -- is the consumer's to supply.
+     * See `OrgSelection`'s `emptyAction`.
+     */
+    orgEmptyAction?: React.ReactNode;
+    /**
+     * Whether the user must select an organization after authenticating. Default
+     * true. Set false for apps with no organization/tenant concept: the org step
+     * is never entered, a stale org-selection step from location state is
+     * ignored, and an authenticated user proceeds into the app even when
+     * `activeTenantId` is null. Pair with `ProtectedRoute`'s matching prop.
+     */
+    requiresOrgSelection?: boolean;
 }
 declare function Login(props: LoginProps): React.ReactElement | null;
 
@@ -92,7 +137,10 @@ declare function Login(props: LoginProps): React.ReactElement | null;
  * Once initialization is complete, guards based on:
  *   - Auth disabled (`authEnabled` false): allow all access
  *   - Not authenticated: redirect to /login with step=credentials
- *   - Authenticated but no tenant: redirect to /login with step=tenant-selection
+ *   - Authenticated but no tenant: redirect to /login with step=org-selection
+ *
+ * Apps with no organization/tenant concept set `requiresOrgSelection={false}`;
+ * an authenticated user is then let through and `activeTenantId` is ignored.
  *
  * All auth state is injected via props -- no direct store or context imports.
  * Target package: @petrarca/sonnet-shell
@@ -111,7 +159,13 @@ interface ProtectedRouteProps {
     activeTenantId: string | null;
     /** Called once on mount to restore and validate a persisted session. */
     initializeAuth: () => Promise<void>;
+    /**
+     * Whether an organization must be selected before entering the app. Default
+     * true. Set false for apps with no organization/tenant concept: an
+     * authenticated user is admitted and `activeTenantId` is not consulted.
+     */
+    requiresOrgSelection?: boolean;
 }
-declare function ProtectedRoute({ children, authEnabled, authConfigLoading, isAuthenticated, accessToken, activeTenantId, initializeAuth, }: ProtectedRouteProps): React.ReactElement;
+declare function ProtectedRoute({ children, authEnabled, authConfigLoading, isAuthenticated, accessToken, activeTenantId, initializeAuth, requiresOrgSelection, }: ProtectedRouteProps): React.ReactElement;
 
-export { type AuthConfig, Login, type LoginProps, ProtectedRoute, type ProtectedRouteProps, type TenantOption, TenantSelection };
+export { type AuthConfig, Login, type LoginProps, type LoginProvider, type OrgOption, OrgSelection, ProtectedRoute, type ProtectedRouteProps };