App Sidebar

Status

C1 (scaffold + types) landed. Items + collapse + drawer + slots roll out across C2–C13. The full AppSidebarProps surface is already typed — your call sites compile against the final shape now.

When to use

Reach for AppSidebar for any desktop app shell that needs a collapsible left (or right) navigation column with a mobile drawer fallback. Replaces the per-app reinvention of: collapse + sections + badges + tooltips-on-collapsed + permission gating + localStorage persist + reduced-motion + WAI-ARIA.

Basic example

import { AppSidebar, type NavItem } from "@ilinxa/app-sidebar";
import { usePathname } from "next/navigation";
import Link from "next/link";

const items: NavItem[] = [
  { id: "home", label: "Home", href: "/" },
  { id: "inbox", label: "Inbox", href: "/inbox", badge: 12 },
];

export function AppShell({ children }) {
  const pathname = usePathname();
  return (
    <div className="flex min-h-screen">
      <AppSidebar
        items={items}
        currentPath={pathname}
        linkComponent={({ href, children, ...rest }) => (
          <Link href={href} {...rest}>{children}</Link>
        )}
      />
      <main className="flex-1">{children}</main>
    </div>
  );
}

Key props

• items — accepts flat NavItem[] OR mixed NavEntry[] (items / sections / separators)
• currentPath + optional isActive predicate drive active-row detection (registry-portable — no router coupling)
• linkComponent— pass your router's link primitive (default <a href>)
• storageKey opt-in localStorage persist of collapse + section-collapse state
• activeVariant — "fill" (default) / "left-bar" / "right-bar" / "outline" / "subtle"

v0.2.0 — additions

v0.2.0 is strictly additive on v0.1 — every existing consumer compiles unchanged. New surface unlocks multi-tenant SaaS shells:

• topSlot — single slot ABOVE the brand row for an AccountSwitcher / governance bar / status banner. Renders nothing when omitted (zero layout shift vs v0.1).
• hrefTemplateValues — map of {key} placeholders substituted in every NavItem.href. e.g. { slug: 'acme' } turns /biz/{slug}/team into /biz/acme/team.
• resolveHref(item, values) — escape-hatch callback; wins precedence over the built-in substitution. Use for subdomain rewrites / locale prefixes / conditional sub-paths. Should be a stable useCallback.
• NavItem.ownerOnly + sidebar prop isOwner — hides the item unless isOwner is true. Pairs with the existing permission gate; both must pass (intersection).
• NavItem.minMembers + sidebar prop currentMaxMembers— hides the item unless plan-tier seat capacity meets the threshold. Useful for “Members tab only on plans with ≥N seats”.
• bypassFiltering — when true, skips ALL permission gates (permission ∩ ownerOnly ∩ minMembers) at BOTH section + item levels. hidden: true is still respected.
• useFilteredNavSections({ sections, permissions?, isOwner?, currentMaxMembers?, bypassFiltering? }) — pure helper hook returning the filtered NavEntry[]. NOT coupled to <AppSidebar> — render your own arbitrary sidebar UI with this hook standalone.
• type NavContext — exported discriminated union covering personal / business / platform / governance / cms-platform / cms-business. Type-only; use it to type your URL→context derivation. (Library does NOT ship useNavContext— that's your router's concern.)

Composition recipe — drop <AccountSwitcher> into topSlot; thread the current context's slug into hrefTemplateValues; pass isOwner + currentMaxMembers from your auth store. Zero hard registry dep between app-sidebar and account-switcher.

Collapse-aware composition (responsive)

app-sidebar is viewport-aware (built-in mobile drawer below mobileBreakpoint) AND container-aware via isCollapsed (icon-only desktop mode). The slotted <AccountSwitcher>is NOT viewport-aware on its own — it's a primitive, not an app-shell. The recipe is to LIFT the collapsed state so it threads into both:

const [sidebarCollapsed, setSidebarCollapsed] = useState(false);

<AppSidebar
  items={items}
  currentPath={pathname}
  isCollapsed={sidebarCollapsed}
  onCollapsedChange={({ collapsed }) => setSidebarCollapsed(collapsed)}
  topSlot={
    <AccountSwitcher
      items={switcherItems}
      activeKey={activeKey}
      onSelect={onSelect}
      isCollapsed={sidebarCollapsed}   // ← passthrough; trigger flips icon-only
    />
  }
/>

Below mobileBreakpoint the sidebar becomes a Sheet drawer; inside that drawer pass isCollapsed={false} (the drawer renders the sidebar full-width on mobile). Full recipe in account-switcher-procomp-guide.md §4.6.