@fragments-sdk/ui 0.1.0

package/src/components/Table/index.tsx

@@ -0,0 +1,266 @@
+import * as React from 'react';
+import {
+  useReactTable,
+  getCoreRowModel,
+  getSortedRowModel,
+  flexRender,
+  type ColumnDef,
+  type SortingState,
+  type RowSelectionState,
+  type OnChangeFn,
+} from '@tanstack/react-table';
+// Import globals to ensure CSS variables are defined
+import '../../styles/globals.scss';
+import styles from './Table.module.scss';
+
+// Column definition helper type
+export type TableColumn<T> = ColumnDef<T, unknown>;
+
+export interface TableProps<T> {
+  /** Column definitions */
+  columns: TableColumn<T>[];
+  /** Data array */
+  data: T[];
+  /** Unique key extractor for each row */
+  getRowId?: (row: T) => string;
+  /** Enable sorting */
+  sortable?: boolean;
+  /** Controlled sorting state */
+  sorting?: SortingState;
+  /** Sorting change handler */
+  onSortingChange?: OnChangeFn<SortingState>;
+  /** Enable row selection */
+  selectable?: boolean;
+  /** Controlled selection state */
+  rowSelection?: RowSelectionState;
+  /** Selection change handler */
+  onRowSelectionChange?: OnChangeFn<RowSelectionState>;
+  /** Row click handler */
+  onRowClick?: (row: T) => void;
+  /** Empty state message */
+  emptyMessage?: string;
+  /** Size variant */
+  size?: 'sm' | 'md';
+  /** Additional class name */
+  className?: string;
+}
+
+export function Table<T>({
+  columns,
+  data,
+  getRowId,
+  sortable = false,
+  sorting: controlledSorting,
+  onSortingChange,
+  selectable = false,
+  rowSelection: controlledRowSelection,
+  onRowSelectionChange,
+  onRowClick,
+  emptyMessage = 'No data available',
+  size = 'md',
+  className,
+}: TableProps<T>) {
+  // Internal sorting state when uncontrolled
+  const [internalSorting, setInternalSorting] = React.useState<SortingState>([]);
+  const sorting = controlledSorting ?? internalSorting;
+  const handleSortingChange = onSortingChange ?? setInternalSorting;
+
+  // Internal selection state when uncontrolled
+  const [internalRowSelection, setInternalRowSelection] = React.useState<RowSelectionState>({});
+  const rowSelection = controlledRowSelection ?? internalRowSelection;
+  const handleRowSelectionChange = onRowSelectionChange ?? setInternalRowSelection;
+
+  const table = useReactTable({
+    data,
+    columns,
+    getRowId,
+    getCoreRowModel: getCoreRowModel(),
+    getSortedRowModel: sortable ? getSortedRowModel() : undefined,
+    state: {
+      sorting: sortable ? sorting : undefined,
+      rowSelection: selectable ? rowSelection : undefined,
+    },
+    onSortingChange: sortable ? handleSortingChange : undefined,
+    onRowSelectionChange: selectable ? handleRowSelectionChange : undefined,
+    enableRowSelection: selectable,
+    enableSorting: sortable,
+  });
+
+  const isEmpty = data.length === 0;
+
+  const rootClasses = [styles.table, styles[size], className]
+    .filter(Boolean)
+    .join(' ');
+
+  if (isEmpty) {
+    return (
+      <div className={styles.emptyState}>
+        <span className={styles.emptyMessage}>{emptyMessage}</span>
+      </div>
+    );
+  }
+
+  return (
+    <div className={styles.wrapper}>
+      <table className={rootClasses}>
+        <thead className={styles.thead}>
+          {table.getHeaderGroups().map((headerGroup) => (
+            <tr key={headerGroup.id} className={styles.headerRow}>
+              {headerGroup.headers.map((header) => {
+                const canSort = sortable && header.column.getCanSort();
+                const sortDirection = header.column.getIsSorted();
+
+                return (
+                  <th
+                    key={header.id}
+                    className={styles.th}
+                    style={{
+                      width: header.getSize() !== 150 ? header.getSize() : undefined,
+                    }}
+                    onClick={canSort ? header.column.getToggleSortingHandler() : undefined}
+                    aria-sort={
+                      sortDirection
+                        ? sortDirection === 'asc'
+                          ? 'ascending'
+                          : 'descending'
+                        : undefined
+                    }
+                  >
+                    <div
+                      className={[
+                        styles.headerContent,
+                        canSort && styles.sortable,
+                      ]
+                        .filter(Boolean)
+                        .join(' ')}
+                    >
+                      {header.isPlaceholder
+                        ? null
+                        : flexRender(
+                            header.column.columnDef.header,
+                            header.getContext()
+                          )}
+                      {canSort && (
+                        <span className={styles.sortIndicator} aria-hidden="true">
+                          {sortDirection === 'asc' ? (
+                            <SortAscIcon />
+                          ) : sortDirection === 'desc' ? (
+                            <SortDescIcon />
+                          ) : (
+                            <SortIcon />
+                          )}
+                        </span>
+                      )}
+                    </div>
+                  </th>
+                );
+              })}
+            </tr>
+          ))}
+        </thead>
+        <tbody className={styles.tbody}>
+          {table.getRowModel().rows.map((row) => {
+            const isClickable = !!onRowClick;
+            const isSelected = selectable ? row.getIsSelected() : false;
+
+            return (
+              <tr
+                key={row.id}
+                className={[
+                  styles.row,
+                  isClickable && styles.clickable,
+                  isSelected && styles.selected,
+                ]
+                  .filter(Boolean)
+                  .join(' ')}
+                onClick={isClickable ? () => onRowClick(row.original) : undefined}
+                data-selected={isSelected || undefined}
+              >
+                {row.getVisibleCells().map((cell) => (
+                  <td key={cell.id} className={styles.td}>
+                    {flexRender(cell.column.columnDef.cell, cell.getContext())}
+                  </td>
+                ))}
+              </tr>
+            );
+          })}
+        </tbody>
+      </table>
+    </div>
+  );
+}
+
+// Sort icons - minimal and functional
+function SortIcon() {
+  return (
+    <svg
+      width="12"
+      height="12"
+      viewBox="0 0 12 12"
+      fill="none"
+      xmlns="http://www.w3.org/2000/svg"
+    >
+      <path
+        d="M6 2L8.5 5H3.5L6 2Z"
+        fill="currentColor"
+        opacity="0.3"
+      />
+      <path
+        d="M6 10L3.5 7H8.5L6 10Z"
+        fill="currentColor"
+        opacity="0.3"
+      />
+    </svg>
+  );
+}
+
+function SortAscIcon() {
+  return (
+    <svg
+      width="12"
+      height="12"
+      viewBox="0 0 12 12"
+      fill="none"
+      xmlns="http://www.w3.org/2000/svg"
+    >
+      <path d="M6 2L8.5 5H3.5L6 2Z" fill="currentColor" />
+    </svg>
+  );
+}
+
+function SortDescIcon() {
+  return (
+    <svg
+      width="12"
+      height="12"
+      viewBox="0 0 12 12"
+      fill="none"
+      xmlns="http://www.w3.org/2000/svg"
+    >
+      <path d="M6 10L3.5 7H8.5L6 10Z" fill="currentColor" />
+    </svg>
+  );
+}
+
+// Helper to create simple columns without TanStack's createColumnHelper
+export function createColumns<T>(
+  columns: Array<{
+    key: string;
+    header: string;
+    width?: number;
+    cell?: (row: T) => React.ReactNode;
+  }>
+): TableColumn<T>[] {
+  return columns.map((col) => ({
+    id: col.key,
+    accessorKey: col.key,
+    header: col.header,
+    size: col.width,
+    cell: col.cell
+      ? ({ row }) => col.cell!(row.original)
+      : ({ getValue }) => getValue() ?? '--',
+  }));
+}
+
+// Re-export useful types
+export type { ColumnDef, SortingState, RowSelectionState };

