@fpkit/acss 0.5.13 → 0.6.0

package/src/components/list/list.tsx

@@ -1,60 +1,148 @@
-import * as React from 'react'
-import UI from '../ui'
+import UI from "#components/ui";
+import React from "react";
+import type { ListProps, ListItemProps } from "./list.types";
 
-type ListProps = {
-  /** Type of list to render (default: 'ul') */
-  type?: 'ul' | 'ol' | 'dl'
-  /** variant of list to render (default: 'none') */
-  variant?: string
-} & React.ComponentProps<typeof UI>
-
-export type ListItemProps = {
-  /** Type of list item to render (default: 'li') */
-  type?: 'li' | 'dt' | 'dd'
-} & React.ComponentProps<typeof UI>
+// Re-export types for external use
+export type { ListProps, ListItemProps };
 
 /**
- * ListItem component
- * @param type - HTML tag type for the list item (default: 'li')
- * @param styles - CSS styles object
- * @param children - Child elements to be rendered inside the list item
- * @param props - Additional props to be passed to the underlying HTML element
- * @returns A React component that renders a list item
+ * ListItem - A flexible list item component for ul, ol, and dl lists.
+ *
+ * This component renders different HTML elements (li, dt, dd) based on the parent
+ * list type, maintaining semantic HTML and accessibility best practices.
+ *
+ * ## Key Features:
+ * - **Semantic HTML**: Renders appropriate element type (li, dt, dd)
+ * - **Type-Safe**: Full TypeScript support with comprehensive props
+ * - **Ref Forwarding**: Enables direct DOM access for focus management
+ * - **Customizable**: Supports custom styles and CSS classes
+ *
+ * ## Accessibility:
+ * - ✅ Uses semantic HTML elements
+ * - ✅ Works with screen readers out of the box
+ * - ✅ Supports all native HTML attributes
+ * - ✅ Ref forwarding for programmatic focus
+ *
+ * @example
+ * ```tsx
+ * // Standard list item
+ * <ListItem>Item content</ListItem>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Definition term
+ * <ListItem type="dt">Term to define</ListItem>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Definition description
+ * <ListItem type="dd">The definition text</ListItem>
+ * ```
+ *
+ * @param {ListItemProps} props - Component props
+ * @param {React.Ref} ref - Forwarded ref for DOM access
+ * @returns {React.ReactElement} A list item element
  */
-export const ListItem = ({
-  type = 'li',
-  id,
-  styles,
-  children,
-  classes,
-  ...props
-}: ListItemProps) => {
+export const ListItem = React.forwardRef<
+  HTMLLIElement | HTMLElement,
+  ListItemProps
+>(({ type = "li", id, styles, children, classes, ...props }, ref) => {
   return (
-    <UI id={id} as={type} className={classes} {...props} style={styles}>
+    <UI
+      id={id}
+      as={type}
+      className={classes}
+      style={styles}
+      ref={ref}
+      {...props}
+    >
       {children}
     </UI>
-  )
-}
+  );
+});
+
+ListItem.displayName = "ListItem";
 
 /**
- * List component renders a list element with provided props
- * @param children - Child elements to render inside the list
- * @param classes - CSS classes to apply
- * @param type - Type of list element (default: 'ul')
- * @param variant - Variant for styling purposes
- * @param styles - Inline styles object
- * @param role - ARIA role
- * @param props - Additional props to pass to underlying element
+ * List - A flexible, accessible list component for creating ul, ol, and dl lists.
+ *
+ * This component provides a type-safe, accessible way to create different types of lists
+ * with built-in support for custom styling, variants, and WCAG 2.1 AA compliance.
+ *
+ * ## Key Features:
+ * - **Multiple List Types**: Supports ul (unordered), ol (ordered), and dl (definition) lists
+ * - **Semantic HTML**: Uses native HTML list elements for proper accessibility
+ * - **Customizable Styling**: CSS custom properties and variant support
+ * - **Type-Safe**: Comprehensive TypeScript types with JSDoc
+ * - **Ref Forwarding**: Direct DOM access for scroll positioning and focus management
+ * - **WCAG 2.1 AA**: Meets accessibility standards with proper semantic structure
+ *
+ * ## Accessibility:
+ * - ✅ WCAG 2.1 AA compliant using semantic HTML
+ * - ✅ Screen reader compatible (announced as "list" with item count)
+ * - ✅ Supports role="list" override for styled lists (Safari/VoiceOver compatibility)
+ * - ✅ Keyboard navigation works naturally with focusable children
+ * - ✅ Ref forwarding for programmatic focus management
+ *
+ * ## Common Use Cases:
+ * - **Navigation menus** - Use ul with variant="inline" or "none"
+ * - **Sequential steps** - Use ol for numbered instructions
+ * - **Glossaries** - Use dl for term-definition pairs
+ * - **Feature lists** - Use ul for product features
+ *
+ * @example
+ * ```tsx
+ * // Basic unordered list
+ * <List>
+ *   <List.ListItem>First item</List.ListItem>
+ *   <List.ListItem>Second item</List.ListItem>
+ * </List>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Ordered list with custom styling
+ * <List
+ *   type="ol"
+ *   variant="numbered"
+ *   styles={{ '--list-marker-color': '#0066cc' }}
+ * >
+ *   <List.ListItem>Step one</List.ListItem>
+ *   <List.ListItem>Step two</List.ListItem>
+ * </List>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Unstyled list with role restoration for accessibility
+ * // IMPORTANT: Use role="list" when removing list styling
+ * <List variant="none" role="list">
+ *   <List.ListItem>Navigation link</List.ListItem>
+ *   <List.ListItem>Another link</List.ListItem>
+ * </List>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Definition list
+ * <List type="dl">
+ *   <List.ListItem type="dt">React</List.ListItem>
+ *   <List.ListItem type="dd">A JavaScript library for building UIs</List.ListItem>
+ *   <List.ListItem type="dt">TypeScript</List.ListItem>
+ *   <List.ListItem type="dd">JavaScript with syntax for types</List.ListItem>
+ * </List>
+ * ```
+ *
+ * @param {ListProps} props - Component props
+ * @param {React.Ref} ref - Forwarded ref for DOM access
+ * @returns {React.ReactElement} A list element (ul, ol, or dl)
  */
