@bensdev/react-sidebar 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,22 @@
+# Changelog
+
+All notable changes to this project are documented here. Format loosely follows
+[Keep a Changelog](https://keepachangelog.com/en/1.1.0/). Pre-1.0: breaking changes bump the
+**minor** version, not the major.
+
+## [0.1.0] — Unreleased
+
+Initial extraction from the B-Lines admin/user sidebars into a standalone package.
+
+- Router-agnostic `<Sidebar>` component: works with plain `<a>`, React Router, Next.js `Link`,
+  or any custom link component via `renderLink`.
+- Full CSS custom-property theming (`--bsb-*`), zero Tailwind requirement.
+- `greenMist`, `slate`, and `midnight` built-in theme presets.
+- Controlled/uncontrolled/persisted collapse state; controlled/uncontrolled mobile drawer.
+- Nested groups with an accordion (expanded) and flyout (collapsed-rail) presentation.
+- Links, actions, groups, headings, dividers, and fully custom items.
+- Zero runtime dependencies; `react`/`react-dom` are the only peer dependencies.
+- Accessible by default: keyboard navigation, focus trap + Escape in the drawer, `aria-current`,
+  `aria-expanded`, visible focus rings, reduced-motion support.
+- SSR-safe (no `window`/`document` access during render); ships a `"use client"` banner for
+  Next.js App Router.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 bensdev
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,279 @@
+# @bensdev/react-sidebar
+
+A themeable, router-agnostic, zero-dependency React sidebar: collapsible rail, nested groups,
+a mobile drawer, and full CSS-custom-property theming. No Tailwind required, no router required,
+no icon library required — bring your own of each, or none at all.
+
+- **Zero runtime dependencies.** `react` / `react-dom` are the only peer dependencies.
+- **Router-agnostic.** Works with a plain `<a>` out of the box; plug in React Router's `Link`,
+  Next.js's `Link`, or anything else via `linkComponent` / `renderLink`.
+- **Themeable via CSS variables.** Every color, size, radius, and transition is a `--bsb-*`
+  custom property. Override with the `theme` prop, plain CSS, or per-slot `classNames`.
+- **Deeply configurable.** Links, actions, nested groups, headings, dividers, badges, disabled/
+  hidden items, and fully custom rows — all data-driven, no forking required.
+- **Accessible.** Keyboard navigation, focus trap + Escape in the drawer, `aria-current`,
+  `aria-expanded`, visible focus rings, `prefers-reduced-motion` support.
+- **SSR-safe.** No `window`/`document` access during render; ships a `"use client"` banner so it
+  drops straight into a Next.js App Router Server Component tree.
+
+## Install
+
+```bash
+npm install @bensdev/react-sidebar
+```
+
+```tsx
+import { Sidebar } from '@bensdev/react-sidebar';
+import '@bensdev/react-sidebar/styles.css';
+```
+
+Import the CSS once, near your app's own global stylesheet (before it, if you want your app's
+CSS to win any conflicts).
+
+## Quick start
+
+```tsx
+import { Sidebar, greenMist, type SidebarItem } from '@bensdev/react-sidebar';
+import '@bensdev/react-sidebar/styles.css';
+import { Home, Store, Settings, LogOut } from 'lucide-react';
+
+const items: SidebarItem[] = [
+  { label: 'Home', href: '/home', icon: <Home size={18} /> },
+  { label: 'Suppliers', href: '/suppliers', icon: <Store size={18} />, badge: 12 },
+  { label: 'Settings', href: '/settings', icon: <Settings size={18} /> },
+];
+
+export function AppSidebar() {
+  return (
+    <Sidebar
+      items={items}
+      theme={greenMist}
+      brand={{ logo: 'B', title: 'My App', subtitle: 'Dashboard' }}
+      user={{ name: 'Ada Lovelace', email: 'ada@example.com' }}
+      footerAction={{ icon: <LogOut size={15} />, label: 'Logout', onClick: () => {} }}
+    />
+  );
+}
+```
+
+With no other props, active-route detection falls back to `window.location.pathname` and links
+render as plain `<a href>` — this works in any React app, router or not. For an SPA router, read
+on.
+
+## Routing recipes
+
+The package computes active state itself, so it behaves identically regardless of router. Pass
+`currentPath` explicitly whenever you have a client-side router — the `window.location` fallback
+only reacts to `popstate`/`hashchange`, not to `pushState`-based navigation.
+
+**React Router (v6/v7)**
+
+```tsx
+import { Link, useLocation } from 'react-router-dom';
+
+<Sidebar items={items} linkComponent={Link} hrefProp="to" currentPath={useLocation().pathname} />
+```
+
+**Next.js App Router**
+
+```tsx
+'use client';
+import Link from 'next/link';
+import { usePathname } from 'next/navigation';
+
+<Sidebar items={items} linkComponent={Link} currentPath={usePathname()} />
+```
+
+**TanStack Router**
+
+```tsx
+import { Link, useRouterState } from '@tanstack/react-router';
+
+<Sidebar
+  items={items}
+  linkComponent={Link}
+  currentPath={useRouterState({ select: (s) => s.location.pathname })}
+/>
+```
+
+**Anything else** — analytics-wrapped links, a design-system `<Link>` with a different prop
+shape, or navigation that isn't a real `<a>` at all:
+
+```tsx
+<Sidebar
+  items={items}
+  renderLink={({ href, isActive, className, children, props }) => (
+    <MyLink to={href} data-active={isActive} className={className} {...props}>
+      {children}
+    </MyLink>
+  )}
+/>
+```
+
+## Items
+
+```ts
+type SidebarItem =
+  | { href: string; label: ReactNode; icon?: ReactNode; badge?: ReactNode; end?: boolean, ... }        // link (default)
+  | { type: 'action'; label: ReactNode; onSelect: (e) => void, ... }                                     // button, no navigation
+  | { type: 'group'; label: ReactNode; items: SidebarItem[]; collapsible?: boolean, ... }                 // nested submenu
+  | { type: 'heading'; label: ReactNode }                                                                 // section label
+  | { type: 'divider' }                                                                                    // horizontal rule
+  | { type: 'custom'; render: (ctx) => ReactNode }                                                          // anything at all
+```
+
+Every item accepts `hidden` (the standard way to do role-based gating — filter is applied at
+render time) and `disabled`. Links accept `end` for exact-match active state (mirrors React
+Router's `NavLink end`), and `isActive` to override the computed value entirely.
+
+```tsx
+{ type: 'group', label: 'Admin', items: [
+  { label: 'Dashboard', href: '/admin', end: true, icon: <LayoutDashboard size={18} /> },
+  { label: 'Users', href: '/admin/users', icon: <Users size={18} />, badge: { content: 3, tone: 'danger' } },
+  { label: 'Billing', href: '/admin/billing', hidden: !user.isAdmin },
+]}
+```
+
+A group with `collapsible: false` renders as a static section (its `label` becomes a heading,
+children are always visible — a lighter-weight alternative to a top-level `heading` + flat items).
+When the sidebar is collapsed to its icon rail, a group renders as a hover/focus **flyout** by
+default (`collapsedGroupBehavior="flyout"`); set it to `"expand"` or `"ignore"` for different
+collapsed-rail behavior.
+
+## Collapse / expand
+
+```tsx
+// Uncontrolled, persisted to localStorage under a key you choose:
+<Sidebar items={items} persistCollapse="my-app-sidebar-collapsed" />
+
+// Fully controlled:
+<Sidebar items={items} collapsed={collapsed} onCollapsedChange={setCollapsed} />
+
+// Non-collapsible:
+<Sidebar items={items} collapsible={false} />
+```
+
+`persistCollapse` also accepts a `StorageAdapter` (`{ getItem, setItem, subscribe? }`) if you
+want to back it with something other than `localStorage`.
+
+## Mobile drawer
+
+Below `breakpoint` (default `1024`px, or pass any media-query string), the desktop rail is
+replaced by a slide-in drawer. Drive it from your own hamburger button:
+
+```tsx
+const [open, setOpen] = useState(false);
+
+<button onClick={() => setOpen(true)}>Menu</button>
+<Sidebar items={items} mobileOpen={open} onMobileClose={() => setOpen(false)} />
+```
+
+The drawer includes a focus trap, Escape-to-close, backdrop-click-to-close, body scroll lock, and
+respects `prefers-reduced-motion` — all on by default and individually toggleable
+(`trapFocus`, `closeOnEscape`, `closeOnBackdropClick`, `lockScroll`, `reduceMotion`).
+
+## Theming
+
+Every visual value is a `--bsb-*` CSS custom property (see `src/styles.css` for the full list —
+layout, radii, typography, motion, and color tokens). Three ways to change them, all without
+touching package source:
+
+**1. The `theme` prop** (inline styles, wins over everything):
+
+```tsx
+<Sidebar items={items} theme={{ bg: '#0f172a', itemActiveBg: '#1d4ed8', radiusItem: '12px' }} />
+
+// Split values per color scheme:
+<Sidebar items={items} colorScheme="auto" theme={{ light: { bg: '#fff' }, dark: { bg: '#0f172a' } }} />
+```
+
+**2. Plain CSS:**
+
+```css
+.my-app .bsb-root {
+  --bsb-bg: #0f3a18;
+  --bsb-item-active-bg: rgba(31, 110, 46, 0.6);
+}
+```
+
+**3. Per-slot class names** (for Tailwind users who'd rather use utilities than tokens):
+
+```tsx
+<Sidebar items={items} classNames={{ item: 'my-tailwind-classes', itemActive: 'bg-primary-600' }} />
+```
+
+### Color scheme
+
+`colorScheme` is `"light" | "dark" | "auto"` (default `"auto"`). In `"auto"` mode the sidebar
+looks for a `.dark`, `[data-theme="dark"]`, or `[data-color-scheme="dark"]` ancestor (or the
+matching `light` variant, or `prefers-color-scheme` as a last resort) and re-resolves whenever
+that ancestor's attributes change — no extra JS wiring needed if your app already toggles a class
+on `<html>`.
+
+### Presets
+
+```tsx
+import { greenMist, midnight, slate } from '@bensdev/react-sidebar';
+
+<Sidebar items={items} theme={greenMist} />
+```
+
+- `slate` — the stylesheet's own defaults (useful for explicitness).
+- `greenMist` — the original B-Lines palette, including its `light`/`dark` split.
+- `midnight` — a neutral dark theme.
+
+Build your own with `defineTheme({...})` for autocomplete, or just pass a plain object.
+
+## Header / footer
+
+```tsx
+<Sidebar
+  items={items}
+  brand={{ logo: <Logo />, title: 'Acme', subtitle: 'Admin', badge: 'Beta' }}
+  user={{ name: user.name, email: user.email, avatarUrl: user.avatarUrl }}
+  footerAction={{ icon: <LogOut size={15} />, label: 'Logout', onClick: logout }}
+  collapsedFooter="stack" // keep the logout button reachable even when collapsed
+/>
+```
+
+For full control, `header` and `footer` accept any `ReactNode` or a `(ctx) => ReactNode`
+render function, replacing the built-in brand/user blocks entirely.
+
+## Escape hatches
+
+- `classNames` — override any of ~30 named slots (`root`, `item`, `itemActive`, `badge`,
+  `groupPanel`, `toggle`, `drawer`, …) without forking styles.
+- `slots` — swap the collapse chevron, group chevron, close icon, or tooltip renderer.
+- `renderItem(item, ctx, defaultNode)` — intercept any single row and return your own markup
+  (return `undefined` to fall through to the default).
+- Item-level `render` on `{ type: 'custom' }` items for one-off rows (dividers with a label,
+  a search box, an upgrade banner, anything).
+
+## Accessibility
+
+`<nav aria-label>` landmark, `aria-current="page"` on the active link, `aria-expanded`/
+`aria-controls` on group triggers, visible `:focus-visible` rings, a labeled and focus-trapped
+drawer dialog (`role="dialog" aria-modal`) with Escape support, and full `prefers-reduced-motion`
+support (respected automatically, or forced with `reduceMotion`).
+
+## SSR / Next.js
+
+The package never touches `window`/`document` during render — only inside effects and
+`useSyncExternalStore`. The compiled bundle starts with `"use client"`, so it can be imported
+directly from a Server Component file in the App Router. Persisted collapse state hydrates safely
+(server and first client paint both render `defaultCollapsed`; the real value swaps in right
+after).
+
+## API reference
+
+The full prop surface is exported as `SidebarProps`, along with every item/theme/slot type
+(`SidebarItem`, `SidebarLinkItem`, `SidebarGroupItem`, `SidebarTheme`, `SidebarClassNames`, …) —
+import them for autocomplete:
+
+```ts
+import type { SidebarProps, SidebarItem, SidebarTheme } from '@bensdev/react-sidebar';
+```
+
+## License
+
+MIT