@canonical/maas-react-components 2.3.0 → 2.5.0

package/dist/src/lib/sections/Navigation/Link/Link.stories.d.ts

@@ -0,0 +1,19 @@
+import { Meta } from '@storybook/react';
+import { Navigation } from '../Navigation';
+declare const meta: Meta<typeof Navigation.Link>;
+export default meta;
+export declare const Example: {
+    args: {
+        as: string;
+        href: string;
+        "aria-current": string;
+        children: import("react/jsx-runtime").JSX.Element;
+    };
+};
+export declare const ButtonExample: {
+    args: {
+        as: <P>({ appearance, children, className, dense, disabled, element: Component, hasIcon, inline, onClick, small, ...buttonProps }: import('@canonical/react-components').ButtonProps<P>) => React.JSX.Element;
+        appearance: string;
+        children: import("react/jsx-runtime").JSX.Element;
+    };
+};

package/dist/src/lib/sections/SidePanel/SidePanel.d.ts

@@ -0,0 +1,42 @@
+import { ReactElement } from 'react';
+/**
+ * Slide-in aside panel rendered at the edge of the page.
+ *
+ * Reads all state from the nearest `SidePanelContextProvider` via `useSidePanel`.
+ * The panel has no props of its own — open it by calling `openSidePanel` from the hook.
+ *
+ * Behaviour:
+ * - Collapses automatically when the current route changes
+ * - Closes when the Escape key is pressed
+ * - Resets its size to `"regular"` on unmount
+ *
+ * Size variants (set via `openSidePanel` or `setSidePanelSize`):
+ * - `"narrow"` — adds the `is-narrow` CSS modifier
+ * - `"regular"` — default, no modifier class
+ * - `"wide"` — adds the `is-wide` CSS modifier
+ * - `"large"` — adds the `is-large` CSS modifier
+ *
+ * @requires SidePanelContextProvider — must be present higher in the tree
+ * @requires A React Router context — must be rendered inside a Router
+ *
+ * @example
+ * ```tsx
+ * // In your app root:
+ * <SidePanelContextProvider>
+ *   <Router>
+ *     <main>…</main>
+ *     <SidePanel />
+ *   </Router>
+ * </SidePanelContextProvider>
+ *
+ * // Anywhere in the tree:
+ * const { openSidePanel } = useSidePanel();
+ * openSidePanel({ component: EditForm, title: "Edit item", size: "wide" });
+ * ```
+ */
+export declare const SidePanel: {
+    (): ReactElement;
+    Skeleton: ({ hasTitle }: {
+        hasTitle?: boolean;
+    }) => ReactElement;
+};

package/dist/src/lib/sections/SidePanel/SidePanel.stories.d.ts

@@ -0,0 +1,12 @@
+import { Meta, StoryObj } from '@storybook/react';
+import { SidePanel } from './SidePanel';
+declare const meta: Meta<typeof SidePanel>;
+export default meta;
+type Story = StoryObj<typeof SidePanel>;
+export declare const Interactive: Story;
+export declare const Default: Story;
+export declare const NarrowSize: Story;
+export declare const WideSize: Story;
+export declare const LargeSize: Story;
+export declare const Skeleton: Story;
+export declare const SkeletonWithTitle: Story;

package/dist/src/lib/sections/SidePanel/SidePanel.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/lib/sections/SidePanel/SidePanelContextProvider/SidePanelContextProvider.d.ts