package/src/components/Tabs/Tabs.fragment.tsx

@@ -0,0 +1,155 @@
+import React from 'react';
+import { defineSegment } from '@fragments/core';
+import { Tabs } from './index.js';
+
+export default defineSegment({
+  component: Tabs,
+
+  meta: {
+    name: 'Tabs',
+    description: 'Organize content into switchable panels. Use for related content that benefits from a compact, navigable layout.',
+    category: 'navigation',
+    status: 'stable',
+    tags: ['tabs', 'navigation', 'panels', 'content-switcher'],
+    since: '0.1.0',
+  },
+
+  usage: {
+    when: [
+      'Organizing related content into sections',
+      'Reducing page scrolling by grouping content',
+      'Settings pages with multiple categories',
+      'Dashboard views with different data perspectives',
+    ],
+    whenNot: [
+      'Primary navigation (use sidebar or header nav)',
+      'Sequential steps (use Stepper or wizard)',
+      'Comparing content side-by-side',
+      'Very long lists of options (use Select or Menu)',
+    ],
+    guidelines: [
+      'Keep tab labels short (1-2 words)',
+      'Order tabs by usage frequency or logical sequence',
+      'Avoid more than 5-6 tabs; consider sub-navigation for more',
+      'Tab content should be roughly equivalent in scope',
+      'Use pills variant for contained sections, underline for page-level tabs',
+    ],
+    accessibility: [
+      'Keyboard navigation with arrow keys',
+      'Tab panels are properly labeled',
+      'Focus management follows WAI-ARIA tabs pattern',
+    ],
+  },
+
+  props: {
+    children: {
+      type: 'node',
+      description: 'Tab list and panels (use Tabs.List, Tabs.Tab, Tabs.Panel)',
+      required: true,
+    },
+    defaultValue: {
+      type: 'string',
+      description: 'Initially active tab (uncontrolled)',
+    },
+    value: {
+      type: 'string',
+      description: 'Controlled active tab value',
+    },
+    onValueChange: {
+      type: 'function',
+      description: 'Called when active tab changes',
+    },
+    orientation: {
+      type: 'enum',
+      description: 'Tab list orientation',
+      values: ['horizontal', 'vertical'],
+      default: 'horizontal',
+    },
+  },
+
+  relations: [
+    { component: 'Select', relationship: 'alternative', note: 'Use Select for many options in compact space' },
+    { component: 'Menu', relationship: 'alternative', note: 'Use Menu for action-based navigation' },
+  ],
+
+  contract: {
+    propsSummary: [
+      'value: string - controlled active tab',
+      'defaultValue: string - initial active tab',
+      'onValueChange: (value) => void - tab change handler',
+      'Tabs.List variant: underline|pills - visual style',
+    ],
+    scenarioTags: [
+      'navigation.tabs',
+      'layout.panels',
+      'content.sections',
+    ],
+    a11yRules: ['A11Y_TABS_KEYBOARD', 'A11Y_TABS_LABELS'],
+  },
+
+  variants: [
+    {
+      name: 'Underline',
+      description: 'Default underline style tabs',
+      render: () => (
+        <Tabs defaultValue="overview">
+          <Tabs.List variant="underline">
+            <Tabs.Tab value="overview">Overview</Tabs.Tab>
+            <Tabs.Tab value="analytics">Analytics</Tabs.Tab>
+            <Tabs.Tab value="settings">Settings</Tabs.Tab>
+          </Tabs.List>
+          <Tabs.Panel value="overview">
+            <p>Overview content goes here.</p>
+          </Tabs.Panel>
+          <Tabs.Panel value="analytics">
+            <p>Analytics content goes here.</p>
+          </Tabs.Panel>
+          <Tabs.Panel value="settings">
+            <p>Settings content goes here.</p>
+          </Tabs.Panel>
+        </Tabs>
+      ),
+    },
+    {
+      name: 'Pills',
+      description: 'Pill-style tabs for contained sections',
+      render: () => (
+        <Tabs defaultValue="all">
+          <Tabs.List variant="pills">
+            <Tabs.Tab value="all">All</Tabs.Tab>
+            <Tabs.Tab value="active">Active</Tabs.Tab>
+            <Tabs.Tab value="archived">Archived</Tabs.Tab>
+          </Tabs.List>
+          <Tabs.Panel value="all">
+            <p>Showing all items.</p>
+          </Tabs.Panel>
+          <Tabs.Panel value="active">
+            <p>Showing active items only.</p>
+          </Tabs.Panel>
+          <Tabs.Panel value="archived">
+            <p>Showing archived items.</p>
+          </Tabs.Panel>
+        </Tabs>
+      ),
+    },
+    {
+      name: 'With Disabled',
+      description: 'Tabs with a disabled option',
+      render: () => (
+        <Tabs defaultValue="general">
+          <Tabs.List variant="underline">
+            <Tabs.Tab value="general">General</Tabs.Tab>
+            <Tabs.Tab value="security">Security</Tabs.Tab>
+            <Tabs.Tab value="billing" disabled>Billing</Tabs.Tab>
+          </Tabs.List>
+          <Tabs.Panel value="general">
+            <p>General settings panel.</p>
+          </Tabs.Panel>
+          <Tabs.Panel value="security">
+            <p>Security settings panel.</p>
+          </Tabs.Panel>
+        </Tabs>
+      ),
+    },
+  ],
+});

