basalt-ui 1.27.0 → 1.29.0

package/src/router-tanstack/use-nav.test.tsx

@@ -1,187 +0,0 @@
-/**
- * `useNav`'s active-resolution pass, under a REAL TanStack memory router — the half that cannot be
- * tested headlessly (`matchRoute`/`useRouterState` both need a live router). The fixture below
- * mirrors every collision shape the playground's own `demo/nav-model.tsx` actually has: a root `/`
- * item, a `/dashboard` parent with three children, flat siblings, a same-path duplicate
- * (`reports`/`components`, mirroring the playground's disabled-placeholder shape), and a
- * search-bearing link (mirroring `dashboardFilters.linkSearch`-style destinations).
- *
- * The harness is modeled on `controls/controls.router.test.tsx`'s `mountPage`, narrowed to a
- * headless probe: `useNav` renders no JSX itself (`./router-tanstack` is a no-JSX barrel), so the
- * probe component only reads its return value into a sink — no `MantineProvider` needed.
- */
-import { cleanup, render, waitFor } from '@testing-library/react'
-import { describe, expect, test } from 'bun:test'
-import type { ReactNode } from 'react'
-import {
-  Outlet,
-  RouterProvider,
-  createMemoryHistory,
-  createRootRoute,
-  createRoute,
-  createRouter,
-} from '@tanstack/react-router'
-import type { SidebarItem, SidebarSection } from '../nav/types'
-import type { AnyNavItem } from './nav'
-import { defineNav, navGroup } from './nav'
-import { useNav } from './use-nav'
-
-const NAV = defineNav({
-  groups: [
-    navGroup({ id: 'main', label: 'Main' }, [
-      { id: 'home', label: 'Home', link: { to: '/' } },
-      {
-        id: 'dashboard',
-        label: 'Dashboard',
-        // A store-backed destination (law C10's shape) — `search` rides the link like every
-        // other field; `matchOf` below never reads it, so it must not affect matching either.
-        link: { to: '/dashboard', search: { window: '30d' } },
-        children: [
-          { id: 'dashboard-sessions', label: 'Sessions', link: { to: '/dashboard/sessions' } },
-          { id: 'dashboard-traffic', label: 'Traffic', link: { to: '/dashboard/traffic' } },
-          { id: 'dashboard-revenue', label: 'Revenue', link: { to: '/dashboard/revenue' } },
-        ],
-      },
-      { id: 'mobile-nav-pill', label: 'Mobile nav pill', link: { to: '/mobile-nav-pill' } },
-      {
-        id: 'controls-mobile',
-        label: 'Controls (mobile)',
-        link: { to: '/controls-mobile' },
-      },
-      { id: 'components', label: 'Components', link: { to: '/components' } },
-      { id: 'charts-page', label: 'Charts', link: { to: '/charts' } },
-      // The playground's `reports` shape: a disabled placeholder that deliberately borrows an
-      // already-covered route rather than inventing one. Declared AFTER `components`, so the
-      // definition-order tie-break keeps `components` the winner at `/components`.
-      { id: 'reports', label: 'Reports', disabled: true, link: { to: '/components' } },
-    ]),
-  ],
-})
-
-const ROUTE_PATHS = [
-  '/',
-  '/dashboard',
-  '/dashboard/sessions',
-  '/dashboard/traffic',
-  '/dashboard/revenue',
-  '/mobile-nav-pill',
-  '/controls-mobile',
-  '/components',
-  '/charts',
-]
-
-type NavProbeOpts = { isActive?: (item: AnyNavItem) => boolean }
-type NavResult = { sections: SidebarSection[] }
-type Sink = { current: NavResult | null }
-
-/** Depth-first flatten of the rendered `SidebarSection[]` — the same shape every downstream reader
- * (the sidebar, the mobile bar, the breadcrumb) walks. */
-function flattenItems(sections: SidebarSection[]): SidebarItem[] {
-  const out: SidebarItem[] = []
-  const walk = (items: SidebarItem[]): void => {
-    for (const item of items) {
-      out.push(item)
-      if (item.children) walk(item.children)
-    }
-  }
-  for (const section of sections) walk(section.items)
-  return out
-}
-
-async function mountNav(entry: string, opts?: NavProbeOpts): Promise<Sink> {
-  const sink: Sink = { current: null }
-
-  function NavProbe(): ReactNode {
-    const nav = useNav(NAV, opts)
-    sink.current = { sections: nav.sections }
-    return null
-  }
-
-  const rootRoute = createRootRoute({
-    component: () => (
-      <>
-        <NavProbe />
-        <Outlet />
-      </>
-    ),
-  })
-  const children = ROUTE_PATHS.map((path) =>
-    createRoute({ getParentRoute: () => rootRoute, path, component: () => null }),
-  )
-  const router = createRouter({
-    routeTree: rootRoute.addChildren(children),
-    history: createMemoryHistory({ initialEntries: [entry] }),
-  })
-
-  render(<RouterProvider router={router} />)
-  await waitFor(() => {
-    expect(router.state.status).toBe('idle')
-  })
-  return sink
-}
-
-describe('useNav — exclusivity', () => {
-  test('exactly one row is active at every route in the definition', async () => {
-    for (const path of ROUTE_PATHS) {
-      const sink = await mountNav(path)
-      const items = flattenItems(sink.current!.sections)
-      const activeCount = items.filter((item) => item.active).length
-      expect(activeCount).toBe(1)
-      cleanup()
-    }
-  })
-
-  test('the deepest match wins — a child route does not also light its parent', async () => {
-    const sink = await mountNav('/dashboard/sessions')
-    const items = flattenItems(sink.current!.sections)
-    const dashboard = items.find((item) => item.key === 'dashboard')
-    const sessions = items.find((item) => item.key === 'dashboard-sessions')
-    expect(dashboard?.active).toBe(false)
-    expect(sessions?.active).toBe(true)
-  })
-
-  test('the parent of the active row is an ancestor, not active', async () => {
-    const sink = await mountNav('/dashboard/sessions')
-    const items = flattenItems(sink.current!.sections)
-    const dashboard = items.find((item) => item.key === 'dashboard')
-    expect(dashboard?.ancestor).toBe(true)
-    expect(dashboard?.active).toBe(false)
-  })
-
-  test('a same-path duplicate destination is neither active nor an ancestor', async () => {
-    const sink = await mountNav('/components')
-    const items = flattenItems(sink.current!.sections)
-    const components = items.find((item) => item.key === 'components')
-    const reports = items.find((item) => item.key === 'reports')
-    expect(components?.active).toBe(true)
-    expect(reports?.active).toBe(false)
-    expect(reports?.ancestor).toBeFalsy()
-  })
-
-  test("'/' stays exact — the root never lights on a nested route", async () => {
-    const sink = await mountNav('/dashboard')
-    const items = flattenItems(sink.current!.sections)
-    const home = items.find((item) => item.key === 'home')
-    expect(home?.active).toBe(false)
-    expect(home?.ancestor).toBeFalsy()
-  })
-
-  test('an item whose exact route is never visited still lights on a descendant route', async () => {
-    // `/dashboard` itself is never the visited entry in this test — only its descendant is —
-    // proving the fix kept `fuzzy: true` as the default rather than flipping every item to exact.
-    const sink = await mountNav('/dashboard/traffic')
-    const items = flattenItems(sink.current!.sections)
-    const dashboard = items.find((item) => item.key === 'dashboard')
-    expect(dashboard?.ancestor).toBe(true)
-    expect(dashboard?.active).toBe(false)
-  })
-
-  test('an isActive override cannot light two rows either', async () => {
-    const sink = await mountNav('/', {
-      isActive: (item) => item.id === 'components' || item.id === 'charts-page',
-    })
-    const items = flattenItems(sink.current!.sections)
-    const activeCount = items.filter((item) => item.active).length
-    expect(activeCount).toBe(1)
-  })
-})

