@fragments-sdk/ui 0.2.3 → 0.4.0

package/src/components/Box/Box.fragment.tsx

@@ -0,0 +1,168 @@
+import React from 'react';
+import { defineSegment } from '@fragments/core';
+import { Box } from './index.js';
+
+export default defineSegment({
+  component: Box,
+
+  meta: {
+    name: 'Box',
+    description: 'Primitive layout component for applying spacing, backgrounds, and borders. A flexible container for building custom layouts.',
+    category: 'layout',
+    status: 'stable',
+    tags: ['layout', 'container', 'spacing', 'primitive', 'box'],
+    since: '0.1.0',
+  },
+
+  usage: {
+    when: [
+      'Applying consistent padding or margin to content sections',
+      'Creating bordered or elevated containers',
+      'Wrapping content with semantic HTML elements',
+      'Building custom layouts not covered by Stack or Grid',
+    ],
+    whenNot: [
+      'Horizontal or vertical stacking (use Stack)',
+      'Grid-based layouts (use Grid)',
+      'Card-like containers with header/body/footer (use Card)',
+      'Simple text styling (use Text)',
+    ],
+    guidelines: [
+      'Use padding props instead of inline styles for consistency',
+      'Choose semantic HTML elements (section, article) where appropriate',
+      'Combine with Stack or Grid for complex layouts',
+      'Use background variants from the design system, not custom colors',
+    ],
+    accessibility: [
+      'Choose semantic as prop values for proper document structure',
+      'Avoid div-soup; use meaningful elements like section, article',
+      'Ensure proper heading hierarchy within Box containers',
+    ],
+  },
+
+  props: {
+    children: {
+      type: 'node',
+      description: 'Content to render inside the box',
+    },
+    as: {
+      type: 'enum',
+      description: 'HTML element to render',
+      values: ['div', 'section', 'article', 'aside', 'main', 'header', 'footer', 'nav', 'span'],
+      default: 'div',
+    },
+    padding: {
+      type: 'enum',
+      description: 'Padding on all sides',
+      values: ['none', 'xs', 'sm', 'md', 'lg', 'xl'],
+    },
+    paddingX: {
+      type: 'enum',
+      description: 'Horizontal padding',
+      values: ['none', 'xs', 'sm', 'md', 'lg', 'xl'],
+    },
+    paddingY: {
+      type: 'enum',
+      description: 'Vertical padding',
+      values: ['none', 'xs', 'sm', 'md', 'lg', 'xl'],
+    },
+    margin: {
+      type: 'enum',
+      description: 'Margin on all sides',
+      values: ['none', 'xs', 'sm', 'md', 'lg', 'xl', 'auto'],
+    },
+    marginX: {
+      type: 'enum',
+      description: 'Horizontal margin',
+      values: ['none', 'xs', 'sm', 'md', 'lg', 'xl', 'auto'],
+    },
+    marginY: {
+      type: 'enum',
+      description: 'Vertical margin',
+      values: ['none', 'xs', 'sm', 'md', 'lg', 'xl', 'auto'],
+    },
+    background: {
+      type: 'enum',
+      description: 'Background color',
+      values: ['none', 'primary', 'secondary', 'tertiary', 'elevated'],
+    },
+    rounded: {
+      type: 'enum',
+      description: 'Border radius',
+      values: ['none', 'sm', 'md', 'lg', 'full'],
+    },
+    border: {
+      type: 'boolean',
+      description: 'Show border',
+      default: 'false',
+    },
+    display: {
+      type: 'enum',
+      description: 'Display type',
+      values: ['block', 'inline', 'inline-block', 'flex', 'inline-flex', 'grid', 'none'],
+    },
+  },
+
+  relations: [
+    { component: 'Stack', relationship: 'alternative', note: 'Use Stack for directional layouts with gap' },
+    { component: 'Grid', relationship: 'alternative', note: 'Use Grid for column-based layouts' },
+    { component: 'Card', relationship: 'alternative', note: 'Use Card for content containers with structure' },
+  ],
+
+  contract: {
+    propsSummary: [
+      'as: div|section|article|... - HTML element',
+      'padding: none|xs|sm|md|lg|xl - all-sides padding',
+      'paddingX/paddingY: directional padding overrides',
+      'margin: none|xs|sm|md|lg|xl|auto - margin',
+      'background: none|primary|secondary|tertiary|elevated',
+      'rounded: none|sm|md|lg|full - border radius',
+      'border: boolean - show border',
+    ],
+    scenarioTags: [
+      'layout.container',
+      'spacing.wrapper',
+      'structure.section',
+    ],
+    a11yRules: ['A11Y_SEMANTIC_HTML'],
+  },
+
+  variants: [
+    {
+      name: 'Default',
+      description: 'Basic box with padding',
+      render: () => (
+        <Box padding="md" background="secondary" rounded="md">
+          Content with padding and background
+        </Box>
+      ),
+    },
+    {
+      name: 'With Border',
+      description: 'Bordered container',
+      render: () => (
+        <Box padding="lg" border rounded="md">
+          Bordered content area
+        </Box>
+      ),
+    },
+    {
+      name: 'Directional Padding',
+      description: 'Different horizontal and vertical padding',
+      render: () => (
+        <Box paddingX="xl" paddingY="sm" background="tertiary" rounded="sm">
+          Wide horizontal padding, short vertical
+        </Box>
+      ),
+    },
+    {
+      name: 'Centered with Auto Margin',
+      description: 'Centered content using margin auto',
+      render: () => (
+        <Box padding="md" marginX="auto" background="elevated" rounded="lg" style={{ maxWidth: '300px' }}>
+          Centered content
+        </Box>
+      ),
+    },
+  ],
+});

