@fragments-sdk/ui 0.2.3 → 0.4.0

package/src/components/Header/index.tsx

@@ -0,0 +1,363 @@
+'use client';
+
+import * as React from 'react';
+import styles from './Header.module.scss';
+import { useSidebar } from '../Sidebar';
+// Import globals to ensure CSS variables are defined
+import '../../styles/globals.scss';
+
+// ============================================
+// Types
+// ============================================
+
+export interface HeaderProps extends React.HTMLAttributes<HTMLElement> {
+  children: React.ReactNode;
+  /** Header height (default: '56px') */
+  height?: string;
+  /** Position behavior */
+  position?: 'static' | 'fixed' | 'sticky';
+}
+
+export interface HeaderBrandProps {
+  children: React.ReactNode;
+  /** Link destination */
+  href?: string;
+  /** Additional class name */
+  className?: string;
+}
+
+export interface HeaderNavProps {
+  children: React.ReactNode;
+  /** Accessible label for navigation */
+  'aria-label'?: string;
+  /** Additional class name */
+  className?: string;
+}
+
+export interface HeaderNavItemProps {
+  children: React.ReactNode;
+  /** Whether this item is active/current */
+  active?: boolean;
+  /** Link destination */
+  href?: string;
+  /** Render as child element (polymorphic) */
+  asChild?: boolean;
+  /** Click handler */
+  onClick?: () => void;
+  /** Additional class name */
+  className?: string;
+}
+
+export interface HeaderSearchProps {
+  children: React.ReactNode;
+  /** Whether search expands on mobile */
+  expandable?: boolean;
+  /** Additional class name */
+  className?: string;
+}
+
+export interface HeaderActionsProps {
+  children: React.ReactNode;
+  /** Additional class name */
+  className?: string;
+}
+
+export interface HeaderTriggerProps {
+  /** Custom trigger content */
+  children?: React.ReactNode;
+  /** Accessible label */
+  'aria-label'?: string;
+  /** Additional class name */
+  className?: string;
+}
+
+// ============================================
+// Icons
+// ============================================
+
+function MenuIcon() {
+  return (
+    <svg
+      xmlns="http://www.w3.org/2000/svg"
+      width="24"
+      height="24"
+      viewBox="0 0 256 256"
+      fill="currentColor"
+      aria-hidden="true"
+    >
+      <path d="M224,128a8,8,0,0,1-8,8H40a8,8,0,0,1,0-16H216A8,8,0,0,1,224,128ZM40,72H216a8,8,0,0,0,0-16H40a8,8,0,0,0,0,16ZM216,184H40a8,8,0,0,0,0,16H216a8,8,0,0,0,0-16Z" />
+    </svg>
+  );
+}
+
+function CloseIcon() {
+  return (
+    <svg
+      xmlns="http://www.w3.org/2000/svg"
+      width="24"
+      height="24"
+      viewBox="0 0 256 256"
+      fill="currentColor"
+      aria-hidden="true"
+    >
+      <path d="M205.66,194.34a8,8,0,0,1-11.32,11.32L128,139.31,61.66,205.66a8,8,0,0,1-11.32-11.32L116.69,128,50.34,61.66A8,8,0,0,1,61.66,50.34L128,116.69l66.34-66.35a8,8,0,0,1,11.32,11.32L139.31,128Z" />
+    </svg>
+  );
+}
+
+// ============================================
+// Hooks
+// ============================================
+
+function useIsMobile() {
+  const [isMobile, setIsMobile] = React.useState(false);
+
+  React.useEffect(() => {
+    if (typeof window === 'undefined') return;
+
+    const mq = window.matchMedia('(max-width: 767px)');
+    setIsMobile(mq.matches);
+
+    const handler = (e: MediaQueryListEvent) => setIsMobile(e.matches);
+    mq.addEventListener('change', handler);
+    return () => mq.removeEventListener('change', handler);
+  }, []);
+
+  return isMobile;
+}
+
+// ============================================
+// Components
+// ============================================
+
+/**
+ * Header - Root header element
+ */
+function HeaderRoot({
+  children,
+  height = '56px',
+  position = 'static',
+  className,
+  style: styleProp,
+  ...htmlProps
+}: HeaderProps) {
+  const classes = [
+    styles.header,
+    position === 'fixed' && styles.fixed,
+    position === 'sticky' && styles.sticky,
+    className,
+  ].filter(Boolean).join(' ');
+
+  const style: React.CSSProperties = {
+    '--header-height': height,
+    ...styleProp,
+  } as React.CSSProperties;
+
+  return (
+    <header {...htmlProps} className={classes} style={style} data-position={position}>
+      <div className={styles.container}>
+        {children}
+      </div>
+    </header>
+  );
+}
+
+/**
+ * Header.Brand - Logo/brand slot
+ */
+function HeaderBrand({ children, href, className }: HeaderBrandProps) {
+  const classes = [styles.brand, className].filter(Boolean).join(' ');
+
+  if (href) {
+    return (
+      <a href={href} className={classes}>
+        {children}
+      </a>
+    );
+  }
+
+  return <div className={classes}>{children}</div>;
+}
+
+/**
+ * Header.Nav - Navigation container (hidden on mobile)
+ */
+function HeaderNav({
+  children,
+  'aria-label': ariaLabel = 'Main navigation',
+  className,
+}: HeaderNavProps) {
+  const classes = [styles.nav, className].filter(Boolean).join(' ');
+
+  return (
+    <nav className={classes} aria-label={ariaLabel}>
+      <ul className={styles.navList}>
+        {children}
+      </ul>
+    </nav>
+  );
+}
+
+/**
+ * Header.NavItem - Navigation link
+ */
+function HeaderNavItem({
+  children,
+  active = false,
+  href,
+  asChild = false,
+  onClick,
+  className,
+}: HeaderNavItemProps) {
+  const classes = [
+    styles.navItem,
+    active && styles.navItemActive,
+    className,
+  ].filter(Boolean).join(' ');
+
+  const itemProps = {
+    className: classes,
+    onClick,
+    'aria-current': active ? 'page' as const : undefined,
+  };
+
+  if (asChild && React.isValidElement(children)) {
+    return (
+      <li>
+        {React.cloneElement(children, {
+          ...itemProps,
+          className: [classes, (children.props as { className?: string }).className].filter(Boolean).join(' '),
+        } as React.HTMLAttributes<HTMLElement>)}
+      </li>
+    );
+  }
+
+  if (href) {
+    return (
+      <li>
+        <a {...itemProps} href={href}>
+          {children}
+        </a>
+      </li>
+    );
+  }
+
+  return (
+    <li>
+      <button {...itemProps} type="button">
+        {children}
+      </button>
+    </li>
+  );
+}
+
+/**
+ * Header.Search - Search input slot (hidden on mobile unless expandable)
+ */
+function HeaderSearch({
+  children,
+  expandable = false,
+  className,
+}: HeaderSearchProps) {
+  const classes = [
+    styles.search,
+    expandable && styles.searchExpandable,
+    className,
+  ].filter(Boolean).join(' ');
+
+  return <div className={classes}>{children}</div>;
+}
+
+/**
+ * Header.Actions - Right-side actions container
+ */
+function HeaderActions({ children, className }: HeaderActionsProps) {
+  const classes = [styles.actions, className].filter(Boolean).join(' ');
+  return <div className={classes}>{children}</div>;
+}
+
+/**
+ * Header.Trigger - Mobile menu trigger (integrates with SidebarProvider)
+ */
+function HeaderTrigger({
+  children,
+  'aria-label': ariaLabel = 'Toggle navigation',
+  className,
+}: HeaderTriggerProps) {
+  const isMobile = useIsMobile();
+  const { open, setOpen } = useSidebar();
+
+  // Only render on mobile
+  if (!isMobile) {
+    return null;
+  }
+
+  const classes = [styles.trigger, className].filter(Boolean).join(' ');
+
+  return (
+    <button
+      type="button"
+      className={classes}
+      onClick={() => setOpen(!open)}
+      aria-label={ariaLabel}
+      aria-expanded={open}
+    >
+      {children || (open ? <CloseIcon /> : <MenuIcon />)}
+    </button>
+  );
+}
+
+/**
+ * Header.Spacer - Flexible spacer to push items apart
+ */
+function HeaderSpacer({ className }: { className?: string }) {
+  const classes = [styles.spacer, className].filter(Boolean).join(' ');
+  return <div className={classes} />;
+}
+
+/**
+ * Header.SkipLink - Skip to main content link (accessibility)
+ */
+function HeaderSkipLink({
+  children = 'Skip to main content',
+  href = '#main-content',
+  className,
+}: {
+  children?: React.ReactNode;
+  href?: string;
+  className?: string;
+}) {
+  const classes = [styles.skipLink, className].filter(Boolean).join(' ');
+  return (
+    <a href={href} className={classes}>
+      {children}
+    </a>
+  );
+}
+
+// ============================================
+// Export compound component
+// ============================================
+
+export const Header = Object.assign(HeaderRoot, {
+  Brand: HeaderBrand,
+  Nav: HeaderNav,
+  NavItem: HeaderNavItem,
+  Search: HeaderSearch,
+  Actions: HeaderActions,
+  Trigger: HeaderTrigger,
+  Spacer: HeaderSpacer,
+  SkipLink: HeaderSkipLink,
+});
+
+export {
+  HeaderRoot,
+  HeaderBrand,
+  HeaderNav,
+  HeaderNavItem,
+  HeaderSearch,
+  HeaderActions,
+  HeaderTrigger,
+  HeaderSpacer,
+  HeaderSkipLink,
+};