package/src/section/index.ts

@@ -1 +0,0 @@
-export { Section, type SectionProps } from './section'

package/src/section/section.test.tsx

@@ -1,204 +0,0 @@
-/**
- * `Section` — the tier-2 heading composer (docs/CONTROLS-SPEC.md §2.2): the collapse contract
- * (persisted vs local, header stays drawn, body unmounts, tabs hide), the scroll-anchor style, and
- * the ≤3-actions dev warning (C6).
- */
-import { MantineProvider } from '@mantine/core'
-import { fireEvent, render, screen } from '@testing-library/react'
-import { beforeEach, describe, expect, spyOn, test } from 'bun:test'
-import type { ReactElement } from 'react'
-import { Section } from './section'
-
-function renderWith(node: ReactElement) {
-  return render(<MantineProvider>{node}</MantineProvider>)
-}
-
-beforeEach(() => {
-  window.localStorage.clear()
-})
-
-describe('Section composes WidgetHeader at the section tier', () => {
-  test('renders an h2 carrying the title', () => {
-    renderWith(
-      <Section title="Revenue">
-        <div>body</div>
-      </Section>,
-    )
-    expect(screen.getByRole('heading', { level: 2, name: 'Revenue' })).toBeDefined()
-  })
-})
-
-describe('collapsible', () => {
-  test('the header stays drawn when closed; only the body unmounts', () => {
-    renderWith(
-      <Section title="Usage" collapsible>
-        <div>body content</div>
-      </Section>,
-    )
-    expect(screen.getByRole('heading', { level: 2, name: 'Usage' })).toBeDefined()
-    expect(screen.getByText('body content')).toBeDefined()
-
-    fireEvent.click(screen.getByRole('button', { name: 'Collapse section' }))
-
-    expect(screen.getByRole('heading', { level: 2, name: 'Usage' })).toBeDefined()
-    expect(screen.queryByText('body content')).toBeNull()
-  })
-
-  test('tabs hide while collapsed', () => {
-    renderWith(
-      <Section title="Usage" collapsible tabs={<div>the tabs</div>}>
-        <div>body</div>
-      </Section>,
-    )
-    expect(screen.getByText('the tabs')).toBeDefined()
-    fireEvent.click(screen.getByRole('button', { name: 'Collapse section' }))
-    expect(screen.queryByText('the tabs')).toBeNull()
-  })
-
-  test('an unpersisted fold (no persistKey) does not touch localStorage', () => {
-    renderWith(
-      <Section title="Usage" collapsible>
-        <div>body</div>
-      </Section>,
-    )
-    fireEvent.click(screen.getByRole('button', { name: 'Collapse section' }))
-    expect(window.localStorage.length).toBe(0)
-  })
-
-  test('persistKey persists the fold state under basalt:section:<key>', () => {
-    renderWith(
-      <Section title="Usage" collapsible persistKey="usage">
-        <div>body</div>
-      </Section>,
-    )
-    fireEvent.click(screen.getByRole('button', { name: 'Collapse section' }))
-
-    const raw = window.localStorage.getItem('basalt:section:usage')
-    expect(raw).not.toBeNull()
-    expect(JSON.parse(raw ?? '{}')).toMatchObject({ value: false })
-  })
-})
-
-describe('id — the scroll-anchor contract', () => {
-  test('sets the id and a scrollMarginTop clearing both sticky bars', () => {
-    const { container } = renderWith(
-      <Section id="usage" title="Usage">
-        <div>body</div>
-      </Section>,
-    )
-    const root = container.querySelector('#usage')
-    expect(root).not.toBeNull()
-    const style = root?.getAttribute('style') ?? ''
-    expect(style).toContain('scroll-margin-top')
-    expect(style).toContain('--app-shell-header-height')
-    expect(style).toContain('--basalt-page-bar-h')
-  })
-
-  test('omitting id sets neither an id nor the anchor style', () => {
-    const { container } = renderWith(
-      <Section title="Usage">
-        <div>body</div>
-      </Section>,
-    )
-    const root = container.firstElementChild
-    expect(root?.id).toBe('')
-    expect(root?.getAttribute('style')).toBeNull()
-  })
-})
-
-// Relies on the default test-runner NODE_ENV being non-production (`isDev()` true), matching
-// `data/data-table.test.tsx`'s manualPagination dev-throw tests — no explicit env override needed.
-describe('≤3 actions — the dev-only budget warning (C6)', () => {
-  // `Children.count` (like every `Children.*` helper) does not recurse into a Fragment passed as
-  // a single node — an ARRAY of actions is what the count actually sees, same shape a consumer
-  // building the list programmatically would pass.
-  test('4 actions warns', () => {
-    const warn = spyOn(console, 'warn').mockImplementation(() => {})
-    renderWith(
-      <Section
-        title="Usage"
-        actions={[1, 2, 3, 4].map((n) => (
-          <button key={n} type="button">
-            {n}
-          </button>
-        ))}
-      >
-        <div>body</div>
-      </Section>,
-    )
-    expect(warn).toHaveBeenCalledTimes(1)
-    expect(String(warn.mock.calls[0]?.[0])).toContain('≤3 budget')
-    warn.mockRestore()
-  })
-
-  test('3 actions does not warn', () => {
-    const warn = spyOn(console, 'warn').mockImplementation(() => {})
-    renderWith(
-      <Section
-        title="Usage"
-        actions={[1, 2, 3].map((n) => (
-          <button key={n} type="button">
-            {n}
-          </button>
-        ))}
-      >
-        <div>body</div>
-      </Section>,
-    )
-    expect(warn).not.toHaveBeenCalled()
-    warn.mockRestore()
-  })
-})
-
-describe('defaultOpen', () => {
-  test('defaultOpen={false} opens collapsed, and the chevron still expands it', () => {
-    renderWith(
-      <Section title="Usage" collapsible defaultOpen={false}>
-        <div>body content</div>
-      </Section>,
-    )
-    expect(screen.queryByText('body content')).toBeNull()
-
-    fireEvent.click(screen.getByRole('button', { name: 'Expand section' }))
-    expect(screen.getByText('body content')).toBeDefined()
-  })
-
-  test('a persisted value outranks it — a section the reader opened stays open', () => {
-    window.localStorage.setItem('basalt:section:usage', JSON.stringify({ v: 1, value: true }))
-    renderWith(
-      <Section title="Usage" collapsible persistKey="usage" defaultOpen={false}>
-        <div>body content</div>
-      </Section>,
-    )
-    expect(screen.getByText('body content')).toBeDefined()
-  })
-})
-
-describe('summary — visible collapsed or not', () => {
-  test('a collapsed section still states its headline figures', () => {
-    renderWith(
-      <Section title="Usage" collapsible summary={<span>48,204 requests</span>}>
-        <div>body content</div>
-      </Section>,
-    )
-    expect(screen.getByText('48,204 requests')).toBeDefined()
-
-    fireEvent.click(screen.getByRole('button', { name: 'Collapse section' }))
-
-    expect(screen.queryByText('body content')).toBeNull()
-    expect(screen.getByText('48,204 requests')).toBeDefined()
-  })
-
-  test('it renders under the header, above where the body starts', () => {
-    renderWith(
-      <Section title="Usage" summary={<span>48,204 requests</span>}>
-        <div>body content</div>
-      </Section>,
-    )
-    const summary = screen.getByText('48,204 requests').parentElement
-    expect(
-      summary?.previousElementSibling?.contains(screen.getByRole('heading', { level: 2 })),
-    ).toBe(true)
-    expect(summary?.nextElementSibling?.contains(screen.getByText('body content'))).toBe(true)
-  })
-})

