@fpkit/acss 0.5.12 → 0.6.0

package/src/components/tag/tag.tsx

@@ -1,25 +1,122 @@
 import React from 'react'
 import UI from '#components/ui'
+import type { TagProps, TagVariant } from './tag.types'
 
-export type TagProps = {
-  /** HTML element to display the badge as span or p */
-  elm?: 'span' | 'p'
-  /**  Aria role for the component - conditional */
-  role: 'note' | 'status'
-} & React.ComponentProps<typeof UI>
-
+/**
+ * Tag - A small inline label component for displaying status, versions, or environment indicators
+ *
+ * The Tag component is used to highlight supplementary information such as release stages
+ * (alpha, beta, stable), environment indicators (production), or version labels. It renders
+ * as either a `<span>` (inline) or `<p>` (block) element with semantic ARIA roles.
+ *
+ * ## Design Philosophy
+ *
+ * Tags serve as visual and semantic indicators that:
+ * - Communicate the state or stage of features, releases, or environments
+ * - Provide quick visual scanning through color-coded variants
+ * - Maintain accessibility through proper ARIA roles and labels
+ *
+ * ## Styling Architecture
+ *
+ * The Tag component uses CSS custom properties (CSS variables) for theming and styling,
+ * allowing for easy customization through the `data-tag` attribute. Each variant
+ * (alpha, beta, stable, production) applies predefined color schemes defined in SCSS.
+ *
+ * ## Accessibility Considerations (WCAG 2.1 AA Compliance)
+ *
+ * - **Semantic Roles**: Uses `role="note"` for static tags or `role="status"` for dynamic content
+ *   - `role="note"`: Read once by screen readers, suitable for static labels (default)
+ *   - `role="status"`: Announces updates to screen readers, use for changing status indicators
+ * - **Color Independence**: Don't rely solely on color to convey meaning - include text labels
+ * - **Text Alternatives**: For icon-only tags, provide `aria-label` for screen reader context
+ * - **Contrast Ratios**: All variants meet WCAG AA contrast requirements (4.5:1 for normal text)
+ * - **Live Regions**: When using `role="status"`, tag becomes a live region for accessibility
+ *
+ * ## When to Use Each Role
+ *
+ * **Use `role="note"` (default) when:**
+ * - Displaying static version numbers (e.g., "v2.1.0")
+ * - Showing fixed environment indicators (e.g., "Beta Feature")
+ * - Labeling unchanging content categories
+ *
+ * **Use `role="status"` when:**
+ * - Indicating real-time status that may change (e.g., "Processing" → "Complete")
+ * - Displaying live build/deployment states
+ * - Showing dynamic feature flags that toggle
+ *
+ * @param {TagProps} props - Component props
+ * @returns {React.ReactElement} A Tag component
+ *
+ * @example
+ * // Basic tag with beta variant (default inline span)
+ * <Tag variant="beta">Beta</Tag>
+ *
+ * @example
+ * // Production environment indicator as block element
+ * <Tag elm="p" variant="production">Production Environment</Tag>
+ *
+ * @example
+ * // Dynamic status tag with live updates
+ * <Tag role="status" variant="stable">
+ *   {isDeployed ? 'Deployed' : 'Deploying...'}
+ * </Tag>
+ *
+ * @example
+ * // Tag with custom styling and accessibility label
+ * <Tag
+ *   variant="alpha"
+ *   aria-label="Alpha version - may contain bugs"
+ *   styles={{ fontSize: '0.75rem' }}
+ * >
+ *   Alpha
+ * </Tag>
+ *
+ * @example
+ * // ✅ GOOD: Clear text content with variant for visual enhancement
+ * <Tag variant="stable">v2.0 Stable</Tag>
+ *
+ * @example
+ * // ✅ GOOD: Dynamic status with proper role
+ * <Tag role="status" variant="production">{deploymentStatus}</Tag>
+ *
+ * @example
+ * // ✅ GOOD: Accessible tag with descriptive label
+ * <Tag variant="beta" aria-label="Beta feature - feedback welcome">
+ *   Beta
+ * </Tag>
+ *
+ * @example
+ * // ❌ BAD: Relying only on color without text
+ * <Tag variant="production" aria-label="Production" />
+ *
+ * @example
+ * // ❌ BAD: Using status role for static content
+ * <Tag role="status" variant="stable">v1.0</Tag>
+ */
 export const Tag = ({
   elm = 'span',
   role = 'note',
+  variant,
   children,
   styles,
   ...props
 }: TagProps) => {
+  // Map variant to data-tag attribute for SCSS styling
+  const dataTag = variant ? variant : undefined
+
   return (
-    <UI as={elm} role={role} styles={styles} {...props}>
+    <UI
+      as={elm}
+      role={role}
+      data-tag={dataTag}
+      styles={styles}
+      {...props}
+    >
       {children}
     </UI>
   )
 }
-export default Tag
+
 Tag.displayName = 'Tag'
+export default Tag
+export type { TagProps, TagVariant }

package/src/components/tag/tag.types.ts

