@fpkit/acss 0.5.12 → 0.6.0

package/src/components/ui.tsx

@@ -2,55 +2,312 @@
 /* eslint-disable */
 import React from "react";
 
-type PolymorphicRef<C extends React.ElementType> =
-  React.ComponentPropsWithRef<C>["ref"];
+/**
+ * Extracts the appropriate ref type for a given element type.
+ *
+ * This utility type ensures that refs are properly typed based on the element
+ * being rendered. For example, a button element receives HTMLButtonElement ref.
+ * Excludes legacy string refs (deprecated since React 16.3).
+ *
+ * @typeParam C - The HTML element type (e.g., 'button', 'div', 'a')
+ * @example
+ * ```typescript
+ * type ButtonRef = PolymorphicRef<'button'>; // React.Ref<HTMLButtonElement>
+ * type DivRef = PolymorphicRef<'div'>; // React.Ref<HTMLDivElement>
+ * ```
+ */
+type PolymorphicRef<C extends React.ElementType> = React.Ref<
+  React.ElementRef<C>
+>;
 
+/**
+ * Defines the 'as' prop that determines which HTML element to render.
+ *
+ * This is the core prop that enables polymorphic behavior, allowing components
+ * to render as any valid React element type while maintaining type safety.
+ *
+ * @typeParam C - The HTML element type to render
+ * @example
+ * ```typescript
+ * <UI as="button">Click me</UI>
+ * <UI as="a" href="/home">Link</UI>
+ * ```
+ */
 type AsProp<C extends React.ElementType> = {
   as?: C;
 };
 
+/**
+ * Identifies props that should be omitted to prevent type conflicts.
+ *
+ * This type ensures that our custom props don't conflict with native element
+ * props by calculating which keys need to be omitted from the native props.
+ *
+ * @typeParam C - The HTML element type
+ * @typeParam P - The custom props to merge
+ */
 type PropsToOmit<C extends React.ElementType, P> = keyof (AsProp<C> & P);
 
+/**
+ * Merges custom props with native element props while preventing conflicts.
+ *
+ * This creates a union of our custom props and the native props for the chosen
+ * element, omitting any conflicting keys to ensure type safety.
+ *
+ * @typeParam C - The HTML element type
+ * @typeParam Props - The custom props to add
+ * @example
+ * ```typescript
+ * // For a button, this merges custom props with HTMLButtonElement props
+ * type ButtonProps = PolymorphicComponentProp<'button', { variant?: string }>;
+ * ```
+ */
 type PolymorphicComponentProp<
   C extends React.ElementType,
   Props = {},
 > = React.PropsWithChildren<Props & AsProp<C>> &
   Omit<React.ComponentPropsWithoutRef<C>, PropsToOmit<C, Props>>;
 
+/**
+ * Extends PolymorphicComponentProp to include properly-typed ref support.
+ *
+ * This is the final type in the polymorphic type chain, adding ref forwarding
+ * with the correct ref type for the chosen element. The ref is properly typed
+ * to match the element being rendered, enabling focus management and direct
+ * DOM access for accessibility features like programmatic focus control.
+ *
+ * Supports both PolymorphicRef and ForwardedRef for compatibility with
+ * React.forwardRef components.
+ *
+ * @typeParam C - The HTML element type
+ * @typeParam Props - The custom props to add
+ *
+ * @example
+ * ```typescript
+ * // Using ref for focus management (important for accessibility)
+ * const buttonRef = useRef<HTMLButtonElement>(null);
+ * useEffect(() => {
+ *   // Programmatically focus for keyboard navigation
+ *   buttonRef.current?.focus();
+ * }, []);
+ *
+ * return <UI as="button" ref={buttonRef}>Accessible Button</UI>;
+ * ```
+ */
 type PolymorphicComponentPropWithRef<
   C extends React.ElementType,
   Props = {},
 > = PolymorphicComponentProp<C, Props> & {
-  ref?: PolymorphicRef<C>;
+  ref?: PolymorphicRef<C> | React.ForwardedRef<React.ElementRef<C>>;
 };
 