package/src/components/Box/Box.module.scss

@@ -0,0 +1,84 @@
+@use '../../tokens/variables' as *;
+
+.box {
+  box-sizing: border-box;
+}
+
+// Padding
+.p-none { padding: 0; }
+.p-xs { padding: var(--fui-space-1, $fui-space-1); }
+.p-sm { padding: var(--fui-space-2, $fui-space-2); }
+.p-md { padding: var(--fui-space-4, $fui-space-4); }
+.p-lg { padding: var(--fui-space-6, $fui-space-6); }
+.p-xl { padding: var(--fui-space-8, $fui-space-8); }
+
+// Padding X
+.px-none { padding-left: 0; padding-right: 0; }
+.px-xs { padding-left: var(--fui-space-1, $fui-space-1); padding-right: var(--fui-space-1, $fui-space-1); }
+.px-sm { padding-left: var(--fui-space-2, $fui-space-2); padding-right: var(--fui-space-2, $fui-space-2); }
+.px-md { padding-left: var(--fui-space-4, $fui-space-4); padding-right: var(--fui-space-4, $fui-space-4); }
+.px-lg { padding-left: var(--fui-space-6, $fui-space-6); padding-right: var(--fui-space-6, $fui-space-6); }
+.px-xl { padding-left: var(--fui-space-8, $fui-space-8); padding-right: var(--fui-space-8, $fui-space-8); }
+
+// Padding Y
+.py-none { padding-top: 0; padding-bottom: 0; }
+.py-xs { padding-top: var(--fui-space-1, $fui-space-1); padding-bottom: var(--fui-space-1, $fui-space-1); }
+.py-sm { padding-top: var(--fui-space-2, $fui-space-2); padding-bottom: var(--fui-space-2, $fui-space-2); }
+.py-md { padding-top: var(--fui-space-4, $fui-space-4); padding-bottom: var(--fui-space-4, $fui-space-4); }
+.py-lg { padding-top: var(--fui-space-6, $fui-space-6); padding-bottom: var(--fui-space-6, $fui-space-6); }
+.py-xl { padding-top: var(--fui-space-8, $fui-space-8); padding-bottom: var(--fui-space-8, $fui-space-8); }
+
+// Margin
+.m-none { margin: 0; }
+.m-xs { margin: var(--fui-space-1, $fui-space-1); }
+.m-sm { margin: var(--fui-space-2, $fui-space-2); }
+.m-md { margin: var(--fui-space-4, $fui-space-4); }
+.m-lg { margin: var(--fui-space-6, $fui-space-6); }
+.m-xl { margin: var(--fui-space-8, $fui-space-8); }
+.m-auto { margin: auto; }
+
+// Margin X
+.mx-none { margin-left: 0; margin-right: 0; }
+.mx-xs { margin-left: var(--fui-space-1, $fui-space-1); margin-right: var(--fui-space-1, $fui-space-1); }
+.mx-sm { margin-left: var(--fui-space-2, $fui-space-2); margin-right: var(--fui-space-2, $fui-space-2); }
+.mx-md { margin-left: var(--fui-space-4, $fui-space-4); margin-right: var(--fui-space-4, $fui-space-4); }
+.mx-lg { margin-left: var(--fui-space-6, $fui-space-6); margin-right: var(--fui-space-6, $fui-space-6); }
+.mx-xl { margin-left: var(--fui-space-8, $fui-space-8); margin-right: var(--fui-space-8, $fui-space-8); }
+.mx-auto { margin-left: auto; margin-right: auto; }
+
+// Margin Y
+.my-none { margin-top: 0; margin-bottom: 0; }
+.my-xs { margin-top: var(--fui-space-1, $fui-space-1); margin-bottom: var(--fui-space-1, $fui-space-1); }
+.my-sm { margin-top: var(--fui-space-2, $fui-space-2); margin-bottom: var(--fui-space-2, $fui-space-2); }
+.my-md { margin-top: var(--fui-space-4, $fui-space-4); margin-bottom: var(--fui-space-4, $fui-space-4); }
+.my-lg { margin-top: var(--fui-space-6, $fui-space-6); margin-bottom: var(--fui-space-6, $fui-space-6); }
+.my-xl { margin-top: var(--fui-space-8, $fui-space-8); margin-bottom: var(--fui-space-8, $fui-space-8); }
+.my-auto { margin-top: auto; margin-bottom: auto; }
+
+// Background
+.bg-none { background-color: transparent; }
+.bg-primary { background-color: var(--fui-bg-primary, $fui-bg-primary); }
+.bg-secondary { background-color: var(--fui-bg-secondary, $fui-bg-secondary); }
+.bg-tertiary { background-color: var(--fui-bg-tertiary, $fui-bg-tertiary); }
+.bg-elevated { background-color: var(--fui-bg-elevated, $fui-bg-elevated); }
+
+// Border radius
+.rounded-none { border-radius: 0; }
+.rounded-sm { border-radius: var(--fui-radius-sm, $fui-radius-sm); }
+.rounded-md { border-radius: var(--fui-radius-md, $fui-radius-md); }
+.rounded-lg { border-radius: var(--fui-radius-lg, $fui-radius-lg); }
+.rounded-full { border-radius: var(--fui-radius-full, $fui-radius-full); }
+
+// Border
+.border {
+  border: 1px solid var(--fui-border, $fui-border);
+}
+
+// Display
+.display-block { display: block; }
+.display-inline { display: inline; }
+.display-inline-block { display: inline-block; }
+.display-flex { display: flex; }
+.display-inline-flex { display: inline-flex; }
+.display-grid { display: grid; }
+.display-none { display: none; }

