@usefragments/ui 1.6.0 → 1.7.0

package/src/components/Sidebar/Sidebar.contract.json

@@ -1,15 +1,9 @@
 {
   "$schema": "https://usefragments.com/schemas/contract.v1.json",
   "name": "Sidebar",
-  "description": "Responsive navigation sidebar with collapsible desktop mode and mobile drawer behavior.",
-  "category": "navigation",
-  "tags": [
-    "sidebar",
-    "navigation",
-    "drawer",
-    "menu",
-    "layout"
-  ],
+  "description": "Collapsible navigation panel that turns into a drawer on mobile.",
+  "category": "layout",
+  "tags": ["sidebar", "navigation", "drawer", "menu", "layout"],
   "status": "stable",
   "sourcePath": "src/components/Sidebar/index.tsx",
   "exportName": "Sidebar",
@@ -83,31 +77,21 @@
       "description": "Sidebar position",
       "default": "left",
       "required": false,
-      "values": [
-        "left",
-        "right"
-      ]
+      "values": ["left", "right"]
     },
     "collapsible": {
       "type": "enum",
       "description": "Collapse behavior mode",
       "default": "icon",
       "required": false,
-      "values": [
-        "icon",
-        "offcanvas",
-        "none"
-      ]
+      "values": ["icon", "offcanvas", "none"]
     },
     "activeIndicator": {
       "type": "enum",
       "description": "Placement of the active-item affordance",
       "default": "start",
       "required": false,
-      "values": [
-        "start",
-        "end"
-      ]
+      "values": ["start", "end"]
     },
     "style": {
       "type": "object",
@@ -117,32 +101,22 @@
   },
   "usage": {
     "when": [
-      "Primary app navigation with multiple sections",
-      "Dashboard layouts requiring persistent navigation",
-      "Admin interfaces with hierarchical menu structure",
-      "Apps that need both mobile drawer and desktop sidebar"
+      "Primary navigation for an app shell",
+      "Navigation that must collapse to icons or hide entirely",
+      "Grouped destinations with active state"
     ],
     "whenNot": [
-      "Simple websites with few pages (use header nav)",
-      "Content-focused sites where navigation is secondary",
-      "Single-page applications with no navigation needs",
-      "Mobile-only apps where bottom navigation is preferred"
+      "Top-level horizontal navigation (use Header)",
+      "Temporary side panels for one task (use Drawer)",
+      "In-page section links (use a list of links)"
     ],
     "guidelines": [
-      "Group related items into sections with clear labels",
-      "Use icons for all items to support collapsed mode",
-      "Limit nesting to 2 levels maximum",
-      "Place most frequently used items at the top",
-      "Use badges sparingly for notifications or counts",
-      "The `active` prop on items should be controlled by your app based on current route",
-      "Use activeIndicator=\"end\" when the product language calls for a trailing status dot instead of the default start rail",
-      "Use `collapsedContent` on Header to show just a logo icon when collapsed",
-      "Submenus are hidden when collapsed - use tooltips for navigation hints instead",
-      "Use SidebarProvider to enable external triggers and keyboard shortcuts",
-      "Use asChild with routing libraries (Next.js Link, React Router NavLink)",
-      "Sidebar.Item and Sidebar.SubItem onClick handlers receive the click event object",
-      "Use `multiline` on Sidebar.Item when the row is a list entry rather than a nav link — a title over a status or preview line. Without it the label is one truncating line",
-      "Use Sidebar.MenuSkeleton while loading navigation data"
+      "Give every item an icon so the collapsed rail stays readable",
+      "collapsible=\"icon\" shrinks to a rail; \"offcanvas\" hides it completely",
+      "Wrap in SidebarProvider only when something outside must toggle it",
+      "An explicit collapsed prop overrides any surrounding provider",
+      "Sidebar.Rail and Sidebar.CollapseToggle are alternative toggles — pick one",
+      "Use Sidebar.MenuSkeleton while navigation data loads"
     ],
     "accessibility": [
       "Uses semantic <nav> element with aria-label",
@@ -157,57 +131,57 @@
   "examples": [
     {
       "name": "Default",
-      "description": "Standard sidebar with navigation sections. The `active` prop highlights the current page.",
+      "description": "Sections group items; active marks the current page.",
       "code": "<Sidebar>\n  <Sidebar.Header>\n    <Logo />\n    <span>Acme App</span>\n  </Sidebar.Header>\n  <Sidebar.Nav>\n    <Sidebar.Section>\n      <Sidebar.Item icon={<HomeIcon />} active>Dashboard</Sidebar.Item>\n      <Sidebar.Item icon={<ChartIcon />}>Analytics</Sidebar.Item>\n      <Sidebar.Item icon={<UsersIcon />}>Team</Sidebar.Item>\n      <Sidebar.Item icon={<FolderIcon />}>Projects</Sidebar.Item>\n    </Sidebar.Section>\n    <Sidebar.Section label=\"Settings\">\n      <Sidebar.Item icon={<GearIcon />}>Preferences</Sidebar.Item>\n      <Sidebar.Item icon={<HelpIcon />}>Help</Sidebar.Item>\n    </Sidebar.Section>\n  </Sidebar.Nav>\n  <Sidebar.Footer>\n    <Sidebar.CollapseToggle />\n  </Sidebar.Footer>\n</Sidebar>"
     },
     {
       "name": "Collapsed",
-      "description": "Icon-only collapsed state. Header shows only logo, tooltips appear on hover.",
+      "description": "Icon-only rail; labels move into hover tooltips.",
       "code": "function App() {\n  const [collapsed, setCollapsed] = useState(true);\n\n  return (\n    <Sidebar collapsed={collapsed} onCollapsedChange={setCollapsed}>\n      <Sidebar.Header collapsedContent={<Logo />}>\n        <Logo />\n        <span>Acme App</span>\n      </Sidebar.Header>\n      <Sidebar.Nav>\n        <Sidebar.Section>\n          <Sidebar.Item icon={<HomeIcon />} active>Dashboard</Sidebar.Item>\n          <Sidebar.Item icon={<ChartIcon />}>Analytics</Sidebar.Item>\n        </Sidebar.Section>\n      </Sidebar.Nav>\n      <Sidebar.Footer>\n        <Sidebar.CollapseToggle />\n      </Sidebar.Footer>\n    </Sidebar>\n  );\n}"
     },
     {
       "name": "With Badges",
-      "description": "Navigation items with notification badges for counts or alerts.",
+      "description": "Trailing counts for unread or pending work.",
       "code": "<Sidebar>\n  <Sidebar.Nav>\n    <Sidebar.Section>\n      <Sidebar.Item icon={<HomeIcon />} active>Dashboard</Sidebar.Item>\n      <Sidebar.Item icon={<ChartIcon />} badge=\"3\">Analytics</Sidebar.Item>\n      <Sidebar.Item icon={<UsersIcon />} badge=\"12\">Team</Sidebar.Item>\n      <Sidebar.Item icon={<FolderIcon />}>Projects</Sidebar.Item>\n    </Sidebar.Section>\n  </Sidebar.Nav>\n</Sidebar>"
     },
     {
       "name": "With Submenu",
-      "description": "Nested navigation with expandable sections. Use defaultExpanded for initial state without manual state tracking.",
+      "description": "Nested items; defaultExpanded sets the opening state.",
       "code": "<Sidebar>\n  <Sidebar.Nav>\n    <Sidebar.Section>\n      <Sidebar.Item icon={<HomeIcon />}>Dashboard</Sidebar.Item>\n      {/* Use defaultExpanded for uncontrolled mode - no state needed! */}\n      <Sidebar.Item icon={<FolderIcon />} hasSubmenu defaultExpanded>\n        Projects\n      </Sidebar.Item>\n      <Sidebar.Submenu>\n        <Sidebar.SubItem active>Website Redesign</Sidebar.SubItem>\n        <Sidebar.SubItem>Mobile App</Sidebar.SubItem>\n        <Sidebar.SubItem>API Integration</Sidebar.SubItem>\n      </Sidebar.Submenu>\n      {/* Multiple submenus work without tracking separate state */}\n      <Sidebar.Item icon={<UsersIcon />} hasSubmenu>\n        Team\n      </Sidebar.Item>\n      <Sidebar.Submenu>\n        <Sidebar.SubItem>Engineering</Sidebar.SubItem>\n        <Sidebar.SubItem>Design</Sidebar.SubItem>\n      </Sidebar.Submenu>\n    </Sidebar.Section>\n  </Sidebar.Nav>\n</Sidebar>"
     },
     {
       "name": "With Disabled Items",
-      "description": "Some navigation items are disabled for permissions or feature flags.",
+      "description": "Items switched off by permissions or feature flags.",
       "code": "<Sidebar>\n  <Sidebar.Nav>\n    <Sidebar.Section>\n      <Sidebar.Item icon={<HomeIcon />} active>Dashboard</Sidebar.Item>\n      <Sidebar.Item icon={<ChartIcon />}>Analytics</Sidebar.Item>\n      <Sidebar.Item icon={<UsersIcon />} disabled>\n        Team (Coming Soon)\n      </Sidebar.Item>\n      <Sidebar.Item icon={<FolderIcon />} disabled>\n        Projects (Upgrade)\n      </Sidebar.Item>\n    </Sidebar.Section>\n  </Sidebar.Nav>\n</Sidebar>"
     },
     {
       "name": "With Provider & External Trigger",
-      "description": "SidebarProvider enables external triggers and keyboard shortcuts (Cmd/Ctrl+B).",
-      "code": "function App() {\n  return (\n    <SidebarProvider>\n      <Sidebar>\n        <Sidebar.Header>\n          <Logo />\n          <span>Acme App</span>\n          <Sidebar.CollapseToggle />\n        </Sidebar.Header>\n        {/* sidebar nav */}\n      </Sidebar>\n      <MainContent />\n    </SidebarProvider>\n  );\n}\n\nfunction MainContent() {\n  const { toggleSidebar, state } = useSidebar();\n  return (\n    <main>\n      <p>State: {state}</p>\n      <button onClick={toggleSidebar}>Toggle</button>\n    </main>\n  );\n}"
+      "description": "useSidebar drives the sidebar from anywhere, plus Cmd/Ctrl+B.",
+      "code": "function App() {\n  return (\n    <SidebarProvider>\n      <Stack direction=\"row\" gap=\"lg\" align=\"start\">\n        <Sidebar>\n          <Sidebar.Header>\n            <Logo />\n            <span>Acme App</span>\n          </Sidebar.Header>\n          <Sidebar.Nav>\n            <Sidebar.Section>\n              <Sidebar.Item icon={<HomeIcon />} active>Dashboard</Sidebar.Item>\n              <Sidebar.Item icon={<ChartIcon />}>Analytics</Sidebar.Item>\n            </Sidebar.Section>\n          </Sidebar.Nav>\n        </Sidebar>\n        <MainContent />\n      </Stack>\n    </SidebarProvider>\n  );\n}\n\nfunction MainContent() {\n  const { toggleSidebar, state } = useSidebar();\n\n  return (\n    <Stack gap=\"sm\" align=\"start\">\n      <Text size=\"sm\" color=\"secondary\">State: {state}</Text>\n      <Button size=\"sm\" variant=\"secondary\" onClick={toggleSidebar}>\n        Toggle sidebar\n      </Button>\n    </Stack>\n  );\n}"
     },
     {
       "name": "With asChild (Polymorphic)",
-      "description": "Use asChild to render items as custom elements like Next.js Link or React Router NavLink.",
-      "code": "import { Link } from 'next/link';\n\n<Sidebar>\n  <Sidebar.Nav>\n    <Sidebar.Section>\n      <Sidebar.Item icon={<HomeIcon />} active asChild>\n        <Link href=\"/dashboard\">Dashboard</Link>\n      </Sidebar.Item>\n      <Sidebar.Item icon={<ChartIcon />} asChild>\n        <Link href=\"/analytics\">Analytics</Link>\n      </Sidebar.Item>\n    </Sidebar.Section>\n  </Sidebar.Nav>\n</Sidebar>"
+      "description": "Render items as your router's link component.",
+      "code": "import Link from 'next/link';\n\n<Sidebar>\n  <Sidebar.Nav>\n    <Sidebar.Section>\n      <Sidebar.Item icon={<HomeIcon />} active asChild>\n        <Link href=\"/dashboard\">Dashboard</Link>\n      </Sidebar.Item>\n      <Sidebar.Item icon={<ChartIcon />} asChild>\n        <Link href=\"/analytics\">Analytics</Link>\n      </Sidebar.Item>\n    </Sidebar.Section>\n  </Sidebar.Nav>\n</Sidebar>"
     },
     {
       "name": "With Section Action",
-      "description": "Section headers can include action buttons for quick actions like \"Add Project\".",
+      "description": "A section header can carry one quick action.",
       "code": "<Sidebar>\n  <Sidebar.Nav>\n    <Sidebar.Section\n      label=\"Projects\"\n      action={\n        <Sidebar.SectionAction aria-label=\"Add project\" onClick={handleAdd}>\n          <PlusIcon />\n        </Sidebar.SectionAction>\n      }\n    >\n      <Sidebar.Item icon={<FolderIcon />}>Website Redesign</Sidebar.Item>\n      <Sidebar.Item icon={<FolderIcon />}>Mobile App</Sidebar.Item>\n    </Sidebar.Section>\n  </Sidebar.Nav>\n</Sidebar>"
     },
     {
       "name": "With Loading Skeleton",
-      "description": "Show skeleton placeholders while navigation data is loading.",
-      "code": "<Sidebar>\n  <Sidebar.Nav>\n    {loading ? (\n      <Sidebar.MenuSkeleton count={6} />\n    ) : (\n      <Sidebar.Section>\n        <Sidebar.Item icon={<HomeIcon />}>Dashboard</Sidebar.Item>\n        {/* ... */}\n      </Sidebar.Section>\n    )}\n  </Sidebar.Nav>\n</Sidebar>"
+      "description": "Placeholder rows to show while navigation data loads.",
+      "code": "<Sidebar>\n  <Sidebar.Header>\n    <Logo />\n    <span>Acme App</span>\n  </Sidebar.Header>\n  <Sidebar.Nav>\n    <Sidebar.MenuSkeleton count={6} />\n  </Sidebar.Nav>\n</Sidebar>"
     },
     {
       "name": "With Rail Toggle",
-      "description": "Add a Rail component for a subtle drag-handle style toggle at the sidebar edge. Hover to reveal, click to toggle.",
-      "code": "<Sidebar collapsed={collapsed} onCollapsedChange={setCollapsed}>\n  <Sidebar.Header>{/* ... */}</Sidebar.Header>\n  <Sidebar.Nav>{/* ... */}</Sidebar.Nav>\n  <Sidebar.Footer>\n    <Sidebar.CollapseToggle />\n  </Sidebar.Footer>\n  <Sidebar.Rail />\n</Sidebar>"
+      "description": "Drag-handle toggle on the sidebar edge — hover to reveal, click to collapse.",
+      "code": "function App() {\n  const [collapsed, setCollapsed] = useState(false);\n\n  return (\n    <Sidebar collapsed={collapsed} onCollapsedChange={setCollapsed}>\n      <Sidebar.Header collapsedContent={<Logo />}>\n        <Logo />\n        <span>Acme App</span>\n      </Sidebar.Header>\n      <Sidebar.Nav>\n        <Sidebar.Section>\n          <Sidebar.Item icon={<HomeIcon />} active>Dashboard</Sidebar.Item>\n          <Sidebar.Item icon={<ChartIcon />}>Analytics</Sidebar.Item>\n          <Sidebar.Item icon={<FolderIcon />}>Projects</Sidebar.Item>\n        </Sidebar.Section>\n      </Sidebar.Nav>\n      <Sidebar.Rail />\n    </Sidebar>\n  );\n}"
     },
     {
       "name": "Offcanvas Collapsed",
-      "description": "Offcanvas mode hides the sidebar completely when collapsed, but the toggle button remains visible as a floating button so the user can always re-expand.",
+      "description": "Hides the panel entirely, leaving a floating re-open button.",
       "code": "function App() {\n  const [collapsed, setCollapsed] = useState(true);\n\n  return (\n    <Sidebar collapsed={collapsed} onCollapsedChange={setCollapsed} collapsible=\"offcanvas\">\n      <Sidebar.Header collapsedContent={<Logo />}>\n        <Logo />\n        <span>Acme App</span>\n      </Sidebar.Header>\n      <Sidebar.Nav>\n        <Sidebar.Section>\n          <Sidebar.Item icon={<HomeIcon />} active>Dashboard</Sidebar.Item>\n          <Sidebar.Item icon={<ChartIcon />}>Analytics</Sidebar.Item>\n        </Sidebar.Section>\n      </Sidebar.Nav>\n      <Sidebar.Footer>\n        <Sidebar.CollapseToggle />\n      </Sidebar.Footer>\n    </Sidebar>\n  );\n}"
     }
   ],
@@ -232,11 +206,7 @@
       "active: boolean - set on Sidebar.Item to mark current page (app-controlled)",
       "Sidebar.Item/SubItem onClick: (event) => void - click handler receives mouse event"
     ],
-    "a11yRules": [
-      "A11Y_NAV_LANDMARK",
-      "A11Y_FOCUS_TRAP",
-      "A11Y_ESCAPE_CLOSE"
-    ]
+    "a11yRules": ["A11Y_NAV_LANDMARK", "A11Y_FOCUS_TRAP", "A11Y_ESCAPE_CLOSE"]
   },
   "ai": {
     "compositionPattern": "compound",
@@ -255,9 +225,7 @@
       "Rail",
       "MenuSkeleton"
     ],
