@fragments-sdk/ui 0.7.5 → 0.8.0

package/src/components/ScrollArea/index.tsx

@@ -0,0 +1,121 @@
+import * as React from 'react';
+import styles from './ScrollArea.module.scss';
+import '../../styles/globals.scss';
+
+// ============================================
+// Types
+// ============================================
+
+export interface ScrollAreaProps extends React.HTMLAttributes<HTMLDivElement> {
+  children: React.ReactNode;
+  /** Scroll direction */
+  orientation?: 'horizontal' | 'vertical' | 'both';
+  /** Scrollbar visibility behavior */
+  scrollbarVisibility?: 'auto' | 'always' | 'hover';
+  /** Whether to show fade indicators at scroll edges */
+  showFades?: boolean;
+  /** Additional class name */
+  className?: string;
+}
+
+// ============================================
+// Component
+// ============================================
+
+/**
+ * ScrollArea - A styled scrollable container with customizable scrollbars.
+ *
+ * Provides thin, unobtrusive scrollbars that appear on hover or scroll,
+ * with optional fade indicators to hint at overflowing content.
+ */
+function ScrollAreaRoot({
+  children,
+  orientation = 'vertical',
+  scrollbarVisibility = 'auto',
+  showFades = false,
+  className,
+  ...htmlProps
+}: ScrollAreaProps) {
+  const viewportRef = React.useRef<HTMLDivElement>(null);
+  const [canScrollStart, setCanScrollStart] = React.useState(false);
+  const [canScrollEnd, setCanScrollEnd] = React.useState(false);
+
+  const updateScrollState = React.useCallback(() => {
+    const el = viewportRef.current;
+    if (!el || !showFades) return;
+
+    if (orientation === 'horizontal') {
+      setCanScrollStart(el.scrollLeft > 1);
+      setCanScrollEnd(el.scrollLeft < el.scrollWidth - el.clientWidth - 1);
+    } else {
+      setCanScrollStart(el.scrollTop > 1);
+      setCanScrollEnd(el.scrollTop < el.scrollHeight - el.clientHeight - 1);
+    }
+  }, [orientation, showFades]);
+
+  React.useEffect(() => {
+    const el = viewportRef.current;
+    if (!el || !showFades) return;
+
+    // Defer initial check to ensure children have laid out
+    const raf = requestAnimationFrame(updateScrollState);
+
+    el.addEventListener('scroll', updateScrollState, { passive: true });
+
+    // Observe both the viewport AND its children for size changes
+    // (viewport size stays constant when children overflow — only scrollWidth changes)
+    const observer = new ResizeObserver(updateScrollState);
+    observer.observe(el);
+    Array.from(el.children).forEach(child => observer.observe(child));
+
+    return () => {
+      cancelAnimationFrame(raf);
+      el.removeEventListener('scroll', updateScrollState);
+      observer.disconnect();
+    };
+  }, [showFades, updateScrollState]);
+
+  const rootClasses = [
+    styles.root,
+    className,
+  ].filter(Boolean).join(' ');
+
+  // Determine which fade mask to apply to the viewport
+  const fadeMask = showFades
+    ? canScrollStart && canScrollEnd
+      ? styles.fadeMaskBoth
+      : canScrollStart
+        ? styles.fadeMaskStart
+        : canScrollEnd
+          ? styles.fadeMaskEnd
+          : undefined
+    : undefined;
+
+  const viewportClasses = [
+    styles.viewport,
+    styles[orientation],
+    scrollbarVisibility === 'always' && styles.scrollbarAlways,
+    scrollbarVisibility === 'hover' && styles.scrollbarHover,
+    fadeMask,
+  ].filter(Boolean).join(' ');
+
+  return (
+    <div
+      {...htmlProps}
+      className={rootClasses}
+      data-orientation={orientation}
+    >
+      <div ref={viewportRef} className={viewportClasses}>
+        {children}
+      </div>
+    </div>
+  );
+}
+
+// ============================================
+// Export
+// ============================================
+
+export const ScrollArea = Object.assign(ScrollAreaRoot, {
+  Root: ScrollAreaRoot,
+});

package/src/components/Select/Select.fragment.tsx