package/src/components/Tabs/Tabs.module.scss

@@ -0,0 +1,142 @@
+@use '../../tokens/variables' as *;
+@use '../../tokens/mixins' as *;
+
+// Root container
+.root {
+  display: flex;
+  flex-direction: column;
+  font-family: var(--fui-font-sans, $fui-font-sans);
+
+  &[data-orientation='vertical'] {
+    flex-direction: row;
+  }
+}
+
+// Tab list container
+.list {
+  position: relative;
+  display: flex;
+  align-items: center;
+  gap: var(--fui-space-1, $fui-space-1);
+  border-bottom: 1px solid var(--fui-border, $fui-border);
+  padding: 0 var(--fui-space-1, $fui-space-1);
+
+  &[data-orientation='vertical'] {
+    flex-direction: column;
+    align-items: stretch;
+    border-bottom: none;
+    border-right: 1px solid var(--fui-border, $fui-border);
+    padding: var(--fui-space-1, $fui-space-1) 0;
+  }
+}
+
+// Variant: pills (no border, background tabs)
+.listPills {
+  border-bottom: none;
+  background-color: var(--fui-bg-tertiary, $fui-bg-tertiary);
+  border-radius: var(--fui-radius-md, $fui-radius-md);
+  padding: var(--fui-space-1, $fui-space-1);
+}
+
+// Variant: underline (default, with indicator line)
+.listUnderline {
+  // Default styles already applied to .list
+}
+
+// Individual tab button
+.tab {
+  @include button-reset;
+  @include interactive-base;
+
+  position: relative;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  gap: var(--fui-space-2, $fui-space-2);
+  padding: var(--fui-space-2, $fui-space-2) var(--fui-space-3, $fui-space-3);
+  font-size: var(--fui-font-size-sm, $fui-font-size-sm);
+  font-weight: var(--fui-font-weight-medium, $fui-font-weight-medium);
+  color: var(--fui-text-secondary, $fui-text-secondary);
+  white-space: nowrap;
+  border-radius: var(--fui-radius-sm, $fui-radius-sm);
+
+  &:hover:not([data-disabled]) {
+    color: var(--fui-text-primary, $fui-text-primary);
+    background-color: var(--fui-bg-hover, $fui-bg-hover);
+  }
+
+  &[data-active] {
+    color: var(--fui-text-primary, $fui-text-primary);
+  }
+
+  &[data-disabled] {
+    color: var(--fui-text-tertiary, $fui-text-tertiary);
+  }
+}
+
+// Tab in underline variant
+.tabUnderline {
+  border-radius: 0;
+  margin-bottom: -1px;
+  padding-bottom: calc(var(--fui-space-2, $fui-space-2) + 1px);
+
+  &:hover:not([data-disabled]) {
+    background-color: transparent;
+  }
+}
+
+// Tab in pills variant
+.tabPills {
+  &[data-active] {
+    background-color: var(--fui-bg-elevated, $fui-bg-elevated);
+    box-shadow: var(--fui-shadow-sm, $fui-shadow-sm);
+  }
+}
+
+// Animated indicator (underline variant)
+.indicator {
+  position: absolute;
+  bottom: 0;
+  left: 0;
+  height: 2px;
+  background-color: var(--fui-color-accent, $fui-color-accent);
+  border-radius: var(--fui-radius-full, $fui-radius-full);
+
+  // Use CSS variables from Base UI for position
+  width: var(--active-tab-width);
+  transform: translateX(var(--active-tab-left));
+  transition:
+    width var(--fui-transition-fast, $fui-transition-fast),
+    transform var(--fui-transition-fast, $fui-transition-fast);
+
+  [data-orientation='vertical'] & {
+    bottom: auto;
+    left: auto;
+    right: 0;
+    top: 0;
+    width: 2px;
+    height: var(--active-tab-height);
+    transform: translateY(var(--active-tab-top));
+  }
+}
+
+// Tab panel content
+.panel {
+  padding: var(--fui-space-4, $fui-space-4) 0;
+  outline: none;
+
+  &[data-hidden] {
+    display: none;
+  }
+
+  // Focus visible for keyboard navigation
+  &:focus-visible {
+    @include focus-ring;
+    border-radius: var(--fui-radius-md, $fui-radius-md);
+  }
+}
+
+// Panel with no padding (for custom layouts)
+.panelFlush {
+  padding: 0;
+}