@@ -0,0 +1,107 @@
+import React from 'react'
+import UI from '#components/ui'
+
+/**
+ * Available visual variants for the Tag component
+ *
+ * Each variant applies predefined color schemes and styling through CSS custom properties:
+ * - `alpha`: Early development stage indicator (warning colors)
+ * - `beta`: Pre-release version indicator (warning colors)
+ * - `stable`: Production-ready release indicator (success colors)
+ * - `production`: Live production environment indicator (primary colors)
+ *
+ * @example
+ * ```tsx
+ * <Tag variant="beta">Beta Feature</Tag>
+ * <Tag variant="stable">v2.0</Tag>
+ * ```
+ */
+export type TagVariant = 'alpha' | 'beta' | 'stable' | 'production'
+
+/**
+ * Props for the Tag component
+ *
+ * @property {React.ReactNode} children - REQUIRED - Content to display inside the tag (typically short text or version numbers)
+ * @property {'span' | 'p'} [elm='span'] - HTML element to render the tag as. Use 'p' for block-level tags, 'span' for inline
+ * @property {'note' | 'status'} [role='note'] - ARIA role for semantic meaning and screen reader announcements
+ * @property {TagVariant} [variant] - Visual variant that applies predefined color schemes (alpha, beta, stable, production)
+ * @property {string} [id] - Optional HTML id attribute for the tag element
+ * @property {React.CSSProperties} [styles] - Inline styles to apply to the tag
+ * @property {string} [classes] - CSS class names to apply to the tag
+ * @property {string} [aria-label] - Accessible label for screen readers. Recommended when tag content needs additional context
+ * @property {string} [aria-labelledby] - Reference to element(s) that label the tag for additional context
+ * @property {string} [aria-describedby] - Reference to element(s) that describe the tag for additional context
+ * @property {'off' | 'polite' | 'assertive'} [aria-live] - ARIA live region politeness setting for dynamic content (use with role="status")
+ *
+ * @example
+ * ```tsx
+ * // Basic tag with variant
+ * <Tag variant="beta">Beta</Tag>
+ *
+ * // Tag with custom element and role
+ * <Tag elm="p" role="status" variant="stable">v1.0 Released</Tag>
+ *
+ * // Tag with accessibility label
+ * <Tag variant="production" aria-label="Currently in production environment">
+ *   Production
+ * </Tag>
+ * ```
+ */
+export type TagProps = {
+  /**
+   * HTML element to display the tag as
+   * - 'span': Inline tag (default) - use for inline placement within text flow
+   * - 'p': Block-level tag - use when tag should appear as a distinct block element
+   */
+  elm?: 'span' | 'p'
+  /**
+   * ARIA role for semantic meaning and screen reader behavior
+   * - 'note': For static, informational tags (default) - screen readers read once
+   * - 'status': For dynamic tags that update - screen readers announce changes to users
+   *
+   * Choose 'status' when tag content changes dynamically (e.g., real-time status updates).
+   * Choose 'note' for static tags that provide contextual information.
+   */
+  role?: 'note' | 'status'
+  /**
+   * Visual variant that applies predefined color schemes
+   * - 'alpha': Early development stage (amber background with warning symbol ⚠)
+   * - 'beta': Pre-release version (amber background with warning symbol ⚠)
+   * - 'stable': Production-ready release (green background with checkmark ✓)
+   * - 'production': Live production environment (blue background with live indicator ●)
+   *
+   * Each variant includes both color AND visual symbols for accessibility (WCAG 1.4.1).
+   */
+  variant?: TagVariant
+  /**
+   * Content to display inside the tag
+   * REQUIRED - Ensures tag has meaningful content for all users including screen reader users
+   * Typically short text, version numbers, or status labels
+   */
+  children: React.ReactNode
+  /**
+   * Accessible label for screen readers
+   * Provides additional context beyond visible text
+   */
+  'aria-label'?: string
+  /**
+   * Reference to element(s) that label the tag
+   * Alternative to aria-label for programmatic labeling
+   */
+  'aria-labelledby'?: string
+  /**
+   * Reference to element(s) that describe the tag
+   * Provides additional descriptive context
+   */
+  'aria-describedby'?: string
+  /**
+   * ARIA live region politeness setting
+   * - 'off': Updates not announced (default)
+   * - 'polite': Announces when user is idle (recommended for role="status")
+   * - 'assertive': Announces immediately (use sparingly for critical updates)
+   */
+  'aria-live'?: 'off' | 'polite' | 'assertive'
+} & Omit<
+  React.ComponentProps<typeof UI>,
+  'as' | 'aria-label' | 'aria-labelledby' | 'aria-describedby' | 'aria-live'
+>

package/src/components/title/MIGRATION.md

