@petrarca/sonnet-shell 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,597 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { RouteObject } from 'react-router-dom';
+import { LucideIcon } from 'lucide-react';
+import * as React from 'react';
+import React__default, { ReactNode } from 'react';
+
+interface SidePaneOptions {
+    /** Content to render inside the side pane. */
+    content: ReactNode;
+    /**
+     * Stable key identifying which module/tool owns this pane instance.
+     * Used by IconRail to highlight the active pane module and by toggle()
+     * to detect whether the same content is already open.
+     */
+    moduleId: string;
+    /** Initial width in pixels. Defaults to 320. */
+    defaultWidth?: number;
+    /** Minimum draggable width in pixels. Defaults to 240. */
+    minWidth?: number;
+    /**
+     * Maximum draggable width in pixels.
+     * Omit or pass Infinity for unlimited (fills remaining space up to viewport).
+     */
+    maxWidth?: number;
+}
+interface SidePaneState {
+    /** Currently open pane options, or null when closed. */
+    pane: SidePaneOptions | null;
+    open: (opts: SidePaneOptions) => void;
+    close: () => void;
+    toggle: (opts: SidePaneOptions) => void;
+}
+declare const SidePaneContext: React.Context<SidePaneState | null>;
+/**
+ * Read the side pane state from context.
+ * Must be called within an AppShell (which provides the context).
+ */
+declare function useSidePaneState(): SidePaneState;
+
+/**
+ * Shell type definitions.
+ *
+ * These types define the contract between the shell and modules.
+ * Modules implement ServiceModule; the shell consumes it.
+ */
+
+interface NavLink {
+    /**
+     * Stable feature identifier in the form "<module>.<feature>".
+     * Used by navigation.goToFeature() for path-independent navigation.
+     * Example: "auditing.audit-events"
+     */
+    id?: string;
+    label: string;
+    path: string;
+}
+interface NavGroup {
+    /** Stable identifier used as React key. Defaults to heading if omitted. */
+    id: string;
+    heading?: string;
+    links: NavLink[];
+}
+/**
+ * An action contributed by a module to the CommandMenu.
+ *
+ * Modules declare commands in ServiceModule.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.
+ */
+interface ModuleCommand {
+    /** Stable identifier — used as React key. */
+    id: string;
+    /** Label shown in the CommandMenu item. */
+    label: string;
+    /** Optional sub-group heading shown above this command's group. */
+    group?: string;
+    /** Optional icon shown beside the label. */
+    icon?: LucideIcon;
+    /** Called when the user selects this command. */
+    action: () => void;
+}
+interface Contribution {
+    /** Target extension point name (e.g. "organization-detail") */
+    extensionPoint: string;
+    /** Display label for the contributed item */
+    label: string;
+    /** Route path (can include params like :orgId) */
+    path: string;
+    /** Sort order within the extension point (lower = earlier) */
+    order: number;
+    /** Optional icon */
+    icon?: LucideIcon;
+}
+/**
+ * Map of known shell event keys to their payload types.
+ *
+ * Modules augment this interface via TypeScript declaration merging to
+ * register their events. The bus API constrains generics to
+ * `keyof ShellEventMap`, giving autocomplete and payload type-checking
+ * across emit/subscribe boundaries.
+ *
+ * The string index signature allows ad-hoc events that are not yet in
+ * the map -- they fall back to `unknown`, nudging developers to register.
+ *
+ * Example (in a module's events.ts):
+ *
+ *   declare module "@/shell/types" {
+ *     interface ShellEventMap {
+ *       "my-domain:something-happened": { id: string };
+ *     }
+ *   }
+ */
+interface ShellEventMap {
+    [custom: string]: unknown;
+}
+interface ServiceModule {
+    /** Unique identifier for this module */
+    id: string;
+    /** Display name (icon rail tooltip, sub-nav header, command menu) */
+    label: string;
+    /** Short description of this module's domain */
+    description?: string;
+    /** Lucide icon for the icon rail */
+    icon: LucideIcon;
+    /** URL prefix used to match this module to the current route */
+    basePath: string;
+    /** Navigation groups for the sub-nav panel */
+    navigation: NavGroup[];
+    /** React Router route definitions owned by this module */
+    routes: RouteObject[];
+    /** Pin to bottom of icon rail (e.g. Settings, Playground) */
+    pinBottom?: boolean;
+    /** Hide from icon rail and command menu (e.g. Home) */
+    hidden?: boolean;
+    /** Items this module contributes to other modules' extension points */
+    contributions?: Contribution[];
+    /**
+     * Actions this module contributes to the CommandMenu (Cmd+K).
+     *
+     * Rendered as a separate CommandGroup below navigation links so users
+     * can trigger module actions without navigating to a route first.
+     * Typical uses: open the side pane, start a workflow, focus a search field.
+     */
+    commands?: ModuleCommand[];
+    /**
+     * Side pane sizing constraints for modules that render a persistent inline
+     * panel via sidePane.open(). Declared here so the module definition is
+     * self-documenting; passed through to sidePane.open() at call time.
+     *
+     * When a module has no SubNavPanel links (navigation: []) and declares
+     * sidePane, the shell treats icon-rail clicks as toggle actions on the
+     * pane rather than route navigations.
+     */
+    sidePane?: Pick<SidePaneOptions, "defaultWidth" | "minWidth" | "maxWidth">;
+}
+
+/**
+ * Module registry factory.
+ *
+ * Accepts a list of ServiceModules 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).
+ */
+
+interface ModuleRegistry {
+    /** All modules in registration order. */
+    modules: ServiceModule[];
+    /** Visible modules shown in the main area of the icon rail. */
+    mainModules: ServiceModule[];
+    /** Modules pinned to the bottom of the icon rail. */
+    bottomModules: ServiceModule[];
+    /** 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;
+
+interface AppShellProps {
+    registry: ModuleRegistry;
+}
+declare function AppShell({ registry }: AppShellProps): react_jsx_runtime.JSX.Element;
+
+interface ShellConfig {
+    /**
+     * Content rendered inside the TopBar header. The shell provides the
+     * `<header>` element with its sizing and border; the consumer owns
+     * everything inside it.
+     *
+     * Compose this using building blocks like `SearchTrigger` and
+     * `UserMenu` (exported from the shell) alongside any app-specific
+     * components.
+     */
+    topBar?: ReactNode;
+}
+/**
+ * Read the shell configuration from context.
+ * Must be called within a ShellConfigProvider.
+ */
+declare function useShellConfig(): ShellConfig;
+
+/**
+ * RootLayout -- top-level layout that wraps the entire authenticated app.
+ * Renders the Toaster for notifications and the AppShell (icon rail + sub-nav + content).
+ */
+interface RootLayoutProps {
+    config: ShellConfig;
+    registry: ModuleRegistry;
+}
+declare function RootLayout({ config, registry }: RootLayoutProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * TopBar -- persistent header across the entire application.
+ *
+ * A pure layout container. The shell provides the `<header>` element with
+ * its sizing, background, and border. The consumer owns all content via
+ * the `children` prop (composed through `ShellConfig.topBar`).
+ */
+interface TopBarProps {
+    children?: ReactNode;
+}
+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.
+ *
+ * Main services scroll in the center, settings/playground pinned at bottom.
+ * Tooltips show service labels on hover.
+ */
+declare function IconRail({ activeServiceId, activeSidePaneModuleId, onServiceSelect, }: IconRailProps): react_jsx_runtime.JSX.Element;
+
+interface SubNavPanelProps {
+    service: ServiceModule;
+    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;
+
+/**
+ * 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;
+
+interface CommandMenuProps {
+    open: boolean;
+    onOpenChange: (open: boolean) => void;
+}
+/**
+ * CommandMenu -- Cmd+K command menu.
+ *
+ * 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;
+
+/**
+ * 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;
+
+/**
+ * Confirm Dialog
+ *
+ * Reusable confirmation dialog for actions that require user confirmation.
+ * Used for discard changes, delete actions, etc.
+ *
+ * Wired into the shell via `initDialog` in `shell/api.ts` so modules can
+ * trigger it imperatively with `dialog.confirm(opts)`.
+ *
+ * @module components/Common/ConfirmDialog
+ */
+
+interface ConfirmDialogProps {
+    /** Whether the dialog is open */
+    open: boolean;
+    /** Dialog title */
+    title: string;
+    /** Description shown below the title */
+    description?: string;
+    /** Confirm button label (default: "Confirm") */
+    confirmLabel?: string;
+    /** Cancel button label (default: "Cancel") */
+    cancelLabel?: string;
+    /**
+     * Controls confirm button appearance.
+     * "destructive" for irreversible actions (delete, revoke, etc.)
+     */
+    variant?: "default" | "destructive";
+    /** Callback when user confirms */
+    onConfirm: () => void;
+    /** Callback when user cancels or closes dialog */
+    onCancel: () => void;
+}
+/**
+ * ConfirmDialog Component
+ *
+ * A reusable confirmation dialog backed by shadcn Dialog primitives.
+ */
+declare function ConfirmDialog({ open, title, description, confirmLabel, cancelLabel, variant, onConfirm, onCancel, }: ConfirmDialogProps): React__default.ReactElement;
+
+interface ShellConfigProviderProps {
+    config: ShellConfig;
+    children: ReactNode;
+}
+declare function ShellConfigProvider({ config, children, }: ShellConfigProviderProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * SearchTrigger -- Cmd+K search button for the TopBar.
+ *
+ * Opens the shell CommandMenu via the imperative navigation API.
+ * Generic building block, no app-specific dependencies.
+ */
+declare function SearchTrigger(): react_jsx_runtime.JSX.Element;
+
+/**
+ * UserMenu -- avatar dropdown for the TopBar.
+ *
+ * Shows the user's initials in an avatar. The dropdown displays name,
+ * email, a profile link, and a sign-out action. Generic building block,
+ * no app-specific dependencies.
+ */
+interface UserMenuUser {
+    name: string;
+    email: string;
+    initials: string;
+}
+interface UserMenuProps {
+    user: UserMenuUser;
+    onSignOut?: () => void;
+}
+declare function UserMenu({ user, onSignOut }: UserMenuProps): react_jsx_runtime.JSX.Element;
+
+/**
+ * Shell API -- imperative domain capabilities for modules.
+ *
+ * Import path: @/shell/api
+ *
+ * Grouped by domain: notification, dialog, navigation, panel, events.
+ */
+
+interface PromiseOptions<T> {
+    loading: string;
+    success: string | ((data: T) => string);
+    error: string | ((err: unknown) => string);
+}
+declare const notification: {
+    success(message: string): void;
+    error(message: string): void;
+    warning(message: string): void;
+    info(message: string): void;
+    promise<T>(promise: Promise<T>, opts: PromiseOptions<T>): (string & {
+        unwrap: () => Promise<T>;
+    }) | (number & {
+        unwrap: () => Promise<T>;
+    }) | {
+        unwrap: () => Promise<T>;
+    };
+    dismiss(id?: string | number): void;
+};
+interface ConfirmOptions {
+    title: string;
+    description?: string;
+    confirmLabel?: string;
+    cancelLabel?: string;
+    variant?: "default" | "destructive";
+}
+type DialogConfirmFn = (opts: ConfirmOptions) => Promise<boolean>;
+/**
+ * Called by the shell during initialization to inject the confirm dialog.
+ * Not part of the public module API -- only the shell calls this.
+ */
+declare function initDialog(confirmFn: DialogConfirmFn): void;
+declare const dialog: {
+    /**
+     * Show a confirmation dialog. Returns true if confirmed, false if cancelled.
+     */
+    confirm(opts: ConfirmOptions): Promise<boolean>;
+};
+type NavigateFn = (path: string) => void;
+type CommandMenuFn = () => void;
+/**
+ * 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;
+declare const navigation: {
+    /** Navigate to a path within the shell. */
+    goTo(path: string): void;
+    /**
+     * Navigate to a feature by its stable identifier (e.g. "auditing.audit-events").
+     * The path is resolved from the module registry at call time, so it stays
+     * correct even if routes are reorganised.
+     */
+    goToFeature(featureId: string): void;
+    /** Open the Cmd+K command menu. */
+    openCommandMenu(): void;
+    /** Go back in browser history. */
+    back(): void;
+};
+interface PanelOptions {
+    /**
+     * Title shown in the panel header. When omitted the header is visually
+     * hidden (the content owns its own header) but a screen-reader-only
+     * title is still rendered for accessibility.
+     */
+    title?: string;
+    /** React content to render inside the panel */
+    content: ReactNode;
+    /** Optional description below the title */
+    description?: string;
+    /**
+     * Panel width token.
+     *
+     * - "narrow"  -- 480px  -- quick actions, simple single-field forms
+     * - "default" -- 640px  -- standard entity forms (default when omitted)
+     * - "wide"    -- 800px  -- forms with embedded tables or complex layouts
+     * - "half"    -- 50vw   -- split-screen inspection, side-by-side context
+     * - "full"    -- 100vw  -- immersive editing, full-width canvases
+     *
+     * Legacy values "lg", "1/3", "1/2" are kept for backward compatibility
+     * and map to "default" (640px), 33vw, and "half" (50vw) respectively.
+     */
+    width?: "narrow" | "default" | "wide" | "half" | "full" | "lg" | "1/3" | "1/2";
+    /**
+     * Vertical coverage of the panel.
+     * - "below-header" (default): panel starts below the TopBar, keeping it visible.
+     * - "full": panel covers the full viewport height including the TopBar.
+     */
+    coverage?: "below-header" | "full";
+    /** Called after the panel finishes closing. Use to restore focus to the triggering element. */
+    onClose?: () => void;
+}
+type PanelOpenFn = (opts: PanelOptions) => void;
+type PanelCloseFn = () => void;
+/**
+ * Called by the shell during initialization to inject panel controls.
+ * Not part of the public module API -- only the shell calls this.
+ */
+declare function initPanel(openFn: PanelOpenFn, closeFn: PanelCloseFn): void;
+declare const panel: {
+    /** Open the shell panel with content rendered inside. */
+    open(opts: PanelOptions): void;
+    /** Close the panel. */
+    close(): void;
+};
+
+type SidePaneOpenFn = (opts: SidePaneOptions) => void;
+type SidePaneCloseFn = () => void;
+type SidePaneIsOpenFn = () => boolean;
+type SidePaneActiveModuleIdFn = () => string | null;
+/**
+ * Called by the shell during initialization to inject side pane controls.
+ * Not part of the public module API -- only the shell calls this.
+ */
+declare function initSidePane(openFn: SidePaneOpenFn, closeFn: SidePaneCloseFn, isOpenFn: SidePaneIsOpenFn, activeModuleIdFn: SidePaneActiveModuleIdFn): void;
+declare const sidePane: {
+    /** Open the side pane with the given content and sizing options. */
+    open(opts: SidePaneOptions): void;
+    /** Close the side pane. */
+    close(): void;
+    /**
+     * Toggle the side pane.
+     *
+     * If the pane is closed, opens it with opts.
+     * If the pane is open with the same moduleId, closes it.
+     * If the pane is open with a different moduleId, replaces it with opts.
+     */
+    toggle(opts: SidePaneOptions): void;
+    /** Returns true when the pane is currently open. */
+    isOpen(): boolean;
+    /** Returns the moduleId of the currently open pane, or null. */
+    activeModuleId(): string | null;
+};
+interface FullscreenOptions {
+    /** React content to render inside the fullscreen overlay. */
+    content: ReactNode;
+}
+declare const fullscreen: {
+    /** Enter fullscreen mode, rendering content over all shell chrome. */
+    enter(opts: FullscreenOptions): void;
+    /** Exit fullscreen mode, restoring the normal shell layout. */
+    exit(): void;
+};
+type Unsubscribe = () => void;
+declare const events: {
+    /** Subscribe to an event. Returns an unsubscribe function. */
+    on<K extends keyof ShellEventMap>(key: K, handler: (payload: ShellEventMap[K]) => void): Unsubscribe;
+    /** Subscribe, auto-unsubscribing after the first emission. */
+    once<K extends keyof ShellEventMap>(key: K, handler: (payload: ShellEventMap[K]) => void): Unsubscribe;
+    /** Emit an event. Handlers run asynchronously (microtask). */
+    emit<K extends keyof ShellEventMap>(key: K, payload: ShellEventMap[K]): void;
+};
+
+/**
+ * Read the module registry from context.
+ * Must be called within an AppShell (which provides the context).
+ */
+declare function useShellModules(): ModuleRegistry;
+
+/**
+ * OverviewCard and FeatureLink -- building blocks for module overview pages.
+ *
+ * OverviewCard presents a feature with icon, title, description, and optional
+ * navigation via a stable feature id.
+ *
+ * FeatureLink is an inline text link for use in descriptions or prose,
+ * also navigating via stable feature id.
+ *
+ * Part of the shell -- extracts to @petrarca/sonnet-shell.
+ */
+
+interface OverviewCardProps {
+    /** Lucide icon component. */
+    icon: React__default.ComponentType<{
+        className?: string;
+    }>;
+    /** Card title. */
+    title: string;
+    /** Description -- plain string or React nodes (e.g. with FeatureLink). */
+    description: React__default.ReactNode;
+    /**
+     * Stable feature identifier (e.g. "auditing.audit-events").
+     * Resolved to a path via the shell registry at click time.
+     * Omit for non-navigable cards.
+     */
+    feature?: string;
+    /** Additional CSS class names. */
+    className?: string;
+}
+/**
+ * FeatureLink -- inline text link navigating to a feature by stable id.
+ *
+ * Use inside OverviewCard descriptions or overview page prose to link
+ * to a feature without hardcoding paths.
+ *
+ * @example
+ *   <FeatureLink feature="auditing.audit-log">Audit Log</FeatureLink>
+ */
+declare function FeatureLink({ feature, children, }: {
+    feature: string;
+    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;
+
+/**
+ * Get sorted contributions for a named extension point.
+ *
+ * Returns all contributions registered by any module for the given
+ * extension point, sorted by `order` (ascending).
+ *
+ * @example
+ * ```tsx
+ * const tabs = useExtensionPoint("organization-detail");
+ * ```
+ */
+declare function useExtensionPoint(name: string): Contribution[];
+/**
+ * Get the list of visible service modules (excludes hidden and bottom-pinned).
+ *
+ * Useful for building overviews like the home page.
+ */
+declare function useMainModules(): ServiceModule[];
+/**
+ * Subscribe to a shell event, auto-unsubscribing on unmount.
+ *
+ * The handler reference is stabilized via useRef so that the
+ * subscription is not torn down and recreated on every render.
+ *
+ * @example
+ * ```tsx
+ * useShellEvent("schema-definition:changed", (payload) => {
+ *   queryClient.invalidateQueries({ queryKey: ["my-key"] });
+ * });
+ * ```
+ */
+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 };