package/src/components/Tabs/index.tsx

@@ -0,0 +1,142 @@
+import * as React from 'react';
+import { Tabs as BaseTabs } from '@base-ui/react/tabs';
+import styles from './Tabs.module.scss';
+// Import globals to ensure CSS variables are defined
+import '../../styles/globals.scss';
+
+// ============================================
+// Types
+// ============================================
+
+export type TabValue = string | number;
+
+export interface TabsProps {
+  children: React.ReactNode;
+  defaultValue?: TabValue;
+  value?: TabValue;
+  onValueChange?: (value: TabValue) => void;
+  orientation?: 'horizontal' | 'vertical';
+  className?: string;
+}
+
+export interface TabsListProps {
+  children: React.ReactNode;
+  variant?: 'underline' | 'pills';
+  className?: string;
+}
+
+export interface TabProps {
+  children: React.ReactNode;
+  value: TabValue;
+  disabled?: boolean;
+  className?: string;
+}
+
+export interface TabsPanelProps {
+  children: React.ReactNode;
+  value: TabValue;
+  keepMounted?: boolean;
+  flush?: boolean;
+  className?: string;
+}
+
+// ============================================
+// Context for variant
+// ============================================
+
+const TabsVariantContext = React.createContext<'underline' | 'pills'>('underline');
+
+// ============================================
+// Components
+// ============================================
+
+function TabsRoot({
+  children,
+  defaultValue,
+  value,
+  onValueChange,
+  orientation = 'horizontal',
+  className,
+}: TabsProps) {
+  const classes = [styles.root, className].filter(Boolean).join(' ');
+
+  return (
+    <BaseTabs.Root
+      defaultValue={defaultValue}
+      value={value}
+      onValueChange={onValueChange}
+      orientation={orientation}
+      className={classes}
+    >
+      {children}
+    </BaseTabs.Root>
+  );
+}
+
+function TabsList({
+  children,
+  variant = 'underline',
+  className,
+}: TabsListProps) {
+  const variantClass = variant === 'pills' ? styles.listPills : styles.listUnderline;
+  const classes = [styles.list, variantClass, className].filter(Boolean).join(' ');
+
+  return (
+    <TabsVariantContext.Provider value={variant}>
+      <BaseTabs.List className={classes}>
+        {children}
+        {variant === 'underline' && <BaseTabs.Indicator className={styles.indicator} />}
+      </BaseTabs.List>
+    </TabsVariantContext.Provider>
+  );
+}
+
+function Tab({
+  children,
+  value,
+  disabled,
+  className,
+}: TabProps) {
+  const variant = React.useContext(TabsVariantContext);
+  const variantClass = variant === 'pills' ? styles.tabPills : styles.tabUnderline;
+  const classes = [styles.tab, variantClass, className].filter(Boolean).join(' ');
+
+  return (
+    <BaseTabs.Tab value={value} disabled={disabled} className={classes}>
+      {children}
+    </BaseTabs.Tab>
+  );
+}
+
+function TabsPanel({
+  children,
+  value,
+  keepMounted = false,
+  flush = false,
+  className,
+}: TabsPanelProps) {
+  const classes = [
+    styles.panel,
+    flush && styles.panelFlush,
+    className,
+  ].filter(Boolean).join(' ');
+
+  return (
+    <BaseTabs.Panel value={value} keepMounted={keepMounted} className={classes}>
+      {children}
+    </BaseTabs.Panel>
+  );
+}
+
+// ============================================
+// Export compound component
+// ============================================
+
+export const Tabs = Object.assign(TabsRoot, {
+  List: TabsList,
+  Tab: Tab,
+  Panel: TabsPanel,
+});
+
+// Re-export individual components
+export { TabsRoot, TabsList, Tab, TabsPanel };