-export const List = ({
-  children,
-  classes,
-  type = 'ul',
-  variant,
-  styles,
-  role,
-  ...props
-}: ListProps) => {
+export const List = React.forwardRef<
+  HTMLUListElement | HTMLOListElement | HTMLDListElement,
+  ListProps
+>(({ children, classes, type = "ul", variant, styles, role, ...props }, ref) => {
   return (
     <UI
       as={type}
@@ -62,13 +150,27 @@ export const List = ({
       className={classes}
       style={styles}
       role={role}
+      ref={ref}
       {...props}
     >
       {children}
     </UI>
-  )
+  );
+});
+
+List.displayName = "List";
+
+// Compound component pattern - attach ListItem to List with proper typing
+export interface ListComponent
+  extends React.ForwardRefExoticComponent<
+    ListProps & React.RefAttributes<HTMLUListElement | HTMLOListElement | HTMLDListElement>
+  > {
+  ListItem: typeof ListItem;
 }
 
-export default List
-List.displayName = 'List'
-List.ListItem = ListItem
+// Attach ListItem to List using Object.assign for better type inference
+const ListWithItem = Object.assign(List, {
+  ListItem,
+});
+
+export default ListWithItem as ListComponent;

package/src/components/list/list.types.ts

@@ -0,0 +1,255 @@
+import React from "react";
+import UI from "#components/ui";
+
+/**
+ * Props for the List component.
+ *
+ * Combines native HTML list element props with custom styling and accessibility features.
+ * The List component provides a flexible, type-safe way to create ordered, unordered,
+ * and definition lists with built-in accessibility support and customizable styling.
+ *
+ * @example
+ * ```tsx
+ * // Unordered list (default)
+ * <List>
+ *   <List.ListItem>Item 1</List.ListItem>
+ *   <List.ListItem>Item 2</List.ListItem>
+ * </List>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Ordered list with custom styling
+ * <List
+ *   type="ol"
+ *   variant="numbered"
+ *   styles={{ '--list-marker-color': 'blue' }}
+ * >
+ *   <List.ListItem>First step</List.ListItem>
+ *   <List.ListItem>Second step</List.ListItem>
+ * </List>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Definition list
+ * <List type="dl">
+ *   <List.ListItem type="dt">Term</List.ListItem>
+ *   <List.ListItem type="dd">Definition</List.ListItem>
+ * </List>
+ * ```
+ */
+export type ListProps = {
+  /**
+   * Type of list element to render.
+   *
+   * - `'ul'` - Unordered list (default) - Use for items where order doesn't matter
+   * - `'ol'` - Ordered list - Use for sequential steps or ranked items
+   * - `'dl'` - Definition list - Use for term-definition pairs
+   *
+   * @default 'ul'
+   * @example
+   * ```tsx
+   * type="ol" // Renders an ordered list with numbers
+   * type="dl" // Renders a definition list
+   * ```
+   */
+  type?: "ul" | "ol" | "dl";
+
+  /**
+   * Variant for custom styling through CSS.
+   * Applied as `data-variant` attribute for CSS targeting.
+   *
+   * Common variants might include:
+   * - `'inline'` - Display items horizontally
+   * - `'none'` - Remove list markers
+   * - `'custom'` - Custom marker styling
+   *
+   * @optional
+   * @example
+   * ```tsx
+   * variant="inline" // Horizontal list for navigation
+   * variant="none"   // Clean list without bullets
+   * ```
+   */
+  variant?: string;
+
+  /**
+   * ARIA role override.
+   *
+   * Note: Only override the default role when necessary for accessibility.
+   * Native list elements have semantic meaning that should be preserved.
+   *
+   * Use `role="list"` when CSS `list-style: none` is applied, as some screen
+   * readers remove list semantics when list styling is removed.
+   *
+   * @optional
+   * @see {@link https://www.scottohara.me/blog/2019/01/12/lists-and-safari.html}
+   * @example
+   * ```tsx
+   * // Restore list semantics when using list-style: none
+   * <List variant="none" role="list">
+   *   <List.ListItem>Navigation item</List.ListItem>
+   * </List>
+   * ```
+   */
+  role?: string;
+
+  /**
+   * Inline CSS styles to apply to the list element.
+   * Can include CSS custom properties for theming.
+   *
+   * @optional
+   * @example
+   * ```tsx
+   * styles={{
+   *   '--list-gap': '1rem',
+   *   '--list-marker-color': '#0066cc'
+   * }}
+   * ```
+   */
+  styles?: React.CSSProperties;
+
+  /**
+   * CSS class names to apply to the list element.
+   *
+   * @optional
+   * @example
+   * ```tsx
+   * classes="navigation-list"
+   * ```
+   */
+  classes?: string;
+
+  /**
+   * HTML id attribute for the list element.
+   *
+   * @optional
+   * @example
+   * ```tsx
+   * id="main-navigation"
+   * ```
+   */
+  id?: string;
+
+  /**
+   * Accessible label for screen readers.
+   *
+   * Use when the list's purpose isn't clear from context or when
+   * multiple lists exist on the page.
+   *
+   * @optional
+   * @example
+   * ```tsx
+   * aria-label="Product features"
+   * aria-labelledby="features-heading"
+   * ```
+   */
+  "aria-label"?: string;
+  "aria-labelledby"?: string;
+
+  /**
+   * Child elements (typically ListItem components).
+   *
+   * @required
+   * @example
+   * ```tsx
+   * <List>
+   *   <List.ListItem>Item 1</List.ListItem>
+   *   <List.ListItem>Item 2</List.ListItem>
+   * </List>
+   * ```
+   */
+  children: React.ReactNode;
+} & Partial<React.ComponentProps<typeof UI>>;
+
+/**
+ * Props for the ListItem component.
+ *
+ * Provides a flexible list item that can render as different HTML elements
+ * depending on the parent list type (li, dt, dd).
+ *
+ * @example
+ * ```tsx
+ * // Standard list item (li) - default
+ * <ListItem>Regular item</ListItem>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Definition term (dt)
+ * <ListItem type="dt">Term to define</ListItem>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Definition description (dd)
+ * <ListItem type="dd">The definition</ListItem>
+ * ```
+ */
+export type ListItemProps = {
+  /**
+   * Type of list item element to render.
+   *
+   * - `'li'` - Standard list item (default) - For ul and ol
+   * - `'dt'` - Definition term - For dl (term being defined)
+   * - `'dd'` - Definition description - For dl (the definition itself)
+   *
+   * @default 'li'
+   * @example
+   * ```tsx
+   * // In a definition list
+   * <List type="dl">
+   *   <ListItem type="dt">React</ListItem>
+   *   <ListItem type="dd">A JavaScript library for building user interfaces</ListItem>
+   * </List>
+   * ```
+   */
+  type?: "li" | "dt" | "dd";
+
+  /**
+   * HTML id attribute for the list item.
+   *
+   * @optional
+   * @example
+   * ```tsx
+   * id="feature-1"
+   * ```
+   */
+  id?: string;
+
+  /**
+   * Inline CSS styles to apply to the list item.
+   *
+   * @optional
+   * @example
+   * ```tsx
+   * styles={{ paddingLeft: '1rem' }}
+   * ```
+   */
+  styles?: React.CSSProperties;
+
+  /**
+   * CSS class names to apply to the list item.
+   *
+   * @optional
+   * @example
+   * ```tsx
+   * classes="list-item-active"
+   * ```
+   */
+  classes?: string;
+
+  /**
+   * Child elements to render inside the list item.
+   *
+   * @required
+   * @example
+   * ```tsx
+   * <ListItem>
+   *   <strong>Bold text</strong> and regular text
+   * </ListItem>
+   * ```
+   */
+  children: React.ReactNode;
+} & Partial<React.ComponentProps<typeof UI>>;