@bensdev/react-sidebar 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -4,14 +4,44 @@ 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.
+## [0.2.0] — Unreleased
 
+- **Fixed:** `collapsible: false` groups (documented as "children always visible") were silently
+  forced into the collapsed rail's flyout/ignore treatment, hiding their entire child list the
+  moment the sidebar collapsed — worst for a group with no icon of its own, which rendered as a
+  blank row. `collapsible: false` now overrides `collapsedGroupBehavior` and always stays fully
+  expanded; an icon-less trigger row is skipped on the rail instead of rendering blank.
+- **Fixed:** nested rows that do render on the rail (the above, or `collapsedGroupBehavior:
+  "expand"`) had their icon pushed off-center by depth-based indentation, which only makes sense
+  once labels are visible. Indentation now resets to flush on the rail (excluding flyout content,
+  see below).
+- **Fixed:** the collapsed-rail **flyout** — one of three `collapsedGroupBehavior` modes, and the
+  default — rendered every row inside it icon-only: the rail's label/badge/chevron-hiding rules
+  are all more specific than the flyout's "show them again" carve-out, so `display: none` silently
+  won regardless of source order. This affected any group with a badge or a nested sub-group (the
+  playground's own "Operations" example, badge included, was hit by it). The carve-out is
+  `!important` now.
+- **Fixed:** the mobile drawer is portaled to `document.body`, which left an empty `.bsb-root`
+  column (sized to the desktop rail's width) sitting in the host layout at the sidebar's original
+  position, and left the portaled drawer itself with none of the sidebar's `--bsb-*` tokens,
+  resets, or dark-mode detection (all scoped to an `.bsb-root` ancestor the portal boundary broke).
+  The in-place wrapper is gone; the theme/reset scope now travels through the portal with the
+  drawer instead.
 - Collapse toggle now defaults to the sidebar's own background color (`--bsb-toggle-bg:
   var(--bsb-bg)`) with a stronger elevation shadow and a translucent ring border, so it reads as
   a floating control instead of an oddly-tinted, hard-to-see button. `greenMist`'s toggle tokens
-  were updated to match.
+  were updated to match. (This was a specificity bug: a bare `.bsb-toggle` rule tied with the
+  `.bsb-root button` reset and lost at rest, leaving the button borderless and near-invisible
+  until `:hover`. Published `0.1.0` still has it; fixed here by scoping to `.bsb-root .bsb-toggle`.)
+- Docs: clarified that `collapsible: false` beats `collapsedGroupBehavior` (see above), added a
+  "Layout requirements" section covering the `height: 100%` contract `.bsb-nav` scrolling depends
+  on and Next.js App Router's fixed CSS import order, and noted the mobile drawer's portal
+  behavior.
+
+## [0.1.0]
+
+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.

package/README.md

@@ -30,6 +30,40 @@ 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).
 
+## Layout requirements
+
+`.bsb-root` is `height: 100%`, and its internal `.bsb-nav` is the only element that scrolls
+(`overflow-y: auto`). Both only work if every ancestor between `<Sidebar>` and a definite-height
+container also resolves to a real height — percentage heights fall back to `auto` otherwise. Miss
+this and two things break together: the rail grows to fit its content instead of scrolling
+internally, and the page picks up a scrollbar it shouldn't have — most visible as a height jump
+whenever a group opens/closes.
+
+Give your root layout a definite height and let `<Sidebar>` sit as a flex/grid item next to your
+content:
+
+```css
+html, body, #root { height: 100%; }
+```
+
+```tsx
+<div style={{ display: 'flex', height: '100vh', overflow: 'hidden' }}>
+  <Sidebar items={items} />
+  <main style={{ flex: 1, overflow: 'auto' }}>{children}</main>
+</div>
+```
+
+A `min-height` (or no height at all) on that wrapper isn't enough — `min-height` doesn't give
+descendants a *definite* height to resolve `height: 100%` against, so `.bsb-nav` still won't scroll.
+
+**CSS import order.** "Near your app's own global stylesheet" above assumes your bundler honors
+source order. Frameworks that bundle by module graph — Next.js App Router in particular — always
+place a component's own imported CSS *after* the root layout's global CSS, regardless of which
+file imports which. If your global CSS and `@bensdev/react-sidebar/styles.css` both set the same
+property on the same selector at equal specificity, the sidebar's rule wins there no matter what
+your source order says — override with a more specific selector (`.my-app .bsb-root`) or
+`!important` instead of relying on import order.
+
 ## Quick start
 
 ```tsx
@@ -134,11 +168,17 @@ Router's `NavLink end`), and `isActive` to override the computed value entirely.
 ]}
 ```
 
-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.
+A group with `collapsible: false` renders as a static section: its `label` becomes a heading and
+children are always visible — a lighter-weight alternative to a top-level `heading` + flat items.
+That holds on the collapsed icon rail too: `collapsible: false` overrides `collapsedGroupBehavior`
+entirely, so its children never fold into a flyout, and never disappear. Give the group its own
+`icon` if you want a row for it on the rail as well; without one, only the children (each with
+their own icon) render there, the same as a `heading` would.
+
+*Collapsible* groups (the default) present differently once the sidebar collapses to its icon
+rail: a hover/focus **flyout** by default (`collapsedGroupBehavior="flyout"`), or set it to
+`"expand"` (rendered inline and indented, same as expanded) or `"ignore"` (trigger only, children
+unreachable while collapsed) instead.
 
 ## Collapse / expand
 
@@ -172,6 +212,12 @@ The drawer includes a focus trap, Escape-to-close, backdrop-click-to-close, body
 respects `prefers-reduced-motion` — all on by default and individually toggleable
 (`trapFocus`, `closeOnEscape`, `closeOnBackdropClick`, `lockScroll`, `reduceMotion`).
 
+It's portaled to `document.body` by default (pass `portalTarget` for somewhere else, or
+`disablePortal` to render it in place), so it escapes any `overflow: hidden`/`z-index` ancestor
+your layout has. The sidebar's theme tokens, resets, and dark-mode detection travel with it across
+the portal boundary — no `.bsb-root` wrapper is left behind at the drawer's original position, and
+none of its own CSS is scoped to depend on being a descendant of one.
+
 ## Theming
 
 Every visual value is a `--bsb-*` CSS custom property (see `src/styles.css` for the full list —

package/dist/index.cjs

@@ -522,10 +522,17 @@ function SidebarGroupRow({ item, depth }) {
             children: /* @__PURE__ */ jsxRuntime.jsx(ChevronDownIcon, { size: 14 })
           }
         ),
-        showTooltip && behavior !== "flyout" && /* @__PURE__ */ jsxRuntime.jsx(Tooltip, { id: tooltipId, className: ctx.classNames.tooltip, children: item.tooltip ?? item.label })
+        showTooltip && (!collapsible || behavior !== "flyout") && /* @__PURE__ */ jsxRuntime.jsx(Tooltip, { id: tooltipId, className: ctx.classNames.tooltip, children: item.tooltip ?? item.label })
       ]
     }
   );
+  if (!collapsible) {
+    const showTrigger = item.icon != null || !isRail;
+    return /* @__PURE__ */ jsxRuntime.jsxs("li", { className: cx("bsb-list-item", "bsb-group"), children: [
+      showTrigger && trigger,
+      /* @__PURE__ */ jsxRuntime.jsx("ul", { id: panelId, className: cx("bsb-group__panel", ctx.classNames.groupPanel), children: /* @__PURE__ */ jsxRuntime.jsx(SidebarNodeList, { items: item.items, depth: depth + 1 }) })
+    ] });
+  }
   if (isRail && behavior === "flyout") {
     return /* @__PURE__ */ jsxRuntime.jsxs("li", { className: cx("bsb-list-item", "bsb-group", "bsb-group--flyout"), children: [
       trigger,
@@ -548,7 +555,7 @@ function SidebarGroupRow({ item, depth }) {
   }
   return /* @__PURE__ */ jsxRuntime.jsxs("li", { className: cx("bsb-list-item", "bsb-group"), children: [
     trigger,
-    (isOpen || !collapsible) && /* @__PURE__ */ jsxRuntime.jsx("ul", { id: panelId, className: cx("bsb-group__panel", ctx.classNames.groupPanel), children: /* @__PURE__ */ jsxRuntime.jsx(SidebarNodeList, { items: item.items, depth: depth + 1 }) })
+    isOpen && /* @__PURE__ */ jsxRuntime.jsx("ul", { id: panelId, className: cx("bsb-group__panel", ctx.classNames.groupPanel), children: /* @__PURE__ */ jsxRuntime.jsx(SidebarNodeList, { items: item.items, depth: depth + 1 }) })
   ] });
 }
 function SidebarNode({ item, depth }) {
@@ -852,7 +859,10 @@ function MobileDrawer({
   closeLabel,
   classNames,
   durationMs = 400,
-  children
+  children,
+  rootClassName,
+  rootStyle,
+  rootDataAttrs
 }) {
   const { mounted, state, onPanelTransitionEnd } = useMountTransition(open, durationMs);
   const panelRef = React21__namespace.useRef(null);
@@ -864,7 +874,7 @@ function MobileDrawer({
   useBodyScrollLock(lockScroll && open);
   if (!mounted) return null;
   const widthValue = typeof width === "number" ? `${width}px` : width;
-  return /* @__PURE__ */ jsxRuntime.jsxs(Portal, { target: portalTarget, disabled: disablePortal, children: [
+  return /* @__PURE__ */ jsxRuntime.jsx(Portal, { target: portalTarget, disabled: disablePortal, children: /* @__PURE__ */ jsxRuntime.jsxs("div", { className: cx(rootClassName, "bsb-root--drawer-host"), style: rootStyle, ...rootDataAttrs, children: [
     /* @__PURE__ */ jsxRuntime.jsx(
       "div",
       {
@@ -903,7 +913,7 @@ function MobileDrawer({
         ]
       }
     )
-  ] });
+  ] }) });
 }
 function widthToCss(value) {
   if (value == null) return void 0;
@@ -1147,35 +1157,32 @@ var Sidebar = React21__namespace.forwardRef(function Sidebar2(props, ref) {
         )
       }
     ),
-    isMobile && /* @__PURE__ */ jsxRuntime.jsx(
-      "div",
-      {
-        ref: rootRef,
-        className: rootClassName,
-        style: mergedStyle,
-        ...rootDataAttrs,
-        children: /* @__PURE__ */ jsxRuntime.jsx(
-          MobileDrawer,
-          {
-            open: mobileOpen,
-            onClose: closeMobile,
-            ariaLabel,
-            width: drawerWidth,
-            position,
-            closeOnEscape,
-            closeOnBackdropClick,
-            trapFocus,
-            lockScroll,
-            restoreFocus,
-            portalTarget,
-            disablePortal,
-            closeLabel: "Close navigation",
-            classNames,
-            children: /* @__PURE__ */ jsxRuntime.jsx(SidebarShell, { ...shellProps, collapsed: false, showToggle: false, onToggle: toggleCollapsed, togglePosition: position, toggleStrategy, toggleLabels: { expand: "Expand sidebar", collapse: "Collapse sidebar" } })
-          }
-        )
-      }
-    )
+    isMobile && /* @__PURE__ */ jsxRuntime.jsxs(jsxRuntime.Fragment, { children: [
+      /* @__PURE__ */ jsxRuntime.jsx("span", { ref: rootRef, "aria-hidden": "true", style: { display: "none" } }),
+      /* @__PURE__ */ jsxRuntime.jsx(
+        MobileDrawer,
+        {
+          open: mobileOpen,
+          onClose: closeMobile,
+          ariaLabel,
+          width: drawerWidth,
+          position,
+          closeOnEscape,
+          closeOnBackdropClick,
+          trapFocus,
+          lockScroll,
+          restoreFocus,
+          portalTarget,
+          disablePortal,
+          closeLabel: "Close navigation",
+          classNames,
+          rootClassName,
+          rootStyle: mergedStyle,
+          rootDataAttrs,
+          children: /* @__PURE__ */ jsxRuntime.jsx(SidebarShell, { ...shellProps, collapsed: false, showToggle: false, onToggle: toggleCollapsed, togglePosition: position, toggleStrategy, toggleLabels: { expand: "Expand sidebar", collapse: "Collapse sidebar" } })
+        }
+      )
+    ] })
   ] });
 });
 Sidebar.displayName = "Sidebar";