package/src/section/section.tsx

@@ -1,220 +0,0 @@
-/**
- * Section — the tier-2 heading composer (docs/CONTROLS-SPEC.md §2.2, law C8): a page-level content
- * grouping under `WidgetHeader tier="section"`. Named exactly `Section` — not `PageSection` — so
- * the existing `shadow-basalt-export` guard fires on a consumer's own hand-rolled `Section` /
- * `PageSection` / `SectionTitle` / `SectionHeading` copy with zero new rule code.
- *
- * No `variant`, no border/background of its own — one shaded container level per page belongs to
- * the cards inside a Section (`ChartCard`/`StatCard`), not to the Section itself.
- *
- * `actions` and `tabs` are two separate `CtlSlot`-wrapped fragments rendered in the header row
- * (C1/C5) via `WidgetHeader`'s single `actions` slot; `tabs` hides while the section is collapsed.
- * `Section` holds ≤3 actions (C6) — past that, a dev-only console warning fires (the AST guard
- * lands in wave 6).
- *
- * `collapsible` state persists via `createPersistedState('basalt:section:<persistKey>')` when
- * `persistKey` is given, else it is local `useState` — the header always stays drawn, only the body
- * unmounts. `defaultOpen` picks the state a first visit lands on; a persisted value outranks it.
- *
- * `summary` renders under the header and survives a collapse. That is the whole reason it is a
- * separate slot rather than the first child: a section a reader folded away should still state its
- * headline figures, or folding it costs them the numbers they were watching.
- *
- * `id` turns the root into a scroll anchor, offset by both the shell header height and the
- * `PageBar`'s measured height (`--basalt-page-bar-h`, wave 4) so an anchor-jumped heading isn't
- * hidden under either sticky bar.
- *
- * @example
- * import { Section, StatCard } from 'basalt-ui'
- *
- * <Section title="Revenue" icon={<IconChartBar size={16} />} count={rows.length}>
- *   <StatCard title="MRR" value="$48,204" delta={3.1} />
- * </Section>
- *
- * @example
- * // Collapsible, with tabs and a persisted fold state.
- * <Section
- *   id="usage"
- *   title="Usage"
- *   collapsible
- *   persistKey="usage"
- *   tabs={<ViewTabs field={viewField} />}
- * >
- *   <UsageChart />
- * </Section>
- */
-import { Children, useId, useMemo, useState } from 'react'
-import type { ReactNode } from 'react'
-import { CtlSlot } from '../theme'
-import { createPersistedState } from '../state'
-import { WidgetHeader } from '../widget-header'
-import type { WidgetHeaderProps } from '../widget-header'
-import classes from './section.module.css'
-
-export type SectionProps = Omit<WidgetHeaderProps, 'tier'> & {
-  /** Rendered in the header row, in its own `CtlSlot` — hidden while the section is collapsed. */
-  tabs?: ReactNode
-  /** Renders a chevron toggle in the header; the header stays drawn when closed, only `children`
-   * (and `tabs`) unmount. @default false */
-  collapsible?: boolean
-  /** Persists the fold state at `basalt:section:<persistKey>`. Omit for a local, unpersisted fold
-   * (`useState`). */
-  persistKey?: string
-  /** The fold state a section opens on, respected only while no persisted value exists — a section
-   * a reader has closed stays closed. `false` is what a long secondary block wants. @default true */
-  defaultOpen?: boolean
-  /** Rendered directly under the header and ALWAYS visible, collapsed or not: a collapsed section
-   * still states its headline figures, which is what makes collapsing it a real option. Keep it to
-   * one row — the body is what `children` is for. */
-  summary?: ReactNode
-  /** Turns the root into a scroll anchor (`id` + `scroll-margin-top` cleared for both sticky bars). */
-  id?: string
-  children: ReactNode
-}
-
-/** The house dev gate (`data/data-table.tsx`, `provider`, `charts/kinds/BandStrip` use the same
- * expression): `basaltViteConfig` defines `process.env.NODE_ENV`, so a production bundle
- * constant-folds this to `false` and drops the warning. Read per call, never hoisted. */
-function isDev(): boolean {
-  return process.env['NODE_ENV'] !== 'production'
-}
-
-/** ≤3 actions is C6 (docs/CONTROLS-SPEC.md §1) — the AST guard (`basalt/page-bar-budget`) lands in
- * wave 6; this is the dev-only stopgap so the budget is visible before the lint rule exists. */
-function warnPastActionBudget(title: string, actions: ReactNode): void {
-  if (!isDev()) return
-  const count = Children.count(actions)
-  if (count <= 3) return
-  console.warn(
-    `Section "${title}": ${count} actions exceeds the ≤3 budget (docs/CONTROLS-SPEC.md C6) — ` +
-      'move the rest behind a menu.',
-  )
-}
-
-const UNPERSISTED_KEY = '__local__'
-
-/** Collapse state — `createPersistedState` when `persistKey` is given, else local `useState`.
- * Both hooks are always called (stable order across renders); only the unpersisted branch's setter
- * is ever invoked when `persistKey` is absent, so no unpersisted Section writes to storage. */
-function useSectionOpen(
-  persistKey: string | undefined,
-  defaultOpen: boolean,
-): readonly [boolean, (next: boolean) => void] {
-  const [localOpen, setLocalOpen] = useState(defaultOpen)
-  const usePersistedOpen = useMemo(
-    () =>
-      createPersistedState<boolean>({
-        key: `section:${persistKey ?? UNPERSISTED_KEY}`,
-        version: 1,
-        initial: defaultOpen,
-      }),
-    [persistKey, defaultOpen],
-  )
-  const [persistedOpen, setPersistedOpen] = usePersistedOpen()
-
-  if (persistKey !== undefined) return [persistedOpen, setPersistedOpen] as const
-  return [localOpen, setLocalOpen] as const
-}
-
-function ChevronToggle({
-  open,
-  onToggle,
-  controls,
-}: {
-  open: boolean
-  onToggle: () => void
-  controls: string
-}) {
-  return (
-    <button
-      type="button"
-      className={classes.chevron}
-      data-open={open}
-      aria-expanded={open}
-      aria-controls={controls}
-      aria-label={open ? 'Collapse section' : 'Expand section'}
-      onClick={onToggle}
-    >
-      <svg
-        width={12}
-        height={12}
-        viewBox="0 0 24 24"
-        fill="none"
-        stroke="currentColor"
-        strokeWidth={2.5}
-        aria-hidden="true"
-      >
-        <path d="M6 9l6 6 6-6" strokeLinecap="round" strokeLinejoin="round" />
-      </svg>
-    </button>
-  )
-}
-
-export function Section({
-  title,
-  icon,
-  subtitle,
-  info,
-  value,
-  delta,
-  deltaPeriod,
-  sparkline,
-  count,
-  actions,
-  tabs,
-  collapsible = false,
-  persistKey,
-  defaultOpen = true,
-  summary,
-  id,
-  children,
-}: SectionProps) {
-  const [open, setOpen] = useSectionOpen(persistKey, defaultOpen)
-  const bodyId = useId()
-
-  if (actions !== undefined) warnPastActionBudget(title, actions)
-
-  const headerActions =
-    tabs !== undefined || actions !== undefined || collapsible ? (
-      <>
-        {tabs !== undefined && open && <CtlSlot>{tabs}</CtlSlot>}
-        {actions !== undefined && <CtlSlot>{actions}</CtlSlot>}
-        {collapsible && (
-          <ChevronToggle open={open} onToggle={() => setOpen(!open)} controls={bodyId} />
-        )}
-      </>
-    ) : undefined
-
-  return (
-    <div
-      className={classes.root}
-      {...(id !== undefined && { id })}
-      {...(id !== undefined && {
-        style: {
-          scrollMarginTop:
-            'calc(var(--app-shell-header-height, 0px) + var(--basalt-page-bar-h, 0px))',
-        },
-      })}
-    >
-      <WidgetHeader
-        tier="section"
-        title={title}
-        {...(icon !== undefined && { icon })}
-        {...(subtitle !== undefined && { subtitle })}
-        {...(info !== undefined && { info })}
-        {...(value !== undefined && { value })}
-        {...(delta !== undefined && { delta })}
-        {...(deltaPeriod !== undefined && { deltaPeriod })}
-        {...(sparkline !== undefined && { sparkline })}
-        {...(count !== undefined && { count })}
-        {...(headerActions !== undefined && { actions: headerActions })}
-      />
-      {summary !== undefined && <div className={classes.summary}>{summary}</div>}
-      {open && (
-        <div id={bodyId} className={classes.body}>
-          {children}
-        </div>
-      )}
-    </div>
-  )
-}