@fragments-sdk/ui 0.1.0

package/src/components/Skeleton/index.tsx

@@ -0,0 +1,185 @@
+import * as React from 'react';
+import styles from './Skeleton.module.scss';
+// Import globals to ensure CSS variables are defined
+import '../../styles/globals.scss';
+
+// ============================================
+// Types
+// ============================================
+
+export type SkeletonVariant =
+  | 'text'      // Single line of text, height: 1em
+  | 'heading'   // Heading text, height: 1.5em
+  | 'avatar'    // Circular, uses size prop
+  | 'button'    // Button shape, uses size prop
+  | 'input'     // Form input height
+  | 'rect';     // Rectangle, requires explicit dimensions or fill
+
+export type SkeletonSize = 'sm' | 'md' | 'lg';
+
+export interface SkeletonProps {
+  /**
+   * Semantic variant that auto-sizes based on design tokens.
+   * @default 'rect'
+   */
+  variant?: SkeletonVariant;
+  /**
+   * Size variant for avatar/button. Ignored for text/heading/input.
+   * @default 'md'
+   */
+  size?: SkeletonSize;
+  /**
+   * Width in pixels or CSS value. Auto-determined for most variants.
+   */
+  width?: number | string;
+  /**
+   * Height in pixels or CSS value. Auto-determined for semantic variants.
+   */
+  height?: number | string;
+  /**
+   * Fill parent container (100% width and height).
+   * Useful when parent has explicit dimensions.
+   */
+  fill?: boolean;
+  /**
+   * Border radius override. Auto-determined for most variants.
+   */
+  radius?: 'none' | 'sm' | 'md' | 'lg' | 'full';
+  /**
+   * Disable animation for reduced motion preference.
+   * @default false
+   */
+  static?: boolean;
+  /** Additional class name */
+  className?: string;
+}
+
+export interface SkeletonTextProps {
+  /** Number of text lines to render */
+  lines?: number;
+  /**
+   * Width of last line as percentage.
+   * Creates natural paragraph appearance.
+   * @default 80
+   */
+  lastLineWidth?: number;
+  /** Gap between lines. Uses spacing tokens. */
+  gap?: 'sm' | 'md';
+  /** Additional class name */
+  className?: string;
+}
+
+// ============================================
+// Component
+// ============================================
+
+const SkeletonBase = React.forwardRef<HTMLDivElement, SkeletonProps>(
+  function SkeletonBase(
+    {
+      variant = 'rect',
+      size = 'md',
+      width,
+      height,
+      fill = false,
+      radius,
+      static: isStatic = false,
+      className,
+    },
+    ref
+  ) {
+    const classes = [
+      styles.skeleton,
+      styles[variant],
+      variant === 'avatar' && styles[`avatar-${size}`],
+      variant === 'button' && styles[`button-${size}`],
+      fill && styles.fill,
+      radius && styles[`radius-${radius}`],
+      isStatic && styles.static,
+      className,
+    ].filter(Boolean).join(' ');
+
+    const style: React.CSSProperties = {};
+
+    if (width !== undefined) {
+      style.width = typeof width === 'number' ? `${width}px` : width;
+    }
+    if (height !== undefined) {
+      style.height = typeof height === 'number' ? `${height}px` : height;
+    }
+
+    return (
+      <div
+        ref={ref}
+        className={classes}
+        style={Object.keys(style).length > 0 ? style : undefined}
+        aria-hidden="true"
+      />
+    );
+  }
+);
+
+// ============================================
+// Skeleton.Text - Multi-line text skeleton
+// ============================================
+
+function SkeletonText({
+  lines = 3,
+  lastLineWidth = 80,
+  gap = 'sm',
+  className,
+}: SkeletonTextProps) {
+  const containerClasses = [
+    styles.textContainer,
+    styles[`gap-${gap}`],
+    className,
+  ].filter(Boolean).join(' ');
+
+  return (
+    <div className={containerClasses} aria-hidden="true">
+      {Array.from({ length: lines }, (_, i) => {
+        const isLast = i === lines - 1;
+        return (
+          <div
+            key={i}
+            className={styles.textLine}
+            style={isLast && lines > 1 ? { width: `${lastLineWidth}%` } : undefined}
+          />
+        );
+      })}
+    </div>
+  );
+}
+
+// ============================================
+// Skeleton.Circle - Shorthand for avatar variant
+// ============================================
+
+function SkeletonCircle({
+  size = 'md',
+  className,
+}: {
+  size?: SkeletonSize | number;
+  className?: string;
+}) {
+  if (typeof size === 'number') {
+    return (
+      <SkeletonBase
+        variant="rect"
+        width={size}
+        height={size}
+        radius="full"
+        className={className}
+      />
+    );
+  }
+  return <SkeletonBase variant="avatar" size={size} className={className} />;
+}
+
+// ============================================
+// Compound Component
+// ============================================
+
+export const Skeleton = Object.assign(SkeletonBase, {
+  Text: SkeletonText,
+  Circle: SkeletonCircle,
+});

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