-    "requiredChildren": [
-      "Nav"
-    ],
+    "requiredChildren": ["Nav"],
     "commonPatterns": [
       "<Sidebar><Sidebar.Header>{logo}</Sidebar.Header><Sidebar.Nav><Sidebar.Section><Sidebar.Item icon={icon} active>{label}</Sidebar.Item></Sidebar.Section></Sidebar.Nav><Sidebar.Footer><Sidebar.CollapseToggle /></Sidebar.Footer></Sidebar>"
     ]

package/src/components/Sidebar/Sidebar.module.scss

@@ -8,7 +8,7 @@
   @include navigation.properties;
 
   --fui-sidebar-row-height: var(--fui-navigation-row-track);
-  --fui-sidebar-row-radius: var(--fui-radius-md, #{$fui-radius-md});
+  --fui-sidebar-row-radius: var(--fui-radius-full, #{$fui-radius-full});
   --fui-sidebar-gutter: var(--fui-navigation-gutter);
   --fui-sidebar-row-gap: var(--fui-navigation-content-gap);
   --fui-sidebar-row-padding-x: var(--fui-navigation-inline-inset);
@@ -35,7 +35,6 @@
   flex-direction: column;
   width: var(--sidebar-width);
   height: 100%;
-  max-height: 100vh;
   background: var(--fui-sidebar-bg, var(--fui-bg-primary, #{$fui-bg-primary}));
   border-inline-end: var(--fui-stroke-hairline, 1px) solid
     var(--fui-sidebar-border, var(--fui-border-default, #{$fui-border-default}));
@@ -160,8 +159,7 @@
   display: flex;
   flex-direction: column;
   overflow: hidden;
-  padding: var(--fui-sidebar-gutter) var(--fui-sidebar-gutter)
-    var(--fui-space-3, $fui-space-3);
+  padding: var(--fui-sidebar-gutter) var(--fui-sidebar-gutter) var(--fui-space-3, $fui-space-3);
 }
 
 .navScrollArea {
@@ -170,7 +168,9 @@
 }
 
 .section:not(:first-child) {
-  margin-top: var(--fui-raw-space-16, 16px);
+  // Consumers with sparse, reading-oriented navigation (docs sites) can open
+  // this up via --fui-sidebar-section-gap without touching the raw scale.
+  margin-top: var(--fui-sidebar-section-gap, var(--fui-raw-space-16, 16px));
 }
 
 .sectionHeader {
@@ -187,11 +187,19 @@
 
 // Override section-label-text inheritance — sidebar groups read as quiet
 // title-case headings, not shouty all-caps labels.
+// Section labels read as small tracked eyebrows — a clearly different voice
+// from the nav items beneath them, so groups can't be mistaken for links.
 .sectionLabel {
   flex: 1;
   min-width: 0;
-  text-transform: none;
-  color: var(--fui-sidebar-faint);
+  font-size: var(--fui-sidebar-section-label-size, var(--fui-font-size-2xs, #{$fui-font-size-2xs}));
+  letter-spacing: var(--fui-sidebar-section-label-tracking, 0.07em);
+  text-transform: var(--fui-sidebar-section-label-transform, uppercase);
+  color: var(--fui-sidebar-section-label-color, var(--fui-sidebar-faint));
+  font-weight: var(
+    --fui-sidebar-section-label-weight,
+    var(--fui-font-weight-medium, #{$fui-font-weight-medium})
+  );
 }
 
 .sectionActionWrapper {
@@ -225,7 +233,7 @@
   padding: 0;
   display: flex;
   flex-direction: column;
-  gap: var(--fui-raw-space-2, 2px);
+  gap: var(--fui-sidebar-item-gap, var(--fui-raw-space-2, 2px));
 }
 
 .sectionCollapsible .sectionTrigger {
@@ -278,6 +286,8 @@
   display: flex;
   align-items: center;
   width: 100%;
+  font-size: var(--fui-sidebar-item-font-size, var(--fui-type-ui-compact-size, 12px));
+  line-height: var(--fui-sidebar-item-line-height, var(--fui-type-ui-compact-line, 16px));
   border: var(--fui-stroke-hairline, 1px) solid transparent;
   border-radius: var(--fui-sidebar-row-radius);
   color: var(--fui-sidebar-muted);
@@ -323,10 +333,7 @@
   &.item:active {
     background-color: var(--fui-sidebar-active-bg);
     border-color: var(--fui-sidebar-active-border);
-    color: var(
-      --fui-sidebar-item-active-color,
-      var(--fui-text-primary, #{$fui-text-primary})
-    );
+    color: var(--fui-sidebar-item-active-color, var(--fui-text-primary, #{$fui-text-primary}));
     text-decoration: none;
   }
 
@@ -340,7 +347,9 @@
 .root[data-active-indicator="end"] .itemActive {
   @include navigation.active-indicator("end");
 
-  padding-inline-end: calc(var(--fui-navigation-inline-inset) * 2 + var(--fui-navigation-active-dot));
+  padding-inline-end: calc(
+    var(--fui-navigation-inline-inset) * 2 + var(--fui-navigation-active-dot)
+  );
 
   &::before {
     content: none;