basalt-ui 1.27.0 → 1.29.0

package/src/shell/app-mobile-nav.tsx

@@ -20,6 +20,10 @@ import { Drawer, Menu, NavLink, ScrollArea, Stack, Text, UnstyledButton } from '
 import { useReducedMotion } from '@mantine/hooks'
 import { Fragment, useState } from 'react'
 import type { MouseEvent, ReactElement, ReactNode } from 'react'
+import { cx } from '../common/props'
+import type { BasaltProps } from '../common/props'
+import { assertRequiredProps } from '../common/validate'
+import { SCROLLPORT_ATTRIBUTE } from '../common/scroll-parent'
 import type {
   MobileNavConfig,
   MobileNavGroup,
@@ -30,7 +34,7 @@ import type {
   SidebarItem,
   SidebarListBlock,
   SidebarProgressBlock,
-} from '../nav/types'
+} from './nav-types'
 import type { BasaltAccountProps } from './account-types'
 import type { SettingsMenuItem } from './index'
 import { NavCountBadge } from './nav-count-badge'
@@ -51,7 +55,7 @@ type LinkSlot = Extract<MobileNavSlot, { kind: 'link' }>
 /** A slot that raises a surface. `menu` and `sheet` share one shape — only the renderer differs. */
 type SurfaceSlot = Exclude<MobileNavSlot, LinkSlot>
 