@@ -0,0 +1,193 @@
+import React from 'react';
+import { defineSegment } from '@fragments/core';
+import { Table, createColumns } from './index.js';
+import { Badge } from '../Badge/index.js';
+
+// Sample data types
+interface User {
+  id: string;
+  name: string;
+  email: string;
+  status: 'active' | 'inactive' | 'pending';
+  role: string;
+}
+
+const sampleUsers: User[] = [
+  { id: '1', name: 'Alice Johnson', email: 'alice@example.com', status: 'active', role: 'Admin' },
+  { id: '2', name: 'Bob Smith', email: 'bob@example.com', status: 'active', role: 'Editor' },
+  { id: '3', name: 'Carol Williams', email: 'carol@example.com', status: 'pending', role: 'Viewer' },
+  { id: '4', name: 'David Brown', email: 'david@example.com', status: 'inactive', role: 'Editor' },
+];
+
+const columns = createColumns<User>([
+  { key: 'name', header: 'Name' },
+  { key: 'email', header: 'Email' },
+  {
+    key: 'status',
+    header: 'Status',
+    cell: (row) => (
+      <Badge
+        variant={row.status === 'active' ? 'success' : row.status === 'pending' ? 'warning' : 'default'}
+        dot
+      >
+        {row.status}
+      </Badge>
+    ),
+  },
+  { key: 'role', header: 'Role' },
+]);
+
+export default defineSegment({
+  component: Table,
+
+  meta: {
+    name: 'Table',
+    description: 'Data table with sorting and row selection. Use for displaying structured data that needs to be scanned, compared, or acted upon.',
+    category: 'data-display',
+    status: 'stable',
+    tags: ['table', 'data', 'grid', 'list', 'sorting'],
+    since: '0.1.0',
+  },
+
+  usage: {
+    when: [
+      'Displaying structured, tabular data',
+      'Data that users need to scan and compare',
+      'Lists with multiple attributes per item',
+      'Data that needs sorting or selection',
+    ],
+    whenNot: [
+      'Simple lists (use List component)',
+      'Card-based layouts (use CardGrid)',
+      'Heavily interactive data (consider DataGrid)',
+      'Small screens (consider card or list view)',
+    ],
+    guidelines: [
+      'Keep columns to a reasonable number (5-7 max)',
+      'Use consistent alignment (numbers right, text left)',
+      'Provide meaningful empty states',
+      'Consider mobile responsiveness',
+    ],
+    accessibility: [
+      'Proper table semantics with headers',
+      'Sortable columns are keyboard accessible',
+      'Row selection is properly announced',
+    ],
+  },
+
+  props: {
+    columns: {
+      type: 'array',
+      description: 'Column definitions',
+      required: true,
+    },
+    data: {
+      type: 'array',
+      description: 'Data rows to display',
+      required: true,
+    },
+    sortable: {
+      type: 'boolean',
+      description: 'Enable column sorting',
+      default: 'false',
+    },
+    selectable: {
+      type: 'boolean',
+      description: 'Enable row selection',
+      default: 'false',
+    },
+    onRowClick: {
+      type: 'function',
+      description: 'Handler for row clicks',
+    },
+    emptyMessage: {
+      type: 'string',
+      description: 'Message when no data',
+      default: 'No data available',
+    },
+    size: {
+      type: 'enum',
+      description: 'Table density',
+      values: ['sm', 'md'],
+      default: 'md',
+    },
+  },
+
+  relations: [
+    { component: 'EmptyState', relationship: 'sibling', note: 'Use EmptyState for empty table states' },
+    { component: 'Badge', relationship: 'sibling', note: 'Use Badge for status columns' },
+  ],
+
+  contract: {
+    propsSummary: [
+      'columns: ColumnDef[] - column definitions',
+      'data: T[] - row data array',
+      'sortable: boolean - enable sorting',
+      'selectable: boolean - enable row selection',
+      'size: sm|md - table density',
+    ],
+    scenarioTags: [
+      'data.table',
+      'display.list',
+      'data.grid',
+    ],
+    a11yRules: ['A11Y_TABLE_HEADERS', 'A11Y_TABLE_SORT'],
+  },
+
+  variants: [
+    {
+      name: 'Default',
+      description: 'Basic data table',
+      render: () => (
+        <Table
+          columns={columns}
+          data={sampleUsers}
+        />
+      ),
+    },
+    {
+      name: 'Sortable',
+      description: 'Table with sortable columns',
+      render: () => (
+        <Table
+          columns={columns}
+          data={sampleUsers}
+          sortable
+        />
+      ),
+    },
+    {
+      name: 'Clickable Rows',
+      description: 'Table with clickable rows',
+      render: () => (
+        <Table
+          columns={columns}
+          data={sampleUsers}
+          onRowClick={(row) => alert(`Clicked: ${row.name}`)}
+        />
+      ),
+    },
+    {
+      name: 'Compact',
+      description: 'Smaller, denser table',
+      render: () => (
+        <Table
+          columns={columns}
+          data={sampleUsers}
+          size="sm"
+        />
+      ),
+    },
+    {
+      name: 'Empty State',
+      description: 'Table with no data',
+      render: () => (
+        <Table
+          columns={columns}
+          data={[]}
+          emptyMessage="No users found"
+        />
+      ),
+    },
+  ],
+});

