basalt-ui 1.27.0 → 1.28.0

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

@@ -4,7 +4,8 @@
  *
  * The mock sidebar has ZERO horizontal rules — separation comes from SPACING only. The one allowed
  * line is the child-list left guide (`--vx-divider`). Never reintroduce brand/section/footer
- * borders.
+ * borders. The column's trailing (right) edge is the `AppShell.Navbar` region seam
+ * (docs/DESIGN-SPEC.md §5) and is not this module's to draw.
  *
  * The active tint and icon-accent color live in the Mantine theme
  * (`NavLink.extend` + `theme/nav-link.module.css`) so they apply to EVERY render path, including a
@@ -39,28 +40,31 @@
 }
 
 /* Inactive rows: muted text + faint icon. Active rows keep the theme's ink text (via `--nl-color`)
- * untouched — this selector only ever matches when neither `data-active` nor `aria-current="page"`
- * is present. `[data-ancestor]` is excluded too: it gets its own ink/accent treatment below and
- * must not fall through to muted/faint here. */
-.link:not([data-active]):not([aria-current='page']):not([data-ancestor]) {
+ * untouched — this selector only ever matches when `data-active` is absent. `aria-current` is no
+ * longer part of the exclusion: `use-nav.ts` is the sole authority on active, stamping exactly one
+ * `data-active` winner, and keying this off `aria-current` too let the router's own looser match
+ * disagree with basalt's model. `[data-ancestor]` is excluded too: it gets its own ink/accent
+ * treatment below and must not fall through to muted/faint here. */
+.link:not([data-active]):not([data-ancestor]) {
   color: var(--vx-muted) !important;
 }
 
-.link:not([data-active]):not([aria-current='page']):not([data-ancestor])
+.link:not([data-active]):not([data-ancestor])
   :global(.mantine-NavLink-section[data-position='left']) {
   color: var(--vx-faint);
 }
 
-/* Hover — ink-6% tint + ink text, for inactive rows only (an active row already carries the
- * theme's stronger ink-9% tint and keeps its own hover via `--nl-hover`; an ancestor row gets its
- * own hover rule below so its accent icon survives the pointer). */
+/* Hover — ink-5% tint + ink text, for inactive rows only (an active row carries the theme's
+ * stronger 12% accent fill via `theme/nav-link.module.css` and keeps its own accent hover; an
+ * ancestor row gets its own hover rule below so its accent icon survives the pointer). Dropped from
+ * 6% alongside the theme-level hover so it reads clearly below the active row's accent fill. */
 @media (hover: hover) {
-  .link:not([data-active]):not([aria-current='page']):not([data-ancestor]):hover {
-    background-color: color-mix(in srgb, var(--vx-ink) 6%, transparent) !important;
+  .link:not([data-active]):not([data-ancestor]):hover {
+    background-color: color-mix(in srgb, var(--vx-ink) 5%, transparent) !important;
     color: var(--vx-ink) !important;
   }
 
-  .link:not([data-active]):not([aria-current='page']):not([data-ancestor]):hover
+  .link:not([data-active]):not([data-ancestor]):hover
     :global(.mantine-NavLink-section[data-position='left']) {
     color: var(--vx-ink);
   }
@@ -68,12 +72,12 @@
 
 /*
  * Ancestor row (`SidebarItem.ancestor` — a parent on the path to the active row, never active
- * itself, never `aria-current`): must read visibly WEAKER than active and visibly STRONGER than a
- * hovered inactive row, since all three now share the same 6%/9% ink-tint family. Active carries a
- * persistent `--nl-bg` ink-9% fill + weight 600 (theme `nav-link.module.css`); a hovered inactive
- * row carries a transient ink-6% fill. An ancestor therefore gets NO fill at rest (unlike active)
- * and NO weight change (still 400, unlike active's 600) — only the ink label + accent icon that an
- * active row also carries, so it reads as "on the path" without claiming to BE the destination.
+ * itself, never `data-active`): must read visibly WEAKER than active and visibly STRONGER than a
+ * hovered inactive row. Active carries a persistent accent-12% fill + weight 600 (theme
+ * `nav-link.module.css`); a hovered inactive row carries a transient ink-5% fill. An ancestor
+ * therefore gets NO fill at rest (unlike active) and NO weight change (still 400, unlike active's
+ * 600) — only the ink label + accent icon that an active row also carries, so it reads as "on the
+ * path" without claiming to BE the destination.
  */
 .link[data-ancestor] {
   color: var(--vx-ink) !important;
@@ -98,70 +102,18 @@
 }
 
 /*
- * Icon-only ghost buttons in shell chrome (collapse toggle, mobile close) — docs/DESIGN-SPEC.md
- * §5: transparent, faint icon, hover ink-6% + ink, radius 6. `!important` for the same reason as
- * the nav-row overrides above: these compete with Mantine's own compiled ActionIcon variant CSS.
- */
-.ghostIcon {
-  color: var(--vx-faint) !important;
-  border-radius: var(--vx-radius-ctrl) !important;
-}
-
-.ghostIcon:hover {
-  background-color: color-mix(in srgb, var(--vx-ink) 6%, transparent) !important;
-  color: var(--vx-ink) !important;
-}
-
-/*
- * Brand row — NO border (the mock's brand row has none; the header divider exists only over the
- * content column). Spacing alone (12px bottom padding) separates it from the nav.
- */
-.brand {
-  justify-content: space-between;
-  padding: var(--vx-space-sidebar-brand-inset-top) var(--vx-space-sidebar-brand-inset-x)
-    var(--vx-space-sidebar-region-gap);
-  flex-shrink: 0;
-}
-
-.brandLead {
-  min-width: 0;
-}
-
-/*
- * Search slot — fixed row between the brand and the nav scroll region. Horizontal padding aligns
- * the field with the brand lead / nav column; the bottom gap opens the nav region the same way the
- * brand row's own bottom padding does.
+ * Search slot — the sidebar's FIRST row now that the brand moved into the header
+ * (`app-brand.module.css`), optional (absent, the nav starts the column). `padding-block` is the
+ * only air above it, so the token that used to merely top up the brand band's centred `min-height`
+ * now owns the whole gap under the header seam.
  */
 /* No horizontal padding — the field spans the same width as the nav rows below it (both sit at the
  * `.root` 10px inset), so the search box edge-aligns with the nav column. */
 .searchSlot {
-  padding: 0 0 var(--vx-space-sidebar-region-gap);
+  padding-block: var(--vx-space-sidebar-region-gap);
   flex-shrink: 0;
 }
 
-/* Brand name — head font at stretch 88% (docs/DESIGN-SPEC.md §3); the 18px/550 land as `fz`/`fw`
- * props (inline, deterministic against Mantine's own Text base rule). */
-.brandName {
-  font-family: var(--basalt-font-head);
-  font-stretch: 88%;
-}
-
-/* Workspace switcher (`brand.menu`) — the brand name plus a chevron, as a row-shaped trigger. The
- * chevron is faint until hover so the brand still reads as the brand, not as a control. */
-.brandButton {
-  display: flex;
-  align-items: center;
-  gap: var(--vx-space-sidebar-section-label-gap);
-  min-width: 0;
-  padding: 0;
-  color: var(--vx-faint);
-  cursor: pointer;
-}
-
-.brandButton:hover {
-  color: var(--vx-ink);
-}
-
 /*
  * Nav scroll region — a Mantine ScrollArea, whose overlay scrollbar is absolutely positioned inside
  * the (position: relative; overflow: hidden) root, so it floats over the rows instead of reserving
@@ -186,7 +138,8 @@
 }
 
 /* Sections separate by SPACING only — 15px between sections, nothing above the first (the brand
- * row's own bottom padding already opens the region). */
+ * band's centred `min-height` already opens the region's air, and the optional search slot's own
+ * `padding-block` opens more when it renders). */
 .nav > div + div {
   margin-top: var(--vx-space-sidebar-section-gap);
 }
@@ -573,21 +526,32 @@
 }
 
 /*
- * Active child = accent text, weight 600, NO fill (docs/DESIGN-SPEC.md §5) — unlike a top-level
- * active row (ink-9% tint). Overrides the `--nl-*` custom properties the theme sets inline on the
- * SAME NavLink root, so `!important` is required.
+ * Active child = the SAME accent-tinted fill as a top-level active row (accent-12% resting,
+ * accent-16% hover), plus accent text, weight 600 (inherited from `.root[data-active]` in
+ * `theme/nav-link.module.css`, which every NavLink root carries regardless of nesting). Previously
+ * NO fill at rest — that read ambiguously once a hovered sibling landed in the same ink-tint family
+ * a stale ink-9% active fill also used; the shared accent family removes the ambiguity outright.
+ * `background-color` is set directly (not via `--nl-bg`): the theme's own active rule now paints
+ * `background-color` as a plain declaration rather than through that custom property, so overriding
+ * only the property would no longer reach the painted color. `[data-active]` alone is the hook —
+ * `use-nav.ts` is the sole authority on active, so `aria-current` is not matched here either.
  */
-.childList :global(.mantine-NavLink-root[data-active]),
-.childList :global(.mantine-NavLink-root[aria-current='page']) {
+.childList :global(.mantine-NavLink-root[data-active]) {
   --nl-color: var(--vx-accent) !important;
-  --nl-bg: transparent !important;
-  --nl-hover: color-mix(in srgb, var(--vx-ink) 5%, transparent) !important;
+  background-color: color-mix(in srgb, var(--vx-accent) 12%, transparent) !important;
 }
 
-/* Child hover (inactive) — ink-5% + ink, one step quieter than the parent rows' 6%. Outranks the
- * `.link` hover rule above on specificity. */
 @media (hover: hover) {
-  .childList :global(.mantine-NavLink-root:not([data-active]):not([aria-current='page'])):hover {
+  .childList :global(.mantine-NavLink-root[data-active]):hover {
+    background-color: color-mix(in srgb, var(--vx-accent) 16%, transparent) !important;
+  }
+}
+
+/* Child hover (inactive) — ink-5%, matching the top-level inactive hover now that both share the
+ * same percentage. `data-active` is excluded so an active child keeps its accent hover above.
+ * Outranks the `.link` hover rule above on specificity. */
+@media (hover: hover) {
+  .childList :global(.mantine-NavLink-root:not([data-active])):hover {
     background-color: color-mix(in srgb, var(--vx-ink) 5%, transparent) !important;
     color: var(--vx-ink) !important;
   }
@@ -609,19 +573,12 @@
 /*
  * Icon-rail (collapsed) — desktop only. Gated behind min-width: sm (48em) so the sidebar doesn't
  * exist at all below that breakpoint (see `MobileNav`) regardless of the persisted collapse flag.
- * Hide the brand text, section labels and nav labels; center the remaining icons.
+ * Hide the section labels and nav labels; center the remaining icons. The brand's own rail form
+ * lives in `app-brand.module.css` now, keyed off the same `data-collapsed` attribute.
  */
 @media (min-width: 48em) {
-  .root[data-collapsed] .brand {
-    justify-content: center;
-  }
-
-  .root[data-collapsed] .brandLead {
-    display: none;
-  }
-
   .root[data-collapsed] .searchSlot {
-    padding: 0 0 var(--vx-space-sidebar-region-gap);
+    padding-block: var(--vx-space-sidebar-region-gap);
     display: flex;
     justify-content: center;
   }

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

@@ -7,10 +7,6 @@ declare const classes: {
   readonly root: string
   readonly link: string
   readonly navItem: string
-  readonly brand: string
-  readonly brandLead: string
-  readonly brandName: string
-  readonly brandButton: string
   readonly searchSlot: string
   readonly navScroll: string
   readonly navViewport: string
@@ -28,7 +24,6 @@ declare const classes: {
   readonly sectionHeader: string
   readonly subnavDropdown: string
   readonly childList: string
-  readonly ghostIcon: string
   readonly block: string
   readonly blockHeader: string
   readonly blockHeaderButton: string

package/src/shell/app-sidebar.tsx

@@ -18,7 +18,6 @@
  * favor of this package.
  */
 import {
-  ActionIcon,
   Box,
   Collapse,
   Group,
@@ -34,6 +33,9 @@ import {
 import { useDisclosure } from '@mantine/hooks'
 import { useEffect, useRef } from 'react'
 import type { ReactNode } from 'react'
+import { cx } from '../common/props'
+import type { BasaltProps } from '../common/props'
+import { assertRequiredProps } from '../common/validate'
 import type { BrandConfig, SettingsMenuItem } from './index'
 import type { SidebarBlock, SidebarItem, SidebarSection } from '../nav/types'
 import { NavCountBadge } from './nav-count-badge'
@@ -56,15 +58,20 @@ import { VX } from '../tokens'
 import { useBasaltSpacing } from '../theme'
 import classes from './app-sidebar.module.css'
 
-export type AppSidebarProps = {
+export type AppSidebarProps = BasaltProps & {
   /**
-   * Brand identity. Supplying `menu` turns the brand row into a `Name ▾` workspace switcher —
+   * Brand identity. Supplying `menu` turns the header's brand into a `Name ▾` workspace switcher —
    * the entries are the existing `AccountMenuItem` shape, so a consumer already mapping account
    * actions needs no second vocabulary.
    */
   brand: BrandConfig & { menu?: AccountMenuItem[] }
   sections: SidebarSection[]
   collapsed: boolean
+  /**
+   * Consumed by the HEADER's brand zone (`app-brand.tsx`), not by this component — the collapse
+   * toggle moved up there with the brand. Still declared here because it is part of the sidebar's
+   * collapse contract and `BasaltShell` feeds both halves from one place.
+   */
   onToggleCollapse: () => void
   /**
    * Footer settings-menu entries (theme switcher, devtools, …) — supplied by the consumer.
@@ -123,27 +130,6 @@ export type AppSidebarProps = {
   blocks?: SidebarBlock[]
 }
 
-/** Inline collapse/expand chevrons — keeps the shell icon-dependency-free. */
-function IconCollapse({ collapsed }: { collapsed: boolean }) {
-  return (
-    <svg
-      width={18}
-      height={18}
-      viewBox="0 0 24 24"
-      fill="none"
-      stroke="currentColor"
-      strokeWidth={2}
-      strokeLinecap="round"
-      strokeLinejoin="round"
-      aria-hidden
-    >
-      <path d="M4 4h16v16H4z" />
-      <path d="M9 4v16" />
-      {collapsed ? <path d="M14 9l3 3l-3 3" /> : <path d="M16 9l-3 3l3 3" />}
-    </svg>
-  )
-}
-
 function IconGear() {
   return (
     <svg
@@ -169,54 +155,6 @@ const HOVER_CLOSE_DELAY = 200
 /** `settingsMenuItems` at or under this count render as flat rows — see the prop's JSDoc. */
 const FLAT_SETTINGS_MAX = 3
 
-/**
- * The brand name, and — when `brand.menu` is supplied — the workspace switcher it becomes.
- *
- * The entries are `AccountMenuItem`s: the shell already had exactly this row shape (label, icon,
- * onClick, danger) for the account menu, and a second vocabulary for the same dropdown would be
- * two things to keep in step for no gain. The chevron is inline text, not an icon dependency.
- */
-function BrandName({
-  brand,
-  menuWidth,
-}: {
-  brand: BrandConfig & { menu?: AccountMenuItem[] }
-  menuWidth: number
-}) {
-  const label = (
-    <Text className={classes.brandName} fz={VX.text.xl} fw={550}>
-      {brand.name}
-    </Text>
-  )
-  const menu = brand.menu
-  if (menu === undefined || menu.length === 0) return label
-
-  return (
-    <Menu position="bottom-start" withArrow width={menuWidth} zIndex={500}>
-      <Menu.Target>
-        <UnstyledButton className={classes.brandButton} aria-label={`${brand.name} workspace`}>
-          {label}
-          {/* `open` is the DOWN glyph — a switcher's affordance points at its dropdown, and this is
-              the same chevron every fold in the sidebar uses rather than a second one. */}
-          <IconChevron open />
-        </UnstyledButton>
-      </Menu.Target>
-      <Menu.Dropdown>
-        {menu.map((entry) => (
-          <Menu.Item
-            key={entry.key}
-            leftSection={entry.icon}
-            {...(entry.danger === true && { color: 'red' })}
-            onClick={entry.onClick}
-          >
-            {entry.label}
-          </Menu.Item>
-        ))}
-      </Menu.Dropdown>
-    </Menu>
-  )
-}
-
 /** True when the item or any descendant is active — drives inline child expansion. */
 function hasActiveDescendant(item: SidebarItem): boolean {
   if (item.active) return true
@@ -469,17 +407,24 @@ function NavItemRow({ item, collapsed }: { item: SidebarItem; collapsed: boolean
   )
 }
 
-export function AppSidebar({
-  brand,
-  sections,
-  collapsed,
-  onToggleCollapse,
-  settingsMenuItems,
-  settingsMenu = 'auto',
-  account,
-  search,
-  blocks,
-}: AppSidebarProps) {
+export function AppSidebar(props: AppSidebarProps) {
+  assertRequiredProps('AppSidebar', props, ['brand'])
+  const {
+    brand,
+    sections,
+    collapsed,
+    // `onToggleCollapse` is deliberately NOT read here any more — the toggle it drives moved into
+    // the header's leading zone with the brand (`app-brand.tsx`). The prop stays on
+    // `AppSidebarProps` because it is the shell's public seam for a consumer-owned collapse, and
+    // dropping it would break every call site for no gain.
+    settingsMenuItems,
+    settingsMenu = 'auto',
+    account,
+    search,
+    blocks,
+    className,
+    style,
+  } = props
   // 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
   // `tokens/palette.ts`).
@@ -570,36 +515,18 @@ export function AppSidebar({
     )
 
   return (
-    <Stack gap={0} h="100%" className={classes.root} data-collapsed={collapsed || undefined}>
-      <Group className={classes.brand} gap="sm" wrap="nowrap">
-        <Group className={classes.brandLead} gap="sm" wrap="nowrap">
-          {brand.logoSrc && (
-            <img
-              src={brand.logoSrc}
-              alt={brand.logoAlt ?? brand.name}
-              width={26}
-              height={26}
-              style={{ display: 'block' }}
-            />
-          )}
-          <BrandName brand={brand} menuWidth={step.sidebarAccountMenuWidth} />
-        </Group>
-        <ActionIcon
-          variant="subtle"
-          // A numeric size, not the named `"md"` — same opt-out as `connectivity-indicator.tsx`'s
-          // toolbar icon (see that comment): this is a plain collapse-toggle icon, not a control meant
-          // to match a `size="md"` Input/Button, so it must not pick up the theme's `ActionIcon.extend`
-          // control-height override. Reproduces Mantine's own static `--ai-size-md` (28px).
-          size={28}
-          visibleFrom="sm"
-          className={classes.ghostIcon}
-          onClick={onToggleCollapse}
-          aria-label={collapsed ? 'Expand sidebar' : 'Collapse sidebar'}
-        >
-          <IconCollapse collapsed={collapsed} />
-        </ActionIcon>
-      </Group>
-
+    <Stack
+      gap={0}
+      h="100%"
+      className={cx(classes.root, className)}
+      data-collapsed={collapsed || undefined}
+      {...(style !== undefined && { style })}
+    >
+      {/* NO brand row. It moved into the header's leading zone (`app-brand.tsx`) when the shell
+          dropped `layout="alt"`: with a full-width header, an `appShellHeaderHeight` brand band
+          here painted as a second 48px row under the header seam. The column now starts with
+          `SidebarSearch` — at the same inset it always had. `brand` stays a prop because
+          `brand.version` labels the settings footer below. */}
       {search && (
         <div className={classes.searchSlot}>
           <SidebarSearch {...search} collapsed={collapsed} />