@fpkit/acss 1.0.0-beta.1 → 1.0.0

package/docs/guides/architecture.md

@@ -0,0 +1,705 @@
+# Architecture Guide
+
+## Overview
+
+@fpkit/acss follows consistent architectural patterns that ensure maintainability, type safety, accessibility, and reusability. This guide explains these patterns to help you use and compose fpkit components effectively.
+
+---
+
+## The UI Component Foundation
+
+All fpkit components are built on a polymorphic `UI` base component that provides:
+
+- **Polymorphic rendering** - Render as any HTML element via `as` prop
+- **Type-safe prop spreading** - Full TypeScript support
+- **Style merging** - Combine default and custom styles
+- **Ref forwarding** - For focus management
+- **Automatic ARIA** - Attribute forwarding
+
+###  Understanding Polymorphism
+
+The `as` prop lets you change the rendered HTML element while preserving component behavior:
+
+```tsx
+import { Button, Card } from '@fpkit/acss'
+
+// Button as link
+<Button as="a" href="/page">
+  Navigate
+</Button>
+// Renders: <a href="/page">Navigate</a>
+
+// Card as section instead of article
+<Card as="section">
+  Content
+</Card>
+// Renders: <section>Content</section>
+
+// Badge as span instead of sup
+<Badge as="span">
+  Label
+</Badge>
+// Renders: <span>Label</span>
+```
+
+**Why this matters:**
+- Semantic HTML flexibility
+- Better accessibility (correct element for the job)
+- SEO benefits (proper HTML structure)
+- CSS targeting (style based on element type)
+
+---
+
+## Component Patterns
+
+### Simple Components
+
+Standalone components with no sub-components.
+
+**Examples**: Badge, Button, Tag, Icon
+
+```tsx
+import { Badge } from '@fpkit/acss'
+
+// Simple component with variant
+<Badge variant="rounded">New</Badge>
+
+// Polymorphic - render as different element
+<Badge as="span">Label</Badge>
+
+// Custom styles via CSS variables
+<Badge style={{ '--badge-bg': '#ff0000' }}>
+  Alert
+</Badge>
+```
+
+**Characteristics:**
+- Single export
+- Props extend base HTML element props
+- Variants via `data-*` attributes
+- Customizable via CSS variables
+
+---
+
+### Compound Components
+
+Complex components with multiple related sub-components.
+
+**Examples**: Card, Dialog, Alert, Form
+
+```tsx
+import { Card } from '@fpkit/acss'
+
+// Using sub-components
+<Card>
+  <Card.Header>
+    <Card.Title>Title</Card.Title>
+  </Card.Header>
+  <Card.Content>
+    Content goes here
+  </Card.Content>
+  <Card.Footer>
+    <Button>Action</Button>
+  </Card.Footer>
+</Card>
+
+// Or import individually
+import { Card, CardHeader, CardTitle, CardContent, CardFooter } from '@fpkit/acss'
+
+<Card>
+  <CardHeader>
+    <CardTitle>Title</CardTitle>
+  </CardHeader>
+  <CardContent>Content</CardContent>
+  <CardFooter>
+    <Button>Action</Button>
+  </CardFooter>
+</Card>
+```
+
+**Characteristics:**
+- Main component + sub-components
+- Available as `Component.SubComponent` or individual exports
+- Each sub-component is independently customizable
+- Flexible composition (use what you need)
+
+---
+
+## TypeScript Support
+
+### Component Props
+
+All fpkit components are fully typed:
+
+```tsx
+import type { ButtonProps, CardProps } from '@fpkit/acss'
+
+// Extend fpkit component props
+interface CustomButtonProps extends ButtonProps {
+  loading?: boolean
+  loadingText?: string
+}
+
+const CustomButton = ({
+  loading,
+  loadingText = 'Loading...',
+  children,
+  ...props
+}: CustomButtonProps) => {
+  return (
+    <Button {...props}>
+      {loading ? loadingText : children}
+    </Button>
+  )
+}
+```
+
+### Polymorphic Types
+
+Types adapt based on the `as` prop:
+
+```tsx
+// Button as button - button props available
+<Button type="submit" onClick={handleClick}>
+  Submit
+</Button>
+
+// Button as link - anchor props available
+<Button as="a" href="/page" target="_blank">
+  Link
+</Button>
+
+// Button as div - div props available
+<Button as="div" onKeyDown={handleKeyDown}>
+  Custom
+</Button>
+```
+
+### Generic Props Pattern
+
+```tsx
+import type { ComponentProps } from 'react'
+import { Button } from '@fpkit/acss'
+
+// Get button props type
+type BaseButtonProps = ComponentProps<typeof Button>
+
+// Extend with custom props
+interface MyButtonProps extends BaseButtonProps {
+  icon?: string
+  badge?: number
+}
+```
+
+---
+
+## Composition Patterns
+
+### Pattern 1: Container + Content
+
+Wrap fpkit components with additional structure:
+
+```tsx
+import { Button, Badge } from '@fpkit/acss'
+
+export const StatusButton = ({ status, children, ...props }) => {
+  return (
+    <Button {...props}>
+      {children}
+      <Badge variant={status}>{status}</Badge>
+    </Button>
+  )
+}
+
+// Usage
+<StatusButton status="active">Server Status</StatusButton>
+```
+
+### Pattern 2: Conditional Composition
+
+Different combinations based on props:
+
+```tsx
+import { Alert, Dialog } from '@fpkit/acss'
+
+export const Notification = ({ inline, variant, children, ...props }) => {
+  if (inline) {
+    return <Alert variant={variant}>{children}</Alert>
+  }
+
+  return (
+    <Dialog {...props}>
+      <Alert variant={variant}>{children}</Alert>
+    </Dialog>
+  )
+}
+
+// Usage
+<Notification inline variant="success">Saved!</Notification>
+<Notification isOpen={showModal} variant="error">Error!</Notification>
+```
+
+### Pattern 3: Enhanced Wrapper
+
+Add behavior around fpkit components:
+
+```tsx
+import { Button } from '@fpkit/acss'
+import { useState } from 'react'
+
+export const LoadingButton = ({ loading, onClick, children, ...props }) => {
+  const [isLoading, setIsLoading] = useState(loading)
+
+  const handleClick = async (e) => {
+    setIsLoading(true)
+    try {
+      await onClick?.(e)
+    } finally {
+      setIsLoading(false)
+    }
+  }
+
+  return (
+    <Button
+      {...props}
+      disabled={isLoading || props.disabled}
+      onClick={handleClick}
+    >
+      {isLoading ? 'Loading...' : children}
+    </Button>
+  )
+}
+
+// Usage
+<LoadingButton onClick={async () => await saveData()}>
+  Save
+</LoadingButton>
+```
+
+See the [Composition Guide](./composition.md) for more patterns and examples.
+
+---
+
+## Styling Architecture
+
+### Attribute-Based Variants
+
+fpkit uses `data-*` attributes for variants:
+
+```tsx
+// Component
+<Button variant="primary" size="large">Click me</Button>
+
+// Renders as
+<button data-btn="primary large">Click me</button>
+
+// Styled with SCSS
+button[data-btn~="primary"] {
+  background: var(--btn-primary-bg);
+}
+
+button[data-btn~="large"] {
+  font-size: var(--btn-size-lg);
+}
+```
+
+**Benefits:**
+- Multiple variants on same element
+- Clean HTML output
+- Type-safe variants in TypeScript
+- Easy CSS targeting
+
+### CSS Variable Integration
+
+All styling uses CSS custom properties:
+
+```tsx
+// Global overrides
+:root {
+  --btn-primary-bg: #0066cc;
+  --btn-padding-inline: 2rem;
+}
+
+// Component-specific overrides
+<Button
+  style={{
+    '--btn-bg': '#e63946',
+    '--btn-color': 'white',
+  }}
+>
+  Custom
+</Button>
+
+// CSS class overrides
+.hero-button {
+  --btn-padding-inline: 3rem;
+  --btn-fs: 1.25rem;
+}
+```
+
+See the [CSS Variables Guide](./css-variables.md) for complete customization options.
+
+---
+
+## Props Patterns
+
+### Common Props
+
+All fpkit components accept these common props:
+
+```tsx
+// className - additional CSS classes
+<Button className="custom-button">Click</Button>
+
+// style - inline styles
+<Button style={{ marginTop: '1rem' }}>Click</Button>
+
+// data-* - custom data attributes
+<Button data-testid="submit-btn">Click</Button>
+
+// aria-* - accessibility attributes
+<Button aria-label="Close dialog">×</Button>
+
+// ref - React ref
+const ref = useRef()
+<Button ref={ref}>Click</Button>
+
+// as - polymorphic element
+<Button as="a" href="/page">Link</Button>
+```
+
+### Variant Props
+
+Components use semantic variant names:
+
+```tsx
+// Button variants
+<Button variant="primary">Primary</Button>
+<Button variant="secondary">Secondary</Button>
+<Button variant="danger">Danger</Button>
+
+// Alert variants
+<Alert variant="error">Error message</Alert>
+<Alert variant="success">Success message</Alert>
+<Alert variant="warning">Warning message</Alert>
+<Alert variant="info">Info message</Alert>
+
+// Badge variants
+<Badge variant="rounded">Rounded</Badge>
+<Badge variant="pill">Pill</Badge>
+```
+
+### Size Props
+
+When components support sizing:
+
+```tsx
+<Button size="small">Small</Button>
+<Button size="medium">Medium</Button>
+<Button size="large">Large</Button>
+```
+
+### Boolean Props
+
+State and behavior props:
+
+```tsx
+// Disabled state
+<Button disabled>Disabled</Button>
+
+// Interactive cards
+<Card interactive onClick={handleClick}>Clickable</Card>
+
+// Modal/dialog states
+<Dialog isOpen={isOpen} onClose={handleClose}>Content</Dialog>
+
+// Dismissable alerts
+<Alert onClose={handleClose}>Dismissable</Alert>
+```
+
+---
+
+## Accessibility Architecture
+
+### Semantic HTML
+
+fpkit components render as appropriate semantic elements:
+
+| Component | Default Element | Purpose |
+|-----------|----------------|---------|
+| Button | `<button>` | Interactive action |
+| Card | `<article>` | Self-contained content |
+| Alert | `<div role="alert">` | Important message |
+| Dialog | `<dialog>` | Modal content |
+| Nav | `<nav>` | Navigation menu |
+
+### ARIA Attributes
+
+Components include built-in ARIA:
+
+```tsx
+// Button disabled state
+<Button disabled>
+// Renders: <button aria-disabled="true">
+
+// Alert role
+<Alert variant="error">
+// Renders: <div role="alert">
+
+// Dialog modal
+<Dialog isOpen>
+// Renders: <dialog aria-modal="true">
+
+// Expandable elements
+<Accordion expanded>
+// Renders: <div aria-expanded="true">
+```
+
+### Keyboard Navigation
+
+All interactive components support:
+- **Tab**: Focus navigation
+- **Enter/Space**: Activation
+- **Escape**: Close modals/dialogs
+- **Arrow keys**: Navigate lists/menus
+
+See the [Accessibility Guide](./accessibility.md) for complete patterns.
+
+---
+
+## Component Lifecycle
+
+### Initialization
+
+```tsx
+// Components accept default HTML element props
+<Button onClick={handleClick}>Click</Button>
+
+// Plus component-specific props
+<Button variant="primary" disabled>Click</Button>
+
+// Props spread to underlying element
+<Button data-testid="btn" aria-label="Submit">
+  Submit
+</Button>
+```
+
+### Updates
+
+```tsx
+// Props update reactively
+const [disabled, setDisabled] = useState(false)
+
+<Button disabled={disabled}>
+  {disabled ? 'Disabled' : 'Enabled'}
+</Button>
+
+// CSS variables update in real-time
+const [color, setColor] = useState('#0066cc')
+
+<Button style={{ '--btn-bg': color }}>
+  Dynamic Color
+</Button>
+```
+
+### Cleanup
+
+```tsx
+// Refs are properly forwarded
+const buttonRef = useRef<HTMLButtonElement>(null)
+
+useEffect(() => {
+  // Access DOM element directly
+  buttonRef.current?.focus()
+
+  return () => {
+    // Cleanup if needed
+  }
+}, [])
+
+<Button ref={buttonRef}>Click</Button>
+```
+
+---
+
+## Best Practices
+
+### ✅ Do
+
+- **Use semantic elements** - Leverage the `as` prop for correct HTML
+- **Compose over create** - Combine fpkit components rather than building from scratch
+- **Extend props properly** - Use TypeScript to extend component props
+- **Customize with CSS variables** - Override styles without modifying components
+- **Preserve accessibility** - Keep ARIA attributes and keyboard navigation
+- **Forward refs** - When wrapping components, forward refs appropriately
+
+```tsx
+// ✅ Good - proper composition
+import { forwardRef } from 'react'
+import { Button, type ButtonProps } from '@fpkit/acss'
+
+interface LoadingButtonProps extends ButtonProps {
+  loading?: boolean
+}
+
+export const LoadingButton = forwardRef<HTMLButtonElement, LoadingButtonProps>(
+  ({ loading, children, ...props }, ref) => {
+    return (
+      <Button ref={ref} {...props} disabled={loading || props.disabled}>
+        {loading ? 'Loading...' : children}
+      </Button>
+    )
+  }
+)
+```
+
+### ❌ Don't
+
+- **Don't duplicate components** - Reuse existing fpkit components
+- **Don't break accessibility** - Maintain ARIA attributes and keyboard support
+- **Don't hardcode styles** - Use CSS variables for customization
+- **Don't ignore types** - Leverage TypeScript for type safety
+- **Don't nest interactive elements** - Avoid `<button>` inside `<a>`
+
+```tsx
+// ❌ Bad - duplicating fpkit logic
+export const MyBadge = ({ children }) => {
+  return <span className="my-badge">{children}</span>
+}
+
+// ✅ Good - reuse fpkit component
+import { Badge } from '@fpkit/acss'
+export const MyBadge = Badge
+```
+
+---
+
+## Component API Patterns
+
+### Children Prop
+
+```tsx
+// String children
+<Button>Click me</Button>
+
+// Element children
+<Button>
+  <Icon name="save" />
+  Save
+</Button>
+
+// Render prop pattern
+<Card>
+  {({ isHovered }) => (
+    <div>Content {isHovered ? 'hovered' : ''}</div>
+  )}
+</Card>
+```
+
+### Event Handlers
+
+```tsx
+// Mouse events
+<Button onClick={handleClick}>Click</Button>
+<Button onMouseEnter={handleHover}>Hover</Button>
+
+// Keyboard events
+<Input onKeyDown={handleKeyPress} />
+
+// Form events
+<Input onChange={handleChange} />
+<Form onSubmit={handleSubmit} />
+
+// Custom events
+<Dialog onClose={handleClose} />
+<Alert onDismiss={handleDismiss} />
+```
+
+### Render Props
+
+```tsx
+// Custom rendering
+<Select>
+  {(option) => (
+    <div>
+      <Icon name={option.icon} />
+      {option.label}
+    </div>
+  )}
+</Select>
+```
+
+---
+
+## Framework Integration
+
+### React
+
+fpkit is designed for React:
+
+```tsx
+import { Button, Card } from '@fpkit/acss'
+
+export default function App() {
+  return (
+    <Card>
+      <Card.Title>Welcome</Card.Title>
+      <Card.Content>
+        <p>Content here</p>
+        <Button variant="primary">Action</Button>
+      </Card.Content>
+    </Card>
+  )
+}
+```
+
+### Next.js
+
+Works seamlessly with Next.js:
+
+```tsx
+import { Button } from '@fpkit/acss'
+import Link from 'next/link'
+
+// Button as Next.js Link
+<Button as={Link} href="/page">
+  Navigate
+</Button>
+```
+
+### TypeScript
+
+Full type safety:
+
+```tsx
+import type { ButtonProps } from '@fpkit/acss'
+
+// Type-safe custom component
+const CustomButton = (props: ButtonProps) => {
+  return <Button {...props} />
+}
+```
+
+---
+
+## Additional Resources
+
+- **[Composition Guide](./composition.md)** - Component composition patterns and strategies
+- **[CSS Variables Guide](./css-variables.md)** - Styling and customization
+- **[Accessibility Guide](./accessibility.md)** - WCAG compliance and ARIA patterns
+- **[Testing Guide](./testing.md)** - Testing strategies for fpkit components
+
+---
+
+## Summary
+
+@fpkit/acss architecture provides:
+
+1. **Polymorphic Components** - Flexible HTML element rendering via `as` prop
+2. **Compound Components** - Complex UIs with sub-components
+3. **Composition-First** - Build custom components by combining primitives
+4. **Type Safety** - Full TypeScript support with proper prop types
+5. **CSS Variables** - Customizable styling without component modification
+6. **Accessibility** - Built-in WCAG 2.1 AA compliance
+
+Understanding these patterns helps you use fpkit effectively and build maintainable, accessible applications.