package/src/components/Table/Table.module.scss

@@ -0,0 +1,152 @@
+@use '../../tokens/variables' as *;
+@use '../../tokens/mixins' as *;
+
+.wrapper {
+  overflow-x: auto;
+  -webkit-overflow-scrolling: touch;
+}
+
+.table {
+  width: 100%;
+  border-collapse: collapse;
+  font-family: var(--fui-font-sans, $fui-font-sans);
+  -webkit-font-smoothing: antialiased;
+  -moz-osx-font-smoothing: grayscale;
+}
+
+// Size variants
+.sm {
+  .th,
+  .td {
+    padding: var(--fui-space-2, $fui-space-2) var(--fui-space-3, $fui-space-3);
+    font-size: var(--fui-font-size-xs, $fui-font-size-xs);
+  }
+}
+
+.md {
+  .th,
+  .td {
+    padding: var(--fui-space-3, $fui-space-3) var(--fui-space-4, $fui-space-4);
+    font-size: var(--fui-font-size-sm, $fui-font-size-sm);
+  }
+}
+
+// Header
+.thead {
+  position: sticky;
+  top: 0;
+  z-index: 1;
+  background-color: var(--fui-bg-secondary, $fui-bg-secondary);
+}
+
+.headerRow {
+  border-bottom: 1px solid var(--fui-border, $fui-border);
+}
+
+.th {
+  text-align: left;
+  font-weight: var(--fui-font-weight-medium, $fui-font-weight-medium);
+  color: var(--fui-text-secondary, $fui-text-secondary);
+  white-space: nowrap;
+  vertical-align: middle;
+  user-select: none;
+
+  &:first-child {
+    border-top-left-radius: var(--fui-radius-md, $fui-radius-md);
+  }
+
+  &:last-child {
+    border-top-right-radius: var(--fui-radius-md, $fui-radius-md);
+  }
+}
+
+.headerContent {
+  display: flex;
+  align-items: center;
+  gap: var(--fui-space-1, $fui-space-1);
+}
+
+.sortable {
+  cursor: pointer;
+  transition: color var(--fui-transition-fast, $fui-transition-fast);
+
+  &:hover {
+    color: var(--fui-text-primary, $fui-text-primary);
+  }
+}
+
+.sortIndicator {
+  display: inline-flex;
+  align-items: center;
+  color: var(--fui-text-tertiary, $fui-text-tertiary);
+  flex-shrink: 0;
+
+  .sortable:hover & {
+    color: var(--fui-text-secondary, $fui-text-secondary);
+  }
+}
+
+// Body
+.tbody {
+  background-color: var(--fui-bg-primary, $fui-bg-primary);
+}
+
+.row {
+  border-bottom: 1px solid var(--fui-border, $fui-border);
+  transition: background-color var(--fui-transition-fast, $fui-transition-fast);
+
+  &:last-child {
+    border-bottom: none;
+  }
+}
+
+.clickable {
+  cursor: pointer;
+
+  &:hover {
+    background-color: var(--fui-bg-hover, $fui-bg-hover);
+  }
+
+  &:active {
+    background-color: var(--fui-bg-active, $fui-bg-active);
+  }
+}
+
+.selected {
+  background-color: var(--fui-color-accent, $fui-color-accent);
+  background-color: rgba($fui-color-accent, 0.08);
+
+  &:hover {
+    background-color: rgba($fui-color-accent, 0.12);
+  }
+}
+
+.td {
+  color: var(--fui-text-primary, $fui-text-primary);
+  vertical-align: middle;
+  line-height: var(--fui-line-height-normal, $fui-line-height-normal);
+}
+
+// Empty state
+.emptyState {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  padding: var(--fui-space-12, $fui-space-12) var(--fui-space-6, $fui-space-6);
+}
+
+.emptyMessage {
+  font-family: var(--fui-font-sans, $fui-font-sans);
+  font-size: var(--fui-font-size-sm, $fui-font-size-sm);
+  color: var(--fui-text-tertiary, $fui-text-tertiary);
+}
+
+// Responsive: allow horizontal scroll on small screens
+@media (max-width: 640px) {
+  .wrapper {
+    margin-left: calc(-1 * var(--fui-space-4, $fui-space-4));
+    margin-right: calc(-1 * var(--fui-space-4, $fui-space-4));
+    padding-left: var(--fui-space-4, $fui-space-4);
+    padding-right: var(--fui-space-4, $fui-space-4);
+  }
+}