package/src/components/Box/index.tsx

@@ -0,0 +1,78 @@
+import * as React from 'react';
+import styles from './Box.module.scss';
+import '../../styles/globals.scss';
+
+export interface BoxProps {
+  children?: React.ReactNode;
+  /** HTML element to render */
+  as?: 'div' | 'section' | 'article' | 'aside' | 'main' | 'header' | 'footer' | 'nav' | 'span';
+  /** Padding on all sides */
+  padding?: 'none' | 'xs' | 'sm' | 'md' | 'lg' | 'xl';
+  /** Horizontal padding (overrides padding) */
+  paddingX?: 'none' | 'xs' | 'sm' | 'md' | 'lg' | 'xl';
+  /** Vertical padding (overrides padding) */
+  paddingY?: 'none' | 'xs' | 'sm' | 'md' | 'lg' | 'xl';
+  /** Margin on all sides */
+  margin?: 'none' | 'xs' | 'sm' | 'md' | 'lg' | 'xl' | 'auto';
+  /** Horizontal margin (overrides margin) */
+  marginX?: 'none' | 'xs' | 'sm' | 'md' | 'lg' | 'xl' | 'auto';
+  /** Vertical margin (overrides margin) */
+  marginY?: 'none' | 'xs' | 'sm' | 'md' | 'lg' | 'xl' | 'auto';
+  /** Background color */
+  background?: 'none' | 'primary' | 'secondary' | 'tertiary' | 'elevated';
+  /** Border radius */
+  rounded?: 'none' | 'sm' | 'md' | 'lg' | 'full';
+  /** Border */
+  border?: boolean;
+  /** Display type */
+  display?: 'block' | 'inline' | 'inline-block' | 'flex' | 'inline-flex' | 'grid' | 'none';
+  /** Additional class name */
+  className?: string;
+  /** Inline styles */
+  style?: React.CSSProperties;
+}
+
+export const Box = React.forwardRef<HTMLElement, BoxProps>(
+  function Box(
+    {
+      children,
+      as: Component = 'div',
+      padding,
+      paddingX,
+      paddingY,
+      margin,
+      marginX,
+      marginY,
+      background,
+      rounded,
+      border,
+      display,
+      className,
+      style,
+    },
+    ref
+  ) {
+    const classes = [
+      styles.box,
+      padding && styles[`p-${padding}`],
+      paddingX && styles[`px-${paddingX}`],
+      paddingY && styles[`py-${paddingY}`],
+      margin && styles[`m-${margin}`],
+      marginX && styles[`mx-${marginX}`],
+      marginY && styles[`my-${marginY}`],
+      background && styles[`bg-${background}`],
+      rounded && styles[`rounded-${rounded}`],
+      border && styles.border,
+      display && styles[`display-${display}`],
+      className,
+    ]
+      .filter(Boolean)
+      .join(' ');
+
+    return (
+      <Component ref={ref as React.Ref<never>} className={classes} style={style}>
+        {children}
+      </Component>
+    );
+  }
+);