-export type MobileNavProps = {
+export type MobileNavProps = BasaltProps & {
   /** The projection from `projectMobileNav` — `BasaltShell` builds it, memoized. */
   model: MobileNavModel
   config?: MobileNavConfig | undefined
@@ -91,6 +95,26 @@ function IconMore() {
   )
 }
 
+/** The `ActionRow.active` glyph — same shape as `app-sidebar.tsx`'s own copy (no icon dependency
+ * to import between the two render trees). */
+function IconCheck() {
+  return (
+    <svg
+      width={14}
+      height={14}
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth={2.5}
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      aria-hidden
+    >
+      <path d="M5 12l5 5l10 -10" />
+    </svg>
+  )
+}
+
 /** A row the More surface derives from `account`/`settingsMenuItems` — never a destination. */
 type ActionRow = {
   key: string
@@ -98,6 +122,8 @@ type ActionRow = {
   icon?: ReactNode
   danger?: boolean
   onClick?: ((e: MouseEvent<HTMLElement>) => void) | undefined
+  /** Mirrors `SettingsMenuItem.active` — a trailing check + `aria-current` in every row form. */
+  active?: boolean
 }
 
 /**
@@ -168,6 +194,7 @@ function settingsRows(items: SettingsMenuItem[] | undefined): ActionRow[] {
     label: item.label,
     icon: item.icon,
     onClick: item.onClick,
+    ...(item.active !== undefined && { active: item.active }),
   }))
 }
 
@@ -230,8 +257,10 @@ const menuActionRow = (row: ActionRow) => (
     key={row.key}
     className={classes.menuItem}
     leftSection={row.icon}
+    rightSection={row.active ? <IconCheck /> : undefined}
     {...(row.danger ? { color: 'red' } : {})}
     onClick={(event: MouseEvent<HTMLElement>) => row.onClick?.(event)}
+    aria-current={row.active ? 'true' : undefined}
   >
     {row.label}
   </Menu.Item>
@@ -251,7 +280,10 @@ export function MobileNav({
   account,
   settingsMenuItems,
   blocks,
+  className,
+  style,
 }: MobileNavProps): ReactElement {
+  assertRequiredProps('MobileNav', { model }, ['model'], { model: '`model.slots`' })
   // `openKey` is the ONLY slot state here, and it is keyed by slot rather than holding a slot
   // object: `sections` identity churning on every consumer render must not close an open menu.
   const [openKey, setOpenKey] = useState<string | null>(null)
@@ -264,10 +296,19 @@ export function MobileNav({
 
   const close = () => setOpenKey(null)
 
-  /** §2.5 — re-tapping the ACTIVE slot scrolls to top instead of pushing a redundant history entry. */
+  /**
+   * §2.5 — re-tapping the ACTIVE slot scrolls to top instead of pushing a redundant history entry.
+   *
+   * `AppShell.Main` is the shell's scrollport (`app-main.module.css`), so `document.scrollingElement`
+   * scrolls nothing inside a shell and the tap read as dead. The declared handle comes FIRST after
+   * the consumer's own override, and the document stays the fallback for a shell-less app.
+   */
   const scrollToTop = () => {
     const target =
-      config?.getScrollElement?.() ?? document.scrollingElement ?? document.documentElement
+      config?.getScrollElement?.() ??
+      document.querySelector(`[${SCROLLPORT_ATTRIBUTE}]`) ??
+      document.scrollingElement ??
+      document.documentElement
     target.scrollTo({ top: 0, behavior: reduceMotion ? 'auto' : 'smooth' })
   }
 
@@ -464,11 +505,13 @@ export function MobileNav({
       classNames={{ root: classes.row }}
       label={row.label}
       leftSection={row.icon}
+      rightSection={row.active ? <IconCheck /> : undefined}
       {...(row.danger ? { color: 'red' } : {})}
       onClick={(event: MouseEvent<HTMLElement>) => {
         row.onClick?.(event)
         close()
       }}
+      aria-current={row.active ? 'true' : undefined}
     />
   )
 
@@ -549,19 +592,31 @@ export function MobileNav({
           timingFunction: 'cubic-bezier(0.32, 0.72, 0, 1)',
         }}
       >
-        <ScrollArea.Autosize mah="62dvh" type="scroll">
-          <Stack gap="xs">
+        {/* `offsetScrollbars="present"` reserves the overlay bar's own gutter (Mantine's
+            `data-offset-scrollbars`) instead of floating it over the rows' trailing edge — the
+            sheet has no spare right inset the way the sidebar's `.navScroll` bleed does. The outer
+            Stack's gap and the group Stack's `gap={2}` both reuse the sidebar's section rhythm
+            (`--vx-space-sidebar-section-gap`/`-section-label-gap`); the inner `gap={1}` is the
+            sidebar's own row-to-row gap (`app-sidebar.tsx`'s nav `Stack gap={1}`).
+            `scrollbarSize={8}` (down from Mantine's 12px default) is the tightest gutter that still
+            clears a touch-sized thumb without the row overlap the M4 fix was written against; the
+            `.sheet :global(.mantine-Drawer-body)` rule in the CSS module trims the body's own
+            RIGHT padding by that same 8px, so the reserved gutter fills the gap it opened instead
+            of stacking on top of the (symmetric) Drawer `padding="md"` — measured 18/18, not the
+            18/30 the untrimmed body produced. */}
+        <ScrollArea.Autosize mah="62dvh" type="scroll" offsetScrollbars="present" scrollbarSize={8}>
+          <Stack gap="var(--vx-space-sidebar-section-gap)">
             {slot.groups.map((group) => (
               <Stack key={group.key} gap={2}>
                 {sheetGroupLabel(group)}
-                {rows(group.items, 0, sheetRow)}
+                <Stack gap={1}>{rows(group.items, 0, sheetRow)}</Stack>
               </Stack>
             ))}
             {slot.isMore && moreBlocks.length > 0 ? (
-              <Stack gap={2}>{moreBlocks.map(sheetBlockRow)}</Stack>
+              <Stack gap={1}>{moreBlocks.map(sheetBlockRow)}</Stack>
             ) : null}
             {slot.isMore && extraRows.length > 0 ? (
-              <Stack gap={2}>{extraRows.map(sheetActionRow)}</Stack>
+              <Stack gap={1}>{extraRows.map(sheetActionRow)}</Stack>
             ) : null}
           </Stack>
         </ScrollArea.Autosize>
@@ -594,14 +649,18 @@ export function MobileNav({
         timingFunction: 'cubic-bezier(0.32, 0.72, 0, 1)',
       }}
     >
-      <ScrollArea.Autosize mah="62dvh" type="scroll">
-        <Stack gap={2}>{block.items.map(blockItemRow)}</Stack>
+      <ScrollArea.Autosize mah="62dvh" type="scroll" offsetScrollbars="present" scrollbarSize={8}>
+        <Stack gap={1}>{block.items.map(blockItemRow)}</Stack>
       </ScrollArea.Autosize>
     </Drawer>
   )
 
   return (
-    <nav className={classes.bar} aria-label="Primary">
+    <nav
+      className={cx(classes.bar, className)}
+      aria-label="Primary"
+      {...(style !== undefined && { style })}
+    >
       {model.slots.map((slot) => {
         if (slot.kind === 'link') return linkTab(slot)
         if (slot.kind === 'menu') return menuSlot(slot)

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

@@ -18,6 +18,9 @@
  */
 import { Group, Menu, Skeleton, Stack, Text, UnstyledButton } from '@mantine/core'
 import { useBasaltSpacing } from '../theme'
+import { cx } from '../common/props'
+import type { BasaltProps } from '../common/props'
+import { assertRequiredProps } from '../common/validate'
 import type { BasaltAccountProps } from './account-types'
 import classes from './app-sidebar.module.css'
 
@@ -59,9 +62,14 @@ function IconUser() {
   )
 }
 
-function AccountSkeleton() {
+function AccountSkeleton({ className, style }: BasaltProps) {
   return (
-    <Group className={classes.accountRow} gap="sm" wrap="nowrap">
+    <Group
+      className={cx(classes.accountRow, className)}
+      gap="sm"
+      wrap="nowrap"
+      {...(style !== undefined && { style })}
+    >
       <Skeleton height={28} width={28} style={{ borderRadius: 'var(--vx-radius-card)' }} />
       <Stack gap={4} className={classes.accountText}>
         <Skeleton height={10} width="70%" radius="sm" />
@@ -71,7 +79,9 @@ function AccountSkeleton() {
   )
 }
 
-export function SidebarAccount({ state, actions, showEmail }: BasaltAccountProps) {
+export function SidebarAccount(props: BasaltAccountProps & BasaltProps) {
+  assertRequiredProps('SidebarAccount', props, ['state'])
+  const { state, actions, showEmail, className, style } = props
   // Density-tracking Menu dropdown width (`SPACE_STEP.sidebarAccountMenuWidth`) — read the ACTIVE
   // resolved level, not the frozen level-0 constant, so the dropdown widens with its rows as density
   // rises (see that constant's own doc in `tokens/palette.ts`). Called unconditionally, ahead of the
@@ -79,12 +89,21 @@ export function SidebarAccount({ state, actions, showEmail }: BasaltAccountProps
   const { step } = useBasaltSpacing()
 
   if (state.status === 'loading') {
-    return <AccountSkeleton />
+    return (
+      <AccountSkeleton
+        {...(className !== undefined && { className })}
+        {...(style !== undefined && { style })}
+      />
+    )
   }
 
   if (state.status === 'unauthenticated') {
     return (
-      <UnstyledButton className={classes.accountRow} onClick={actions?.onSignIn}>
+      <UnstyledButton
+        className={cx(classes.accountRow, className)}
+        onClick={actions?.onSignIn}
+        {...(style !== undefined && { style })}
+      >
         <IconUser />
         <Text className={classes.accountText} size="sm" fw={500}>
           Sign in
@@ -99,7 +118,11 @@ export function SidebarAccount({ state, actions, showEmail }: BasaltAccountProps
   return (
     <Menu position="right-end" withArrow width={step.sidebarAccountMenuWidth} zIndex={500}>
       <Menu.Target>
-        <UnstyledButton className={classes.accountRow} aria-label="Account menu">
+        <UnstyledButton
+          className={cx(classes.accountRow, className)}
+          aria-label="Account menu"
+          {...(style !== undefined && { style })}
+        >
           <InitialsBlock name={identity.name} />
           <Stack gap={2} className={classes.accountText}>
             <Text className={classes.accountName} truncate>

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
@@ -25,6 +26,16 @@
   padding: 0 var(--vx-space-row-inset-x);
 }
 
+/* Installed PWA (C5 consolidation, seeded from argo's `styles/native.css`): clear the landscape
+ * notch on the side the sidebar touches. `max()` is a FLOOR — the inset only grows the padding
+ * past its normal value, never shrinks it. Right inset is `app-main.module.css`'s to draw; the
+ * PWA's top inset needs no rule here (the status bar uses the opaque `default` style). */
+@media (display-mode: standalone) {
+  .root {
+    padding-left: max(var(--vx-space-row-inset-x), env(safe-area-inset-left));
+  }
+}
+
 .link {
   font-size: var(--vx-text-md);
   border-radius: var(--vx-radius-ctrl) !important;
@@ -39,28 +50,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 +82,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 +112,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 +148,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 +536,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;
+}
+
+@media (hover: 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% + ink, one step quieter than the parent rows' 6%. Outranks the
- * `.link` hover rule above on specificity. */
+/* 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]):not([aria-current='page'])):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 +583,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