@@ -72,6 +72,19 @@ export default defineSegment({
       type: 'function',
       description: 'Called when selection changes',
     },
+    open: {
+      type: 'boolean',
+      description: 'Controlled open state of the dropdown',
+    },
+    defaultOpen: {
+      type: 'boolean',
+      description: 'Initial open state for uncontrolled usage',
+      default: 'false',
+    },
+    onOpenChange: {
+      type: 'function',
+      description: 'Called when dropdown open state changes',
+    },
     placeholder: {
       type: 'string',
       description: 'Placeholder text when no value selected',
@@ -81,11 +94,6 @@ export default defineSegment({
       description: 'Disable the select',
       default: 'false',
     },
-    maxVisibleItems: {
-      type: 'number',
-      description: 'Maximum visible options before scrolling. Shows half of the next item as a scroll hint.',
-      default: '4',
-    },
   },
 
   relations: [

package/src/components/Separator/index.tsx

@@ -34,7 +34,7 @@ const spacingClasses = {
 // Component
 // ============================================
 
-export const Separator = React.forwardRef<HTMLDivElement, SeparatorProps>(
+const SeparatorRoot = React.forwardRef<HTMLDivElement, SeparatorProps>(
   function Separator(
     {
       orientation = 'horizontal',
@@ -91,3 +91,7 @@ export const Separator = React.forwardRef<HTMLDivElement, SeparatorProps>(
     );
   }
 );
+
+export const Separator = Object.assign(SeparatorRoot, {
+  Root: SeparatorRoot,
+});

package/src/components/Sidebar/Sidebar.fragment.tsx

@@ -182,11 +182,12 @@ function ExternalTriggerContent() {
 function ProviderDemo() {
   return (
     <div style={demoContainerStyle}>
-      <SidebarProvider defaultCollapsed={false}>
+      <SidebarProvider>
         <Sidebar>
           <Sidebar.Header collapsedContent={<LogoIcon size={32} />}>
             <LogoIcon size={32} />
             <span style={{ fontWeight: 600, fontSize: '16px' }}>Acme App</span>
+            <Sidebar.CollapseToggle />
           </Sidebar.Header>
           <Sidebar.Nav>
             <Sidebar.Section>
@@ -195,9 +196,6 @@ function ProviderDemo() {
               <Sidebar.Item icon={<UsersIcon />}>Team</Sidebar.Item>
             </Sidebar.Section>
           </Sidebar.Nav>
-          <Sidebar.Footer>
-            <Sidebar.CollapseToggle />
-          </Sidebar.Footer>
         </Sidebar>
         <ExternalTriggerContent />
       </SidebarProvider>
@@ -322,6 +320,35 @@ function SkeletonDemo() {
   );
 }
 
+// Demo for offcanvas collapsed state
+function OffcanvasDemo() {
+  const [collapsed, setCollapsed] = useState(true);
+  return (
+    <div style={demoContainerStyle}>
+      <Sidebar collapsed={collapsed} onCollapsedChange={setCollapsed} collapsible="offcanvas">
+        <Sidebar.Header collapsedContent={<LogoIcon size={32} />}>
+          <LogoIcon size={32} />
+          <span style={{ fontWeight: 600, fontSize: '16px' }}>Acme App</span>
+        </Sidebar.Header>
+        <Sidebar.Nav>
+          <Sidebar.Section>
+            <Sidebar.Item icon={<HomeIcon />} active>Dashboard</Sidebar.Item>
+            <Sidebar.Item icon={<ChartIcon />}>Analytics</Sidebar.Item>
+            <Sidebar.Item icon={<UsersIcon />}>Team</Sidebar.Item>
+            <Sidebar.Item icon={<FolderIcon />}>Projects</Sidebar.Item>
+          </Sidebar.Section>
+        </Sidebar.Nav>
+        <Sidebar.Footer>
+          <Sidebar.CollapseToggle />
+        </Sidebar.Footer>
+      </Sidebar>
+      <main style={mainContentStyle}>
+        Offcanvas mode hides sidebar completely. Toggle stays visible to re-open.
+      </main>
+    </div>
+  );
+}
+
 // Demo for rail toggle
 function RailDemo() {
   const [collapsed, setCollapsed] = useState(false);
@@ -459,11 +486,6 @@ export default defineSegment({
       values: ['icon', 'offcanvas', 'none'],
       default: 'icon',
     },
-    asChild: {
-      type: 'boolean',
-      description: '(Sidebar.Item) Render as child element for polymorphic composition',
-      default: false,
-    },
   },
 
   relations: [
@@ -690,9 +712,14 @@ export default defineSegment({
       description: 'SidebarProvider enables external triggers and keyboard shortcuts (Cmd/Ctrl+B).',
       code: `function App() {
   return (
-    <SidebarProvider defaultCollapsed={false}>
+    <SidebarProvider>
       <Sidebar>
-        {/* sidebar content */}
+        <Sidebar.Header>
+          <Logo />
+          <span>Acme App</span>
+          <Sidebar.CollapseToggle />
+        </Sidebar.Header>
+        {/* sidebar nav */}
       </Sidebar>
       <MainContent />
     </SidebarProvider>
@@ -779,5 +806,31 @@ function MainContent() {
 </Sidebar>`,
       render: () => <RailDemo />,
     },
+    {
+      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.',
+      code: `function App() {
+  const [collapsed, setCollapsed] = useState(true);
+
+  return (
+    <Sidebar collapsed={collapsed} onCollapsedChange={setCollapsed} collapsible="offcanvas">
+      <Sidebar.Header collapsedContent={<Logo />}>
+        <Logo />
+        <span>Acme App</span>
+      </Sidebar.Header>
+      <Sidebar.Nav>
+        <Sidebar.Section>
+          <Sidebar.Item icon={<HomeIcon />} active>Dashboard</Sidebar.Item>
+          <Sidebar.Item icon={<ChartIcon />}>Analytics</Sidebar.Item>
+        </Sidebar.Section>
+      </Sidebar.Nav>
+      <Sidebar.Footer>
+        <Sidebar.CollapseToggle />
+      </Sidebar.Footer>
+    </Sidebar>
+  );
+}`,
+      render: () => <OffcanvasDemo />,
+    },
   ],
 });

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

@@ -27,11 +27,15 @@
 
 // Desktop collapsed state
 .collapsed {
-  width: var(--sidebar-collapsed-width);
+  width: var(--sidebar-effective-collapsed-width, var(--sidebar-collapsed-width));
 
   .header {
     justify-content: center;
-    padding: var(--fui-padding-container-sm, $fui-padding-container-sm);
+    padding: var(--fui-padding-item-xs, $fui-padding-item-xs);
+  }
+
+  .nav {
+    padding: var(--fui-padding-item-xs, $fui-padding-item-xs);
   }
 
   .sectionLabel {
@@ -46,7 +50,8 @@
 
   .item {
     justify-content: center;
-    padding: var(--fui-padding-container-sm, $fui-padding-container-sm);
+    padding: var(--fui-padding-item-xs, $fui-padding-item-xs);
+    min-height: $fui-touch-md;
   }
 
   .itemIcon {
@@ -55,7 +60,7 @@
 
   .footer {
     justify-content: center;
-    padding: var(--fui-padding-container-sm, $fui-padding-container-sm);
+    padding: var(--fui-padding-item-xs, $fui-padding-item-xs);
   }
 
   .collapseToggle {
@@ -63,6 +68,22 @@
   }
 }
 
+.collapsedNoIcons {
+  overflow: visible;
+
+  .header,
+  .nav,
+  .footer {
+    visibility: hidden;
+    pointer-events: none;
+  }
+
+  .collapseToggleFloating {
+    visibility: visible;
+    pointer-events: auto;
+  }
+}
+
 // Mobile state
 .mobile {
   position: fixed;
@@ -208,7 +229,7 @@
   @include interactive-base;
   @include text-base;
 
-  display: inline-flex;
+  display: flex;
   align-items: center;
   gap: var(--fui-space-3, $fui-space-3);
   padding: var(--fui-padding-item-xs, $fui-padding-item-xs) var(--fui-padding-item-sm, $fui-padding-item-sm);
@@ -229,13 +250,19 @@
 }
 
 .itemActive {
-  // Use accent-hover for active state to ensure WCAG AA contrast (4.5:1 minimum)
-  background-color: var(--fui-color-accent-hover, $fui-color-accent-hover);
-  color: var(--fui-text-inverse, $fui-text-inverse);
+  // Use secondary surface + primary text so active state adapts in light and dark themes
+  background-color: var(--fui-bg-secondary, $fui-bg-secondary);
+  color: var(--fui-text-primary, $fui-text-primary);
 
   &:hover {
-    background-color: var(--fui-color-accent-hover, $fui-color-accent-hover) !important;
-    color: var(--fui-text-inverse, $fui-text-inverse) !important;
+    background-color: var(--fui-bg-secondary, $fui-bg-secondary) !important;
+    color: var(--fui-text-primary, $fui-text-primary) !important;
+    text-decoration: none;
+  }
+
+  &:active {
+    background-color: var(--fui-bg-secondary, $fui-bg-secondary) !important;
+    color: var(--fui-text-primary, $fui-text-primary) !important;
     text-decoration: none;
   }
 
@@ -485,16 +512,41 @@
   }
 }
 
+.collapseToggleFloating {
+  position: absolute;
+  top: var(--fui-space-3, $fui-space-3);
+  left: calc(100% + var(--fui-space-2, $fui-space-2));
+  z-index: 20;
+  margin: 0;
+  background-color: var(--fui-bg-primary, $fui-bg-primary);
+  border: 1px solid var(--fui-border, $fui-border);
+  box-shadow: var(--fui-shadow-sm, $fui-shadow-sm);
+
+  .positionRight & {
+    left: auto;
+    right: calc(100% + var(--fui-space-2, $fui-space-2));
+  }
+}
+
 // ============================================
-// Offcanvas Mode (slides completely off-screen)
+// Offcanvas Mode (collapses to zero width with floating toggle)
 // ============================================
 
-.offcanvas {
-  transform: translateX(-100%);
-  position: absolute;
+.offcanvasCollapsed {
+  width: 0;
+  overflow: visible;
 
-  &.positionRight {
-    transform: translateX(100%);
+  .header,
+  .nav,
+  .footer,
+  .rail {
+    visibility: hidden;
+    pointer-events: none;
+  }
+
+  .collapseToggleFloating {
+    visibility: visible;
+    pointer-events: auto;
   }
 }
 

package/src/components/Sidebar/Sidebar.test.tsx

@@ -1,5 +1,5 @@
-import { describe, it, expect, vi, beforeAll, afterAll } from 'vitest';
-import { render, screen, userEvent, expectNoA11yViolations } from '../../test/utils';
+import { describe, it, expect, vi, beforeAll } from 'vitest';
+import { render, screen, expectNoA11yViolations } from '../../test/utils';
 import { Sidebar } from './index';
 
 // Mock matchMedia for jsdom
@@ -78,6 +78,35 @@ describe('Sidebar', () => {
     expect(aside).toHaveAttribute('data-state');
   });
 
+  it('uses icon collapse width when collapsed with icons', () => {
+    renderSidebar({ collapsed: true });
+    const aside = document.querySelector('aside');
+    expect(aside).toHaveStyle('--sidebar-effective-collapsed-width: 56px');
+    expect(aside).toHaveAttribute('data-icon-collapse', 'icons');
+  });
+
+  it('collapses fully when collapsed with no item icons and keeps toggle visible', () => {
+    render(
+      <Sidebar collapsed aria-label="Text-only sidebar">
+        <Sidebar.Header>
+          Header Content
+          <Sidebar.CollapseToggle />
+        </Sidebar.Header>
+        <Sidebar.Nav aria-label="Main">
+          <Sidebar.Section label="Section One">
+            <Sidebar.Item>Dashboard</Sidebar.Item>
+            <Sidebar.Item active>Settings</Sidebar.Item>
+          </Sidebar.Section>
+        </Sidebar.Nav>
+      </Sidebar>
+    );
+
+    const aside = document.querySelector('aside');
+    expect(aside).toHaveStyle('--sidebar-effective-collapsed-width: 0px');
+    expect(aside).toHaveAttribute('data-icon-collapse', 'none');
+    expect(screen.getByRole('button', { name: /expand sidebar/i })).toBeInTheDocument();
+  });
+
   it('has no accessibility violations', async () => {
     const { container } = renderSidebar();
     await expectNoA11yViolations(container);