@fragments-sdk/ui 0.3.0 → 0.5.0

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>
+    );
+  }
+);

package/src/components/Card/Card.fragment.tsx

@@ -1,6 +1,6 @@
 import React from 'react';
 import { defineSegment } from '@fragments/core';
-import { Card } from './index.js';
+import { Card } from '.';
 
 export default defineSegment({
   component: Card,
@@ -40,15 +40,7 @@ export default defineSegment({
   props: {
     children: {
       type: 'node',
-      description: 'Card content',
-    },
-    title: {
-      type: 'string',
-      description: 'Card header title',
-    },
-    description: {
-      type: 'string',
-      description: 'Card header description/subtitle',
+      description: 'Card content - use Card.Header, Card.Body, Card.Footer sub-components',
     },
     variant: {
       type: 'enum',
@@ -86,9 +78,8 @@ export default defineSegment({
     propsSummary: [
       'variant: default|outlined|elevated (default: default)',
       'padding: none|sm|md|lg (default: md)',
-      'title: string - header title',
-      'description: string - header subtitle',
       'onClick: () => void - makes card interactive',
+      'Sub-components: Card.Header, Card.Title, Card.Description, Card.Body, Card.Footer',
     ],
     scenarioTags: [
       'layout.container',
@@ -102,13 +93,28 @@ export default defineSegment({
     ],
   },
 
+  ai: {
+    compositionPattern: 'compound',
+    subComponents: ['Header', 'Title', 'Description', 'Body', 'Footer'],
+    requiredChildren: ['Body'],
+    commonPatterns: [
+      '<Card><Card.Body>{content}</Card.Body></Card>',
+      '<Card><Card.Header><Card.Title>{title}</Card.Title></Card.Header><Card.Body>{content}</Card.Body></Card>',
+      '<Card><Card.Header><Card.Title>{title}</Card.Title><Card.Description>{desc}</Card.Description></Card.Header><Card.Body>{content}</Card.Body><Card.Footer>{actions}</Card.Footer></Card>',
+    ],
+  },
+
   variants: [
     {
       name: 'Default',
       description: 'Standard card with subtle shadow',
       render: () => (
-        <Card title="Card Title" description="A brief description">
-          Card content goes here.
+        <Card>
+          <Card.Header>
+            <Card.Title>Card Title</Card.Title>
+            <Card.Description>A brief description</Card.Description>
+          </Card.Header>
+          <Card.Body>Card content goes here.</Card.Body>
         </Card>
       ),
     },
@@ -116,8 +122,11 @@ export default defineSegment({
       name: 'Outlined',
       description: 'Card with border instead of shadow',
       render: () => (
-        <Card variant="outlined" title="Outlined Card">
-          Content with border.
+        <Card variant="outlined">
+          <Card.Header>
+            <Card.Title>Outlined Card</Card.Title>
+          </Card.Header>
+          <Card.Body>Content with border.</Card.Body>
         </Card>
       ),
     },
@@ -125,8 +134,11 @@ export default defineSegment({
       name: 'Elevated',
       description: 'Card with prominent shadow for emphasis',
       render: () => (
-        <Card variant="elevated" title="Featured Item">
-          Important content.
+        <Card variant="elevated">
+          <Card.Header>
+            <Card.Title>Featured Item</Card.Title>
+          </Card.Header>
+          <Card.Body>Important content.</Card.Body>
         </Card>
       ),
     },
@@ -134,21 +146,35 @@ export default defineSegment({
       name: 'Interactive',
       description: 'Clickable card',
       render: () => (
-        <Card
-          title="Click Me"
-          description="This card is interactive"
-          onClick={() => alert('Card clicked!')}
-        >
-          Click anywhere on this card.
+        <Card onClick={() => alert('Card clicked!')}>
+          <Card.Header>
+            <Card.Title>Click Me</Card.Title>
+            <Card.Description>This card is interactive</Card.Description>
+          </Card.Header>
+          <Card.Body>Click anywhere on this card.</Card.Body>
+        </Card>
+      ),
+    },
+    {
+      name: 'With Footer',
+      description: 'Card with header, body, and footer',
+      render: () => (
+        <Card>
+          <Card.Header>
+            <Card.Title>Card with Footer</Card.Title>
+            <Card.Description>Complete card layout</Card.Description>
+          </Card.Header>
+          <Card.Body>Main content area.</Card.Body>
+          <Card.Footer>Footer actions go here</Card.Footer>
         </Card>
       ),
     },
     {
       name: 'Content Only',
-      description: 'Card without header',
+      description: 'Card with just body content',
       render: () => (
         <Card>
-          Just content, no title or description.
+          <Card.Body>Just content, no header or footer.</Card.Body>
         </Card>
       ),
     },

package/src/components/Card/Card.module.scss

@@ -6,7 +6,8 @@
   font-family: var(--fui-font-sans, $fui-font-sans);
   transition:
     box-shadow var(--fui-transition-fast, $fui-transition-fast),
-    border-color var(--fui-transition-fast, $fui-transition-fast);
+    border-color var(--fui-transition-fast, $fui-transition-fast),
+    transform var(--fui-transition-fast, $fui-transition-fast);
 }
 
 // Variants
@@ -29,15 +30,15 @@
 }
 
 .paddingSm {
-  padding: var(--fui-space-3, $fui-space-3);
+  padding: var(--fui-padding-container-sm, $fui-padding-container-sm);
 }
 
 .paddingMd {
-  padding: var(--fui-space-4, $fui-space-4);
+  padding: var(--fui-padding-container-md, $fui-padding-container-md);
 }
 
 .paddingLg {
-  padding: var(--fui-space-6, $fui-space-6);
+  padding: var(--fui-padding-container-lg, $fui-padding-container-lg);
 }
 
 // Interactive card (when onClick is provided)
@@ -53,10 +54,12 @@
   &:hover {
     border-color: var(--fui-border-strong, $fui-border-strong);
     box-shadow: var(--fui-shadow-md, $fui-shadow-md);
+    transform: translateY(-2px);
   }
 
   &:active {
     box-shadow: var(--fui-shadow-sm, $fui-shadow-sm);
+    transform: translateY(0);
   }
 }
 
@@ -79,8 +82,52 @@
   line-height: var(--fui-line-height-normal, $fui-line-height-normal);
 }
 
-.content {
+.body {
   color: var(--fui-text-primary, $fui-text-primary);
   font-size: var(--fui-font-size-sm, $fui-font-size-sm);
   line-height: var(--fui-line-height-normal, $fui-line-height-normal);
 }
+
+.footer {
+  display: flex;
+  align-items: center;
+  gap: var(--fui-space-2, $fui-space-2);
+  margin-top: var(--fui-space-4, $fui-space-4);
+  padding-top: var(--fui-space-4, $fui-space-4);
+  border-top: 1px solid var(--fui-border, $fui-border);
+}
+
+// ============================================
+// Accessibility: Reduced Motion
+// ============================================
+
+@media (prefers-reduced-motion: reduce) {
+  .card {
+    transition: none;
+  }
+
+  .interactive {
+    &:hover {
+      transform: none;
+    }
+
+    &:active {
+      transform: none;
+    }
+  }
+}
+
+// ============================================
+// Accessibility: High Contrast Mode
+// ============================================
+
+@media (prefers-contrast: more) {
+  .card {
+    border-width: 2px;
+    border-color: var(--fui-text-primary, $fui-text-primary);
+  }
+
+  .footer {
+    border-top-width: 2px;
+  }
+}

package/src/components/Card/index.tsx

@@ -3,16 +3,61 @@ import styles from './Card.module.scss';
 // Import globals to ensure CSS variables are defined
 import '../../styles/globals.scss';
 
-export interface CardProps {
-  children?: React.ReactNode;
-  title?: string;
-  description?: string;
+// ============================================
+// Types
+// ============================================
+
+export interface CardProps extends Omit<React.HTMLAttributes<HTMLDivElement>, 'onClick'> {
+  children: React.ReactNode;
   variant?: 'default' | 'outlined' | 'elevated';
   padding?: 'none' | 'sm' | 'md' | 'lg';
   onClick?: () => void;
-  className?: string;
 }
 
+export interface CardHeaderProps extends React.HTMLAttributes<HTMLDivElement> {
+  children: React.ReactNode;
+}
+
+export interface CardTitleProps extends React.HTMLAttributes<HTMLHeadingElement> {
+  children: React.ReactNode;
+}
+
+export interface CardDescriptionProps extends React.HTMLAttributes<HTMLParagraphElement> {
+  children: React.ReactNode;
+}
+
+export interface CardBodyProps extends React.HTMLAttributes<HTMLDivElement> {
+  children: React.ReactNode;
+}
+
+export interface CardFooterProps extends React.HTMLAttributes<HTMLDivElement> {
+  children: React.ReactNode;
+}
+
+// ============================================
+// Context
+// ============================================
+
+interface CardContextValue {
+  variant: 'default' | 'outlined' | 'elevated';
+  padding: 'none' | 'sm' | 'md' | 'lg';
+  isInteractive: boolean;
+}
+
+const CardContext = React.createContext<CardContextValue | null>(null);
+
+function useCardContext() {
+  const context = React.useContext(CardContext);
+  if (!context) {
+    throw new Error('Card compound components must be used within a Card');
+  }
+  return context;
+}
+
+// ============================================
+// Padding Map
+// ============================================
+
 const paddingMap = {
   none: styles.paddingNone,
   sm: styles.paddingSm,
@@ -20,60 +65,116 @@ const paddingMap = {
   lg: styles.paddingLg,
 };
 
-export const Card = React.forwardRef<HTMLDivElement, CardProps>(
-  function Card(
-    {
-      children,
-      title,
-      description,
-      variant = 'default',
-      padding = 'md',
-      onClick,
-      className,
-    },
-    ref
-  ) {
-    const isInteractive = !!onClick;
-
-    const classes = [
-      styles.card,
-      styles[variant],
-      paddingMap[padding],
-      isInteractive && styles.interactive,
-      className,
-    ]
-      .filter(Boolean)
-      .join(' ');
-
-    const content = (
-      <>
-        {(title || description) && (
-          <div className={children ? styles.header : undefined}>
-            {title && <h3 className={styles.title}>{title}</h3>}
-            {description && <p className={styles.description}>{description}</p>}
-          </div>
-        )}
-        {children && <div className={styles.content}>{children}</div>}
-      </>
-    );
+// ============================================
+// Components
+// ============================================
+
+function CardRoot({
+  children,
+  variant = 'default',
+  padding = 'md',
+  onClick,
+  className,
+  style,
+  'aria-label': ariaLabel,
+  'aria-describedby': ariaDescribedBy,
+  ...htmlProps
+}: CardProps) {
+  const isInteractive = !!onClick;
 
-    if (isInteractive) {
-      return (
+  const classes = [
+    styles.card,
+    styles[variant],
+    paddingMap[padding],
+    isInteractive && styles.interactive,
+    className,
+  ]
+    .filter(Boolean)
+    .join(' ');
+
+  const contextValue: CardContextValue = {
+    variant,
+    padding,
+    isInteractive,
+  };
+
+  if (isInteractive) {
+    return (
+      <CardContext.Provider value={contextValue}>
         <button
-          ref={ref as React.Ref<HTMLButtonElement>}
           type="button"
+          {...(htmlProps as React.ButtonHTMLAttributes<HTMLButtonElement>)}
           onClick={onClick}
           className={classes}
+          style={style}
+          aria-label={ariaLabel}
+          aria-describedby={ariaDescribedBy}
         >
-          {content}
+          {children}
         </button>
-      );
-    }
-
-    return (
-      <div ref={ref} className={classes}>
-        {content}
-      </div>
+      </CardContext.Provider>
     );
   }
-);
+
+  return (
+    <CardContext.Provider value={contextValue}>
+      <article
+        {...htmlProps}
+        className={classes}
+        style={style}
+        aria-label={ariaLabel}
+        aria-describedby={ariaDescribedBy}
+      >
+        {children}
+      </article>
+    </CardContext.Provider>
+  );
+}
+
+function CardHeader({ children, className, ...htmlProps }: CardHeaderProps) {
+  const classes = [styles.header, className].filter(Boolean).join(' ');
+  return <div {...htmlProps} className={classes}>{children}</div>;
+}
+
+function CardTitle({ children, className, ...htmlProps }: CardTitleProps) {
+  const classes = [styles.title, className].filter(Boolean).join(' ');
+  return <h3 {...htmlProps} className={classes}>{children}</h3>;
+}
+
+function CardDescription({ children, className, ...htmlProps }: CardDescriptionProps) {
+  const classes = [styles.description, className].filter(Boolean).join(' ');
+  return <p {...htmlProps} className={classes}>{children}</p>;
+}
+
+function CardBody({ children, className, ...htmlProps }: CardBodyProps) {
+  const classes = [styles.body, className].filter(Boolean).join(' ');
+  return <div {...htmlProps} className={classes}>{children}</div>;
+}
+
+function CardFooter({ children, className, ...htmlProps }: CardFooterProps) {
+  const classes = [styles.footer, className].filter(Boolean).join(' ');
+  return <div {...htmlProps} className={classes}>{children}</div>;
+}
+
+// ============================================
+// Export compound component
+// ============================================
+
+export const Card = Object.assign(CardRoot, {
+  Header: CardHeader,
+  Title: CardTitle,
+  Description: CardDescription,
+  Body: CardBody,
+  Footer: CardFooter,
+});
+
+// Re-export individual components for tree-shaking
+export {
+  CardRoot,
+  CardHeader,
+  CardTitle,
+  CardDescription,
+  CardBody,
+  CardFooter,
+  useCardContext,
+};