@vvedantb/ui 0.7.1 → 0.7.2

package/README.md

@@ -299,7 +299,7 @@ import {
 - `SidebarPanel`: legacy (still supported) `headerTrailing`, `onClose`, `closeLabel` and `closeButtonClassName`; compose `Sidebar.Panel` parts instead. `title`, `headerTrailing`, `onClose` (adds the close button; pass it on the mobile drawer only), `closeLabel`, `closeButtonClassName`, `collapsed` (`md:hidden`), `className`, `children`.
 - `SidebarAccountMenu`: legacy (still supported) `badge`, `triggerProps`, `contentProps` and `stackedLabel`; compose `Sidebar.Account*` parts instead. `name`, `email` (two-line label when set), `stackedLabel` (two-line layout even without `email`, default `false`), `imageUrl` (initials without it), `align` (`"center"`), `side` (`"right"`), `sideOffset` (8), `collisionPadding`, `contentClassName`, `children` (menu items). 0.5.2 adds `badge` (unread dot beside the trigger, in a `relative` wrapper around the menu, so the trigger's dimming and press scale skip it: `true` shows it, `false` fades it out, omitted renders no wrapper and no dot), `triggerProps` (spread onto the trigger `Button` after the defaults; `className` merges last) and `contentProps` (spread onto `DropdownMenuContent`, for example `fitViewport` or `aria-label`; no `className`, use `contentClassName`). `SidebarAccountMenuPlaceholder` is the tile-sized loading box.
 - `SignOutDialog`: legacy (still supported) `question` and `title`; compose `ConfirmDialog` parts with `alert={false}` for other copy. `open`, `onOpenChange` (not called with `false` while `pending`), `pending`, `onConfirm`, `description`, `contentClassName`, `title` (`"Sign out"`), `question` (`"Sign out of your account?"`).
-- Class helpers: `railTileClass`, `railTileStateClass(active)`, `railBadgeClass`, `sidebarNavRowClass(isIconOnly)`, `sidebarNavLinkTextClass(isActive)`, `sidebarNavItemClass({ active, iconOnly })`, `sidebarNavIconClass(active)`, `sidebarSectionLabelClass`. See [Menu item corners and sidebar nav rows (0.7.1)](#menu-item-corners-and-sidebar-nav-rows-071).
+- Class helpers: `railTileClass`, `railTileStateClass(active)`, `railBadgeClass`, `sidebarNavRowClass(isIconOnly)`, `sidebarNavLinkTextClass(isActive)`, `sidebarNavItemClass({ active, iconOnly, selected, dragging, dropTarget })`, `sidebarNavIconClass(active)`, `sidebarSectionLabelClass`, and the row parts `sidebarNavItemLeadingClass`, `sidebarNavItemLabelClass`, `sidebarNavItemSubtitleClass`, `sidebarNavItemTrailingClass`, `sidebarNavItemActionsClass` and `sidebarNavItemIndentStyle(indent)`. See [Menu item corners and sidebar nav rows (0.7.1)](#menu-item-corners-and-sidebar-nav-rows-071) and [Sidebar nav row parts (0.7.2)](#sidebar-nav-row-parts-072).
 
 ### Header actions and account badge (0.5.2)
 
@@ -434,7 +434,8 @@ Convention: compound parts are static members of a namespace object, `<Namespace
 | `PanelHeader` | Padded header row for `PanelTitle` and `PanelActions`. |
 | `PanelTitle` / `PanelActions` | The `<h2>` and the trailing actions. |
 | `PanelClose` | Ghost close button. `label` (`"Close navigation"`). Without `onClick` it closes the drawer. |
-| `NavItem` | Panel nav row (`sidebarNavItemClass`). `active` (fill, `font-medium`, `aria-current="page"`), `iconOnly`, `icon` (element; gets `sidebarNavIconClass`), `asChild` for a router link. A `<button type="button">` without `asChild`. |
+| `NavItem` | Panel nav row (`sidebarNavItemClass`). `active` (fill, `font-medium`, `aria-current="page"`), `iconOnly`, `icon` (element; gets `sidebarNavIconClass`), `asChild` for a router link. A `<button type="button">` without `asChild`. 0.7.2: `selected`, `indent`, `dragging`, `dropTarget`; see [Sidebar nav row parts (0.7.2)](#sidebar-nav-row-parts-072). |
+| `NavItemLeading` / `NavItemLabel` / `NavItemTrailing` / `NavItemActions` | Row parts (0.7.2): leading slot, truncated label, always-visible trailing content and hover-revealed actions. `<span>`, or the child with `asChild`. |
 | `AccountMenu` | Dropdown root. `badge` adds the unread dot (`AccountBadge`) in a `relative` wrapper. |
 | `AccountTrigger` | Rail-tile-sized avatar button. `userName` (default `title` and `aria-label`, and the initials), `imageUrl`, plus `Button` props; native `name` goes to the button. |
 | `AccountAvatar` | Avatar image or initials. `userName`, `imageUrl`. |
@@ -693,12 +694,104 @@ Colour mapping. The package has no sidebar colour tokens, so the rows use the ne
 
 | Role | Reference look (light / dark, sRGB) | Package token (light / dark, sRGB) |
 | --- | --- | --- |
-| Hover and active fill | 233 234 236 / 28 28 28 | `surface-tertiary`: 234 234 234 / about 39 39 39. Light matches; dark is a step lighter. It is the rail tile's active fill too, so a rail tile and a nav row stay the same. |
+| Hover and active fill | 233 234 236 / 28 28 28 | `surface-tertiary`: 234 234 234 / about 39 39 39. Light matches; dark is a step lighter. It is the rail tile's active fill too, so a rail tile and a nav row stay the same. From 0.7.2 the rows use `sidebar-accent` (234 234 234 / 28 28 28); see below. |
 | Active text and icon | 9 9 11 / 250 250 250 | `foreground`: 24 24 24 / 252 252 252 |
 | Idle text (80%) | 24 24 25 / 251 252 253 | `foreground` at 80% |
 | Idle icon | 100 101 103 / 159 160 162 | `muted-foreground` (`--muted`): 114 114 114 / 160 160 160 |
 | Focus ring (35%) | 9 9 11 / 250 250 250 | `foreground` at 35% |
 
+## Sidebar nav row parts (0.7.2)
+
+One row style for every sidebar list: plain nav links and rich rows (checkbox, avatar, two-line label, nested folders, `...` menus, drag and drop, rename inputs). `Sidebar.NavItem` is the row; the parts go inside it.
+
+Rich row (the link is the row; the parts are its children):
+
+```tsx
+<Sidebar.NavItem asChild active={isActive} selected={selected} indent={1} dragging={isDragged} dropTarget={isOver}>
+  <Link to="/chat/$id" params={{ id }} draggable onDragStart={onDragStart}>
+    <Sidebar.NavItemLeading>
+      <Checkbox checked={selected} onClick={(event) => event.stopPropagation()} aria-label={`Select ${title}`} />
+    </Sidebar.NavItemLeading>
+    <Sidebar.NavItemLabel>{title}</Sidebar.NavItemLabel>
+    <Sidebar.NavItemTrailing>{generating ? <Spinner size={14} decorative /> : count}</Sidebar.NavItemTrailing>
+    <Sidebar.NavItemActions>
+      <DropdownMenu>
+        <DropdownMenuTrigger asChild>
+          <Button
+            variant="ghost"
+            size="icon-xs"
+            aria-label="Row actions"
+            onClick={(event) => {
+              event.stopPropagation();
+              event.preventDefault();
+            }}
+          >
+            <IconDots size={16} />
+          </Button>
+        </DropdownMenuTrigger>
+        <DropdownMenuContent>...</DropdownMenuContent>
+      </DropdownMenu>
+    </Sidebar.NavItemActions>
+  </Link>
+</Sidebar.NavItem>
+```
+
+Simple row (unchanged from 0.7.1):
+
+```tsx
+<Sidebar.NavItem asChild active={active} icon={<IconHome />}>
+  <Link to="/home"><span className="truncate">Home</span></Link>
+</Sidebar.NavItem>
+```
+
+`Sidebar.NavItem` props added in 0.7.2:
+
+| Prop | Effect |
+| --- | --- |
+| `selected` | The active fill (`bg-sidebar-accent text-foreground`) without `font-medium` or `aria-current`. `data-selected="true"`. |
+| `indent` | Nesting level from 0. Left padding is `calc(1rem + indent * 12px)`: 16px, 28px, 40px, ... Set as inline `paddingLeft`, so any depth works and a `style.paddingLeft` you pass wins. Ignored with `iconOnly`. |
+| `dragging` | `opacity-40 cursor-grabbing`. `data-dragging="true"`. |
+| `dropTarget` | Fill plus `ring-2 ring-inset ring-focus`. `data-drop-target="true"`. |
+
+`active` also sets `data-active="true"`. Each attribute is left off when its prop is false. The styles key off the attributes (`data-[selected=true]:`, `data-[dragging=true]:`, `data-[drop-target=true]:`), so a row that sets them itself (for example from a tree library's drag state) gets the same look. `sidebarNavItemClass` takes the same `selected`, `dragging` and `dropTarget` options for rows that use the class only.
+
+Parts. Each renders a `<span>` with its class (`className` merges last), or merges onto its single child with `asChild`:
+
+| Part | Class | Use |
+| --- | --- | --- |
+| `NavItemLeading` | `sidebarNavItemLeadingClass`: `flex shrink-0 items-center` | Checkbox, icon, avatar, status dot, folder chevron. Put `sidebarNavIconClass(active)` on an icon. A 40px avatar makes the row taller; add `py-2` to the row if you want more room. |
+| `NavItemLabel` | `sidebarNavItemLabelClass`: `min-w-0 flex-1 truncate` | The title. For two lines, put `<span className="block truncate">` and `<span className={sidebarNavItemSubtitleClass}>` (`block truncate text-xs text-muted-foreground`) inside. For rename, `asChild` on the input. |
+| `NavItemTrailing` | `sidebarNavItemTrailingClass`: `ml-auto flex shrink-0 items-center gap-1.5 text-xs text-muted-foreground` | Always visible: counts, unread dots, spinners, badges. |
+| `NavItemActions` | `sidebarNavItemActionsClass` (below) | Hover-revealed `...` button. |
+
+Actions sit in the row flow at the end (`ml-auto`), so an `asChild` link row needs no `relative`. The part is `h-6` with `-my-1`, so a 24px or 28px icon button does not change the 30px row height. It reserves its width while hidden, so the label truncates a little earlier. For the older overlay look, pass `className="absolute right-3"` to the part and `relative` to the row. Visibility:
+
+- `opacity-0` by default, `transition-opacity duration-75`.
+- `group-hover:opacity-100` and `group-focus-within:opacity-100`: the row is a `group`.
+- `has-[[data-state=open]]:opacity-100`: a Radix menu trigger inside it is open.
+- `data-[state=open]:opacity-100`: the part itself is the trigger (`asChild`).
+
+The part adds no handlers. Call `stopPropagation()` (and `preventDefault()` inside a link) on the button so it does not run the row click.
+
+Other rich-row needs:
+
+- Folder rows and drop zones: render the row as a `<div>` or `<button>` (`asChild` on a `<div>` when the row holds its own buttons) and wrap it in your drop zone. Set `dropTarget` while a drag is over it.
+- Indent guide lines: absolutely positioned spans in the row; add `relative` to the row.
+- Context menus and hover cards: wrap `Sidebar.NavItem` as before; `ContextMenuTrigger asChild` can wrap it directly.
+
+Classes a rich row no longer needs beside the parts: `rounded-lg`, `rounded-md`, `text-sm` (and `text-sm` on the title span), `px-3 py-1.5`, `gap-3`, `py-2`/`gap-3` for padding alone, `pl-7`/`pl-8` (use `indent`), `bg-surface-tertiary` for active, hover or selected, `ring-2 ring-inset ring-focus` and `opacity-40 cursor-grabbing` for drag states, `opacity-0 group-hover:opacity-100 group-focus-within:opacity-100 transition-opacity` on the menu button, `mr-2` on a checkbox (the row `gap-2` spaces it), `truncate flex-1 min-w-0` on the title, `text-xs text-muted` on counts, and app row helpers that set any of these (a local list-item class, an outer `group py-px` wrapper, a `ui-sidebar-row` class).
+
+### Fill colour: `sidebar-accent`
+
+Rows (hover, active, selected, drop target) use `bg-sidebar-accent` instead of `bg-surface-tertiary`.
+
+| | Light | Dark |
+| --- | --- | --- |
+| `tokens.css` `--sidebar-accent` | `var(--surface-tertiary)` (about 234 234 234; unchanged) | `oklch(22.64% 0 0)` (28 28 28; was about 39 39 39) |
+| `compat-shadcn-rgb.css` `--color-sidebar-accent` | `rgb(var(--sidebar-accent, var(--secondary)))`: the app's `--sidebar-accent` channels if defined, else `--secondary` as before | same |
+
+Rail tiles keep `surface-tertiary`, so in dark mode the active rail tile is a step lighter than the active row. An app that imports `tokens.css` and defines its own `--sidebar-accent` overrides the fill; it must be a full colour value there (use `compat-shadcn-rgb.css` for `R G B` channels).
+
 ## Toaster
 
 ```tsx
@@ -747,7 +840,7 @@ Components use `text-muted-foreground`, `primary` and `--color-*` theme variable
 Use this when the app defines shadcn-style variables as space-separated channels (`--background: 244 245 246`) and reads them as `rgb(var(--background) / 0.5)`.
 
 1. Import `compat-shadcn-rgb.css` **instead of** `tokens.css`. Never import both.
-2. The app keeps `--background`, `--foreground`, `--card`, `--popover`, `--primary`, `--secondary`, `--muted`, `--accent`, `--destructive`, `--border`, `--input`, `--ring` (each with its `-foreground` where shadcn has one) and `--radius`. The compat file does not define them. It only references them, so the app can change `--primary`, `--ring`, `--radius` or `--font-sans` at runtime.
+2. The app keeps `--background`, `--foreground`, `--card`, `--popover`, `--primary`, `--secondary`, `--muted`, `--accent`, `--destructive`, `--border`, `--input`, `--ring` (each with its `-foreground` where shadcn has one) and `--radius`. The compat file does not define them. It only references them, so the app can change `--primary`, `--ring`, `--radius` or `--font-sans` at runtime. `--sidebar-accent` is optional: sidebar nav rows use it when set, else `--secondary` (0.7.2).
 3. Add the `@source` line for the package sources.
 
 ```css

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vvedantb/ui",
-  "version": "0.7.1",
+  "version": "0.7.2",
   "license": "MIT",
   "description": "Shared React 19 UI for web apps: one JavaScript entry (primitives, shell pieces, app helpers, native tokens), design-token CSS, shared Tailwind v4 CSS and a Tailwind preset.",
   "type": "module",

package/shell/src/Sidebar.tsx

@@ -9,7 +9,18 @@ import {
   AccountSeparator,
   AccountTrigger,
 } from "./SidebarAccountMenu";
-import { NavItem, Panel, PanelActions, PanelClose, PanelHeader, PanelTitle } from "./SidebarPanel";
+import {
+  NavItem,
+  NavItemActions,
+  NavItemLabel,
+  NavItemLeading,
+  NavItemTrailing,
+  Panel,
+  PanelActions,
+  PanelClose,
+  PanelHeader,
+  PanelTitle,
+} from "./SidebarPanel";
 import { Rail, RailBody, RailFooter, RailHeader, RailItem, RailSeparator } from "./SidebarRail";
 
 export type {
@@ -36,6 +47,7 @@ export type {
   SidebarPanelHeaderProps,
   SidebarPanelRootProps,
   SidebarPanelTitleProps,
+  SidebarNavItemPartProps,
   SidebarNavItemProps,
 } from "./SidebarPanel";
 export type {
@@ -70,6 +82,10 @@ export const Sidebar = {
   PanelActions,
   PanelClose,
   NavItem,
+  NavItemLeading,
+  NavItemLabel,
+  NavItemTrailing,
+  NavItemActions,
   AccountMenu,
   AccountTrigger,
   AccountAvatar,

package/shell/src/SidebarPanel.tsx

@@ -3,7 +3,17 @@ import { Slot, Slottable } from "@radix-ui/react-slot";
 import { IconX } from "@tabler/icons-react";
 import { Button, type ButtonProps } from "../../src/ui/button";
 import { cn } from "../../src/utils/cn";
-import { panelCloseButtonClass, sidebarHeaderRowClass, sidebarNavIconClass, sidebarNavItemClass } from "./app-shell-classes";
+import {
+  panelCloseButtonClass,
+  sidebarHeaderRowClass,
+  sidebarNavIconClass,
+  sidebarNavItemActionsClass,
+  sidebarNavItemClass,
+  sidebarNavItemIndentStyle,
+  sidebarNavItemLabelClass,
+  sidebarNavItemLeadingClass,
+  sidebarNavItemTrailingClass,
+} from "./app-shell-classes";
 import { useOptionalSidebar } from "./SidebarChrome";
 
 export type SidebarPanelProps = {
@@ -134,23 +144,36 @@ export function PanelClose({ label = "Close navigation", onClick, className, chi
 }
 
 export type SidebarNavItemProps = ComponentPropsWithoutRef<"button"> & {
-  /** Current route: static fill, `font-medium`, `aria-current="page"`. */
+  /** Current route: static fill, `font-medium`, `aria-current="page"`, `data-active="true"`. */
   active?: boolean;
   /** Collapsed panel: centred icon, no horizontal padding. */
   iconOnly?: boolean;
-  /** Leading icon element; gets `sidebarNavIconClass(active)` merged onto it. */
+  /** Leading icon element; gets `sidebarNavIconClass(active)` merged onto it. For other leading content use `Sidebar.NavItemLeading`. */
   icon?: ReactElement;
   /** Render the single child element (for example a router link) as the row. */
   asChild?: boolean;
+  /** Picked (for example in a multi-select list): the active fill without `font-medium`. Sets `data-selected="true"`. */
+  selected?: boolean;
+  /** Nesting level from 0. Each level adds 12px to the 16px left padding. Ignored with `iconOnly`. */
+  indent?: number;
+  /** Row being dragged. Sets `data-dragging="true"`. */
+  dragging?: boolean;
+  /** Row under a drag. Sets `data-drop-target="true"`. */
+  dropTarget?: boolean;
 };
 
-/** Panel nav row (`sidebarNavItemClass`). Renders a native `<button>`, or its child with `asChild`. */
+/** Panel nav row (`sidebarNavItemClass`). Renders a native `<button>`, or its child with `asChild`. Compose `NavItemLeading`, `NavItemLabel`, `NavItemTrailing` and `NavItemActions` inside. */
 export function NavItem({
   active = false,
   iconOnly = false,
   icon,
   asChild = false,
+  selected = false,
+  indent = 0,
+  dragging = false,
+  dropTarget = false,
   className,
+  style,
   children,
   ...props
 }: SidebarNavItemProps) {
@@ -160,6 +183,11 @@ export function NavItem({
       type={asChild ? undefined : "button"}
       {...props}
       aria-current={active ? "page" : undefined}
+      data-active={active || undefined}
+      data-selected={selected || undefined}
+      data-dragging={dragging || undefined}
+      data-drop-target={dropTarget || undefined}
+      style={indent > 0 && !iconOnly ? { ...sidebarNavItemIndentStyle(indent), ...style } : style}
       className={cn(sidebarNavItemClass({ active, iconOnly }), className)}
     >
       {icon ? <Slot className={sidebarNavIconClass(active)}>{icon}</Slot> : null}
@@ -167,3 +195,36 @@ export function NavItem({
     </Row>
   );
 }
+
+export type SidebarNavItemPartProps = ComponentPropsWithoutRef<"span"> & {
+  /** Merge the part classes onto the single child element instead of a `<span>`. */
+  asChild?: boolean;
+};
+
+function NavItemPart({ partClass, asChild = false, className, ...props }: SidebarNavItemPartProps & { partClass: string }) {
+  const Part = asChild ? Slot : "span";
+  return <Part {...props} className={cn(partClass, className)} />;
+}
+
+/** Leading slot of a nav row: checkbox, icon, avatar or status dot (`sidebarNavItemLeadingClass`). */
+export function NavItemLeading(props: SidebarNavItemPartProps) {
+  return <NavItemPart {...props} partClass={sidebarNavItemLeadingClass} />;
+}
+
+/** Truncated label of a nav row (`sidebarNavItemLabelClass`). `asChild` on a rename input keeps the layout. */
+export function NavItemLabel(props: SidebarNavItemPartProps) {
+  return <NavItemPart {...props} partClass={sidebarNavItemLabelClass} />;
+}
+
+/** Always-visible trailing content of a nav row: counts, badges, spinners (`sidebarNavItemTrailingClass`). */
+export function NavItemTrailing(props: SidebarNavItemPartProps) {
+  return <NavItemPart {...props} partClass={sidebarNavItemTrailingClass} />;
+}
+
+/**
+ * Hover-revealed actions of a nav row, such as a `...` menu (`sidebarNavItemActionsClass`).
+ * Adds no handlers: stop propagation (and prevent default inside a link) on the button.
+ */
+export function NavItemActions(props: SidebarNavItemPartProps) {
+  return <NavItemPart {...props} partClass={sidebarNavItemActionsClass} />;
+}

package/shell/src/app-shell-classes.ts

@@ -28,13 +28,14 @@ export const sidebarSectionLabelClass =
   "sidebar-section-label px-4 py-1 text-[11px] leading-4 font-medium tracking-[-0.01em]";
 
 /**
- * Nav row state: idle rows are `foreground/80` and get the fill on hover;
- * the active row is `font-medium text-foreground` on a static fill.
+ * Nav row state: idle rows are `foreground/80` and get the `sidebar-accent`
+ * fill on hover; the active row is `font-medium text-foreground` on a static
+ * fill.
  */
 export function sidebarNavLinkTextClass(isActive: boolean): string {
   return isActive
-    ? "bg-surface-tertiary font-medium text-foreground"
-    : "font-normal text-foreground/80 hover:bg-surface-tertiary hover:text-foreground";
+    ? "bg-sidebar-accent font-medium text-foreground"
+    : "font-normal text-foreground/80 hover:bg-sidebar-accent hover:text-foreground";
 }
 
 /**
@@ -53,13 +54,73 @@ export type SidebarNavItemClassOptions = {
   active?: boolean;
   /** Collapsed panel: centred icon, no horizontal padding. */
   iconOnly?: boolean;
+  /** Picked (for example in a multi-select list): the active fill, without `font-medium`. Same as `data-selected="true"`. */
+  selected?: boolean;
+  /** Row being dragged: `opacity-40 cursor-grabbing`. Same as `data-dragging="true"`. */
+  dragging?: boolean;
+  /** Row under a drag: fill plus an inset `ring-focus` ring. Same as `data-drop-target="true"`. */
+  dropTarget?: boolean;
 };
 
-/** Whole panel nav row: `sidebarNavRowClass` plus `sidebarNavLinkTextClass`. */
-export function sidebarNavItemClass({ active = false, iconOnly = false }: SidebarNavItemClassOptions = {}): string {
-  return cn(sidebarNavRowClass(iconOnly), sidebarNavLinkTextClass(active));
+// Row states an app can also set as data attributes on the row itself.
+const sidebarNavItemDataStateClass =
+  "data-[selected=true]:bg-sidebar-accent data-[selected=true]:text-foreground data-[dragging=true]:cursor-grabbing data-[dragging=true]:opacity-40 data-[drop-target=true]:bg-sidebar-accent data-[drop-target=true]:text-foreground data-[drop-target=true]:ring-2 data-[drop-target=true]:ring-inset data-[drop-target=true]:ring-focus";
+
+/**
+ * Whole panel nav row: `sidebarNavRowClass` plus `sidebarNavLinkTextClass`,
+ * plus `data-selected`, `data-dragging` and `data-drop-target` (`="true"`)
+ * styles. The `selected`, `dragging` and `dropTarget` options apply the same
+ * styles without the attributes.
+ */
+export function sidebarNavItemClass({
+  active = false,
+  iconOnly = false,
+  selected = false,
+  dragging = false,
+  dropTarget = false,
+}: SidebarNavItemClassOptions = {}): string {
+  return cn(
+    sidebarNavRowClass(iconOnly),
+    sidebarNavLinkTextClass(active),
+    sidebarNavItemDataStateClass,
+    selected && "bg-sidebar-accent text-foreground",
+    dragging && "cursor-grabbing opacity-40",
+    dropTarget && "bg-sidebar-accent text-foreground ring-2 ring-inset ring-focus",
+  );
+}
+
+/**
+ * Nested row padding: each `indent` level adds 12px to the row's 16px
+ * (`px-4`) left padding. Put it on the row's `style`.
+ */
+export function sidebarNavItemIndentStyle(indent: number): { paddingLeft: string } {
+  return { paddingLeft: `calc(1rem + ${indent * 12}px)` };
 }
 
+/** Row part: leading checkbox, icon, avatar or status dot. */
+export const sidebarNavItemLeadingClass = "flex shrink-0 items-center";
+
+/**
+ * Row part: the label, which takes the free width and truncates. For two
+ * lines, put `block truncate` spans inside (subtitle: `sidebarNavItemSubtitleClass`).
+ */
+export const sidebarNavItemLabelClass = "min-w-0 flex-1 truncate";
+
+/** Second, muted line inside the label. */
+export const sidebarNavItemSubtitleClass = "block truncate text-xs text-muted-foreground";
+
+/** Row part: always-visible trailing content (counts, badges, spinners). */
+export const sidebarNavItemTrailingClass = "ml-auto flex shrink-0 items-center gap-1.5 text-xs text-muted-foreground";
+
+/**
+ * Row part: actions such as a `...` menu button. In the row flow at the end,
+ * 24px tall without growing the row. Hidden until the row is hovered or has
+ * focus, or a menu trigger inside it (or the part itself) is
+ * `data-state="open"`.
+ */
+export const sidebarNavItemActionsClass =
+  "-my-1 ml-auto flex h-6 shrink-0 items-center opacity-0 transition-opacity duration-75 group-hover:opacity-100 group-focus-within:opacity-100 has-[[data-state=open]]:opacity-100 data-[state=open]:opacity-100";
+
 /** Nav row icon (put it on the `<svg>`): 19px, muted until active. */
 export function sidebarNavIconClass(active: boolean): string {
   return cn("size-[19px] shrink-0", active ? "text-foreground" : "text-muted-foreground");

package/shell/src/index.ts

@@ -46,7 +46,13 @@ export {
   railTileClass,
   railTileStateClass,
   sidebarNavIconClass,
+  sidebarNavItemActionsClass,
   sidebarNavItemClass,
+  sidebarNavItemIndentStyle,
+  sidebarNavItemLabelClass,
+  sidebarNavItemLeadingClass,
+  sidebarNavItemSubtitleClass,
+  sidebarNavItemTrailingClass,
   sidebarNavLinkTextClass,
   sidebarNavRowClass,
   sidebarSectionLabelClass,

package/src/index.ts

@@ -159,7 +159,13 @@ export {
   railTileClass,
   railTileStateClass,
   sidebarNavIconClass,
+  sidebarNavItemActionsClass,
   sidebarNavItemClass,
+  sidebarNavItemIndentStyle,
+  sidebarNavItemLabelClass,
+  sidebarNavItemLeadingClass,
+  sidebarNavItemSubtitleClass,
+  sidebarNavItemTrailingClass,
   sidebarNavLinkTextClass,
   sidebarNavRowClass,
   sidebarSectionLabelClass,

package/tokens/README.md

@@ -6,7 +6,7 @@ Design tokens and shared Tailwind v4 CSS for the vvedantb web apps. The CSS and
 
 | Export | File | What it is |
 | --- | --- | --- |
-| `@vvedantb/ui/tokens`, `@vvedantb/ui/tokens/tokens.css` | `src/tokens.css` | Colour, radius, shadow, ease and font tokens (`@theme`), light/dark variables, `dark` variant, the radius utilities `rounded-surface` (`clamp(0.75rem, var(--radius), 1rem)`), `rounded-menu-item` (`min(var(--radius), 0.5rem)`) and `rounded-control` (`min(var(--radius), 0.625rem)`) (0.7.1; `rounded-surface` was in `utilities.css` before), `*` border and `body` defaults. In 0.2.1 it also defines shadcn-style aliases (`primary`, `muted-foreground`, `secondary`, `destructive`, `card`, `popover`, `input`, `ring`) that point at the same tokens. |
+| `@vvedantb/ui/tokens`, `@vvedantb/ui/tokens/tokens.css` | `src/tokens.css` | Colour, radius, shadow, ease and font tokens (`@theme`), light/dark variables, `dark` variant, the radius utilities `rounded-surface` (`clamp(0.75rem, var(--radius), 1rem)`), `rounded-menu-item` (`min(var(--radius), 0.5rem)`) and `rounded-control` (`min(var(--radius), 0.625rem)`) (0.7.1; `rounded-surface` was in `utilities.css` before), `*` border and `body` defaults. 0.7.2 adds `--sidebar-accent` / `sidebar-accent` (sidebar nav row fill: light `var(--surface-tertiary)`, dark `oklch(22.64% 0 0)`). In 0.2.1 it also defines shadcn-style aliases (`primary`, `muted-foreground`, `secondary`, `destructive`, `card`, `popover`, `input`, `ring`) that point at the same tokens. |
 | `tokens` and `Tokens` from `@vvedantb/ui` | `src/native.ts` | JS colours, radii and spacing for React Native. `@vvedantb/native-ui` keeps its own copy in `src/tokens.ts`; a test keeps the two equal. |
 | `@vvedantb/ui/tokens/css/base.css` | `src/css/base.css` | `html` touch/accent, `::selection`, control transitions, pointer cursor, range accent (`@layer base`). |
 | `@vvedantb/ui/tokens/css/dialog.css` | `src/css/dialog.css` | Unlayered `max-width: none` for `@vvedantb/ui` compact (bottom-sheet) dialogs. |

package/tokens/src/css/compat-shadcn-rgb.css

@@ -23,6 +23,9 @@
  * --accent, --accent-foreground, --destructive, --destructive-foreground,
  * --border, --input, --ring and --radius (all colours as "R G B").
  *
+ * `--color-sidebar-accent` (sidebar nav row fill) reads the app's
+ * `--sidebar-accent` when it is defined, else `--secondary`.
+ *
  * `--color-card` and `--color-muted` are references to `--card` and `--muted`.
  * `SonnerToaster sonnerVars` reads them, along with `--color-border` and
  * `--color-foreground`. An app that already maps those names keeps its own
@@ -44,6 +47,7 @@
   --color-surface-secondary-foreground: rgb(var(--foreground));
   --color-surface-tertiary: rgb(var(--secondary));
   --color-surface-tertiary-foreground: rgb(var(--secondary-foreground));
+  --color-sidebar-accent: rgb(var(--sidebar-accent, var(--secondary)));
   --color-overlay: rgb(var(--popover));
   --color-overlay-foreground: rgb(var(--popover-foreground));
   --color-field-background: rgb(var(--card));

package/tokens/src/tokens.css

@@ -56,6 +56,7 @@
   --color-surface-tertiary: var(--surface-tertiary);
   --color-surface-tertiary-foreground: var(--surface-tertiary-foreground);
   --color-surface-card: var(--surface-card);
+  --color-sidebar-accent: var(--sidebar-accent);
   --color-warning: var(--warning);
   --color-warning-foreground: var(--warning-foreground);
 
@@ -155,6 +156,8 @@
     --surface-tertiary: oklch(93.73% 0 0);
     --surface-tertiary-foreground: oklch(21.03% 0 0);
     --surface-card: oklch(98% 0 0);
+    /* Sidebar nav row hover, active and selected fill. */
+    --sidebar-accent: var(--surface-tertiary);
     --warning: oklch(78.19% 0.159 72.33);
     --warning-foreground: oklch(21.03% 0.0059 72.33);
     --radius: 1rem;
@@ -202,6 +205,8 @@
     --surface-tertiary: oklch(27.21% 0.0023 0);
     --surface-tertiary-foreground: oklch(99.11% 0 0);
     --surface-card: oklch(25.7% 0.0023 0);
+    /* sRGB 28 28 28: a step darker than --surface-tertiary. */
+    --sidebar-accent: oklch(22.64% 0 0);
     --warning: oklch(82.03% 0.1392 76.34);
     --warning-foreground: oklch(21.03% 0.0059 76.34);
     --radius: 1rem;