@@ -0,0 +1,95 @@
+import { ComponentType, PropsWithChildren, ReactElement } from 'react';
+type SidePanelSize = "large" | "narrow" | "regular" | "wide";
+interface SidePanelState<TProps = Record<string, unknown>> {
+    isOpen: boolean;
+    title: string;
+    size: SidePanelSize;
+    component: ComponentType<TProps> | null;
+    props: TProps;
+}
+export interface SidePanelActions {
+    openSidePanel: <TProps extends Record<string, unknown> = Record<string, unknown>>(params: {
+        component: ComponentType<TProps>;
+        title: string;
+        props?: TProps;
+        size?: SidePanelSize;
+    }) => void;
+    closeSidePanel: () => void;
+    setSidePanelSize: (size: SidePanelSize) => void;
+}
+type SidePanelContextValue = SidePanelActions & SidePanelState;
+/**
+ * Hook for managing side panel state and actions.
+ *
+ * Provides methods to open/close side panels with React components and manages
+ * panel size and visibility state.
+ *
+ * @returns Object containing:
+ *   - `isOpen`: Boolean indicating if the side panel is currently open
+ *   - `title`: Current panel title string
+ *   - `size`: Current panel size ('narrow' | 'regular' | 'wide' | 'large')
+ *   - `component`: Currently rendered component
+ *   - `props`: Props passed to the current component
+ *   - `openSidePanel({component, title, props?, size?})`: Opens panel with given component
+ *   - `closeSidePanel()`: Closes the panel and resets state
+ *   - `setSidePanelSize(size)`: Changes the panel width
+ *
+ * @throws Error when used outside SidePanelProvider
+ *
+ * @example
+ * ```tsx
+ * const { open, close, isOpen } = useSidePanel();
+ *
+ * // Open a panel with a form component
+ * const handleEdit = (userId: number) => {
+ *   open(EditUserForm, 'Edit User', { userId }, 'wide');
+ * };
+ *
+ * // Close the panel
+ * const handleCancel = () => {
+ *   close();
+ * };
+ * ```
+ */
+export declare const useSidePanel: () => SidePanelContextValue;
+/**
+ * Provider component for managing side panel state and actions.
+ *
+ * Wraps your application or subtree to provide side panel context to all child
+ * components. Child components can use the `useSidePanel` hook to access and
+ * control the side panel.
+ *
+ * @param children - React elements to render within the provider
+ *
+ * @returns A React element wrapping children with SidePanelContext
+ *
+ * @example
+ * ```tsx
+ * function App() {
+ *   return (
+ *     <SidePanelContextProvider>
+ *       <MainLayout />
+ *     </SidePanelContextProvider>
+ *   );
+ * }
+ *
+ * function MainLayout() {
+ *   const { openSidePanel, closeSidePanel, isOpen } = useSidePanel();
+ *
+ *   return (
+ *     <>
+ *       <button onClick={() => openSidePanel({
+ *         component: UserForm,
+ *         title: 'Create User',
+ *         size: 'wide'
+ *       })}>
+ *         New User
+ *       </button>
+ *       {isOpen && <SidePanel />}
+ *     </>
+ *   );
+ * }
+ * ```
+ */
+export declare const SidePanelContextProvider: ({ children, }: PropsWithChildren) => ReactElement;
+export {};

package/dist/src/lib/sections/SidePanel/index.d.ts

@@ -0,0 +1,2 @@
+export { SidePanel } from './SidePanel';
+export { SidePanelContextProvider, useSidePanel } from './SidePanelContextProvider/SidePanelContextProvider';

package/dist/src/lib/sections/SidePanel/utils.d.ts

@@ -0,0 +1,22 @@
+import { ComponentType } from 'react';
+/**
+ * Lazily loads a side panel component wrapped in its own Suspense boundary.
+ * Define the panel at module scope in the file that opens it and pass it
+ * straight to `openSidePanel`:
+ *
+ * @example
+ * const AddUser = lazySidePanel(() => import("./UserAddForm"));
+ * // ...
+ * openSidePanel({ component: AddUser, title: "Add user" });
+ *
+ * The `<SidePanel />` component from `@canonical/maas-react-components` renders
+ * the panel component directly, so a bare `React.lazy` panel would suspend the
+ * whole `<SidePanel />` on first open. That remounts `<SidePanel />`, and on
+ * remount its internal "close on navigation" effect runs and immediately closes
+ * the panel that was just opened. Giving each panel its own Suspense boundary
+ * keeps `<SidePanel />` mounted (and open) while the chunk loads, and shows the
+ * spinner inside the panel.
+ */
+export declare const lazyLoadSidePanel: (loader: () => Promise<{
+    default: ComponentType;
+}>, showSkeletonTitle?: boolean) => ComponentType;

package/dist/src/lib/sections/index.d.ts

@@ -1,5 +1,6 @@
-export * from './Navigation';
-export * from './InputGroup';
+export * from './ContentSection';
 export * from './FormSection';
+export * from './InputGroup';
 export * from './MainToolbar';
-export * from './ContentSection';
+export * from './Navigation';
+export * from './SidePanel';

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@canonical/maas-react-components",
   "description": "React components for use in MAAS UI projects.",
-  "version": "2.3.0",
+  "version": "2.5.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/canonical/maas-react-components.git"
@@ -93,7 +93,7 @@
     "vitest": "^3.0.8"
   },
   "peerDependencies": {
-    "@canonical/react-components": "^2.2.0",
+    "@canonical/react-components": "^4.5.0",
     "@tanstack/react-table": "^8.15.3",
     "@types/react": "^19.1.2",
     "@types/react-dom": "^19.1.3",
@@ -101,6 +101,7 @@
     "react": "19.1.0",
     "react-dom": "19.1.0",
     "react-dropzone": "14.3.8",
+    "react-router": "^6.0.0",
     "react-router-dom": "^6.0.0",
     "vanilla-framework": "^4.10.0"
   }