basalt-ui 1.12.0 → 1.14.0

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 })}

package/src/surfaces.ts

@@ -385,7 +385,7 @@ export const SURFACES = {
     skill: ['basalt-app'],
     guardKinds: [],
     description:
-      'Mantine-styled thread-chat components over basalt-ui/agent: ThreadWorkspace, ThreadFeed, ThreadOutcomeCard, ThreadDetailPanel, Composer, ThreadTranscript (open part-renderer registry via its renderers/fallbackRenderer props), threadPartRenderers, ToolChip (Mantine-coupled). motion is required, not optional — ThreadFeed/ThreadDetailPanel import motion/react eagerly, so this subpath fails to resolve without it installed even though peerDependenciesMeta marks it optional (npm has no per-subpath optionality). remend is genuinely optional here — ThreadTranscript reaches it only through the lazy dynamic import() inside content/markdown.tsx.',
+      'Mantine-styled thread-chat components over basalt-ui/agent: ThreadWorkspace, ThreadFeed (variant/renderRow), ThreadFeedRow (inline-expanding Slack row, lazily mounted + kept mounted), ThreadOutcomeCard, ThreadDetailPanel, Composer, ThreadTranscript (open part-renderer registry via its renderers/fallbackRenderer props, per-message MessageAffordances, groupConsecutive, and an optional virtualize/height windowing mode whose VirtualizeOptions carry overscan/estimateSize/initialScroll — a virtualized transcript opens scrolled to the newest message unless initialScroll is "start"), threadPartRenderers, ToolChip (Mantine-coupled). motion is required, not optional — ThreadFeed/ThreadDetailPanel import motion/react eagerly, so this subpath fails to resolve without it installed even though peerDependenciesMeta marks it optional (npm has no per-subpath optionality). remend is genuinely optional here — ThreadTranscript reaches it only through the lazy dynamic import() inside content/markdown.tsx, and @tanstack/react-virtual the same way through the lazy import() behind ThreadTranscript virtualize (absent peer degrades to an unwindowed, height-bound pane).',
     optionalPeers: [
       'ai',
       'motion',
@@ -397,6 +397,7 @@ export const SURFACES = {
       '@shikijs/langs',
       '@shikijs/themes',
       'beautiful-mermaid',
+      '@tanstack/react-virtual',
     ],
     forbiddenImports: [],
   },

package/src/theme/shadow-surfaces.test.ts

@@ -386,6 +386,15 @@ export const SHADOW_SURFACES: readonly ShadowSurfaceEntry[] = [
     site: 'default',
     roundedBy: 'borderRadius: VX.radiusCard (co-declared in the same inline style object).',
   },
+  {
+    file: 'agent-chat/thread-feed-row.tsx',
+    site: 'default',
+    roundedBy:
+      'borderRadius: VX.radiusCard (co-declared in the same inline style object as the shadow). ' +
+      'This box also carries overflow: hidden, which is what lets the header button and the ' +
+      'expanded body square off against the row’s rounded corners; an element’s own overflow ' +
+      'never clips its own ring, so the shadow is unaffected.',
+  },
   // ── agent ────────────────────────────────────────────────────────────────────────────────────
   {
     file: 'agent/stick-to-bottom.tsx',