-type FPProps<C extends React.ElementType> = PolymorphicComponentPropWithRef<
+/**
+ * Props for the UI component, extending polymorphic props with style and class support.
+ *
+ * The UI component automatically forwards all ARIA attributes and native HTML props
+ * to the rendered element, ensuring full accessibility support. This includes:
+ * - `aria-label`, `aria-labelledby` - Accessible names for screen readers
+ * - `aria-describedby` - Additional descriptive text references
+ * - `aria-expanded`, `aria-controls` - Interactive widget states
+ * - `role` - Semantic role override when needed
+ * - All other ARIA attributes and HTML props
+ *
+ * @typeParam C - The HTML element type to render
+ * @property {boolean} [renderStyles] - Reserved for future use. Currently has no effect.
+ *   Styles are always rendered regardless of this prop value.
+ * @property {React.CSSProperties} [styles] - Inline styles to apply (overrides defaultStyles)
+ * @property {React.CSSProperties} [defaultStyles] - Base styles that can be overridden by styles prop
+ * @property {string} [classes] - CSS class names to apply to the element
+ * @property {string} [id] - HTML id attribute
+ * @property {React.ReactNode} [children] - Child elements to render
+ *
+ * @example
+ * ```typescript
+ * // All ARIA attributes are automatically forwarded
+ * <UI as="button" aria-label="Close dialog" aria-expanded={isOpen}>
+ *   <CloseIcon />
+ * </UI>
+ * ```
+ */
+type UIProps<C extends React.ElementType> = PolymorphicComponentPropWithRef<
   C,
   {
+    /** @deprecated Reserved for future use. Currently has no effect. Styles are always rendered. */
     renderStyles?: boolean;
     styles?: React.CSSProperties;
+    defaultStyles?: React.CSSProperties;
     classes?: string;
     id?: string;
     children?: React.ReactNode;
   }
 >;
 
-/*
- * FPComponent type definition
+/**
+ * UI Component function signature.
  *
- * Defines the component function signature for the FP component.
+ * Defines the polymorphic component that can render as any HTML element while
+ * maintaining full TypeScript type safety for element-specific props.
  *
- * @typeParam C - The HTML element type to render
- * @param props - The component props
- * @returns React component
+ * @typeParam C - The HTML element type to render (defaults to 'div')
+ * @param {UIProps<C>} props - Component props including 'as', styles, and native element props
+ * @returns {React.ReactElement} A React element of the specified type
+ * @example
+ * ```typescript
+ * <UI as="button" onClick={handler}>Button</UI>
+ * <UI as="a" href="/link">Link</UI>
+ * <UI>Default div</UI>
+ * ```
  */
-type FPComponent = <C extends React.ElementType = "span">(
-  props: FPProps<C>
-) => React.ReactElement | (any & { displayName?: String });
+type UIComponent = (<C extends React.ElementType = "div">(
+  props: UIProps<C>
+) => React.ReactElement | any) & { displayName?: string };
 
