@tpzdsp/next-toolkit 2.5.0 → 3.0.0

package/src/components/Sidebar/Sidebar.css

@@ -0,0 +1,203 @@
+@layer components {
+  /* MARK: Provider
+     Flex shell. Horizontal (default) = row for left/right sidebars.
+     Vertical = column for top/bottom sidebars. Fills the height of whatever
+     it's placed in (not the viewport), so it works both as a full-page shell
+     and inside a container already constrained by a header/footer. Needs an
+     ancestor that actually establishes a height for this to have any effect,
+     the same requirement as any other height: 100% layout. */
+  .cn-sidebar-provider {
+    display: flex;
+    height: 100%;
+  }
+
+  .cn-sidebar-provider[data-orientation='vertical'] {
+    flex-direction: column;
+  }
+
+  /* MARK: Sidebar root
+     Flex child, the gap div inside drives the layout space. */
+  .cn-sidebar-root {
+    position: relative;
+  }
+
+  /* MARK: Gap div
+     In-flow placeholder. Horizontal sidebars animate width, vertical animate height. */
+  .cn-sidebar-gap {
+    flex-shrink: 0;
+    pointer-events: none;
+    width: var(--cn-sidebar-width, 16rem);
+    transition: width 0.2s ease;
+  }
+
+  [data-orientation='vertical'] .cn-sidebar-gap {
+    width: auto;
+    height: var(--cn-sidebar-height, 12rem);
+    transition: height 0.2s ease;
+  }
+
+  .cn-sidebar-root[data-state='collapsed'] .cn-sidebar-gap {
+    width: 0;
+  }
+
+  [data-orientation='vertical'] .cn-sidebar-root[data-state='collapsed'] .cn-sidebar-gap {
+    width: auto;
+    height: 0;
+  }
+
+  .cn-sidebar-root[data-variant='overlay'] .cn-sidebar-gap,
+  .cn-sidebar-root[data-mobile] .cn-sidebar-gap {
+    width: 0;
+    height: 0;
+  }
+
+  /* MARK: Panel
+     Absolutely positioned against cn-sidebar-root (position: relative above),
+     not the viewport, so the panel stretches to fill its container's height
+     rather than the full page. If the container happens to be full page
+     height already, this looks identical to position: fixed. Uses panel
+     background and border weight/colour. A container-query provider: this is
+     the actual available width for anything stacked inside a sidebar (Stack,
+     HeadingGroup, etc.), which is usually much narrower than the viewport, so
+     their spacing needs to key off this element's width, not the viewport's. */
+  .cn-sidebar {
+    position: absolute;
+    z-index: 20;
+    display: flex;
+    flex-direction: column;
+    overflow-y: auto;
+    background: var(--color-panel);
+    transition: transform 0.2s ease;
+    container-type: inline-size;
+  }
+
+  /* Left/right: full height, fixed width */
+  .cn-sidebar-root[data-side='left'] .cn-sidebar,
+  .cn-sidebar-root[data-side='right'] .cn-sidebar {
+    top: 0;
+    bottom: 0;
+    width: var(--cn-sidebar-width, 16rem);
+  }
+
+  .cn-sidebar-root[data-side='left'] .cn-sidebar {
+    left: 0;
+    border-right: var(--border-width-form) solid var(--color-panel-border);
+  }
+
+  .cn-sidebar-root[data-side='right'] .cn-sidebar {
+    right: 0;
+    border-left: var(--border-width-form) solid var(--color-panel-border);
+  }
+
+  .cn-sidebar-root[data-state='collapsed'][data-side='left'] .cn-sidebar {
+    transform: translateX(-100%);
+  }
+
+  .cn-sidebar-root[data-state='collapsed'][data-side='right'] .cn-sidebar {
+    transform: translateX(100%);
+  }
+
+  /* Top/bottom: full width, fixed height */
+  .cn-sidebar-root[data-side='top'] .cn-sidebar,
+  .cn-sidebar-root[data-side='bottom'] .cn-sidebar {
+    left: 0;
+    right: 0;
+    height: var(--cn-sidebar-height, 12rem);
+    overflow-x: auto;
+    overflow-y: hidden;
+    flex-direction: row;
+  }
+
+  .cn-sidebar-root[data-side='top'] .cn-sidebar {
+    top: 0;
+    border-bottom: var(--border-width-form) solid var(--color-panel-border);
+  }
+
+  .cn-sidebar-root[data-side='bottom'] .cn-sidebar {
+    bottom: 0;
+    border-top: var(--border-width-form) solid var(--color-panel-border);
+  }
+
+  .cn-sidebar-root[data-state='collapsed'][data-side='top'] .cn-sidebar {
+    transform: translateY(-100%);
+  }
+
+  .cn-sidebar-root[data-state='collapsed'][data-side='bottom'] .cn-sidebar {
+    transform: translateY(100%);
+  }
+
+  /* Mobile: full container */
+  .cn-sidebar-root[data-mobile] .cn-sidebar {
+    width: 100%;
+    height: 100%;
+    border: none;
+  }
+
+  .cn-sidebar-root[data-mobile][data-state='collapsed'] .cn-sidebar {
+    transform: translateX(-100%);
+  }
+
+  .cn-sidebar-root[data-mobile][data-state='collapsed'][data-side='right'] .cn-sidebar {
+    transform: translateX(100%);
+  }
+
+  /* MARK: Backdrop
+     Absolute (against cn-sidebar-root), same reasoning as the panel above:
+     it should only cover the sidebar's own container, not the full page. */
+  .cn-sidebar-backdrop {
+    position: absolute;
+    inset: 0;
+    z-index: 19;
+    background: rgb(0 0 0 / 50%);
+  }
+
+  /* MARK: Inset */
+  .cn-sidebar-inset {
+    flex: 1;
+    min-width: 0;
+    min-height: 0;
+    display: flex;
+    flex-direction: column;
+  }
+
+  /* MARK: Resizable sidebar (ResizableSidebar)
+     Used instead of cn-sidebar-root/cn-sidebar when the sidebar lives inside
+     a ResizablePanelGroup. No position/width rules here, ResizablePanel
+     already controls sizing, and the ResizableHandle is the visual divider
+     (so no border, unlike cn-sidebar). Height comes for free: this class
+     lands on ResizablePanel's own inner content div, which the library
+     already stretches to fill the panel via flexbox, the same mechanism
+     cn-sidebar-root relies on above. Same container-query provider reasoning
+     as cn-sidebar: its width is whatever the user has resized the panel to,
+     not the viewport. */
+  .cn-resizable-sidebar {
+    @apply flex flex-col overflow-y-auto @container;
+    background: var(--color-panel);
+  }
+
+  /* MARK: Resizable sidebar open/close (deliberately no transition)
+     react-resizable-panels sizes a panel via an inline flex-grow number (not
+     width or flex-basis), so animating it (as tried previously, via a
+     [data-panel]:has(> .cn-resizable-sidebar) transition) genuinely resizes
+     the panel's box on every frame, which squishes/reflows the header,
+     content and footer inside it for the whole 200ms, unlike cn-sidebar's
+     own translateX transform (same width throughout, just slides off
+     screen). A min-width workaround doesn't hold up either: expand()
+     restores whatever size the user last dragged to, not a fixed value CSS
+     could pin to, and permanently pinning one would fight the user's own
+     drag-resized width at rest. Snapping open/closed instantly avoids the
+     squish entirely. */
+
+  /* MARK: Structure */
+  .cn-sidebar-header {
+    @apply p-gds-2 flex items-center gap-gds-2 shrink-0;
+  }
+
+  .cn-sidebar-content {
+    @apply flex-1 overflow-y-auto;
+  }
+
+  .cn-sidebar-footer {
+    @apply p-gds-2 shrink-0;
+  }
+}

