@fpkit/acss 0.5.12 → 0.6.0

package/libs/list.types-d26de310.d.ts

@@ -0,0 +1,245 @@
+import React from 'react';
+import { U as UI } from './ui-d01b50d4.js';
+
+/**
+ * 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>
+ * ```
+ */
+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>
+ * ```
+ */
+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>>;
+
+export { ListItemProps as L, ListProps as a };

package/libs/ui-d01b50d4.d.ts

@@ -0,0 +1,289 @@
+import React from 'react';
+
+/**
+ * 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> | React.ForwardedRef<React.ElementRef<C>>;
+};
+/**
+ * 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;
+}>;
+/**
+ * UI Component function signature.
+ *
+ * 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 (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 UIComponent = (<C extends React.ElementType = "div">(props: UIProps<C>) => React.ReactElement | any) & {
+    displayName?: string;
+};
+/**
+ * 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}
+ *       />
+ *     );
+ *   }
+ * );
+ */
+declare const UI: UIComponent;
+
+export { UI as U };

package/package.json

@@ -2,16 +2,15 @@
   "name": "@fpkit/acss",
   "description": "A lightweight React UI library for building modern and accessible components that leverage CSS custom properties for reactive Styles.",
   "private": false,
-  "version": "0.5.12",
+  "version": "0.6.0",
   "engines": {
-    "node": ">=20.9.0",
+    "node": ">=22.12.0",
     "npm": ">=8.0.0"
   },
   "scripts": {
     "start": "run-p package:watch sass:watch",
     "dev": "vite --open",
     "build": "run-s package sass build:sass build:css",
-    "build:components": "tsup --config tsup.components.config.cjs",
     "package": "tsc && tsup --dts",
     "package:watch": "tsc && tsup --watch --dts",
     "build::css": "postcss ./libs/components/**/*.css --base libs/components/  --use autoprefixer -d ./libs/components/ --ext min.css",
@@ -25,7 +24,6 @@
     "test:coverage": "vitest --coverage",
     "test:ui:coverage": "vitest --coverage --ui",
     "test:snapshot": "vitest --run --update",
-    "release": "npm publish",
     "lint": "eslint . --ext .jsx,.tsx",
     "lint-fix": "eslint . --ext .jsx,.tsx"
   },
@@ -82,86 +80,6 @@
       "require": "./libs/index.cjs",
       "default": "./libs/index.js"
     },
-    "./button": {
-      "import": "./libs/components/button.js",
-      "require": "./libs/components/button.cjs",
-      "default": "./libs/components/button.js"
-    },
-    "./card": {
-      "import": "./libs/components/card.js",
-      "require": "./libs/components/card.cjs",
-      "default": "./libs/components/card.js"
-    },
-    "./modal": {
-      "import": "./libs/components/modal.js",
-      "require": "./libs/components/modal.cjs",
-      "default": "./libs/components/modal.js"
-    },
-    "./input": {
-      "import": "./libs/components/input.js",
-      "require": "./libs/components/input.cjs",
-      "default": "./libs/components/input.js"
-    },
-    "./link": {
-      "import": "./libs/components/link.js",
-      "require": "./libs/components/link.cjs",
-      "default": "./libs/components/link.js"
-    },
-    "./list": {
-      "import": "./libs/components/list.js",
-      "require": "./libs/components/list.cjs",
-      "default": "./libs/components/list.js"
-    },
-    "./icon": {
-      "import": "./libs/components/icon.js",
-      "require": "./libs/components/icon.cjs",
-      "default": "./libs/components/icon.js"
-    },
-    "./table": {
-      "import": "./libs/components/table.js",
-      "require": "./libs/components/table.cjs",
-      "default": "./libs/components/table.js"
-    },
-    "./dialog": {
-      "import": "./libs/components/dialog.js",
-      "require": "./libs/components/dialog.cjs",
-      "default": "./libs/components/dialog.js"
-    },
-    "./nav": {
-      "import": "./libs/components/nav.js",
-      "require": "./libs/components/nav.cjs",
-      "default": "./libs/components/nav.js"
-    },
-    "./popover": {
-      "import": "./libs/components/popover.js",
-      "require": "./libs/components/popover.cjs",
-      "default": "./libs/components/popover.js"
-    },
-    "./text": {
-      "import": "./libs/components/text.js",
-      "require": "./libs/components/text.cjs",
-      "default": "./libs/components/text.js"
-    },
-    "./heading": {
-      "import": "./libs/components/heading.js",
-      "require": "./libs/components/heading.cjs",
-      "default": "./libs/components/heading.js"
-    },
-    "./breadcrumb": {
-      "import": "./libs/components/breadcrumb.js",
-      "require": "./libs/components/breadcrumb.cjs",
-      "default": "./libs/components/breadcrumb.js"
-    },
-    "./textarea": {
-      "import": "./libs/components/textarea.js",
-      "require": "./libs/components/textarea.cjs",
-      "default": "./libs/components/textarea.js"
-    },
-    "./field": {
-      "import": "./libs/components/field.js",
-      "require": "./libs/components/field.cjs",
-      "default": "./libs/components/field.js"
-    },
     "./hooks": {
       "import": "./libs/hooks.js",
       "require": "./libs/hooks.cjs",
@@ -175,7 +93,7 @@
     "./package.json": "./package.json",
     "./styles": {
       "import": "./libs/index.css",
-      "require": "./libs/index.ccs",
+      "require": "./libs/index.css",
       "default": "./libs/index.css"
     },
     "./css": "./libs/components",
@@ -183,7 +101,6 @@
   },
   "files": [
     "src",
-    "dist",
     "libs",
     "libs/index.css"
   ],
@@ -208,5 +125,5 @@
   "publishConfig": {
     "access": "public"
   },
-  "gitHead": "d43bc984c7cb56b3b37ebb85f71d92b06a1a654f"
+  "gitHead": "9c4bba23e1f85ae1ec81a63ec9488a5e36ff5c5b"
 }