basalt-ui 1.13.0 → 1.14.0

package/CHANGELOG.md

@@ -1,3 +1,10 @@
+# [1.14.0](https://github.com/jkrumm/basalt-ui/compare/v1.13.0...v1.14.0) (2026-08-10)
+
+
+### Features
+
+* let the sidebar host arbitrary content in its nav scroll region ([1b1a5f3](https://github.com/jkrumm/basalt-ui/commit/1b1a5f3f50cba0cf5f89e767d438dbd02adfe03f))
+
 # [1.13.0](https://github.com/jkrumm/basalt-ui/compare/v1.12.0...v1.13.0) (2026-08-04)
 
 

package/dist/shell/app-sidebar.d.ts

@@ -51,6 +51,24 @@ export type AppSidebarProps = {
      * fixed, non-scrolling row. Pair with basalt-ui/commands' openSpotlight.
      */
     search?: SidebarSearchConfig;
+    /**
+     * Arbitrary content appended after `sections` inside the nav `ScrollArea` — a tree, a filter
+     * panel, a project list, anything a set of `SidebarItem`s can't express. Renders as the last
+     * child of the scrolling nav column, so a long list scrolls with the rest of the nav instead of
+     * fighting it for height. Pass `sections={[]}` to use this slot exclusively; the section-spacing
+     * rule only fires between adjacent children, so an empty `sections` produces no orphan divider or
+     * dead padding above it.
+     *
+     * Hidden on the collapsed desktop rail; still present in the mobile drawer, which opens at full
+     * width. The rail is ~56px of icon buttons with no sensible representation for arbitrary
+     * consumer content, so the CSS media query that drives the rail hides this slot the same way it
+     * hides `.childList` — never a JS check on `collapsed`, since that one value is shared by the
+     * rail AND the drawer (only the media query tells them apart). `SidebarSearch` gets to adapt
+     * itself to the rail (it takes `collapsed` and renders its own icon-only form) because the shell
+     * owns that control; it cannot adapt content it knows nothing about, so this slot hides instead
+     * of squashing it.
+     */
+    navExtra?: ReactNode;
 };
-export declare function AppSidebar({ brand, sections, collapsed, onToggleCollapse, onClose, renderNavLink, settingsMenuItems, footerExtra, account, search, }: AppSidebarProps): import("react").JSX.Element;
+export declare function AppSidebar({ brand, sections, collapsed, onToggleCollapse, onClose, renderNavLink, settingsMenuItems, footerExtra, account, search, navExtra, }: AppSidebarProps): import("react").JSX.Element;
 //# sourceMappingURL=app-sidebar.d.ts.map

package/dist/shell/app-sidebar.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"app-sidebar.d.ts","sourceRoot":"","sources":["../../src/shell/app-sidebar.tsx"],"names":[],"mappings":"AA+BA,OAAO,KAAK,EAAc,SAAS,EAAE,MAAM,OAAO,CAAA;AAClD,OAAO,KAAK,EAAE,WAAW,EAAE,gBAAgB,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,SAAS,CAAA;AAEzF,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAA;AAEzD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAA;AAK3D;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,eAAe,GAAG,CAC5B,IAAI,EAAE,WAAW,EACjB,IAAI,EAAE;IACJ,MAAM,EAAE,OAAO,CAAA;IACf,KAAK,CAAC,EAAE,CAAC,MAAM,IAAI,CAAC,GAAG,SAAS,CAAA;IAChC,gBAAgB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;CACtC,KACE,SAAS,CAAA;AAEd,MAAM,MAAM,eAAe,GAAG;IAC5B,KAAK,EAAE,WAAW,CAAA;IAClB,QAAQ,EAAE,cAAc,EAAE,CAAA;IAC1B,SAAS,EAAE,OAAO,CAAA;IAClB,gBAAgB,EAAE,MAAM,IAAI,CAAA;IAC5B,OAAO,EAAE,MAAM,IAAI,CAAA;IACnB;;;OAGG;IACH,aAAa,CAAC,EAAE,eAAe,CAAA;IAC/B;;;;;OAKG;IACH,iBAAiB,CAAC,EAAE,gBAAgB,EAAE,CAAA;IACtC,mGAAmG;IACnG,WAAW,CAAC,EAAE,SAAS,CAAA;IACvB;;;;OAIG;IACH,OAAO,CAAC,EAAE,kBAAkB,CAAA;IAC5B;;;OAGG;IACH,MAAM,CAAC,EAAE,mBAAmB,CAAA;CAC7B,CAAA;AAkWD,wBAAgB,UAAU,CAAC,EACzB,KAAK,EACL,QAAQ,EACR,SAAS,EACT,gBAAgB,EAChB,OAAO,EACP,aAAa,EACb,iBAAiB,EACjB,WAAW,EACX,OAAO,EACP,MAAM,GACP,EAAE,eAAe,+BAsLjB"}
+{"version":3,"file":"app-sidebar.d.ts","sourceRoot":"","sources":["../../src/shell/app-sidebar.tsx"],"names":[],"mappings":"AA+BA,OAAO,KAAK,EAAc,SAAS,EAAE,MAAM,OAAO,CAAA;AAClD,OAAO,KAAK,EAAE,WAAW,EAAE,gBAAgB,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,SAAS,CAAA;AAEzF,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,iBAAiB,CAAA;AAEzD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAA;AAK3D;;;;;;;;;;;;GAYG;AACH,MAAM,MAAM,eAAe,GAAG,CAC5B,IAAI,EAAE,WAAW,EACjB,IAAI,EAAE;IACJ,MAAM,EAAE,OAAO,CAAA;IACf,KAAK,CAAC,EAAE,CAAC,MAAM,IAAI,CAAC,GAAG,SAAS,CAAA;IAChC,gBAAgB,CAAC,EAAE,MAAM,GAAG,SAAS,CAAA;CACtC,KACE,SAAS,CAAA;AAEd,MAAM,MAAM,eAAe,GAAG;IAC5B,KAAK,EAAE,WAAW,CAAA;IAClB,QAAQ,EAAE,cAAc,EAAE,CAAA;IAC1B,SAAS,EAAE,OAAO,CAAA;IAClB,gBAAgB,EAAE,MAAM,IAAI,CAAA;IAC5B,OAAO,EAAE,MAAM,IAAI,CAAA;IACnB;;;OAGG;IACH,aAAa,CAAC,EAAE,eAAe,CAAA;IAC/B;;;;;OAKG;IACH,iBAAiB,CAAC,EAAE,gBAAgB,EAAE,CAAA;IACtC,mGAAmG;IACnG,WAAW,CAAC,EAAE,SAAS,CAAA;IACvB;;;;OAIG;IACH,OAAO,CAAC,EAAE,kBAAkB,CAAA;IAC5B;;;OAGG;IACH,MAAM,CAAC,EAAE,mBAAmB,CAAA;IAC5B;;;;;;;;;;;;;;;;OAgBG;IACH,QAAQ,CAAC,EAAE,SAAS,CAAA;CACrB,CAAA;AAkWD,wBAAgB,UAAU,CAAC,EACzB,KAAK,EACL,QAAQ,EACR,SAAS,EACT,gBAAgB,EAChB,OAAO,EACP,aAAa,EACb,iBAAiB,EACjB,WAAW,EACX,OAAO,EACP,MAAM,EACN,QAAQ,GACT,EAAE,eAAe,+BAyLjB"}

package/dist/shell/app-sidebar.js

@@ -314,7 +314,8 @@ function AppSidebar({
   settingsMenuItems,
   footerExtra,
   account,
-  search
+  search,
+  navExtra
 }) {
   const { step } = useBasaltSpacing();
   const [collapsedSections, setCollapsedSections] = useState(
@@ -410,33 +411,36 @@ function AppSidebar({
         scrollbarSize: 9,
         className: classes.navScroll,
         classNames: { viewport: classes.navViewport },
-        children: /* @__PURE__ */ jsx(Stack, { gap: 0, className: classes.nav, children: sections.map((section) => {
-          if (!section.collapsible) {
+        children: /* @__PURE__ */ jsxs(Stack, { gap: 0, className: classes.nav, children: [
+          sections.map((section) => {
+            if (!section.collapsible) {
+              return /* @__PURE__ */ jsxs("div", { children: [
+                /* @__PURE__ */ jsx("div", { className: classes.sectionBand, children: /* @__PURE__ */ jsx(SectionLabel, { flush: true, children: section.label }) }),
+                /* @__PURE__ */ jsx(Stack, { gap: 1, children: renderSectionItems(section) })
+              ] }, section.label);
+            }
+            const isOpen = !collapsedSections[section.label];
             return /* @__PURE__ */ jsxs("div", { children: [
-              /* @__PURE__ */ jsx("div", { className: classes.sectionBand, children: /* @__PURE__ */ jsx(SectionLabel, { flush: true, children: section.label }) }),
-              /* @__PURE__ */ jsx(Stack, { gap: 1, children: renderSectionItems(section) })
+              /* @__PURE__ */ jsxs(
+                UnstyledButton,
+                {
+                  className: `${classes.sectionBand} ${classes.sectionHeader}`,
+                  onClick: () => setCollapsedSections((prev) => ({
+                    ...prev,
+                    [section.label]: !prev[section.label]
+                  })),
+                  "aria-expanded": isOpen,
+                  children: [
+                    /* @__PURE__ */ jsx(SectionLabel, { flush: true, children: section.label }),
+                    /* @__PURE__ */ jsx(IconChevron, { open: isOpen })
+                  ]
+                }
+              ),
+              /* @__PURE__ */ jsx(Collapse, { expanded: isOpen, children: /* @__PURE__ */ jsx(Stack, { gap: 1, children: renderSectionItems(section) }) })
             ] }, section.label);
-          }
-          const isOpen = !collapsedSections[section.label];
-          return /* @__PURE__ */ jsxs("div", { children: [
-            /* @__PURE__ */ jsxs(
-              UnstyledButton,
-              {
-                className: `${classes.sectionBand} ${classes.sectionHeader}`,
-                onClick: () => setCollapsedSections((prev) => ({
-                  ...prev,
-                  [section.label]: !prev[section.label]
-                })),
-                "aria-expanded": isOpen,
-                children: [
-                  /* @__PURE__ */ jsx(SectionLabel, { flush: true, children: section.label }),
-                  /* @__PURE__ */ jsx(IconChevron, { open: isOpen })
-                ]
-              }
-            ),
-            /* @__PURE__ */ jsx(Collapse, { expanded: isOpen, children: /* @__PURE__ */ jsx(Stack, { gap: 1, children: renderSectionItems(section) }) })
-          ] }, section.label);
-        }) })
+          }),
+          navExtra !== void 0 && navExtra !== null && /* @__PURE__ */ jsx("div", { className: classes.navExtra, children: navExtra })
+        ] })
       }
     ),
     account ? /* @__PURE__ */ jsxs(Stack, { gap: 0, className: classes.footer, children: [

package/dist/shell/app-sidebar.module.css

@@ -419,4 +419,15 @@
   .root[data-collapsed] .childList {
     display: none;
   }
+
+  /* `navExtra` has no sensible icon-rail representation (arbitrary consumer content, not a nav
+   * row) — hide it in the rail, same treatment as `.childList`. It stays mounted (never a JS
+   * conditional on `collapsed`): `collapsed` is one value shared by the desktop rail AND the
+   * mobile drawer (`AppShell.Navbar`'s `collapsed: { mobile: !mobileOpened }` only ever un-collapses
+   * the mobile side), and the rail-vs-drawer split lives ENTIRELY in this media query, never in JS —
+   * a JS gate on `collapsed` would also drop `navExtra` from the mobile drawer, which opens at full
+   * width regardless of the persisted rail state. */
+  .root[data-collapsed] .navExtra {
+    display: none;
+  }
 }

package/dist/shell/app-sidebar.module.css.d.ts

@@ -29,6 +29,7 @@ declare const classes: {
   readonly sectionHeader: string
   readonly subnavDropdown: string
   readonly childList: string
+  readonly navExtra: string
   readonly ghostIcon: string
 }
 export default classes

package/dist/shell/app-sidebar.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=app-sidebar.test.d.ts.map

package/dist/shell/app-sidebar.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"app-sidebar.test.d.ts","sourceRoot":"","sources":["../../src/shell/app-sidebar.test.tsx"],"names":[],"mappings":""}

package/dist/shell/index.d.ts

@@ -73,6 +73,15 @@ export type BasaltShellProps = {
     globalActions?: ReactNode;
     /** Extra content appended to the sidebar footer, beside the settings menu (mobile close, etc.). */
     sidebarFooterExtra?: ReactNode;
+    /**
+     * Arbitrary content appended after `sections` inside the sidebar's nav scroll region (a tree, a
+     * filter panel, a project list, …). Hidden on the collapsed desktop rail; still present in the
+     * mobile drawer, which opens at full width — see `AppSidebarProps.navExtra`'s JSDoc for why.
+     * `AppSidebar` renders once and serves both the desktop rail and the mobile drawer (collapse
+     * styling is gated behind a `min-width: sm` media query, not a second render), so this slot
+     * reaches both.
+     */
+    sidebarNavExtra?: ReactNode;
     /** Entries appended to the sidebar settings menu. */
     settingsMenuItems?: SettingsMenuItem[];
     /**
@@ -119,5 +128,5 @@ export type BasaltShellProps = {
 export declare function NavCountBadge({ count }: {
     count: number;
 }): import("react").JSX.Element | null;
-export declare function BasaltShell({ brand, sections, renderNavLink, globalActions, sidebarFooterExtra, settingsMenuItems, storageKey, collapsed: collapsedProp, onCollapsedChange, renderBreadcrumbLink, account, search, children, }: BasaltShellProps): import("react").JSX.Element;
+export declare function BasaltShell({ brand, sections, renderNavLink, globalActions, sidebarFooterExtra, sidebarNavExtra, settingsMenuItems, storageKey, collapsed: collapsedProp, onCollapsedChange, renderBreadcrumbLink, account, search, children, }: BasaltShellProps): import("react").JSX.Element;
 //# sourceMappingURL=index.d.ts.map

package/dist/shell/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/shell/index.tsx"],"names":[],"mappings":"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"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/shell/index.tsx"],"names":[],"mappings":"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"}

package/dist/shell/index.js

@@ -95,6 +95,7 @@ function BasaltShell({
   renderNavLink,
   globalActions,
   sidebarFooterExtra,
+  sidebarNavExtra,
   settingsMenuItems,
   storageKey = "basalt-sidebar-collapsed",
   collapsed: collapsedProp,
@@ -153,6 +154,7 @@ function BasaltShell({
             onToggleCollapse: toggleCollapse,
             onClose: closeMobile,
             footerExtra: sidebarFooterExtra,
+            navExtra: sidebarNavExtra,
             ...renderNavLink !== void 0 && { renderNavLink },
             ...settingsMenuItems !== void 0 && { settingsMenuItems },
             ...account !== void 0 && { account },

package/dist/shell/index.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=index.test.d.ts.map

package/dist/shell/index.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.test.d.ts","sourceRoot":"","sources":["../../src/shell/index.test.tsx"],"names":[],"mappings":""}

package/llms.txt

@@ -1,4 +1,4 @@
-# basalt-ui v1.13.0
+# basalt-ui v1.14.0
 # Opinionated framework for Mantine-based React apps — theme, app shell, visx charts, toolchain presets
 #
 # basalt-ui is an opinionated framework for Mantine-based React apps.
@@ -19,7 +19,7 @@
 # ./tokens.css subpath. Guide: docs/FRAMEWORK-FREE.md in the repo.
 
 Package: basalt-ui
-Version: 1.13.0
+Version: 1.14.0
 
 ## basalt-ui
 Import: import { ... } from 'basalt-ui'

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "basalt-ui",
-  "version": "1.13.0",
+  "version": "1.14.0",
   "description": "Opinionated framework for Mantine-based React apps — theme, app shell, visx charts, toolchain presets",
   "keywords": [
     "charts",

package/src/shell/app-sidebar.module.css

@@ -419,4 +419,15 @@
   .root[data-collapsed] .childList {
     display: none;
   }
+
+  /* `navExtra` has no sensible icon-rail representation (arbitrary consumer content, not a nav
+   * row) — hide it in the rail, same treatment as `.childList`. It stays mounted (never a JS
+   * conditional on `collapsed`): `collapsed` is one value shared by the desktop rail AND the
+   * mobile drawer (`AppShell.Navbar`'s `collapsed: { mobile: !mobileOpened }` only ever un-collapses
+   * the mobile side), and the rail-vs-drawer split lives ENTIRELY in this media query, never in JS —
+   * a JS gate on `collapsed` would also drop `navExtra` from the mobile drawer, which opens at full
+   * width regardless of the persisted rail state. */
+  .root[data-collapsed] .navExtra {
+    display: none;
+  }
 }

package/src/shell/app-sidebar.module.css.d.ts

@@ -29,6 +29,7 @@ declare const classes: {
   readonly sectionHeader: string
   readonly subnavDropdown: string
   readonly childList: string
+  readonly navExtra: string
   readonly ghostIcon: string
 }
 export default classes

package/src/shell/app-sidebar.test.tsx

@@ -0,0 +1,98 @@
+/**
+ * `navExtra` — the seam that lets a consumer put arbitrary content (a tree, a filter panel,
+ * a project list) inside the sidebar's nav scroll region instead of rendering a second column
+ * beside the shell. Four invariants:
+ *
+ *  1. It renders INSIDE the nav `ScrollArea`'s content (Mantine's own `.mantine-ScrollArea-content`
+ *     class, stable across runs — CSS-module class hashes are not available under `bun test`, see
+ *     `stat-card.test.tsx`/`use-basalt-spacing.test.tsx` for the same constraint elsewhere), as the
+ *     LAST child, so a long tree scrolls with the nav instead of fighting it for height.
+ *  2. It STAYS MOUNTED when `collapsed` — `collapsed` is one value shared by the desktop rail AND
+ *     the mobile drawer (`AppShell.Navbar`'s `collapsed: { mobile: !mobileOpened }` never touches
+ *     the desktop side), and the rail-vs-drawer split lives entirely in a `min-width: sm` CSS media
+ *     query, never in JS. A JS gate on `collapsed` would silently drop `navExtra` from the mobile
+ *     drawer too, which opens at full width regardless of the persisted rail state. jsdom does not
+ *     evaluate the media query, so this asserts presence in the DOM, not computed visibility — the
+ *     CSS half (`.root[data-collapsed] .navExtra { display: none }`) is exercised by the guard rules
+ *     it shares with `.childList`/`.sectionBand`, not by this test.
+ *  3. `sections={[]}` plus only `navExtra` renders cleanly: the nav Stack holds exactly the
+ *     extra content, no orphan section wrapper.
+ *  4. Omitting the prop reproduces today's DOM exactly — the nav Stack's child count matches
+ *     `sections.length`, with no stray wrapper appended for the (absent) slot. This is the
+ *     regression guard for every existing consumer.
+ */
+import { MantineProvider } from '@mantine/core'
+import { render, screen } from '@testing-library/react'
+import { describe, expect, test } from 'bun:test'
+import type { ReactNode } from 'react'
+import { AppSidebar } from './app-sidebar'
+import type { AppSidebarProps } from './app-sidebar'
+
+const BRAND = { name: 'Argo' }
+const ONE_SECTION: AppSidebarProps['sections'] = [
+  { label: 'Main', items: [{ key: 'home', label: 'Home', icon: null }] },
+]
+
+function renderSidebar(props: Partial<AppSidebarProps> & { navExtra?: ReactNode }) {
+  return render(
+    <MantineProvider>
+      <AppSidebar
+        brand={BRAND}
+        sections={ONE_SECTION}
+        collapsed={false}
+        onToggleCollapse={() => {}}
+        onClose={() => {}}
+        {...props}
+      />
+    </MantineProvider>,
+  )
+}
+
+/** The nav `ScrollArea`'s content Stack — the direct parent of `sections` and `navExtra`. */
+function navStack(container: HTMLElement): Element {
+  const stack = container.querySelector('.mantine-ScrollArea-content > .mantine-Stack-root')
+  if (!stack) throw new Error('expected the nav ScrollArea content Stack to render')
+  return stack
+}
+
+describe('navExtra', () => {
+  test('renders inside the nav scroll region, as the last child, when expanded', () => {
+    const { container } = renderSidebar({
+      navExtra: <div data-testid="nav-extra">Extra</div>,
+    })
+    const extra = screen.getByTestId('nav-extra')
+    const stack = navStack(container)
+    expect(stack.contains(extra)).toBe(true)
+    expect(stack.lastElementChild?.contains(extra)).toBe(true)
+  })
+
+  test('stays mounted in the DOM when collapsed — hiding it is CSS-only, not a JS gate', () => {
+    const { container } = renderSidebar({
+      collapsed: true,
+      navExtra: <div data-testid="nav-extra">Extra</div>,
+    })
+    const extra = screen.getByTestId('nav-extra')
+    const stack = navStack(container)
+    // Presence, not visibility — jsdom never evaluates the `min-width: sm` media query that hides
+    // this in the rail. A regression here (reintroducing `!collapsed &&` in app-sidebar.tsx) would
+    // fail this assertion instead of only breaking silently in a real mobile-drawer browser.
+    expect(stack.contains(extra)).toBe(true)
+  })
+
+  test('sections={[]} plus only navExtra renders cleanly — no orphan section wrapper', () => {
+    const { container } = renderSidebar({
+      sections: [],
+      navExtra: <div data-testid="nav-extra">Extra</div>,
+    })
+    const stack = navStack(container)
+    expect(screen.getByTestId('nav-extra')).toBeTruthy()
+    expect(stack.children.length).toBe(1)
+  })
+
+  test("omitting the prop reproduces today's DOM — no stray wrapper for the unused slot", () => {
+    const { container } = renderSidebar({})
+    expect(screen.queryByTestId('nav-extra')).toBeNull()
+    const stack = navStack(container)
+    expect(stack.children.length).toBe(ONE_SECTION.length)
+  })
+})

package/src/shell/app-sidebar.tsx

@@ -92,6 +92,24 @@ export type AppSidebarProps = {
    * fixed, non-scrolling row. Pair with basalt-ui/commands' openSpotlight.
    */
   search?: SidebarSearchConfig
+  /**
+   * Arbitrary content appended after `sections` inside the nav `ScrollArea` — a tree, a filter
+   * panel, a project list, anything a set of `SidebarItem`s can't express. Renders as the last
+   * child of the scrolling nav column, so a long list scrolls with the rest of the nav instead of
+   * fighting it for height. Pass `sections={[]}` to use this slot exclusively; the section-spacing
+   * rule only fires between adjacent children, so an empty `sections` produces no orphan divider or
+   * dead padding above it.
+   *
+   * Hidden on the collapsed desktop rail; still present in the mobile drawer, which opens at full
+   * width. The rail is ~56px of icon buttons with no sensible representation for arbitrary
+   * consumer content, so the CSS media query that drives the rail hides this slot the same way it
+   * hides `.childList` — never a JS check on `collapsed`, since that one value is shared by the
+   * rail AND the drawer (only the media query tells them apart). `SidebarSearch` gets to adapt
+   * itself to the rail (it takes `collapsed` and renders its own icon-only form) because the shell
+   * owns that control; it cannot adapt content it knows nothing about, so this slot hides instead
+   * of squashing it.
+   */
+  navExtra?: ReactNode
 }
 
 /** Inline collapse/expand chevrons — keeps the shell icon-dependency-free. */
@@ -457,6 +475,7 @@ export function AppSidebar({
   footerExtra,
   account,
   search,
+  navExtra,
 }: AppSidebarProps) {
   // Density-tracking Menu dropdown width (`SPACE_STEP.sidebarSettingsMenuWidth`) — read the ACTIVE
   // resolved level, not the frozen level-0 constant (see that constant's own doc in
@@ -622,6 +641,9 @@ export function AppSidebar({
               </div>
             )
           })}
+          {navExtra !== undefined && navExtra !== null && (
+            <div className={classes.navExtra}>{navExtra}</div>
+          )}
         </Stack>
       </ScrollArea>
 

package/src/shell/index.test.tsx

@@ -0,0 +1,35 @@
+/**
+ * `BasaltShell`'s `sidebarNavExtra` forwarding path — `AppSidebar` (exercised directly in
+ * `app-sidebar.test.tsx`) is not the only place this prop can break. `BasaltShell` destructures
+ * `sidebarNavExtra` and hands it to `AppSidebar` as `navExtra`; a typo'd destructure key, a dropped
+ * prop, or a `sidebarFooterExtra`/`sidebarNavExtra` mix-up in that hand-off would ship silently
+ * without a test that renders `BasaltShell` itself.
+ */
+import { MantineProvider } from '@mantine/core'
+import { render, screen } from '@testing-library/react'
+import { describe, expect, test } from 'bun:test'
+import { BasaltShell } from './index'
+import type { SidebarSection } from './index'
+
+const BRAND = { name: 'Argo' }
+const ONE_SECTION: SidebarSection[] = [
+  { label: 'Main', items: [{ key: 'home', label: 'Home', icon: null }] },
+]
+
+describe('BasaltShell sidebarNavExtra', () => {
+  test("reaches AppSidebar's nav scroll region through the BasaltShell -> AppSidebar hand-off", () => {
+    const { container } = render(
+      <MantineProvider>
+        <BasaltShell
+          brand={BRAND}
+          sections={ONE_SECTION}
+          sidebarNavExtra={<div data-testid="nav-extra">Extra</div>}
+        />
+      </MantineProvider>,
+    )
+    const extra = screen.getByTestId('nav-extra')
+    const stack = container.querySelector('.mantine-ScrollArea-content > .mantine-Stack-root')
+    expect(stack).not.toBeNull()
+    expect(stack?.contains(extra)).toBe(true)
+  })
+})

package/src/shell/index.tsx

@@ -115,6 +115,15 @@ export type BasaltShellProps = {
   globalActions?: ReactNode
   /** Extra content appended to the sidebar footer, beside the settings menu (mobile close, etc.). */
   sidebarFooterExtra?: ReactNode
+  /**
+   * Arbitrary content appended after `sections` inside the sidebar's nav scroll region (a tree, a
+   * filter panel, a project list, …). Hidden on the collapsed desktop rail; still present in the
+   * mobile drawer, which opens at full width — see `AppSidebarProps.navExtra`'s JSDoc for why.
+   * `AppSidebar` renders once and serves both the desktop rail and the mobile drawer (collapse
+   * styling is gated behind a `min-width: sm` media query, not a second render), so this slot
+   * reaches both.
+   */
+  sidebarNavExtra?: ReactNode
   /** Entries appended to the sidebar settings menu. */
   settingsMenuItems?: SettingsMenuItem[]
   /**
@@ -262,6 +271,7 @@ export function BasaltShell({
   renderNavLink,
   globalActions,
   sidebarFooterExtra,
+  sidebarNavExtra,
   settingsMenuItems,
   storageKey = 'basalt-sidebar-collapsed',
   collapsed: collapsedProp,
@@ -332,6 +342,7 @@ export function BasaltShell({
             onToggleCollapse={toggleCollapse}
             onClose={closeMobile}
             footerExtra={sidebarFooterExtra}
+            navExtra={sidebarNavExtra}
             {...(renderNavLink !== undefined && { renderNavLink })}
             {...(settingsMenuItems !== undefined && { settingsMenuItems })}
             {...(account !== undefined && { account })}