@petrarca/sonnet-shell 0.7.0 → 0.9.0

package/README.md

@@ -7,7 +7,8 @@ command menu and a set of surfaces any module can reach imperatively.
 ## What it provides
 
 **A module system.** A `ShellModule` declares its routes, navigation, command
-menu entries, side pane and contributions to other modules.
+menu entries, side pane and contributions to other modules -- links, routed
+pages, and components another module renders with its own props.
 `createModuleRegistry` aggregates them and derives the navigation zones and the
 flattened route list once.
 

package/dist/auth/index.d.ts

@@ -168,4 +168,5 @@ interface ProtectedRouteProps {
 }
 declare function ProtectedRoute({ children, authEnabled, authConfigLoading, isAuthenticated, accessToken, activeTenantId, initializeAuth, requiresOrgSelection, }: ProtectedRouteProps): React.ReactElement;
 
-export { type AuthConfig, Login, type LoginProps, type LoginProvider, type OrgOption, OrgSelection, ProtectedRoute, type ProtectedRouteProps };
+export { Login, OrgSelection, ProtectedRoute };
+export type { AuthConfig, LoginProps, LoginProvider, OrgOption, ProtectedRouteProps };

package/dist/index.d.ts

@@ -1,6 +1,5 @@
-import * as react_jsx_runtime from 'react/jsx-runtime';
 import * as React from 'react';
-import React__default, { ReactNode } from 'react';
+import React__default, { ReactNode, ComponentType } from 'react';
 import { RouteObject } from 'react-router-dom';
 import { LucideIcon } from 'lucide-react';
 
@@ -98,12 +97,38 @@ interface Contribution {
     extensionPoint: string;
     /** Display label for the contributed item */
     label: string;
-    /** Route path (can include params like :orgId) */
+    /**
+     * Route path (can include params like :orgId, filled by the host with
+     * `contributionPath`). For a contribution with an `element`, the path of its
+     * child route, relative to the host route.
+     */
     path: string;
     /** Sort order within the extension point (lower = earlier) */
     order: number;
     /** Optional icon */
     icon?: LucideIcon;
+    /**
+     * Optional one-line description, for hosts that show their contributions as
+     * cards or with an explanation (an overview page, say). Links ignore it.
+     */
+    description?: string;
+    /**
+     * A page this module contributes into another module's page -- a tab, say.
+     * It becomes a child route at `path` under the route whose `id` is this
+     * contribution's `extensionPoint`, so it renders in that route's `<Outlet>`
+     * and reads what the host passes through the outlet context. Without it the
+     * contribution is a link only.
+     */
+    element?: React__default.ReactNode;
+    /**
+     * A component this module offers another module to render where it wants --
+     * in a pane, a side panel, a dialog -- with the props the extension point
+     * defines (callbacks included). Not routed: the host reads it with
+     * `useContributedComponent` and renders it; `path` names it among the
+     * extension point's contributions. The props type is the contract between
+     * the two modules -- define it somewhere both can import.
+     */
+    component?: React__default.ComponentType<never>;
 }
 /**
  * Map of known shell event keys to their payload types.
@@ -161,6 +186,13 @@ interface ShellModule {
     topNav?: NavLink[];
     /** Navigation groups for the sub-nav panel and sidebar grouped sections */
     navigation: NavGroup[];
+    /**
+     * Navigation known only at runtime (e.g. one link per item a server lists),
+     * appended after `navigation`. A React hook: it may use queries, and must
+     * return a stable array between renders when nothing changed. Other modules
+     * plug links in through the `<moduleId>.nav` extension point instead.
+     */
+    useNavigation?: () => NavGroup[];
     /** React Router route definitions owned by this module */
     routes: RouteObject[];
     /** Pin to bottom of icon rail (e.g. Settings, Playground) */