package/src/components/Button/Button.module.scss

@@ -95,3 +95,45 @@
     background-color: var(--fui-color-danger-hover, $fui-color-danger-hover);
   }
 }
+
+// Icon-only button (square aspect ratio)
+.icon {
+  aspect-ratio: 1;
+  padding: 0;
+
+  &.sm {
+    width: var(--fui-button-height-sm, $fui-button-height-sm);
+  }
+
+  &.md {
+    width: var(--fui-button-height-md, $fui-button-height-md);
+  }
+
+  &.lg {
+    width: var(--fui-button-height-lg, $fui-button-height-lg);
+  }
+}
+
+// Full width
+.fullWidth {
+  width: 100%;
+}
+
+// ============================================
+// Accessibility: High Contrast Mode
+// ============================================
+
+@media (prefers-contrast: more) {
+  .secondary {
+    border-width: 2px;
+    border-color: var(--fui-text-primary, $fui-text-primary);
+  }
+
+  .ghost {
+    border-width: 2px;
+
+    &:hover:not(:disabled) {
+      border-color: var(--fui-text-primary, $fui-text-primary);
+    }
+  }
+}

package/src/components/Button/index.tsx

@@ -4,48 +4,82 @@ import styles from './Button.module.scss';
 // Import globals to ensure CSS variables are defined
 import '../../styles/globals.scss';
 
