@fragments-sdk/ui 0.7.5 → 0.8.0

package/src/components/Sidebar/index.tsx

@@ -212,7 +212,7 @@ function CloseIcon() {
   );
 }
 
-function CollapseLeftIcon() {
+function CollapsePanelIcon() {
   return (
     <svg
       xmlns="http://www.w3.org/2000/svg"
@@ -222,22 +222,7 @@ function CollapseLeftIcon() {
       fill="currentColor"
       aria-hidden="true"
     >
-      <path d="M141.66,181.66a8,8,0,0,1-11.32,0l-48-48a8,8,0,0,1,0-11.32l48-48a8,8,0,0,1,11.32,11.32L99.31,128l42.35,42.34A8,8,0,0,1,141.66,181.66Zm40-96L139.31,128l42.35,42.34a8,8,0,0,1-11.32,11.32l-48-48a8,8,0,0,1,0-11.32l48-48a8,8,0,0,1,11.32,11.32Z" />
-    </svg>
-  );
-}
-
-function CollapseRightIcon() {
-  return (
-    <svg
-      xmlns="http://www.w3.org/2000/svg"
-      width="20"
-      height="20"
-      viewBox="0 0 256 256"
-      fill="currentColor"
-      aria-hidden="true"
-    >
-      <path d="M141.66,133.66l-48,48a8,8,0,0,1-11.32-11.32L124.69,128,82.34,85.66a8,8,0,0,1,11.32-11.32l48,48A8,8,0,0,1,141.66,133.66Zm40-11.32-48-48a8,8,0,0,0-11.32,11.32L164.69,128l-42.35,42.34a8,8,0,0,0,11.32,11.32l48-48A8,8,0,0,0,181.66,122.34Z" />
+      <path d="M216,40H40A16,16,0,0,0,24,56V200a16,16,0,0,0,16,16H216a16,16,0,0,0,16-16V56A16,16,0,0,0,216,40ZM40,56H80V200H40ZM216,200H96V56H216V200Z" />
     </svg>
   );
 }
@@ -271,6 +256,7 @@ interface SidebarContextValue {
   width: string;
   collapsedWidth: string;
   collapsible: SidebarCollapsible;
+  hasIcons: boolean;
   toggleSidebar: () => void;
   sidebarId: string;
 }
@@ -293,8 +279,9 @@ function useSidebar() {
       isMobile: false,
       position: 'left' as const,
       width: '240px',
-      collapsedWidth: '64px',
+      collapsedWidth: '56px',
       collapsible: 'icon' as SidebarCollapsible,
+      hasIcons: true,
       toggleSidebar: () => {},
       sidebarId: 'sidebar',
       state: 'expanded' as 'expanded' | 'collapsed' | 'open' | 'closed',
@@ -359,6 +346,32 @@ function useControllableState<T>(
   return [value, setValue];
 }
 
+function hasSidebarItemIcons(children: React.ReactNode): boolean {
+  let found = false;
+
+  const visit = (nodes: React.ReactNode) => {
+    React.Children.forEach(nodes, child => {
+      if (found || !React.isValidElement(child)) return;
+
+      if (child.type === SidebarItem) {
+        const props = child.props as SidebarItemProps;
+        if (props.icon) {
+          found = true;
+          return;
+        }
+      }
+
+      const childProps = child.props as { children?: React.ReactNode };
+      if (childProps?.children) {
+        visit(childProps.children);
+      }
+    });
+  };
+
+  visit(children);
+  return found;
+}
+
 // ============================================
 // Components
 // ============================================
@@ -376,7 +389,7 @@ function SidebarProvider({
   defaultOpen = false,
   onOpenChange,
   width = '240px',
-  collapsedWidth = '64px',
+  collapsedWidth = '56px',
   position = 'left',
   collapsible = 'icon',
   enableKeyboardShortcut = true,
@@ -459,6 +472,7 @@ function SidebarProvider({
     width,
     collapsedWidth,
     collapsible,
+    hasIcons: true,
     toggleSidebar,
     sidebarId,
   };
@@ -479,7 +493,7 @@ function SidebarRoot({
   defaultOpen = false,
   onOpenChange,
   width = '240px',
-  collapsedWidth = '64px',
+  collapsedWidth = '56px',
   position = 'left',
   collapsible = 'icon',
   className,
@@ -512,6 +526,10 @@ function SidebarRoot({
   const resolvedWidth = existingContext ? existingContext.width : width;
   const resolvedCollapsedWidth = existingContext ? existingContext.collapsedWidth : collapsedWidth;
   const resolvedCollapsible = existingContext ? existingContext.collapsible : collapsible;
+  const hasIcons = React.useMemo(() => hasSidebarItemIcons(children), [children]);
+  const shouldCollapseToZero = !isMobile && resolvedCollapsible === 'icon' && collapsed && !hasIcons;
+  const isOffcanvasCollapsed = !isMobile && resolvedCollapsible === 'offcanvas' && collapsed;
+  const effectiveCollapsedWidth = (shouldCollapseToZero || isOffcanvasCollapsed) ? '0px' : resolvedCollapsedWidth;
   const sidebarId = React.useId();
   const resolvedSidebarId = existingContext ? existingContext.sidebarId : sidebarId;
   const sidebarRef = React.useRef<HTMLElement>(null);
@@ -558,28 +576,32 @@ function SidebarRoot({
     };
   }, [existingContext, isMobile, open]);
 
-  const contextValue: SidebarContextValue = existingContext || {
-    collapsed,
-    setCollapsed,
-    open,
-    setOpen,
-    isMobile,
-    position: resolvedPosition,
-    width: resolvedWidth,
-    collapsedWidth: resolvedCollapsedWidth,
-    collapsible: resolvedCollapsible,
-    toggleSidebar,
-    sidebarId: resolvedSidebarId,
+  const contextValue: SidebarContextValue = {
+    ...(existingContext || {
+      collapsed,
+      setCollapsed,
+      open,
+      setOpen,
+      isMobile,
+      position: resolvedPosition,
+      width: resolvedWidth,
+      collapsedWidth: resolvedCollapsedWidth,
+      collapsible: resolvedCollapsible,
+      hasIcons,
+      toggleSidebar,
+      sidebarId: resolvedSidebarId,
+    }),
+    hasIcons,
   };
 
   const isCollapsedForStyle = resolvedCollapsible === 'icon' && collapsed;
-  const isOffcanvas = resolvedCollapsible === 'offcanvas' && collapsed;
 
   const classes = [
     styles.root,
     isMobile && styles.mobile,
     !isMobile && isCollapsedForStyle && styles.collapsed,
-    !isMobile && isOffcanvas && styles.offcanvas,
+    !isMobile && isCollapsedForStyle && shouldCollapseToZero && styles.collapsedNoIcons,
+    isOffcanvasCollapsed && styles.offcanvasCollapsed,
     resolvedPosition === 'right' && styles.positionRight,
     className,
   ].filter(Boolean).join(' ');
@@ -587,6 +609,7 @@ function SidebarRoot({
   const style: React.CSSProperties = {
     '--sidebar-width': resolvedWidth,
     '--sidebar-collapsed-width': resolvedCollapsedWidth,
+    '--sidebar-effective-collapsed-width': effectiveCollapsedWidth,
     ...styleProp,
   } as React.CSSProperties;
 
@@ -604,16 +627,12 @@ function SidebarRoot({
       data-state={isMobile ? (open ? 'open' : 'closed') : (collapsed ? 'collapsed' : 'expanded')}
       data-position={resolvedPosition}
       data-collapsible={resolvedCollapsible}
+      data-icon-collapse={resolvedCollapsible === 'icon' ? (hasIcons ? 'icons' : 'none') : undefined}
     >
       {children}
     </aside>
   );
 
-  // If already inside a provider, don't wrap with another provider
-  if (existingContext) {
-    return content;
-  }
-
   return (
     <SidebarContext.Provider value={contextValue}>
       {content}
@@ -951,19 +970,24 @@ function SidebarOverlay({ className }: SidebarOverlayProps) {
 }
 
 function SidebarCollapseToggle({ 'aria-label': ariaLabel, className }: SidebarCollapseToggleProps) {
-  const { collapsed, setCollapsed, isMobile, position, collapsible } = useSidebarContext();
+  const { collapsed, setCollapsed, isMobile, collapsible, hasIcons } = useSidebarContext();
 
   // Don't show on mobile or when collapsing is disabled
   if (isMobile || collapsible === 'none') {
     return null;
   }
 
-  const classes = [styles.collapseToggle, className].filter(Boolean).join(' ');
+  const shouldFloat = collapsed && (
+    (collapsible === 'icon' && !hasIcons) ||
+    collapsible === 'offcanvas'
+  );
+  const classes = [
+    styles.collapseToggle,
+    shouldFloat && styles.collapseToggleFloating,
+    className,
+  ].filter(Boolean).join(' ');
   const label = ariaLabel || (collapsed ? 'Expand sidebar' : 'Collapse sidebar');
 
-  // Determine which icon to show based on position and state
-  const showExpandIcon = position === 'left' ? collapsed : !collapsed;
-
   return (
     <button
       type="button"
@@ -971,7 +995,7 @@ function SidebarCollapseToggle({ 'aria-label': ariaLabel, className }: SidebarCo
       onClick={() => setCollapsed(!collapsed)}
       aria-label={label}
     >
-      {showExpandIcon ? <CollapseRightIcon /> : <CollapseLeftIcon />}
+      <CollapsePanelIcon />
     </button>
   );
 }

package/src/components/Skeleton/Skeleton.fragment.tsx

@@ -69,6 +69,11 @@ export default defineSegment({
       values: ['none', 'sm', 'md', 'lg', 'full'],
       description: 'Border radius override',
     },
+    static: {
+      type: 'boolean',
+      default: false,
+      description: 'Disable skeleton animation',
+    },
   },
 
   relations: [

package/src/components/Slider/index.tsx

@@ -24,7 +24,7 @@ export interface SliderProps extends Omit<React.HTMLAttributes<HTMLDivElement>,
   'aria-describedby'?: string;
 }
 
-export const Slider = React.forwardRef<HTMLDivElement, SliderProps>(
+const SliderRoot = React.forwardRef<HTMLDivElement, SliderProps>(
   function Slider(
     {
       label,
@@ -96,3 +96,7 @@ export const Slider = React.forwardRef<HTMLDivElement, SliderProps>(
     );
   }
 );
+
+export const Slider = Object.assign(SliderRoot, {
+  Root: SliderRoot,
+});

package/src/components/Stack/Stack.fragment.tsx

@@ -48,12 +48,12 @@ export default defineSegment({
       required: true,
     },
     direction: {
-      type: 'string | object',
+      type: 'union',
       description: 'Stack direction: "row", "column", or responsive object',
       default: 'column',
     },
     gap: {
-      type: 'string | object',
+      type: 'union',
       description: 'Spacing between items: "none", "xs", "sm", "md", "lg", "xl", or responsive object',
       default: 'md',
     },

package/src/components/Stack/index.tsx

@@ -71,7 +71,7 @@ function isResponsiveGap(gap: StackProps['gap']): gap is ResponsiveGap {
   return typeof gap === 'object' && gap !== null;
 }
 
-export const Stack = React.forwardRef<HTMLElement, StackProps>(
+const StackRoot = React.forwardRef<HTMLElement, StackProps>(
   function Stack(
     {
       children,
@@ -180,3 +180,7 @@ function gapToSpace(gap: Gap): string {
   };
   return map[gap];
 }
+
+export const Stack = Object.assign(StackRoot, {
+  Root: StackRoot,
+});

package/src/components/Table/Table.fragment.tsx

@@ -86,16 +86,36 @@ export default defineSegment({
       description: 'Data rows to display',
       required: true,
     },
+    getRowId: {
+      type: 'function',
+      description: 'Unique key extractor for each row',
+    },
     sortable: {
       type: 'boolean',
       description: 'Enable column sorting',
       default: 'false',
     },
+    sorting: {
+      type: 'object',
+      description: 'Controlled sorting state',
+    },
+    onSortingChange: {
+      type: 'function',
+      description: 'Sorting change handler',
+    },
     selectable: {
       type: 'boolean',
       description: 'Enable row selection',
       default: 'false',
     },
+    rowSelection: {
+      type: 'object',
+      description: 'Controlled row selection state',
+    },
+    onRowSelectionChange: {
+      type: 'function',
+      description: 'Row selection change handler',
+    },
     onRowClick: {
       type: 'function',
       description: 'Handler for row clicks',
@@ -111,6 +131,15 @@ export default defineSegment({
       values: ['sm', 'md'],
       default: 'md',
     },
+    caption: {
+      type: 'string',
+      description: 'Visible caption for the table',
+    },
+    captionHidden: {
+      type: 'boolean',
+      default: 'false',
+      description: 'Hide caption visually but keep it for screen readers',
+    },
     striped: {
       type: 'boolean',
       description: 'Show alternating row backgrounds',

package/src/components/Table/index.tsx

@@ -51,7 +51,7 @@ export interface TableProps<T> extends Omit<React.HTMLAttributes<HTMLTableElemen
   bordered?: boolean;
 }
 
-export function Table<T>({
+function TableRoot<T>({
   columns,
   data,
   getRowId,
@@ -330,3 +330,8 @@ export function createColumns<T>(
 
 // Re-export useful types
 export type { ColumnDef, SortingState, RowSelectionState };
+
+export const Table = Object.assign(TableRoot, {
+  Root: TableRoot,
+  Columns: createColumns,
+});

package/src/components/TableOfContents/TableOfContents.fragment.tsx

@@ -0,0 +1,149 @@
+import React from 'react';
+import { defineSegment } from '@fragments/core';
+import { TableOfContents } from '.';
+
+export default defineSegment({
+  component: TableOfContents,
+
+  meta: {
+    name: 'TableOfContents',
+    description: 'Sticky sidebar navigation for long-form content. Renders heading links with active state highlighting for scroll spy integration.',
+    category: 'navigation',
+    status: 'stable',
+    tags: ['toc', 'table-of-contents', 'navigation', 'sidebar', 'scroll-spy', 'headings'],
+    since: '0.9.0',
+  },
+
+  usage: {
+    when: [
+      'Long-form content pages (docs, blog posts, articles)',
+      'Component documentation with multiple sections',
+      'Any page with 3+ headings that benefits from quick navigation',
+    ],
+    whenNot: [
+      'Short pages with only 1-2 sections',
+      'Primary site navigation (use Sidebar or Header)',
+      'Step-by-step flows (use Stepper)',
+    ],
+    guidelines: [
+      'Pair with a scroll spy hook (e.g., IntersectionObserver) to track active heading',
+      'Use indent on sub-headings (h3) to show hierarchy',
+      'Place in a sticky aside for best UX',
+      'Heading IDs must match between TOC items and the actual DOM headings',
+    ],
+    accessibility: [
+      'Uses <nav aria-label="Table of contents"> for landmark navigation',
+      'Active item is marked with aria-current="true"',
+      'All items are links with smooth scroll behavior',
+      'Focus-visible ring on keyboard navigation',
+    ],
+  },
+
+  props: {
+    children: {
+      type: 'node',
+      description: 'TableOfContents.Item elements',
+      required: true,
+    },
+    label: {
+      type: 'string',
+      description: 'Accessible label for the nav landmark',
+      default: '"Table of contents"',
+    },
+    title: {
+      type: 'string',
+      description: 'Visible title above the list',
+      default: '"On This Page"',
+    },
+    hideTitle: {
+      type: 'boolean',
+      description: 'Hide the visible title',
+      default: 'false',
+    },
+  },
+
+  relations: [
+    { component: 'Breadcrumbs', relationship: 'complementary', note: 'Breadcrumbs show hierarchy, TOC shows page sections' },
+    { component: 'Sidebar', relationship: 'complementary', note: 'Sidebar for site nav, TOC for in-page nav' },
+    { component: 'Tabs', relationship: 'alternative', note: 'Tabs for switching views, TOC for scrolling to sections' },
+  ],
+
+  contract: {
+    propsSummary: [
+      'title: string - visible heading (default "On This Page")',
+      'hideTitle: boolean - hide the title',
+      'label: string - aria-label for nav landmark',
+      'TableOfContents.Item id: string - heading ID to link to',
+      'TableOfContents.Item active: boolean - highlight as current',
+      'TableOfContents.Item indent: boolean - indent for sub-headings',
+    ],
+    scenarioTags: [
+      'navigation.toc',
+      'navigation.scroll-spy',
+      'layout.sidebar',
+    ],
+    a11yRules: ['A11Y_NAV_LANDMARK', 'A11Y_ARIA_CURRENT'],
+  },
+
+  ai: {
+    compositionPattern: 'compound',
+    subComponents: ['Item'],
+    requiredChildren: ['Item'],
+    commonPatterns: [
+      '<TableOfContents>{headings.map(h => <TableOfContents.Item key={h.id} id={h.id} active={activeId === h.id} indent={h.level === 3}>{h.text}</TableOfContents.Item>)}</TableOfContents>',
+    ],
+  },
+
+  variants: [
+    {
+      name: 'Default',
+      description: 'Basic table of contents with section links',
+      render: () => (
+        <TableOfContents>
+          <TableOfContents.Item id="introduction">Introduction</TableOfContents.Item>
+          <TableOfContents.Item id="getting-started">Getting Started</TableOfContents.Item>
+          <TableOfContents.Item id="installation" indent>Installation</TableOfContents.Item>
+          <TableOfContents.Item id="configuration" indent>Configuration</TableOfContents.Item>
+          <TableOfContents.Item id="api-reference">API Reference</TableOfContents.Item>
+          <TableOfContents.Item id="examples">Examples</TableOfContents.Item>
+        </TableOfContents>
+      ),
+    },
+    {
+      name: 'With Active Item',
+      description: 'Active state highlighting the current section',
+      render: () => (
+        <TableOfContents>
+          <TableOfContents.Item id="overview">Overview</TableOfContents.Item>
+          <TableOfContents.Item id="setup" active>Setup</TableOfContents.Item>
+          <TableOfContents.Item id="usage" indent>Basic Usage</TableOfContents.Item>
+          <TableOfContents.Item id="advanced" indent>Advanced</TableOfContents.Item>
+          <TableOfContents.Item id="props">Props</TableOfContents.Item>
+          <TableOfContents.Item id="accessibility">Accessibility</TableOfContents.Item>
+        </TableOfContents>
+      ),
+    },
+    {
+      name: 'Custom Title',
+      description: 'Table of contents with a custom title',
+      render: () => (
+        <TableOfContents title="Contents">
+          <TableOfContents.Item id="chapter-1">Chapter 1: The Beginning</TableOfContents.Item>
+          <TableOfContents.Item id="chapter-2">Chapter 2: The Middle</TableOfContents.Item>
+          <TableOfContents.Item id="chapter-3">Chapter 3: The End</TableOfContents.Item>
+        </TableOfContents>
+      ),
+    },
+    {
+      name: 'No Title',
+      description: 'Table of contents without a visible title',
+      render: () => (
+        <TableOfContents hideTitle>
+          <TableOfContents.Item id="section-a">Section A</TableOfContents.Item>
+          <TableOfContents.Item id="section-b" active>Section B</TableOfContents.Item>
+          <TableOfContents.Item id="section-c">Section C</TableOfContents.Item>
+        </TableOfContents>
+      ),
+    },
+  ],
+});

package/src/components/TableOfContents/TableOfContents.module.scss

@@ -0,0 +1,71 @@
+@use '../../tokens/variables' as *;
+
+// Root nav wrapper
+.root {
+  font-family: var(--fui-font-sans, $fui-font-sans);
+  font-size: var(--fui-font-size-sm, $fui-font-size-sm);
+  line-height: var(--fui-line-height-normal, $fui-line-height-normal);
+}
+
+// Title text ("On This Page")
+.title {
+  font-size: var(--fui-font-size-xs, $fui-font-size-xs);
+  font-weight: var(--fui-font-weight-semibold, $fui-font-weight-semibold);
+  color: var(--fui-text-secondary, $fui-text-secondary);
+  text-transform: uppercase;
+  letter-spacing: 0.05em;
+  margin: 0;
+  padding: 0 0 var(--fui-space-2, $fui-space-2) 0;
+}
+
+// List container
+.list {
+  display: flex;
+  flex-direction: column;
+  list-style: none;
+  margin: 0;
+  padding: 0;
+}
+
+// Individual item
+.item {
+  display: block;
+}
+
+// Link styling shared by all items
+.link {
+  display: block;
+  padding: var(--fui-space-1, $fui-space-1) 0 var(--fui-space-1, $fui-space-1) var(--fui-space-3, $fui-space-3);
+  border-left: 2px solid transparent;
+  color: var(--fui-text-secondary, $fui-text-secondary);
+  font-size: var(--fui-font-size-xs, $fui-font-size-xs);
+  line-height: var(--fui-line-height-normal, $fui-line-height-normal);
+  text-decoration: none;
+  transition: color var(--fui-transition-fast, $fui-transition-fast),
+    border-color var(--fui-transition-fast, $fui-transition-fast);
+
+  &:hover {
+    color: var(--fui-text-primary, $fui-text-primary);
+  }
+
+  &:focus-visible {
+    outline: var(--fui-focus-ring-width, $fui-focus-ring-width) solid var(--fui-focus-ring-color, $fui-focus-ring-color);
+    outline-offset: var(--fui-focus-ring-offset, $fui-focus-ring-offset);
+    border-radius: var(--fui-radius-sm, $fui-radius-sm);
+  }
+}
+
+// Indent for depth > 2 (h3s)
+.indent {
+  padding-left: var(--fui-space-6, $fui-space-6);
+}
+
+// Active state
+.active {
+  border-left-color: var(--fui-color-accent, $fui-color-accent);
+  color: var(--fui-color-accent, $fui-color-accent);
+
+  &:hover {
+    color: var(--fui-color-accent, $fui-color-accent);
+  }
+}