package/src/components/Icon/Icon.fragment.tsx

@@ -0,0 +1,138 @@
+import React from 'react';
+import { defineSegment } from '@fragments/core';
+import { Icon } from './index.js';
+import { Heart, Star, Check, Warning, Info } from '@phosphor-icons/react';
+
+export default defineSegment({
+  component: Icon,
+
+  meta: {
+    name: 'Icon',
+    description: 'Wrapper for Phosphor icons with consistent sizing and semantic colors. Provides standardized icon rendering across the design system.',
+    category: 'data-display',
+    status: 'stable',
+    tags: ['icon', 'phosphor', 'visual', 'symbol', 'graphic'],
+    since: '0.1.0',
+  },
+
+  usage: {
+    when: [
+      'Displaying UI icons alongside text or in buttons',
+      'Indicating status or state visually',
+      'Adding visual hierarchy to feature lists',
+      'Decorating cards or stats with relevant symbols',
+    ],
+    whenNot: [
+      'Large decorative illustrations (use Image or custom SVG)',
+      'Logo display (use dedicated Logo component)',
+      'Complex graphics with multiple colors',
+      'Animated icons (use custom implementation)',
+    ],
+    guidelines: [
+      'Use semantic color variants (success, error, warning) for status indication',
+      'Pair icons with text labels for accessibility',
+      'Match icon weight to surrounding text weight for visual consistency',
+      'Use consistent sizes within the same context',
+    ],
+    accessibility: [
+      'Icons are decorative by default (aria-hidden)',
+      'Always pair with visible or visually-hidden text for meaning',
+      'Do not rely on color alone to convey information',
+      'Consider using VisuallyHidden for icon-only buttons',
+    ],
+  },
+
+  props: {
+    icon: {
+      type: 'component',
+      description: 'Phosphor icon component to render',
+      required: true,
+    },
+    size: {
+      type: 'enum',
+      description: 'Icon size',
+      values: ['xs', 'sm', 'md', 'lg', 'xl'],
+      default: 'md',
+    },
+    weight: {
+      type: 'enum',
+      description: 'Icon stroke weight/style',
+      values: ['thin', 'light', 'regular', 'bold', 'fill', 'duotone'],
+      default: 'regular',
+    },
+    variant: {
+      type: 'enum',
+      description: 'Semantic color variant',
+      values: ['default', 'primary', 'secondary', 'tertiary', 'accent', 'success', 'warning', 'error'],
+      default: 'default',
+    },
+  },
+
+  relations: [
+    { component: 'Button', relationship: 'child', note: 'Use inside icon-only buttons with VisuallyHidden label' },
+    { component: 'VisuallyHidden', relationship: 'sibling', note: 'Pair with VisuallyHidden for accessible icon-only elements' },
+    { component: 'Badge', relationship: 'child', note: 'Can be used as badge icon prop' },
+  ],
+
+  contract: {
+    propsSummary: [
+      'icon: PhosphorIcon - icon component (required)',
+      'size: xs|sm|md|lg|xl - icon size',
+      'weight: thin|light|regular|bold|fill|duotone - stroke style',
+      'variant: default|primary|secondary|tertiary|accent|success|warning|error - color',
+    ],
+    scenarioTags: [
+      'display.icon',
+      'feedback.status',
+      'decoration.visual',
+    ],
+    a11yRules: ['A11Y_ICON_LABEL', 'A11Y_COLOR_CONTRAST'],
+  },
+
+  variants: [
+    {
+      name: 'Default',
+      description: 'Basic icon with default styling',
+      render: () => <Icon icon={Heart} />,
+    },
+    {
+      name: 'Sizes',
+      description: 'Available size options',
+      render: () => (
+        <div style={{ display: 'flex', gap: '12px', alignItems: 'center' }}>
+          <Icon icon={Star} size="xs" />
+          <Icon icon={Star} size="sm" />
+          <Icon icon={Star} size="md" />
+          <Icon icon={Star} size="lg" />
+          <Icon icon={Star} size="xl" />
+        </div>
+      ),
+    },
+    {
+      name: 'Semantic Colors',
+      description: 'Status and semantic color variants',
+      render: () => (
+        <div style={{ display: 'flex', gap: '12px', alignItems: 'center' }}>
+          <Icon icon={Check} variant="success" />
+          <Icon icon={Warning} variant="warning" />
+          <Icon icon={Warning} variant="error" />
+          <Icon icon={Info} variant="accent" />
+        </div>
+      ),
+    },
+    {
+      name: 'Weights',
+      description: 'Icon weight/style options',
+      render: () => (
+        <div style={{ display: 'flex', gap: '12px', alignItems: 'center' }}>
+          <Icon icon={Heart} weight="thin" />
+          <Icon icon={Heart} weight="light" />
+          <Icon icon={Heart} weight="regular" />
+          <Icon icon={Heart} weight="bold" />
+          <Icon icon={Heart} weight="fill" />
+          <Icon icon={Heart} weight="duotone" />
+        </div>
+      ),
+    },
+  ],
+});

