@fpkit/acss 0.5.12 → 0.5.13

package/src/components/images/img.types.ts

@@ -0,0 +1,211 @@
+import React from 'react'
+
+/**
+ * Props for the Img component.
+ *
+ * Extends native HTML img element attributes with additional functionality
+ * for responsive images, loading states, and error handling.
+ *
+ * ## Accessibility Guidelines (WCAG 2.1 AA)
+ *
+ * **Decorative Images:**
+ * Images that are purely visual decoration should have an empty alt attribute.
+ *
+ * @example
+ * ```tsx
+ * // ✅ Decorative image (border, background pattern, visual separator)
+ * <Img src="/decorative-border.png" alt="" />
+ * ```
+ *
+ * **Semantic Images:**
+ * Images that convey information or meaning must have descriptive alt text.
+ *
+ * @example
+ * ```tsx
+ * // ✅ Semantic image (charts, diagrams, photos with meaning)
+ * <Img
+ *   src="/sales-chart.png"
+ *   alt="Sales chart showing 30% growth in Q4 2024"
+ * />
+ * ```
+ *
+ * **Responsive Images:**
+ * Use srcset and sizes for responsive images to optimize performance.
+ *
+ * @example
+ * ```tsx
+ * // ✅ Responsive image with srcset
+ * <Img
+ *   src="/photo.jpg"
+ *   srcSet="/photo-320w.jpg 320w, /photo-640w.jpg 640w, /photo-1024w.jpg 1024w"
+ *   sizes="(max-width: 640px) 100vw, (max-width: 1024px) 50vw, 33vw"
+ *   alt="Team photo from annual conference"
+ * />
+ * ```
+ *
+ * @see https://www.w3.org/WAI/WCAG21/Understanding/non-text-content.html
+ */
+export interface ImgProps
+  extends Omit<React.ImgHTMLAttributes<HTMLImageElement>, 'placeholder'> {
+  /**
+   * The image source URL.
+   * @default '//'
+   */
+  src?: string
+
+  /**
+   * Alternative text for the image.
+   * - **Empty string (`""`)** for decorative images
+   * - **Descriptive text** for semantic images that convey meaning
+   *
+   * @example
+   * ```tsx
+   * // Decorative
+   * <Img src="/border.png" alt="" />
+   *
+   * // Semantic
+   * <Img src="/logo.png" alt="Company logo" />
+   * ```
+   */
+  alt?: string
+
+  /**
+   * Width of the image in pixels.
+   * @default 480
+   */
+  width?: number | string
+
+  /**
+   * Height of the image in pixels.
+   * When not provided, defaults to 'auto'.
+   */
+  height?: number | string
+
+  /**
+   * Inline styles to apply to the image.
+   */
+  styles?: React.CSSProperties
+
+  /**
+   * Loading behavior for the image.
+   * - `"lazy"` (default): Defers loading until near viewport
+   * - `"eager"`: Loads immediately
+   *
+   * @default "lazy"
+   * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#loading
+   */
+  loading?: 'eager' | 'lazy'
+
+  /**
+   * Fallback placeholder image URL to display on error.
+   * If not provided and image fails to load, a default placeholder is used.
+   *
+   * @example
+   * ```tsx
+   * <Img
+   *   src="/photo.jpg"
+   *   placeholder="/fallback.png"
+   *   alt="User profile photo"
+   * />
+   * ```
+   */
+  placeholder?: string
+
+  /**
+   * Hint for the browser to prioritize image fetching.
+   * - `"high"`: High priority (above-the-fold images)
+   * - `"low"` (default): Low priority
+   * - `"auto"`: Browser decides
+   *
+   * @default "low"
+   * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#fetchpriority
+   */
+  fetchpriority?: 'high' | 'low' | 'auto'
+
+  /**
+   * Decoding hint for the browser.
+   * - `"async"`: Decode asynchronously (don't block rendering)
+   * - `"sync"`: Decode synchronously
+   * - `"auto"` (default): Browser decides
+   *
+   * @default "auto"
+   * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#decoding
+   */
+  decoding?: 'sync' | 'async' | 'auto'
+
+  /**
+   * Responsive image sources with width descriptors.
+   * Allows browser to choose appropriate image based on viewport.
+   *
+   * @example
+   * ```tsx
+   * <Img
+   *   src="/photo.jpg"
+   *   srcSet="/photo-320w.jpg 320w, /photo-640w.jpg 640w"
+   *   sizes="(max-width: 640px) 100vw, 640px"
+   *   alt="Responsive image"
+   * />
+   * ```
+   *
+   * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#srcset
+   */
+  srcSet?: string
+
+  /**
+   * Media conditions for responsive image sizing.
+   * Works with srcSet to determine which image to load.
+   *
+   * @example
+   * ```tsx
+   * sizes="(max-width: 640px) 100vw, (max-width: 1024px) 50vw, 800px"
+   * ```
+   *
+   * @see https://developer.mozilla.org/en-US/docs/Web/HTML/Element/img#sizes
+   */
+  sizes?: string
+
+  /**
+   * Callback fired when the image fails to load.
+   * The default SVG placeholder is still applied after calling this handler.
+   * Call `event.preventDefault()` to prevent the default fallback behavior.
+   *
+   * @param event - The error event
+   *
+   * @example
+   * ```tsx
+   * // Log error and show default placeholder
+   * <Img
+   *   src="/photo.jpg"
+   *   onError={(e) => console.error('Image failed to load', e)}
+   *   alt="Photo"
+   * />
+   *
+   * // Prevent default and use custom fallback
+   * <Img
+   *   src="/photo.jpg"
+   *   onError={(e) => {
+   *     e.preventDefault()
+   *     e.currentTarget.src = '/custom-fallback.jpg'
+   *   }}
+   *   alt="Photo"
+   * />
+   * ```
+   */
+  onError?: (event: React.SyntheticEvent<HTMLImageElement, Event>) => void
+
+  /**
+   * Callback fired when the image successfully loads.
+   *
+   * @param event - The load event
+   *
+   * @example
+   * ```tsx
+   * <Img
+   *   src="/photo.jpg"
+   *   onLoad={(e) => console.log('Image loaded successfully')}
+   *   alt="Photo"
+   * />
+   * ```
+   */
+  onLoad?: (event: React.SyntheticEvent<HTMLImageElement, Event>) => void
+}

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!