-export interface ButtonProps {
+type ButtonBaseProps = {
   children: React.ReactNode;
   variant?: 'primary' | 'secondary' | 'ghost' | 'danger';
   size?: 'sm' | 'md' | 'lg';
-  disabled?: boolean;
-  onClick?: (e: React.MouseEvent<HTMLButtonElement>) => void;
-  type?: 'button' | 'submit' | 'reset';
-  className?: string;
+  /** Render as icon-only button (square aspect ratio) */
+  icon?: boolean;
+  /** Make button full width of container */
+  fullWidth?: boolean;
+};
+
+// Button as native button element
+export interface ButtonAsButtonProps
+  extends ButtonBaseProps,
+    Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, 'children'> {
+  as?: 'button';
+}
+
+// Button as anchor element
+export interface ButtonAsAnchorProps
+  extends ButtonBaseProps,
+    Omit<React.AnchorHTMLAttributes<HTMLAnchorElement>, 'children'> {
+  as: 'a';
 }
 
-export const Button = React.forwardRef<HTMLButtonElement, ButtonProps>(
-  function Button(
-    {
-      children,
-      variant = 'primary',
-      size = 'md',
-      disabled = false,
-      onClick,
-      type = 'button',
-      className,
-    },
-    ref
-  ) {
-    const classNames = [
-      styles.button,
-      styles[size],
-      styles[variant],
-      className,
-    ]
-      .filter(Boolean)
-      .join(' ');
+export type ButtonProps = ButtonAsButtonProps | ButtonAsAnchorProps;
 
+export const Button = React.forwardRef<
+  HTMLButtonElement | HTMLAnchorElement,
+  ButtonProps
+>(function Button(props, ref) {
+  const {
+    children,
+    variant = 'primary',
+    size = 'md',
+    icon = false,
+    fullWidth = false,
+    className,
+    ...rest
+  } = props;
+
+  const classNames = [
+    styles.button,
+    styles[size],
+    styles[variant],
+    icon && styles.icon,
+    fullWidth && styles.fullWidth,
+    className,
+  ]
+    .filter(Boolean)
+    .join(' ');
+
+  // Render as anchor
+  if (props.as === 'a') {
+    const { as: _as, ...anchorProps } = rest as ButtonAsAnchorProps & { as?: 'a' };
     return (
-      <BaseButton
-        ref={ref}
-        type={type}
-        disabled={disabled}
-        onClick={onClick}
+      <a
+        ref={ref as React.Ref<HTMLAnchorElement>}
         className={classNames}
+        {...anchorProps}
       >
         {children}
-      </BaseButton>
+      </a>
     );
   }
-);
+
+  // Render as button (default)
+  const { as: _as, ...buttonProps } = rest as ButtonAsButtonProps;
+  return (
+    <BaseButton
+      ref={ref as React.Ref<HTMLButtonElement>}
+      type={(buttonProps as ButtonAsButtonProps).type || 'button'}
+      disabled={(buttonProps as ButtonAsButtonProps).disabled || false}
+      className={classNames}
+      {...buttonProps}
+    >
+      {children}
+    </BaseButton>
+  );
+});

package/src/components/ButtonGroup/ButtonGroup.module.scss

@@ -0,0 +1,37 @@
+@use '../../tokens/variables' as *;
+
+.group {
+  display: flex;
+  flex-direction: row;
+}
+
+// Gap sizes
+.gap-xs {
+  gap: var(--fui-space-1, $fui-space-1);
+}
+
+.gap-sm {
+  gap: var(--fui-space-2, $fui-space-2);
+}
+
+.gap-md {
+  gap: var(--fui-space-3, $fui-space-3);
+}
+
+// Wrap
+.wrap {
+  flex-wrap: wrap;
+}
+
+// Alignment
+.align-start {
+  justify-content: flex-start;
+}
+
+.align-center {
+  justify-content: center;
+}
+
+.align-end {
+  justify-content: flex-end;
+}

package/src/components/ButtonGroup/index.tsx

@@ -0,0 +1,40 @@
+import * as React from 'react';
+import styles from './ButtonGroup.module.scss';
+import '../../styles/globals.scss';
+
+export interface ButtonGroupProps {
+  children: React.ReactNode;
+  gap?: 'none' | 'xs' | 'sm' | 'md';
+  wrap?: boolean;
+  align?: 'start' | 'center' | 'end';
+  className?: string;
+}
+
+export const ButtonGroup = React.forwardRef<HTMLDivElement, ButtonGroupProps>(
+  function ButtonGroup(
+    {
+      children,
+      gap = 'sm',
+      wrap = false,
+      align,
+      className,
+    },
+    ref
+  ) {
+    const classes = [
+      styles.group,
+      gap !== 'none' && styles[`gap-${gap}`],
+      wrap && styles.wrap,
+      align && styles[`align-${align}`],
+      className,
+    ]
+      .filter(Boolean)
+      .join(' ');
+
+    return (
+      <div ref={ref} className={classes}>
+        {children}
+      </div>
+    );
+  }
+);