package/src/components/Sidebar/Sidebar.stories.tsx

@@ -0,0 +1,438 @@
+import { LuPanelLeft } from 'react-icons/lu';
+
+import type { Meta, StoryObj } from '@storybook/react-vite';
+
+import { ResizableSidebar, ResizableSidebarHandle } from './ResizableSidebar';
+import {
+  Sidebar,
+  SidebarClose,
+  SidebarContent,
+  SidebarFooter,
+  SidebarHeader,
+  SidebarInset,
+  SidebarProvider,
+  useSidebar,
+} from './Sidebar';
+import {
+  Accordion,
+  AccordionContent,
+  AccordionItem,
+  AccordionTrigger,
+} from '../Accordion/Accordion';
+import { Button } from '../Button/Button';
+import { ResizablePanel, ResizablePanelGroup } from '../Resizable/Resizable';
+import { Tabs, TabsContent, TabsList, TabsTrigger } from '../Tabs/Tabs';
+
+const meta: Meta<typeof Sidebar> = {
+  title: 'Components/Sidebar',
+  component: Sidebar,
+  parameters: { layout: 'fullscreen' },
+};
+
+export default meta;
+type Story = StoryObj<typeof Sidebar>;
+
+const SidebarTrigger = () => {
+  const { toggleSidebar, open } = useSidebar();
+
+  return (
+    <Button
+      appearance="ghost"
+      onClick={toggleSidebar}
+      aria-expanded={open}
+      aria-label={open ? 'Close sidebar' : 'Open sidebar'}
+    >
+      <LuPanelLeft aria-hidden />
+    </Button>
+  );
+};
+
+const SampleContent = () => (
+  <Accordion type="multiple">
+    <AccordionItem value="layers">
+      <AccordionTrigger>Layers</AccordionTrigger>
+
+      <AccordionContent>Toggle individual map layers here.</AccordionContent>
+    </AccordionItem>
+
+    <AccordionItem value="filters">
+      <AccordionTrigger>Filters</AccordionTrigger>
+
+      <AccordionContent>Apply filters to narrow the displayed data.</AccordionContent>
+    </AccordionItem>
+
+    <AccordionItem value="legend">
+      <AccordionTrigger>Legend</AccordionTrigger>
+
+      <AccordionContent>Colour scale and symbol reference.</AccordionContent>
+    </AccordionItem>
+  </Accordion>
+);
+
+export const Push: Story = {
+  render: () => (
+    <div className="h-screen">
+      <SidebarProvider>
+        <Sidebar>
+          <SidebarHeader>
+            <strong className="text-body text-base flex-1">Filters</strong>
+
+            <SidebarClose />
+          </SidebarHeader>
+
+          <SidebarContent>
+            <SampleContent />
+          </SidebarContent>
+
+          <SidebarFooter>
+            <Button appearance="secondary" className="w-full">
+              Clear all
+            </Button>
+          </SidebarFooter>
+        </Sidebar>
+
+        <SidebarInset>
+          <header className="flex items-center gap-gds-2 p-gds-2 border-b border-divider">
+            <SidebarTrigger />
+
+            <h1 className="text-base font-bold text-body">Map view</h1>
+          </header>
+
+          <div className="p-gds-4 text-body">
+            <p>
+              Main content area. With <code>variant=&quot;push&quot;</code> (default) the page
+              content shifts as the sidebar opens and closes.
+            </p>
+          </div>
+        </SidebarInset>
+      </SidebarProvider>
+    </div>
+  ),
+};
+
+export const WithinConstrainedContainer: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'The sidebar fills the height of its own container, not the page. Here the outer shell has a fixed-height header and footer, and the sidebar only spans the inner area between them, rather than covering the whole viewport.',
+      },
+    },
+  },
+  render: () => (
+    <div className="flex h-screen flex-col">
+      <header
+        className="flex shrink-0 items-center gap-gds-2 p-gds-2 bg-panel border-b border-divider"
+      >
+        <h1 className="text-base font-bold text-body">App header</h1>
+      </header>
+
+      <div className="min-h-0 flex-1">
+        <SidebarProvider>
+          <Sidebar>
+            <SidebarHeader>
+              <strong className="text-body text-base flex-1">Filters</strong>
+
+              <SidebarClose />
+            </SidebarHeader>
+
+            <SidebarContent>
+              <SampleContent />
+            </SidebarContent>
+          </Sidebar>
+
+          <SidebarInset>
+            <header className="flex items-center gap-gds-2 p-gds-2 border-b border-divider">
+              <SidebarTrigger />
+
+              <h1 className="text-base font-bold text-body">Map view</h1>
+            </header>
+
+            <div className="p-gds-4 text-body">
+              <p>The sidebar panel stops above the footer instead of covering it.</p>
+            </div>
+          </SidebarInset>
+        </SidebarProvider>
+      </div>
+
+      <footer
+        className="flex shrink-0 items-center gap-gds-2 p-gds-2 bg-panel border-t border-divider"
+      >
+        <p className="text-body text-sm">App footer</p>
+      </footer>
+    </div>
+  ),
+};
+
+export const WithFixedHeader: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Put the trigger in an app-level header that never moves, instead of inside SidebarInset where it shifts or gets overlaid with the rest of the content. Override SidebarProvider to stack vertically with className="flex-col" (it\'s a flex row by default), put the header first, then wrap Sidebar and SidebarInset in a plain flex row div as the second child. The header stays put; only that row pushes or overlays.',
+      },
+    },
+  },
+  render: () => (
+    <div className="h-screen">
+      <SidebarProvider className="flex-col">
+        <header className="flex shrink-0 items-center gap-gds-2 p-gds-2 border-b border-divider">
+          <SidebarTrigger />
+
+          <h1 className="text-base font-bold text-body">App header</h1>
+        </header>
+
+        <div className="flex flex-1 min-h-0">
+          <Sidebar>
+            <SidebarHeader>
+              <strong className="text-body text-base flex-1">Filters</strong>
+
+              <SidebarClose />
+            </SidebarHeader>
+
+            <SidebarContent>
+              <SampleContent />
+            </SidebarContent>
+          </Sidebar>
+
+          <SidebarInset>
+            <div className="p-gds-4 text-body">
+              <p>The header above stays fixed. Only this content area shifts or is overlaid.</p>
+            </div>
+          </SidebarInset>
+        </div>
+      </SidebarProvider>
+    </div>
+  ),
+};
+
+export const Resizable: Story = {
+  parameters: {
+    docs: {
+      description: {
+        story:
+          'Use ResizableSidebar instead of Sidebar to make the panel drag-resizable, by placing it inside a ResizablePanelGroup alongside a ResizableSidebarHandle and a plain ResizablePanel for the content. ResizableSidebar still reads open state from the same useSidebar() context as the trigger button, so opening and closing both work exactly as before: the drag handle just also lets the user resize it while open, and it snaps back to its previous size the next time it opens. ResizableSidebarHandle disables itself while closed, dragging or arrow-keying a fully collapsed panel back open is not reliable in the underlying library, so reopening goes through the trigger instead.',
+      },
+    },
+  },
+  render: () => (
+    <div className="h-screen">
+      <Tabs defaultValue="overview" className="flex h-full flex-col">
+        <SidebarProvider className="flex-col">
+          <div className="flex shrink-0 items-center gap-gds-2 p-gds-2 border-b border-divider">
+            <SidebarTrigger />
+
+            <TabsList>
+              <TabsTrigger value="overview">Overview</TabsTrigger>
+
+              <TabsTrigger value="details">Details</TabsTrigger>
+
+              <TabsTrigger value="history">History</TabsTrigger>
+            </TabsList>
+          </div>
+
+          <ResizablePanelGroup className="flex flex-1 min-h-0">
+            <ResizableSidebar>
+              <SidebarHeader>
+                <strong className="text-body text-base flex-1">Filters</strong>
+              </SidebarHeader>
+
+              <SidebarContent>
+                <SampleContent />
+              </SidebarContent>
+            </ResizableSidebar>
+
+            <ResizableSidebarHandle withHandle />
+
+            <ResizablePanel>
+              <SidebarInset>
+                <TabsContent value="overview">
+                  <p className="p-gds-4 text-body">Overview tab content.</p>
+                </TabsContent>
+
+                <TabsContent value="details">
+                  <p className="p-gds-4 text-body">Details tab content.</p>
+                </TabsContent>
+
+                <TabsContent value="history">
+                  <p className="p-gds-4 text-body">History tab content.</p>
+                </TabsContent>
+              </SidebarInset>
+            </ResizablePanel>
+          </ResizablePanelGroup>
+        </SidebarProvider>
+      </Tabs>
+    </div>
+  ),
+};
+
+export const Overlay: Story = {
+  render: () => (
+    <div className="h-screen">
+      <SidebarProvider>
+        <Sidebar variant="overlay">
+          <SidebarHeader>
+            <strong className="text-body text-base flex-1">Filters</strong>
+
+            <SidebarClose />
+          </SidebarHeader>
+
+          <SidebarContent>
+            <SampleContent />
+          </SidebarContent>
+        </Sidebar>
+
+        <SidebarInset>
+          <header className="flex items-center gap-gds-2 p-gds-2 border-b border-divider">
+            <SidebarTrigger />
+
+            <h1 className="text-base font-bold text-body">Map view</h1>
+          </header>
+
+          <div className="p-gds-4 text-body">
+            <p>
+              With <code>variant=&quot;overlay&quot;</code> the sidebar floats above the content.
+              Click the X or the backdrop to close.
+            </p>
+          </div>
+        </SidebarInset>
+      </SidebarProvider>
+    </div>
+  ),
+};
+
+export const RightSide: Story = {
+  render: () => (
+    <div className="h-screen">
+      <SidebarProvider>
+        <SidebarInset>
+          <header className="flex items-center gap-gds-2 p-gds-2 border-b border-divider">
+            <h1 className="text-base font-bold text-body flex-1">Map view</h1>
+
+            <SidebarTrigger />
+          </header>
+
+          <div className="p-gds-4 text-body">
+            <p>Sidebar anchored to the right.</p>
+          </div>
+        </SidebarInset>
+
+        <Sidebar side="right">
+          <SidebarHeader>
+            <strong className="text-body text-base flex-1">Details</strong>
+
+            <SidebarClose />
+          </SidebarHeader>
+
+          <SidebarContent>
+            <SampleContent />
+          </SidebarContent>
+        </Sidebar>
+      </SidebarProvider>
+    </div>
+  ),
+};
+
+export const DefaultClosed: Story = {
+  render: () => (
+    <div className="h-screen">
+      <SidebarProvider defaultOpen={false}>
+        <Sidebar>
+          <SidebarHeader>
+            <strong className="text-body text-base flex-1">Filters</strong>
+
+            <SidebarClose />
+          </SidebarHeader>
+
+          <SidebarContent>
+            <SampleContent />
+          </SidebarContent>
+        </Sidebar>
+
+        <SidebarInset>
+          <header className="flex items-center gap-gds-2 p-gds-2 border-b border-divider">
+            <SidebarTrigger />
+
+            <h1 className="text-base font-bold text-body">Starts closed</h1>
+          </header>
+
+          <div className="p-gds-4 text-body">Toggle the sidebar with the button in the header.</div>
+        </SidebarInset>
+      </SidebarProvider>
+    </div>
+  ),
+};
+
+export const TopDrawer: Story = {
+  render: () => (
+    <div className="h-screen">
+      <SidebarProvider orientation="vertical" height="10rem">
+        <Sidebar side="top">
+          <SidebarHeader>
+            <strong className="text-body text-base flex-1">Top drawer</strong>
+
+            <SidebarClose />
+          </SidebarHeader>
+
+          <SidebarContent className="flex-row p-gds-2 gap-gds-4">
+            <p className="text-body text-sm">Drawer content goes here — filters, controls, etc.</p>
+          </SidebarContent>
+        </Sidebar>
+
+        <SidebarInset>
+          <header className="flex items-center gap-gds-2 p-gds-2 border-b border-divider">
+            <SidebarTrigger />
+
+            <h1 className="text-base font-bold text-body">Map view</h1>
+          </header>
+
+          <div className="p-gds-4 text-body">
+            <p>
+              Set <code>side=&quot;top&quot;</code> on the Sidebar.
+            </p>
+
+            <p>
+              Pass <code>orientation=&quot;vertical&quot;</code> to the provider so the gap div
+              animates height as the drawer opens.
+            </p>
+          </div>
+        </SidebarInset>
+      </SidebarProvider>
+    </div>
+  ),
+};
+
+export const BottomDrawer: Story = {
+  render: () => (
+    <div className="h-screen">
+      <SidebarProvider orientation="vertical" height="10rem">
+        <SidebarInset>
+          <header className="flex items-center gap-gds-2 p-gds-2 border-b border-divider">
+            <SidebarTrigger />
+
+            <h1 className="text-base font-bold text-body">Map view</h1>
+          </header>
+
+          <div className="p-gds-4 text-body">
+            <p>
+              <code>side=&quot;bottom&quot;</code> — drawer slides up from the bottom of the
+              viewport.
+            </p>
+          </div>
+        </SidebarInset>
+
+        <Sidebar side="bottom">
+          <SidebarHeader>
+            <strong className="text-body text-base flex-1">Bottom drawer</strong>
+
+            <SidebarClose />
+          </SidebarHeader>
+
+          <SidebarContent className="p-gds-2">
+            <p className="text-body text-sm">Drawer content.</p>
+          </SidebarContent>
+        </Sidebar>
+      </SidebarProvider>
+    </div>
+  ),
+};