@@ -0,0 +1,199 @@
+# Migration Guide: Heading → Title
+
+## Summary of Changes
+
+The `Heading` component has been refactored and renamed to `Title` with improved API design, better accessibility, and enhanced developer experience.
+
+## What Changed?
+
+### 1. Component Name
+- **Old**: `Heading`
+- **New**: `Title`
+
+### 2. Prop Names
+- **Old**: `type` prop
+- **New**: `level` prop (more semantic)
+
+### 3. Default Behavior
+- **Old**: Default heading level was `h3`
+- **New**: Default heading level is `h2`
+
+### 4. Improvements Added
+- ✅ **Memoization**: Component wrapped with `React.memo` for performance
+- ✅ **Ref Forwarding**: Properly typed refs for DOM access
+- ✅ **Better TypeScript**: Comprehensive JSDoc comments for IDE support
+- ✅ **Enhanced Accessibility**: Better WCAG 2.1 AA compliance documentation
+- ✅ **Comprehensive Tests**: 31 test cases covering all functionality
+- ✅ **Storybook Stories**: Interactive examples with accessibility checks
+
+## Quick Migration
+
+### Before (Deprecated)
+```tsx
+import { Heading } from '@fpkit/acss';
+
+<Heading type="h2">Section Title</Heading>
+<Heading type="h3" id="subsection">Subsection</Heading>
+<Heading>Default (renders as h3)</Heading>
+```
+
+### After (Recommended)
+```tsx
+import { Title } from '@fpkit/acss';
+
+<Title level="h2">Section Title</Title>
+<Title level="h3" id="subsection">Subsection</Title>
+<Title>Default (renders as h2)</Title>
+```
+
+## Backwards Compatibility
+
+The `Heading` component **still works** and provides 100% backwards compatibility:
+
+- ✅ All existing code continues to function
+- ⚠️ Console warnings in development mode
+- 📅 Will be removed in **v3.0.0**
+
+### Deprecation Warnings
+
+In development mode, you'll see:
+
+```
+[@fpkit/acss] Heading component is deprecated and will be removed in v3.0.0.
+Please use the Title component instead.
+Migration: <Heading type="h2"> → <Title level="h2">
+See documentation: https://fpkit.dev/components/title
+```
+
+## Migration Steps
+
+### Step 1: Find All Usages
+
+```bash
+# Search for all Heading imports
+grep -r "import.*Heading" src/
+
+# Search for all Heading components in JSX
+grep -r "<Heading" src/
+```
+
+### Step 2: Update Imports
+
+```tsx
+// Before:
+import { Heading } from '@fpkit/acss';
+
+// After:
+import { Title } from '@fpkit/acss';
+```
+
+### Step 3: Update Component Names and Props
+
+```tsx
+// Before:
+<Heading type="h1">Page Title</Heading>
+<Heading type="h2">Section</Heading>
+
+// After:
+<Title level="h1">Page Title</Title>
+<Title level="h2">Section</Title>
+```
+
+### Step 4: Handle Default Behavior
+
+If you relied on the default `h3` behavior:
+
+```tsx
+// Before (default was h3):
+<Heading>Title</Heading>
+
+// After (default is now h2):
+// Option 1: Accept new default
+<Title>Title</Title>
+
+// Option 2: Explicitly use h3
+<Title level="h3">Title</Title>
+```
+
+### Step 5: Test Your Changes
+
+```bash
+# Run your tests
+npm test
+
+# Check your app visually
+npm start
+```
+
+## Automated Migration (Optional)
+
+You can use find-and-replace, but **review changes carefully**:
+
+```bash
+# Replace component name (dry run first!)
+find src/ -type f \( -name "*.tsx" -o -name "*.ts" \) \
+  -exec sed -i '' 's/<Heading/<Title/g' {} +
+
+# Replace prop name
+find src/ -type f \( -name "*.tsx" -o -name "*.ts" \) \
+  -exec sed -i '' 's/type="/level="/g' {} +
+
+# Update imports
+find src/ -type f \( -name "*.tsx" -o -name "*.ts" \) \
+  -exec sed -i '' 's/import { Heading }/import { Title }/g' {} +
+```
+
+⚠️ **Warning**: The `type=` replacement may affect other components. Review all changes!
+
+## Type Safety
+
+Both components are fully typed:
+
+```tsx
+import { Title, type TitleProps, type HeadingLevel } from '@fpkit/acss';
+
+// Custom wrapper
+interface SectionTitleProps extends TitleProps {
+  emphasized?: boolean;
+}
+
+const SectionTitle = ({ emphasized, ...props }: SectionTitleProps) => (
+  <Title
+    {...props}
+    className={emphasized ? 'font-bold' : ''}
+  />
+);
+```
+
+## Benefits of Migrating
+
+### Better API
+- `level` is more semantic than `type`
+- Clearer intent in code
+
+### Performance
+- Memoization reduces unnecessary re-renders
+- Better for large component trees
+
+### Developer Experience
+- Comprehensive JSDoc comments
+- Better IDE autocomplete
+- Improved error messages
+
+### Accessibility
+- Enhanced WCAG 2.1 documentation
+- Better examples for screen reader support
+- Improved heading hierarchy guidance
+
+## Need Help?
+
+- 📚 [Full Documentation](README.md)
+- 📖 [Storybook Examples](?path=/docs/fp-react-components-title--docs)
+- 🐛 [Report Issues](https://github.com/fpkit/acss/issues)
+
+## Timeline
+
+- **v2.x**: Both components available, `Heading` deprecated
+- **v3.0.0**: `Heading` component removed (breaking change)
+
+Migrate before v3.0.0 to avoid breaking changes!