@@ -279,7 +311,11 @@ interface ModuleRegistry {
     mainModules: ShellModule[];
     /** Modules pinned to the bottom of the icon rail. */
     bottomModules: ShellModule[];
-    /** All routes from all modules, flattened. */
+    /**
+     * All routes from all modules, flattened -- with each contribution that
+     * carries an `element` nested as a child of the route whose `id` is its
+     * extension point.
+     */
     allRoutes: RouteObject[];
     /** Get contributions for a named extension point, sorted by order. */
     getExtensionPoint: (name: string) => Contribution[];
@@ -296,7 +332,7 @@ interface AppShellProps {
      */
     sidebar?: React__default.ReactNode;
 }
-declare function AppShell({ registry, sidebar }: AppShellProps): react_jsx_runtime.JSX.Element;
+declare function AppShell({ registry, sidebar }: AppShellProps): React__default.JSX.Element;
 
 interface ShellConfig {
     /**
@@ -347,7 +383,7 @@ interface RootLayoutProps {
     /** Optional custom sidebar replacing the default IconRail + SubNavPanel. */
     sidebar?: React__default.ReactNode;
 }
-declare function RootLayout({ config, registry, sidebar, }: RootLayoutProps): react_jsx_runtime.JSX.Element;
+declare function RootLayout({ config, registry, sidebar, }: RootLayoutProps): React__default.JSX.Element;
 
 /**
  * TopBar -- persistent header across the entire application.
@@ -359,7 +395,7 @@ declare function RootLayout({ config, registry, sidebar, }: RootLayoutProps): re
 interface TopBarProps {
     children?: ReactNode;
 }
-declare function TopBar({ children }: TopBarProps): react_jsx_runtime.JSX.Element;
+declare function TopBar({ children }: TopBarProps): React.JSX.Element;
 
 /**
  * IconRail primitives — composable building blocks for the narrow
@@ -398,14 +434,14 @@ interface SubNavPanelProps {
     collapsed: boolean;
     onToggleCollapse: () => void;
 }
-declare function SubNavPanel({ service, collapsed, onToggleCollapse, }: SubNavPanelProps): react_jsx_runtime.JSX.Element;
+declare function SubNavPanel(props: SubNavPanelProps): React.JSX.Element;
 
 /**
  * SidePane renders nothing when no pane is open.
  * When open it renders a bordered panel with a drag handle on its right edge.
  * Double-clicking the handle resets to defaultWidth.
  */
-declare function SidePane(): react_jsx_runtime.JSX.Element | null;
+declare function SidePane(): React.JSX.Element | null;
 
 interface CommandMenuProps {
     open: boolean;
@@ -417,13 +453,68 @@ interface CommandMenuProps {
  * Indexes all navigation items from the service domains so users can
  * quickly jump to any page by typing.
  */
-declare function CommandMenu({ open, onOpenChange }: CommandMenuProps): react_jsx_runtime.JSX.Element;
+declare function CommandMenu({ open, onOpenChange }: CommandMenuProps): React__default.JSX.Element;
 
 /**
  * PlaceholderPage — generic wireframe page for routes not yet implemented.
  * Shows the current path and a placeholder content area.
  */
-declare function PlaceholderPage(): react_jsx_runtime.JSX.Element;
+declare function PlaceholderPage(): React.JSX.Element;
+
+/**
+ * Breadcrumbs -- where a drill-down page sits: module root, then the page's own steps.
+ *
+ * A page states its drill-down trail (`items`); the shell prepends the active
+ * module (its label, linking to its base path), so a page lists only what it
+ * drilled into: `Sources > my-source > Origins` is `items` of two plus the
+ * module root. Every crumb but the last links back; the last is the current
+ * page. Long labels truncate with the full text as a tooltip, and a deep trail
+ * collapses its middle into an ellipsis.
+ */
+
+/** One step of a trail: a label, and where it leads (omit for the current page). */
+interface BreadcrumbItem {
+    label: React__default.ReactNode;
+    to?: string;
+}
+interface BreadcrumbsProps {
+    /** The page's drill-down steps, after the module root; the last is the current page. */
+    items: BreadcrumbItem[];
+    /** Leave out the module root (a page outside any module, or one that states it itself). */
+    omitModule?: boolean;
+    /** Collapse the middle of a longer trail into an ellipsis (first and last two stay). */
+    maxItems?: number;
+    className?: string;
+}
+/** The trail of a drill-down page, module root first. */
+declare function Breadcrumbs({ items, omitModule, maxItems, className, }: BreadcrumbsProps): React__default.ReactElement;
+
+/**
+ * DrillDownHeader -- the header of a drill-down page: trail, title, actions.
+ *
+ * A detail or drill-down page (an entity, then a facet of it, then a step
+ * within that) starts with where it sits (Breadcrumbs), its title -- with an
+ * optional adornment beside it, such as a status badge or a copyable id -- the
+ * actions that apply to it, and a short subtitle. The actions slot is where
+ * operations on the page's subject live as they are added; deeper views are
+ * reached by actions here, each with a trail of its own.
+ */
+
+interface DrillDownHeaderProps {
+    /** The page's drill-down steps after the module root; the last is this page. */
+    breadcrumbs: BreadcrumbItem[];
+    /** The page title. */
+    title: React__default.ReactNode;
+    /** Shown beside the title: a status badge, a copyable id. */
+    adornment?: React__default.ReactNode;
+    /** Operations on the page's subject, right-aligned with the title. */
+    actions?: React__default.ReactNode;
+    /** A short line under the title: kind, dates. */
+    subtitle?: React__default.ReactNode;
+    className?: string;
+}
+/** Trail, title row (title, adornment, actions), subtitle. */
+declare function DrillDownHeader({ breadcrumbs, title, adornment, actions, subtitle, className, }: DrillDownHeaderProps): React__default.ReactElement;
 
 /**
  * Confirm Dialog
@@ -453,6 +544,11 @@ interface ConfirmDialogProps {
      * "destructive" for irreversible actions (delete, revoke, etc.)
      */
     variant?: "default" | "destructive";
+    /**
+     * A text the user must type to confirm (the item's name, for a delete that
+     * cascades); Confirm stays disabled until it matches exactly.
+     */
+    confirmText?: string;
     /** Callback when user confirms */
     onConfirm: () => void;
     /** Callback when user cancels or closes dialog */
@@ -463,7 +559,7 @@ interface ConfirmDialogProps {
  *
  * A reusable confirmation dialog backed by shadcn Dialog primitives.
  */
-declare function ConfirmDialog({ open, title, description, confirmLabel, cancelLabel, variant, onConfirm, onCancel, }: ConfirmDialogProps): React__default.ReactElement;
+declare function ConfirmDialog({ open, title, description, confirmLabel, cancelLabel, variant, confirmText, onConfirm, onCancel, }: ConfirmDialogProps): React__default.ReactElement;
 
 /**
  * Sidebar — single-column navigation layout.
@@ -547,7 +643,7 @@ declare function ShellSidebar({ bottomGroupLabel, ...sidebarProps }: ShellSideba
 interface ShellFooterProps {
     children?: ReactNode;
 }
-declare function ShellFooter({ children }: ShellFooterProps): react_jsx_runtime.JSX.Element;
+declare function ShellFooter({ children }: ShellFooterProps): React.JSX.Element;
 
 /**
  * ShellVersion — displays the app name and optional version in the footer.
@@ -568,7 +664,7 @@ interface ShellConfigProviderProps {
     config: ShellConfig;
     children: ReactNode;
 }
-declare function ShellConfigProvider({ config, children, }: ShellConfigProviderProps): react_jsx_runtime.JSX.Element;
+declare function ShellConfigProvider({ config, children, }: ShellConfigProviderProps): React.JSX.Element;
 
 /**
  * SearchTrigger -- Cmd+K search button for the TopBar.
@@ -576,7 +672,16 @@ declare function ShellConfigProvider({ config, children, }: ShellConfigProviderP
  * Opens the shell CommandMenu via the imperative navigation API.
  * Generic building block, no app-specific dependencies.
  */
-declare function SearchTrigger(): react_jsx_runtime.JSX.Element;
+declare function SearchTrigger(): React.JSX.Element;
+
+/**
+ * ThemeToggle -- switches between the light and the dark theme, for the
+ * TopBar. The choice is remembered (sonnet-core's useTheme); call initTheme()
+ * before the app renders so a visit starts in it.
+ *
+ * Generic building block, no app-specific dependencies.
+ */
+declare function ThemeToggle(): React.JSX.Element;
 
 /**
  * UserMenu -- avatar dropdown for the TopBar.
@@ -594,7 +699,7 @@ interface UserMenuProps {
     user: UserMenuUser;
     onSignOut?: () => void;
 }
-declare function UserMenu({ user, onSignOut }: UserMenuProps): react_jsx_runtime.JSX.Element;
+declare function UserMenu({ user, onSignOut }: UserMenuProps): React.JSX.Element;
 
 /**
  * Default (kind, surface) → effect matrix. App overrides are merged over this.
@@ -637,11 +742,23 @@ interface PromiseOptions<T> {
     success: string | ((data: T) => string);
     error: string | ((err: unknown) => string);
 }
+/** A step a toast offers -- "Undo", "Open it" --; the toast closes when it is taken. */
+interface NotificationAction {
+    label: string;
+    onClick: () => void;
+}
+/** What a toast may carry beside its message. */
+interface NotificationOptions {
+    /** A second line under the message. */
+    description?: string;
+    /** A button on the toast, for the step that follows from it. */
+    action?: NotificationAction;
+}
 declare const notification: {
-    success(message: string): void;
-    error(message: string): void;
-    warning(message: string): void;
-    info(message: string): void;
+    success(message: string, options?: NotificationOptions): void;
+    error(message: string, options?: NotificationOptions): void;
+    warning(message: string, options?: NotificationOptions): void;
+    info(message: string, options?: NotificationOptions): void;
     promise<T>(promise: Promise<T>, opts: PromiseOptions<T>): (string & {
         unwrap: () => Promise<T>;
     }) | (number & {
@@ -657,6 +774,11 @@ interface ConfirmOptions {
     confirmLabel?: string;
     cancelLabel?: string;
     variant?: "default" | "destructive";
+    /**
+     * A text the user must type to confirm -- the item's name, for a delete that
+     * cascades. Confirm stays disabled until it matches exactly.
+     */
+    confirmText?: string;
 }
 type DialogConfirmFn = (opts: ConfirmOptions) => Promise<boolean>;
 /**
@@ -836,9 +958,45 @@ interface ShellNavigationState {
     subNavCollapsed: boolean;
     onToggleSubNav: () => void;
     onServiceSelect: (id: string) => void;
+    /**
+     * Ask for the sub-navigation to collapse until the returned release is
+     * called. Optional so custom providers need not implement it; pages use
+     * useCollapsedSubNav rather than calling it.
+     */
+    requestSubNavCollapse?: () => () => void;
 }
 /** Read shell navigation state. Must be used within AppShell. */
 declare function useShellNavigation(): ShellNavigationState;
+/**
+ * Collapse the sub-navigation while the calling page is shown, so the content
+ * area gets its full width (a canvas, an editor). On unmount the panel returns
+ * to the user's own setting; the user can still expand it meanwhile. Outside
+ * AppShell, or with `active` false, it does nothing.
+ *
+ * @example
+ * ```tsx
+ * function GraphWorkspacePage() {
+ *   useCollapsedSubNav();
+ *   return <Canvas />;
+ * }
+ * ```
+ */
+declare function useCollapsedSubNav(active?: boolean): void;
+
+/**
+ * A contribution's path with its `:params` filled in by the host.
+ *
+ * A contribution names what it needs from the place it is shown in --
+ * `/files?scope=:name`, `/orgs/:orgId/report` -- and the host that renders the
+ * extension point supplies the values. Each `:param` is replaced wherever it
+ * stands, the query included, its value URL-encoded; a param the host does not
+ * supply is left as written.
+ *
+ * @example
+ * contributionPath("/files?scope=:name", { name: "billing api" })
+ * // "/files?scope=billing%20api"
+ */
+declare function contributionPath(path: string, params: Record<string, string>): string;
 
 /**
  * OverviewCard and FeatureLink -- building blocks for module overview pages.
@@ -849,6 +1007,9 @@ declare function useShellNavigation(): ShellNavigationState;
  * FeatureLink is an inline text link for use in descriptions or prose,
  * also navigating via stable feature id.
  *
+ * OverviewGroupHeading heads a group of cards, with one line saying what the
+ * group is.
+ *
  * Part of the shell -- extracts to @petrarca/sonnet-shell.
  */
 
@@ -867,6 +1028,11 @@ interface OverviewCardProps {
      * Omit for non-navigable cards.
      */
     feature?: string;
+    /**
+     * A path to navigate to instead -- for a card whose target is known only at
+     * runtime (no stable feature id). `feature` wins when both are given.
+     */
+    path?: string;
     /** Additional CSS class names. */
     className?: string;
 }
@@ -884,7 +1050,29 @@ declare function FeatureLink({ feature, children, }: {
     children: React__default.ReactNode;
 }): React__default.ReactElement;
 /** Feature card for module overview pages. Navigates via the shell API. */
-declare function OverviewCard({ icon: Icon, title, description, feature, className, }: OverviewCardProps): React__default.ReactElement;
+declare function OverviewCard({ icon: Icon, title, description, feature, path, className, }: OverviewCardProps): React__default.ReactElement;
+/**
+ * OverviewGroupHeading -- a group's heading on an overview page, and the one
+ * line saying what the group is. "Capabilities" -- the cards of an area
+ * without groups -- needs no line.
+ *
+ * Its size (`text-sm font-semibold`) is not a heading role: an overview is a
+ * dense list of cards, and a section-sized heading would outweigh them.
+ *
+ * @example
+ *   <OverviewGroupHeading heading="Capabilities" />
+ *   <OverviewGroupHeading heading="Runtime" description="What this server runs." />
+ */
+declare function OverviewGroupHeading({ heading, description, }: {
+    heading: string;
+    description?: string;
+}): React__default.ReactElement;
+
+/**
+ * Shell hooks -- reactive APIs for modules.
+ *
+ * Import path: @/shell/hooks
+ */
 
 /**
  * Get sorted contributions for a named extension point.
@@ -898,6 +1086,30 @@ declare function OverviewCard({ icon: Icon, title, description, feature, classNa
  * ```
  */
 declare function useExtensionPoint(name: string): Contribution[];
+/**
+ * The component a module contributes to an extension point under `path`, typed
+ * with the props the extension point defines -- or undefined when no module
+ * contributes one. The host renders it where it wants, with those props.
+ *
+ * @example
+ * ```tsx
+ * const FlowSelector = useContributedComponent<SelectorProps>("selectors", "flows");
+ * return FlowSelector ? <FlowSelector onPick={assign} /> : null;
+ * ```
+ */
+declare function useContributedComponent<P>(extensionPoint: string, path: string): ComponentType<P> | undefined;
+/**
+ * A module's complete navigation, as every surface shows it: its static
+ * `navigation`, then the groups its `useNavigation` hook supplies at runtime
+ * (e.g. loaded from a server), then the links other modules contribute to its
+ * `<moduleId>.nav` extension point (sorted by `order`).
+ *
+ * Call it once per rendered module -- the module's `useNavigation` is a hook,
+ * and modules' hooks differ. A component calling it must therefore render one
+ * module for its whole life: key it by the module's id, so a switch to another
+ * module mounts a new instance instead of changing the hooks of a mounted one.
+ */
+declare function useModuleNavigation(module: ShellModule): NavGroup[];
 /**
  * Get the list of visible service modules (excludes hidden and bottom-pinned).
  *
@@ -919,4 +1131,5 @@ declare function useMainModules(): ShellModule[];
  */
 declare function useShellEvent<K extends keyof ShellEventMap>(key: K, handler: (payload: ShellEventMap[K]) => void): void;
 
-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 };
+export { AppShell, Breadcrumbs, CommandMenu, ConfirmDialog, DEFAULT_CAPABILITY_POLICY, DrillDownHeader, FeatureLink, IconRail, OverviewCard, OverviewGroupHeading, PlaceholderPage, RailIcon, RailSeparator, RootLayout, SearchTrigger, ShellConfigProvider, ShellFooter, ShellRail, ShellSidebar, ShellVersion, SidePane, SidePaneContext, Sidebar, SidebarGroup, SidebarItem, SubNavPanel, ThemeToggle, TopBar, UserMenu, contributionPath, createModuleRegistry, dialog, evaluateModule, events, fullscreen, initDialog, initFeatureNav, initFullscreen, initNavigation, initPanel, initSidePane, navigation, notification, panel, resolveCapabilityPolicy, sidePane, useCollapsedSubNav, useContributedComponent, useExtensionPoint, useMainModules, useModuleNavigation, useShellConfig, useShellEvent, useShellModules, useShellNavigation, useSidePaneState };
+export type { BreadcrumbItem, BreadcrumbsProps, CapabilityPolicy, CapabilityResolver, CapabilityResult, ConfirmDialogProps, ConfirmOptions, Contribution, DrillDownHeaderProps, Effect, FullscreenOptions, IconRailProps, ModuleCommand, ModuleEffect, ModuleRegistry, NavGroup, NavLink, NotificationAction, NotificationOptions, PanelOptions, RailIconProps, ShellConfig, ShellEventMap, ShellFooterProps, ShellModule, ShellNavigationState, ShellSidebarProps, ShellVersionProps, SidePaneOptions as SidePaneApiOptions, SidePaneOptions, SidePaneState, SidebarGroupProps, SidebarItemProps, SidebarProps, SubNavPanelProps, Surface, UnmetKind, UserMenuUser };