aibos-design-system 1.0.0 → 1.1.0

package/components/README.md

@@ -0,0 +1,130 @@
+# AIBOS Design System - React Components
+
+React components for AIBOS Design System, optimized for Next.js integration.
+
+## Installation
+
+The React components are included in the `aibos-design-system` package. No additional installation needed.
+
+## Usage
+
+### StatusIndicator
+
+The `StatusIndicator` component provides accessible status indicators using AIBOS CSS classes.
+
+```tsx
+import { StatusIndicator } from 'aibos-design-system/react';
+
+// Success status
+<StatusIndicator variant="success" label="Complete" />
+
+// Error status
+<StatusIndicator variant="error" label="Failed" />
+
+// Warning status
+<StatusIndicator variant="warning" label="Attention Required" />
+
+// Pending status
+<StatusIndicator variant="pending" label="In Progress" />
+```
+
+### With Custom Classes
+
+```tsx
+<StatusIndicator
+  variant="success"
+  label="Approved"
+  className="ml-4"
+/>
+```
+
+### In Cards/Tables
+
+```tsx
+import { Card, CardBody } from '@nextui-org/react';
+import { StatusIndicator } from 'aibos-design-system/react';
+
+<Card>
+  <CardBody>
+    <div className="flex items-center gap-4">
+      <span>Invoice #12345</span>
+      <StatusIndicator variant="pending" label="Under Review" />
+    </div>
+  </CardBody>
+</Card>
+```
+
+## API Reference
+
+### StatusIndicator Props
+
+| Prop | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| `variant` | `'success' \| 'error' \| 'warning' \| 'pending'` | Yes | - | Status variant |
+| `label` | `string` | Yes | - | Status label text |
+| `className` | `string` | No | - | Custom CSS classes |
+| `size` | `'small' \| 'default' \| 'large'` | No | `'default'` | Size variant |
+| `showDot` | `boolean` | No | `true` | Show dot indicator |
+| `aria-live` | `'polite' \| 'assertive' \| 'off'` | No | `'polite'` | ARIA live region |
+
+## Variant Mapping
+
+| React Variant | AIBOS CSS Class | Color | Usage |
+|---------------|----------------|-------|-------|
+| `success` | `ok` | Green (#10b981) | Complete, approved, ready |
+| `error` | `bad` | Red (#f43f5e) | Error, declined, failed |
+| `warning` | `warn` | Yellow (#f59e0b) | Requires attention |
+| `pending` | `pending` | Yellow (#f59e0b) | In progress, under review |
+
+## Accessibility
+
+The `StatusIndicator` component includes:
+- `role="status"` - Indicates live region for status updates
+- `aria-label` - Descriptive label for screen readers
+- `aria-live` - Optional, for dynamic status updates (default: 'polite')
+
+## TypeScript Support
+
+Full TypeScript support is included:
+
+```tsx
+import { StatusIndicator, type StatusIndicatorProps, type StatusVariant } from 'aibos-design-system/react';
+
+const variant: StatusVariant = 'success';
+const props: StatusIndicatorProps = {
+  variant: 'success',
+  label: 'Complete',
+};
+```
+
+## Utilities
+
+### cn() - Class Name Merger
+
+```tsx
+import { cn } from 'aibos-design-system/utils';
+
+const classes = cn('na-status', 'ok', isActive && 'active');
+// => 'na-status ok active'
+```
+
+## Next.js Integration
+
+See [NEXTJS_DESIGN_SYSTEM_IMPROVEMENTS.md](../NEXTJS_DESIGN_SYSTEM_IMPROVEMENTS.md) for complete Next.js integration guide.
+
+## Design Tokens
+
+```tsx
+import { designTokens } from 'aibos-design-system/design-tokens';
+
+const successColor = designTokens.colors.success; // 'var(--color-success)'
+const spacing = designTokens.spacing.md; // 'var(--spacing-4)'
+const h1Class = designTokens.typography.h1.class; // 'na-h1'
+```
+
+## Type Definitions
+
+```tsx
+import type { AIBOSStatusVariant, AIBOSTypographyClass } from 'aibos-design-system/types';
+```
+

package/components/react/Button.tsx

@@ -0,0 +1,82 @@
+/**
+ * Button Component
+ * 
+ * AIBOS-enhanced NextUI Button component
+ * Combines NextUI Button with AIBOS design system classes
+ * 
+ * @example
+ * ```tsx
+ * <Button variant="primary">Click me</Button>
+ * <Button variant="secondary">Cancel</Button>
+ * ```
+ */
+
+import React from 'react';
+import { Button as NextUIButton, ButtonProps as NextUIButtonProps } from '@nextui-org/react';
+import { cn } from '../utils.js';
+
+export type ButtonVariant = 'primary' | 'secondary' | 'ghost' | 'danger';
+
+export interface ButtonProps extends Omit<NextUIButtonProps, 'className' | 'variant'> {
+  /**
+   * Custom className - will be merged with AIBOS classes
+   */
+  className?: string;
+  
+  /**
+   * Button variant
+   * Maps to AIBOS button classes
+   */
+  variant?: ButtonVariant;
+  
+  /**
+   * Apply AIBOS button styling
+   * Default: true
+   */
+  withAIBOSStyles?: boolean;
+}
+
+/**
+ * Maps Button variant to AIBOS classes
+ */
+const variantClassMap: Record<ButtonVariant, string> = {
+  primary: 'na-btn-primary',
+  secondary: 'na-btn-secondary',
+  ghost: 'na-btn-ghost',
+  danger: 'na-btn-danger',
+} as const;
+
+/**
+ * Button Component
+ * 
+ * Enhanced NextUI Button with AIBOS design system integration.
+ * Automatically applies AIBOS button classes for consistent styling.
+ */
+export function Button({
+  className,
+  variant = 'primary',
+  withAIBOSStyles = true,
+  color,
+  ...props
+}: ButtonProps): JSX.Element {
+  // Map AIBOS variant to NextUI color if not provided
+  const nextUIColor = color || (variant === 'primary' ? 'primary' : 
+                                variant === 'danger' ? 'danger' : 
+                                variant === 'secondary' ? 'secondary' : 'default');
+
+  const classes = cn(
+    withAIBOSStyles && variantClassMap[variant],
+    className
+  );
+
+  return (
+    <NextUIButton
+      className={classes}
+      color={nextUIColor}
+      {...props}
+    />
+  );
+}
+
+export default Button;
+

package/components/react/Card.tsx

@@ -0,0 +1,73 @@
+/**
+ * Card Component
+ * 
+ * AIBOS-enhanced NextUI Card component
+ * Combines NextUI Card with AIBOS design system classes
+ * 
+ * @example
+ * ```tsx
+ * <Card>
+ *   <CardHeader>
+ *     <h2 className="na-h4">Card Title</h2>
+ *   </CardHeader>
+ *   <CardBody>
+ *     <div className="na-data">$12,450.00</div>
+ *   </CardBody>
+ * </Card>
+ * ```
+ */
+
+import React from 'react';
+import { Card as NextUICard, CardProps as NextUICardProps, CardHeader, CardBody, CardFooter } from '@nextui-org/react';
+import { cn } from '../utils.js';
+
+export interface CardProps extends Omit<NextUICardProps, 'className'> {
+  /**
+   * Custom className - will be merged with AIBOS classes
+   */
+  className?: string;
+  
+  /**
+   * Apply AIBOS card padding (na-p-6)
+   * Default: true
+   */
+  withPadding?: boolean;
+  
+  /**
+   * Apply AIBOS card styling
+   * Default: true
+   */
+  withAIBOSStyles?: boolean;
+}
+
+/**
+ * Card Component
+ * 
+ * Enhanced NextUI Card with AIBOS design system integration.
+ * Automatically applies AIBOS card classes for consistent styling.
+ */
+export function Card({
+  className,
+  withPadding = true,
+  withAIBOSStyles = true,
+  ...props
+}: CardProps): JSX.Element {
+  const classes = cn(
+    withAIBOSStyles && 'na-card',
+    withPadding && 'na-p-6',
+    className
+  );
+
+  return (
+    <NextUICard
+      className={classes}
+      {...props}
+    />
+  );
+}
+
+// Re-export NextUI Card sub-components for convenience
+export { CardHeader, CardBody, CardFooter };
+
+export default Card;
+

package/components/react/README.md

@@ -0,0 +1,324 @@
+# AIBOS Design System - React Components for NextUI/HeroUI
+
+Complete React component library for seamless NextUI/HeroUI integration with AIBOS Design System.
+
+---
+
+## Components
+
+### StatusIndicator
+
+Accessible status indicators with AIBOS styling.
+
+```tsx
+import { StatusIndicator } from 'aibos-design-system/react';
+
+<StatusIndicator variant="success" label="Complete" />
+<StatusIndicator variant="error" label="Failed" />
+<StatusIndicator variant="warning" label="Attention Required" />
+<StatusIndicator variant="pending" label="In Progress" />
+```
+
+### Card
+
+Enhanced NextUI Card with AIBOS styling.
+
+```tsx
+import { Card, CardHeader, CardBody } from 'aibos-design-system/react';
+
+<Card>
+  <CardHeader>
+    <h2 className="na-h4">Card Title</h2>
+  </CardHeader>
+  <CardBody>
+    <div className="na-data">$12,450.00</div>
+    <div className="na-metadata">PO-88219 • Feed Supply</div>
+  </CardBody>
+</Card>
+```
+
+**Props:**
+- `withPadding` (default: `true`) - Apply AIBOS padding (`na-p-6`)
+- `withAIBOSStyles` (default: `true`) - Apply AIBOS card styling (`na-card`)
+
+### Button
+
+Enhanced NextUI Button with AIBOS styling.
+
+```tsx
+import { Button } from 'aibos-design-system/react';
+
+<Button variant="primary">Click me</Button>
+<Button variant="secondary">Cancel</Button>
+<Button variant="danger">Delete</Button>
+<Button variant="ghost">Skip</Button>
+```
+
+**Props:**
+- `variant` - `'primary' | 'secondary' | 'ghost' | 'danger'`
+- `withAIBOSStyles` (default: `true`) - Apply AIBOS button styling
+
+---
+
+## Integration Helpers
+
+### withAIBOS()
+
+Combine AIBOS classes with NextUI components.
+
+```tsx
+import { withAIBOS } from 'aibos-design-system/react';
+import { Card } from '@nextui-org/react';
+
+<Card className={withAIBOS('na-card', 'na-p-6', customClass)}>
+  Content
+</Card>
+```
+
+### aibosTypography()
+
+Get AIBOS typography classes.
+
+```tsx
+import { aibosTypography } from 'aibos-design-system/react';
+
+<h1 className={aibosTypography('h1')}>Title</h1>
+<div className={aibosTypography('data')}>$12,450.00</div>
+<div className={aibosTypography('metadata')}>Label</div>
+```
+
+### aibosSpacing()
+
+Get AIBOS spacing classes.
+
+```tsx
+import { aibosSpacing } from 'aibos-design-system/react';
+
+<div className={aibosSpacing('p-6', 'mt-4')}>Content</div>
+```
+
+### withAIBOSClasses()
+
+HOC to add AIBOS classes to any component.
+
+```tsx
+import { withAIBOSClasses } from 'aibos-design-system/react';
+import { Card as NextUICard } from '@nextui-org/react';
+
+const AIBOSCard = withAIBOSClasses(NextUICard, 'na-card', 'na-p-6');
+
+<AIBOSCard>
+  Content
+</AIBOSCard>
+```
+
+---
+
+## Complete Examples
+
+### Data Dashboard Card
+
+```tsx
+import { Card, CardHeader, CardBody, Button, StatusIndicator } from 'aibos-design-system/react';
+
+export function VendorCard({ vendor }) {
+  return (
+    <Card>
+      <CardHeader>
+        <h2 className="na-h4">{vendor.name}</h2>
+      </CardHeader>
+      <CardBody>
+        <div className="na-data">${vendor.amount.toLocaleString()}</div>
+        <div className="na-metadata">{vendor.id} • {vendor.type}</div>
+        <div className="flex items-center gap-4 mt-4">
+          <StatusIndicator variant={vendor.status === 'approved' ? 'success' : 'pending'} label={vendor.status} />
+          <Button variant="primary">View Details</Button>
+        </div>
+      </CardBody>
+    </Card>
+  );
+}
+```
+
+### Form with AIBOS Styling
+
+```tsx
+import { Card, CardBody, Button } from 'aibos-design-system/react';
+import { Input } from '@nextui-org/react';
+
+export function VendorForm() {
+  return (
+    <Card>
+      <CardBody>
+        <h2 className="na-h4 mb-4">Create Vendor</h2>
+        <Input
+          label="Vendor Name"
+          className="mb-4"
+        />
+        <Input
+          label="Amount"
+          type="number"
+          className="mb-4"
+        />
+        <div className="flex gap-4">
+          <Button variant="primary">Submit</Button>
+          <Button variant="secondary">Cancel</Button>
+        </div>
+      </CardBody>
+    </Card>
+  );
+}
+```
+
+### Table with Status Indicators
+
+```tsx
+import { StatusIndicator } from 'aibos-design-system/react';
+import { Table, TableHeader, TableColumn, TableBody, TableRow, TableCell } from '@nextui-org/react';
+
+export function VendorTable({ vendors }) {
+  return (
+    <Table>
+      <TableHeader>
+        <TableColumn>Name</TableColumn>
+        <TableColumn>Amount</TableColumn>
+        <TableColumn>Status</TableColumn>
+      </TableHeader>
+      <TableBody>
+        {vendors.map((vendor) => (
+          <TableRow key={vendor.id}>
+            <TableCell className="na-h4">{vendor.name}</TableCell>
+            <TableCell className="na-data">${vendor.amount}</TableCell>
+            <TableCell>
+              <StatusIndicator 
+                variant={vendor.status === 'approved' ? 'success' : 'pending'} 
+                label={vendor.status} 
+              />
+            </TableCell>
+          </TableRow>
+        ))}
+      </TableBody>
+    </Table>
+  );
+}
+```
+
+---
+
+## TypeScript Support
+
+Full TypeScript support with exported types:
+
+```tsx
+import type {
+  StatusIndicatorProps,
+  StatusVariant,
+  CardProps,
+  ButtonProps,
+  ButtonVariant,
+} from 'aibos-design-system/react';
+```
+
+---
+
+## Best Practices
+
+### 1. Use AIBOS Components for Consistency
+
+✅ **Good:**
+```tsx
+import { Card, CardBody } from 'aibos-design-system/react';
+<Card><CardBody>Content</CardBody></Card>
+```
+
+❌ **Avoid:**
+```tsx
+import { Card } from '@nextui-org/react';
+<Card className="na-card na-p-6">Content</Card>
+```
+
+### 2. Combine AIBOS Typography with NextUI Components
+
+✅ **Good:**
+```tsx
+<Card>
+  <CardHeader>
+    <h2 className="na-h4">Title</h2>
+  </CardHeader>
+  <CardBody>
+    <div className="na-data">$12,450.00</div>
+  </CardBody>
+</Card>
+```
+
+### 3. Use StatusIndicator for Status Display
+
+✅ **Good:**
+```tsx
+<StatusIndicator variant="success" label="Approved" />
+```
+
+❌ **Avoid:**
+```tsx
+<span className="na-status ok">Approved</span>
+```
+
+---
+
+## Peer Dependencies
+
+These components require NextUI to be installed:
+
+```bash
+pnpm add @nextui-org/react framer-motion
+```
+
+React is a peer dependency (optional, but required for React components):
+
+```bash
+pnpm add react react-dom
+```
+
+---
+
+## Migration from Direct NextUI Usage
+
+### Before (Direct NextUI)
+
+```tsx
+import { Card, CardBody, Button } from '@nextui-org/react';
+
+<Card className="na-card na-p-6">
+  <CardBody>
+    <Button className="na-btn-primary">Click</Button>
+  </CardBody>
+</Card>
+```
+
+### After (AIBOS Components)
+
+```tsx
+import { Card, CardBody, Button } from 'aibos-design-system/react';
+
+<Card>
+  <CardBody>
+    <Button variant="primary">Click</Button>
+  </CardBody>
+</Card>
+```
+
+**Benefits:**
+- ✅ Cleaner code (no manual class application)
+- ✅ Consistent styling
+- ✅ Type-safe props
+- ✅ Better maintainability
+
+---
+
+## See Also
+
+- [Main Components README](../README.md)
+- [Design Tokens Documentation](../../types/design-tokens.ts)
+- [Type Definitions](../../types/aibos-classes.ts)
+- [NextUI Integration Guide](../../docs/INTEGRATION_GUIDE.md)
+

package/components/react/StatusIndicator.tsx

@@ -0,0 +1,101 @@
+/**
+ * StatusIndicator Component
+ * 
+ * AIBOS Design System Status Indicator with NextUI integration
+ * Provides accessible status indicators using AIBOS CSS classes
+ * 
+ * @example
+ * ```tsx
+ * <StatusIndicator variant="success" label="Complete" />
+ * <StatusIndicator variant="error" label="Failed" />
+ * ```
+ */
+
+import React from 'react';
+import { cn } from '../utils.js';
+
+export type StatusVariant = 'success' | 'error' | 'warning' | 'pending';
+
+export interface StatusIndicatorProps extends React.HTMLAttributes<HTMLSpanElement> {
+  /**
+   * Status variant
+   * Maps to AIBOS CSS classes: ok, bad, warn, pending
+   */
+  variant: StatusVariant;
+  
+  /**
+   * Status label text
+   * Required - AIBOS guidelines require text labels with icons
+   */
+  label: string;
+  
+  /**
+   * Optional size variant
+   * Default: 'default'
+   */
+  size?: 'small' | 'default' | 'large';
+  
+  /**
+   * Optional icon override
+   * Default: true (uses AIBOS ::before pseudo-element dot)
+   */
+  showDot?: boolean;
+  
+  /**
+   * Optional aria-live attribute for dynamic updates
+   * Default: 'polite'
+   */
+  'aria-live'?: 'polite' | 'assertive' | 'off';
+}
+
+/**
+ * Maps React variant prop to AIBOS CSS class
+ */
+const variantClassMap: Record<StatusVariant, string> = {
+  success: 'ok',
+  error: 'bad',
+  warning: 'warn',
+  pending: 'pending',
+} as const;
+
+/**
+ * StatusIndicator Component
+ * 
+ * Renders an accessible status indicator using AIBOS design system classes.
+ * Uses space-separated modifier classes (e.g., "na-status ok") as per AIBOS guidelines.
+ */
+export function StatusIndicator({
+  variant,
+  label,
+  className,
+  size = 'default',
+  showDot = true,
+  'aria-live': ariaLive = 'polite',
+  ...props
+}: StatusIndicatorProps): JSX.Element {
+  // Map variant to AIBOS CSS class
+  const variantClass = variantClassMap[variant];
+  
+  // Build className string with space-separated classes
+  const classes = cn(
+    'na-status',           // Base AIBOS class
+    variantClass,          // Variant class (ok, bad, warn, pending) - space-separated
+    size !== 'default' && `na-status-${size}`, // Optional size modifier
+    className              // Custom classes
+  );
+
+  return (
+    <span
+      className={classes}
+      role="status"
+      aria-label={`Status: ${label}`}
+      aria-live={ariaLive}
+      {...props}
+    >
+      {label}
+    </span>
+  );
+}
+
+export default StatusIndicator;
+