package/src/components/Icon/Icon.module.scss

@@ -0,0 +1,38 @@
+@use '../../tokens/variables' as *;
+
+.icon {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  color: currentColor;
+  line-height: 1;
+}
+
+// Color variants (matching Badge/Alert pattern)
+.primary {
+  color: var(--fui-text-primary, $fui-text-primary);
+}
+
+.secondary {
+  color: var(--fui-text-secondary, $fui-text-secondary);
+}
+
+.tertiary {
+  color: var(--fui-text-tertiary, $fui-text-tertiary);
+}
+
+.accent {
+  color: var(--fui-color-accent, $fui-color-accent);
+}
+
+.success {
+  color: var(--fui-color-success, $fui-color-success);
+}
+
+.warning {
+  color: var(--fui-color-warning, $fui-color-warning);
+}
+
+.error {
+  color: var(--fui-color-danger, $fui-color-danger);
+}

package/src/components/Icon/index.tsx

@@ -0,0 +1,58 @@
+import * as React from 'react';
+import type { IconProps as PhosphorIconProps } from '@phosphor-icons/react';
+import styles from './Icon.module.scss';
+import '../../styles/globals.scss';
+
+export interface IconProps extends Omit<React.HTMLAttributes<HTMLSpanElement>, 'color'> {
+  /** The Phosphor icon component to render */
+  icon: React.ComponentType<PhosphorIconProps>;
+  /** Size of the icon */
+  size?: 'xs' | 'sm' | 'md' | 'lg' | 'xl';
+  /** Weight/style of the icon */
+  weight?: 'thin' | 'light' | 'regular' | 'bold' | 'fill' | 'duotone';
+  /** Semantic color variant */
+  variant?: 'default' | 'primary' | 'secondary' | 'tertiary' | 'accent' | 'success' | 'warning' | 'error';
+  /** @deprecated Use variant instead */
+  color?: 'primary' | 'secondary' | 'tertiary' | 'accent' | 'success' | 'warning' | 'error';
+}
+
+const sizeMap: Record<NonNullable<IconProps['size']>, number> = {
+  xs: 12,
+  sm: 16,
+  md: 20,
+  lg: 24,
+  xl: 32,
+};
+
+export const Icon = React.forwardRef<HTMLSpanElement, IconProps>(
+  function Icon(
+    {
+      icon: IconComponent,
+      size = 'md',
+      weight = 'regular',
+      variant,
+      color,
+      className,
+      style,
+      ...htmlProps
+    },
+    ref
+  ) {
+    // Support deprecated color prop (variant takes precedence)
+    const colorVariant = variant || color;
+
+    const classes = [
+      styles.icon,
+      colorVariant && colorVariant !== 'default' && styles[colorVariant],
+      className,
+    ]
+      .filter(Boolean)
+      .join(' ');
+
+    return (
+      <span ref={ref} {...htmlProps} className={classes} style={style}>
+        <IconComponent size={sizeMap[size]} weight={weight} />
+      </span>
+    );
+  }
+);