-const FP: FPComponent = React.forwardRef(
+/**
+ * UI - A polymorphic React component that can render as any HTML element.
+ *
+ * The UI component is a foundational primitive used throughout fpkit to create
+ * flexible, type-safe components. It implements the polymorphic component pattern,
+ * allowing a single component to render as different HTML elements while maintaining
+ * full TypeScript type safety for element-specific props.
+ *
+ * ## Accessibility Considerations
+ *
+ * The UI component forwards all ARIA attributes and native HTML props, placing
+ * accessibility responsibility on the consumer. When creating interactive elements,
+ * you MUST ensure WCAG 2.1 AA compliance:
+ *
+ * - **Accessible Names**: All interactive elements need an accessible name via
+ *   `aria-label`, `aria-labelledby`, or visible text content
+ * - **Semantic HTML**: Prefer semantic elements (`button`, `a`, `nav`) over
+ *   generic containers (`div`, `span`) with ARIA roles when possible
+ * - **Focus Indicators**: Ensure focus indicators meet WCAG 2.4.7 (3:1 contrast)
+ * - **Keyboard Support**: Interactive elements must be keyboard accessible
+ *
+ * @typeParam C - The HTML element type to render (e.g., 'button', 'div', 'a')
+ *
+ * @param {C} [as='div'] - The HTML element type to render. Defaults to 'div'.
+ * @param {React.CSSProperties} [styles] - Inline styles to apply. Overrides defaultStyles.
+ * @param {string} [classes] - CSS class names to apply to the element.
+ * @param {React.CSSProperties} [defaultStyles] - Base styles that can be overridden by styles prop.
+ * @param {React.ReactNode} [children] - Child elements to render inside the component.
+ * @param {PolymorphicRef<C>} [ref] - Forwarded ref with proper typing for the element type.
+ * @param {boolean} [renderStyles] - Reserved for future use. Currently has no effect.
+ *
+ * @returns {React.ReactElement} A React element of the specified type with merged props.
+ *
+ * @example
+ * // Basic usage - renders as div
+ * <UI>Hello World</UI>
+ *
+ * @example
+ * // Polymorphic rendering - renders as button with type-safe props
+ * <UI as="button" onClick={handleClick} disabled>
+ *   Click me
+ * </UI>
+ *
+ * @example
+ * // ✅ GOOD: Accessible button with aria-label for icon-only button
+ * <UI as="button" aria-label="Close dialog" onClick={handleClose}>
+ *   <CloseIcon />
+ * </UI>
+ *
+ * @example
+ * // ✅ GOOD: Accessible link with descriptive text
+ * <UI as="a" href="/products">
+ *   View all products
+ * </UI>
+ *
+ * @example
+ * // ✅ GOOD: Interactive element with proper role and keyboard support
+ * <UI
+ *   as="div"
+ *   role="button"
+ *   tabIndex={0}
+ *   aria-label="Toggle menu"
+ *   onClick={handleToggle}
+ *   onKeyDown={(e) => e.key === 'Enter' && handleToggle()}
+ * >
+ *   Menu
+ * </UI>
+ *
+ * @example
+ * // ❌ BAD: Button without accessible name (screen readers can't identify it)
+ * <UI as="button" onClick={handleClose}>
+ *   <CloseIcon />
+ * </UI>
+ *
+ * @example
+ * // ❌ BAD: Non-semantic div with click handler (not keyboard accessible)
+ * <UI as="div" onClick={handleClick}>
+ *   Click me
+ * </UI>
+ *
+ * @example
+ * // ✅ GOOD: Custom focus indicator with WCAG 2.4.7 compliant contrast
+ * <UI
+ *   as="button"
+ *   styles={{
+ *     outline: '2px solid transparent',
+ *     outlineOffset: '2px',
+ *   }}
+ *   classes="focus:outline-blue-500"
+ * >
+ *   Accessible Button
+ * </UI>
+ *
+ * @example
+ * // Style merging - defaultStyles provide base, styles override
+ * <UI
+ *   as="span"
+ *   defaultStyles={{ padding: '0.5rem', color: 'blue' }}
+ *   styles={{ color: 'red' }}
+ * >
+ *   Red text with padding
+ * </UI>
+ *
+ * @example
+ * // Ref forwarding for focus management
+ * const buttonRef = useRef<HTMLButtonElement>(null);
+ * useEffect(() => {
+ *   // Programmatically focus for keyboard navigation
+ *   buttonRef.current?.focus();
+ * }, []);
+ * <UI as="button" ref={buttonRef}>Auto-focused Button</UI>
+ *
+ * @example
+ * // Building accessible higher-level components with TypeScript
+ * interface AccessibleButtonProps extends React.ComponentPropsWithoutRef<'button'> {
+ *   variant?: 'primary' | 'secondary';
+ *   // Require either aria-label or children for accessibility
+ *   'aria-label'?: string;
+ *   children?: React.ReactNode;
+ * }
+ *
+ * const AccessibleButton = React.forwardRef<HTMLButtonElement, AccessibleButtonProps>(
+ *   ({ variant = 'primary', ...props }, ref) => {
+ *     // Runtime check: ensure accessible name is provided
+ *     if (!props['aria-label'] && !props.children) {
+ *       console.warn('AccessibleButton requires either aria-label or children');
+ *     }
+ *
+ *     return (
+ *       <UI
+ *         as="button"
+ *         ref={ref}
+ *         defaultStyles={{
+ *           padding: '0.5rem 1rem',
+ *           borderRadius: '0.25rem',
+ *           backgroundColor: variant === 'primary' ? '#007bff' : '#6c757d',
+ *         }}
+ *         {...props}
+ *       />
+ *     );
+ *   }
+ * );
+ */
+const UI: UIComponent = React.forwardRef(
   <C extends React.ElementType>(
-    { as, styles, classes, children, defaultStyles, ...props }: FPProps<C>,
+    { as, styles, classes, children, defaultStyles, ...props }: UIProps<C>,
     ref?: PolymorphicRef<C>
   ) => {
     const Component = as ?? "div";
@@ -65,6 +322,5 @@ const FP: FPComponent = React.forwardRef(
   }
 );
 
-export default FP;
-// @ts-expect-error -- React component displayName
-FP.displayName = "FP";
+export default UI;
+UI.displayName = "UI";

package/src/components/word-count/README.md

@@ -0,0 +1,240 @@
+# WordCount Component
+
+A React component that displays word count, character count, and reading time estimates for text content. Built with TypeScript and follows WCAG 2.1 accessibility guidelines.
+
+## Features
+
+- 📊 **Word Count**: Accurate word counting with proper handling of whitespace
+- 🔢 **Character Count**: Optional character counting functionality  
+- ⏱️ **Reading Time**: Estimated reading time based on average reading speed
+- ♿ **Accessible**: Full WCAG 2.1 compliance with proper ARIA labels
+- 🎨 **Customizable**: Custom labels and styling options
+- 📱 **Responsive**: Works across all device sizes
+- 🎯 **Type Safe**: Full TypeScript support
+
+## Installation
+
+The WordCount component is part of the FPKit component library:
+
+```bash
+npm install @fpkit/acss
+```
+
+## Basic Usage
+
+```tsx
+import { WordCount } from '@fpkit/acss'
+
+function MyComponent() {
+  const text = "Hello world, this is a sample text for word counting."
+  
+  return <WordCount text={text} />
+}
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `text` | `string` | **required** | The text content to analyze |
+| `showCharacterCount` | `boolean` | `false` | Whether to display character count |
+| `showReadingTime` | `boolean` | `false` | Whether to display estimated reading time |
+| `wordLabel` | `string` | `"Words"` | Custom label for word count |
+| `characterLabel` | `string` | `"Characters"` | Custom label for character count |
+| `readingTimeLabel` | `string` | `"Reading time"` | Custom label for reading time |
+| `className` | `string` | `""` | Additional CSS classes |
+
+## Examples
+
+### Basic Word Count
+
+```tsx
+<WordCount text="Hello world, this is a test." />
+// Output: "7 Words"
+```
+
+### With Character Count
+
+```tsx
+<WordCount 
+  text="Hello world, this is a test."
+  showCharacterCount={true}
+/>
+// Output: "7 Words • 28 Characters"
+```
+
+### With Reading Time
+
+```tsx
+<WordCount 
+  text="Your long article content here..."
+  showReadingTime={true}
+/>
+// Output: "250 Words • 2 min Reading time"
+```
+
+### All Features Enabled
+
+```tsx
+<WordCount 
+  text="Your content here..."
+  showCharacterCount={true}
+  showReadingTime={true}
+/>
+// Output: "250 Words • 1,234 Characters • 2 min Reading time"
+```
+
+### Custom Labels
+
+```tsx
+<WordCount 
+  text="Your content here..."
+  wordLabel="Terms"
+  characterLabel="Chars"
+  readingTimeLabel="Est. read time"
+  showCharacterCount={true}
+  showReadingTime={true}
+/>
+// Output: "250 Terms • 1,234 Chars • 2 min Est. read time"
+```
+
+### Interactive Example
+
+```tsx
+function InteractiveWordCount() {
+  const [text, setText] = useState('')
+  
+  return (
+    <div>
+      <textarea 
+        value={text}
+        onChange={(e) => setText(e.target.value)}
+        placeholder="Type your text here..."
+      />
+      <WordCount 
+        text={text}
+        showCharacterCount={true}
+        showReadingTime={true}
+      />
+    </div>
+  )
+}
+```
+
+## Accessibility Features
+
+The WordCount component is built with accessibility in mind:
+
+- **ARIA Labels**: Proper `aria-label` attributes for screen readers
+- **Live Regions**: Uses `aria-live="polite"` for dynamic updates
+- **Role Attributes**: Proper `role="status"` for status information
+- **Semantic HTML**: Uses semantic HTML elements for better structure
+- **High Contrast**: Supports high contrast mode
+- **Keyboard Navigation**: Fully keyboard accessible
+
+## Styling
+
+The component comes with built-in CSS classes for styling:
+
+- `.word-count` - Main container
+- `.word-count__stat` - Individual stat container
+- `.word-count__label` - Label text
+- `.word-count__separator` - Separator between stats
+
+### CSS Custom Properties
+
+The component supports CSS custom properties for theming:
+
+```css
+.word-count {
+  --text-primary: #111827;
+  --text-secondary: #6b7280;
+  --text-tertiary: #9ca3af;
+  --focus-ring: #3b82f6;
+}
+```
+
+### Size Modifiers
+
+```css
+.word-count--small { /* Smaller text size */ }
+.word-count--large { /* Larger text size */ }
+.word-count--block { /* Vertical layout */ }
+.word-count--status { /* Status indicator styling */ }
+```
+
+## Algorithm Details
+
+### Word Counting
+
+- Splits text on whitespace using regex `/\s+/`
+- Filters out empty strings
+- Handles multiple spaces, tabs, and line breaks correctly
+
+### Reading Time Calculation
+
+- Based on average reading speed of 200 words per minute
+- Uses `Math.ceil()` to round up to nearest minute
+- Only shows for text with > 0 words
+
+### Character Counting
+
+- Uses `string.length` property
+- Includes all characters (spaces, punctuation, etc.)
+
+## Browser Support
+
+The WordCount component supports all modern browsers:
+
+- Chrome 60+
+- Firefox 60+
+- Safari 12+
+- Edge 79+
+
+## Performance
+
+- Uses `React.useMemo()` for efficient re-computation
+- Only recalculates when text content changes
+- Minimal DOM manipulation for optimal performance
+
+## TypeScript Support
+
+Full TypeScript support with exported types:
+
+```tsx
+import { WordCount, type WordCountProps } from '@fpkit/acss'
+
+const props: WordCountProps = {
+  text: "Sample text",
+  showCharacterCount: true,
+  showReadingTime: true
+}
+```
+
+## Testing
+
+The component includes comprehensive unit tests covering:
+
+- Basic functionality
+- Edge cases (empty text, whitespace)
+- Accessibility features
+- Custom props
+- Error handling
+
+Run tests with:
+
+```bash
+npm test word-count
+```
+
+## Contributing
+
+1. Fork the repository
+2. Create your feature branch (`git checkout -b feature/amazing-feature`)
+3. Commit your changes (`git commit -m 'feat: add amazing feature'`)
+4. Push to the branch (`git push origin feature/amazing-feature`)
+5. Open a Pull Request
+
+## License
+
+This component is part of the FPKit library and follows the same licensing terms.