@fpkit/acss 0.5.12 → 0.6.0

package/libs/components/icons/icon.d.cts

@@ -1,29 +1,158 @@
-import { C as ComponentProps } from '../../component-props-a8a2f97e.js';
-import React__default from 'react';
-import { F as FP } from '../../ui-9a6f9f8d.js';
+import { C as ComponentProps } from '../../component-props-67d978a2.js';
+import React from 'react';
+import { U as UI } from '../../ui-d01b50d4.js';
 
+/**
+ * Props for individual icon SVG components (e.g., Icon.Code, Icon.Home).
+ *
+ * These props control the visual presentation of SVG icons. Icon components
+ * are decorative by default and should be wrapped in the `Icon` container
+ * component which handles accessibility concerns.
+ *
+ * @property {string} [fill] - SVG fill color (CSS color value)
+ * @property {number} [size] - Icon size in pixels (sets both width and height)
+ * @property {string} [strokeColor] - SVG stroke color (CSS color value)
+ * @property {string} [strokeWidth] - SVG stroke width (e.g., '2px', '1.5')
+ * @property {string} [role] - ARIA role (use 'img' for semantic icons)
+ * @property {string} [aria-label] - Accessible label for standalone icons
+ * @property {boolean} [aria-hidden] - Hide from screen readers (default: true via Icon wrapper)
+ * @property {string} [alt] - @deprecated Use aria-label instead. Legacy prop for accessible label.
+ * @property {number} [width] - Explicit width in pixels (overrides size)
+ * @property {number} [height] - Explicit height in pixels (overrides size)
+ *
+ * @example
+ * ```tsx
+ * // Decorative icon with custom styling
+ * <Icon>
+ *   <Icon.Code size={24} fill="blue" />
+ *   View Code
+ * </Icon>
+ *
+ * // Standalone semantic icon
+ * <Icon aria-hidden={false} aria-label="Code snippet">
+ *   <Icon.Code size={20} />
+ * </Icon>
+ * ```
+ */
 interface IconProps$1 extends Partial<ComponentProps> {
+    /** SVG fill color */
     fill?: string;
+    /** Icon size in pixels (sets both width and height) */
     size?: number;
+    /** SVG stroke color */
     strokeColor?: string;
+    /** SVG stroke width */
     strokeWidth?: string;
+    /** ARIA role (use 'img' for semantic icons) */
     role?: string;
+    /** Accessible label (required for standalone icons) */
+    'aria-label'?: string;
+    /** Hide from screen readers (default: true) */
+    'aria-hidden'?: boolean;
+    /**
+     * @deprecated Use aria-label instead. This prop exists for backward compatibility.
+     * The alt attribute is only valid for img elements, not SVG.
+     */
     alt?: string;
+    /** Explicit width in pixels */
     width?: number;
+    /** Explicit height in pixels */
     height?: number;
 }
 
-declare function Star({ size, fill, strokeColor, styles, role, alt, ...props }: Pick<IconProps$1, 'strokeColor' | 'fill' | 'styles' | 'size' | 'role' | 'alt'>): React__default.JSX.Element;
+declare function Star({ size, fill, strokeColor, styles, role, alt, ...props }: Pick<IconProps$1, 'strokeColor' | 'fill' | 'styles' | 'size' | 'role' | 'alt'>): React.JSX.Element;
 declare namespace Star {
     var displayName: string;
 }
 
-type IconProps = React__default.ComponentProps<typeof FP>;
+type IconProps = React.ComponentProps<typeof UI> & {
+    /**
+     * Controls screen reader visibility.
+     * - `true` (default): Hides icon from screen readers (decorative icon)
+     * - `false`: Makes icon visible to screen readers (semantic icon)
+     *
+     * **When to use decorative (aria-hidden="true", default):**
+     * - Icon accompanies visible text (e.g., button with icon + label)
+     * - Icon is purely visual decoration
+     *
+     * **When to use semantic (aria-hidden="false"):**
+     * - Icon is the only content (e.g., icon-only button)
+     * - Must provide `aria-label` or `aria-labelledby` for accessible name
+     *
+     * @default true
+     * @see https://www.w3.org/WAI/WCAG21/Understanding/non-text-content.html
+     */
+    "aria-hidden"?: boolean;
+    /**
+     * Accessible label for semantic icons.
+     * Required when icon is standalone (not accompanied by visible text).
+     *
+     * @example
+     * ```tsx
+     * // ✅ GOOD: Icon-only button with accessible name
+     * <button>
+     *   <Icon aria-hidden={false} aria-label="Close dialog">
+     *     <Icon.Remove />
+     *   </Icon>
+     * </button>
+     *
+     * // ✅ GOOD: Icon with visible text (default decorative)
+     * <button>
+     *   <Icon><Icon.Add /></Icon>
+     *   Add Item
+     * </button>
+     * ```
+     */
+    "aria-label"?: string;
+    /**
+     * Semantic role override.
+     * Use `role="img"` when icon conveys meaning and is not decorative.
+     *
+     * @default undefined (no role for decorative icons)
+     */
+    role?: string;
+};
+/**
+ * Icon wrapper component that enforces accessibility best practices.
+ *
+ * **Default behavior (decorative icon):**
+ * - Hidden from screen readers (`aria-hidden="true"`)
+ * - Used when icon accompanies visible text
+ *
+ * **Semantic icon pattern:**
+ * - Set `aria-hidden={false}` to expose to screen readers
+ * - Must provide `aria-label` for accessible name
+ * - Consider `role="img"` for complex SVG icons
+ *
+ * @param {IconProps} props - Component props
+ * @returns {React.ReactElement} Accessible icon wrapper
+ *
+ * @example
+ * // ✅ Decorative icon with text (default)
+ * <button>
+ *   <Icon><Icon.Save /></Icon>
+ *   Save Changes
+ * </button>
+ *
+ * @example
+ * // ✅ Semantic icon-only button
+ * <button aria-label="Close dialog">
+ *   <Icon aria-hidden={false}>
+ *     <Icon.Remove />
+ *   </Icon>
+ * </button>
+ *
+ * @example
+ * // ❌ BAD: Icon-only button without accessible name
+ * <button>
+ *   <Icon><Icon.Remove /></Icon>
+ * </button>
+ */
 declare const Icon: {
-    ({ id, classes, children, styles, ...props }: IconProps): React__default.JSX.Element;
+    ({ id, classes, children, styles, "aria-hidden": ariaHidden, "aria-label": ariaLabel, role, ...props }: IconProps): React.JSX.Element;
     displayName: string;
     Add: {
-        ({ fill, size, role, alt, ...props }: Pick<IconProps$1, "role" | "fill" | "alt" | "size" | "styles" | "strokeColor">): JSX.Element;
+        ({ fill, size, role, alt, ...props }: Pick<IconProps$1, "styles" | "role" | "fill" | "alt" | "size" | "strokeColor">): JSX.Element;
         styles: {
             fill: string;
             display: string;
@@ -33,7 +162,7 @@ declare const Icon: {
         displayName: string;
     };
     ArrowDown: {
-        ({ fill, styles, size, role, alt, ...props }: Pick<IconProps$1, "role" | "fill" | "alt" | "size" | "styles">): React__default.JSX.Element;
+        ({ fill, styles, size, role, alt, ...props }: Pick<IconProps$1, "styles" | "role" | "fill" | "alt" | "size">): React.JSX.Element;
         styles: {
             display: string;
             alignItems: string;
@@ -42,7 +171,7 @@ declare const Icon: {
         displayName: string;
     };
     ArrowLeft: {
-        ({ strokeColor, fill, size, styles, role, alt, ...props }: Pick<IconProps$1, "role" | "fill" | "alt" | "size" | "styles" | "strokeColor">): React__default.JSX.Element;
+        ({ strokeColor, fill, size, styles, role, alt, ...props }: Pick<IconProps$1, "styles" | "role" | "fill" | "alt" | "size" | "strokeColor">): React.JSX.Element;
         styles: {
             display: string;
             alignItems: string;
@@ -51,11 +180,11 @@ declare const Icon: {
         displayName: string;
     };
     ArrowRight: {
-        ({ size, fill, strokeColor, styles, role, alt, ...props }: Pick<IconProps$1, "role" | "fill" | "alt" | "size" | "styles" | "strokeColor">): React__default.JSX.Element;
+        ({ size, fill, strokeColor, styles, role, alt, ...props }: Pick<IconProps$1, "styles" | "role" | "fill" | "alt" | "size" | "strokeColor">): React.JSX.Element;
         displayName: string;
     };
     ArrowUp: {
-        ({ strokeColor, styles, size, role, alt, ...props }: Pick<IconProps$1, "role" | "fill" | "alt" | "size" | "styles" | "strokeColor">): React__default.JSX.Element;
+        ({ strokeColor, styles, size, role, alt, ...props }: Pick<IconProps$1, "styles" | "role" | "fill" | "alt" | "size" | "strokeColor">): React.JSX.Element;
         displayName: string;
         style: {
             fill: string;
@@ -66,7 +195,7 @@ declare const Icon: {
         };
     };
     Chat: {
-        ({ size, strokeColor, styles, role, alt, ...props }: Pick<IconProps$1, "role" | "fill" | "alt" | "size" | "styles" | "strokeColor">): JSX.Element;
+        ({ size, strokeColor, styles, role, alt, ...props }: Pick<IconProps$1, "styles" | "role" | "fill" | "alt" | "size" | "strokeColor">): JSX.Element;
         styles: {
             display: string;
             alignItems: string;
@@ -75,7 +204,7 @@ declare const Icon: {
         displayName: string;
     };
     Code: {
-        ({ strokeColor, fill, size, styles, role, alt, ...props }?: Pick<IconProps$1, "role" | "fill" | "alt" | "size" | "styles" | "strokeColor">): React__default.JSX.Element;
+        ({ strokeColor, fill, size, styles, role, alt, ...props }?: Pick<IconProps$1, "styles" | "role" | "fill" | "alt" | "size" | "strokeColor">): React.JSX.Element;
         styles: {
             fill: string;
             stroke: string;
@@ -85,7 +214,7 @@ declare const Icon: {
         };
     };
     Copy: {
-        ({ size, strokeColor, styles, role, alt, ...props }: Pick<IconProps$1, "role" | "fill" | "alt" | "size" | "styles" | "strokeColor">): JSX.Element;
+        ({ size, strokeColor, styles, role, alt, ...props }: Pick<IconProps$1, "styles" | "role" | "fill" | "alt" | "size" | "strokeColor">): JSX.Element;
         displayName: string;
         styles: {
             stroke: string;
@@ -95,7 +224,7 @@ declare const Icon: {
         };
     };
     Down: {
-        ({ size, fill, styles, role, alt, ...props }: Pick<IconProps$1, "role" | "fill" | "alt" | "size" | "styles" | "strokeColor">): React__default.JSX.Element;
+        ({ size, fill, styles, role, alt, ...props }: Pick<IconProps$1, "styles" | "role" | "fill" | "alt" | "size" | "strokeColor">): React.JSX.Element;
         displayName: string;
         styles: {
             display: string;
@@ -104,7 +233,7 @@ declare const Icon: {
         };
     };
     Home: {
-        ({ strokeColor, fill, size, styles, role, alt, ...props }: Pick<IconProps$1, "role" | "fill" | "alt" | "size" | "styles" | "strokeColor">): React__default.JSX.Element;
+        ({ strokeColor, fill, size, styles, role, alt, ...props }: Pick<IconProps$1, "styles" | "role" | "fill" | "alt" | "size" | "strokeColor">): React.JSX.Element;
         displayName: string;
         styles: {
             fill: string;
@@ -115,19 +244,19 @@ declare const Icon: {
         };
     };
     Info: {
-        ({ fill, size, role, alt, ...props }: Pick<IconProps$1, "role" | "fill" | "alt" | "size" | "styles" | "strokeColor">): JSX.Element;
+        ({ fill, size, role, alt, ...props }: Pick<IconProps$1, "styles" | "role" | "fill" | "alt" | "size" | "strokeColor">): JSX.Element;
         displayName: string;
     };
     InfoSolid: {
-        ({ fill, size, role, alt, ...props }: Pick<IconProps$1, "role" | "fill" | "alt" | "size" | "styles" | "strokeColor">): JSX.Element;
+        ({ fill, size, role, alt, ...props }: Pick<IconProps$1, "styles" | "role" | "fill" | "alt" | "size" | "strokeColor">): JSX.Element;
         displayName: string;
     };
     AlertSolid: {
-        ({ fill, size, role, alt, ...props }: Pick<IconProps$1, "role" | "fill" | "alt" | "size" | "styles" | "strokeColor">): JSX.Element;
+        ({ fill, size, role, alt, ...props }: Pick<IconProps$1, "styles" | "role" | "fill" | "alt" | "size" | "strokeColor">): JSX.Element;
         displayName: string;
     };
     Left: {
-        ({ fill, size, styles, role, alt, ...props }: Pick<IconProps$1, "role" | "fill" | "alt" | "size" | "styles" | "strokeColor">): React__default.JSX.Element;
+        ({ fill, size, styles, role, alt, ...props }: Pick<IconProps$1, "styles" | "role" | "fill" | "alt" | "size" | "strokeColor">): React.JSX.Element;
         displayName: string;
         styles: {
             fill: string;
@@ -137,14 +266,14 @@ declare const Icon: {
         };
     };
     Minus: {
-        ({ size, fill, styles, role, alt, ...props }: Pick<IconProps$1, "role" | "fill" | "alt" | "size" | "styles" | "strokeColor">): React__default.JSX.Element;
+        ({ size, fill, styles, role, alt, ...props }: Pick<IconProps$1, "styles" | "role" | "fill" | "alt" | "size" | "strokeColor">): React.JSX.Element;
         displayName: string;
         styles: {
             fill: string;
         };
     };
     Pause: {
-        ({ strokeColor, styles, size, role, alt, ...props }: Pick<IconProps$1, "role" | "fill" | "alt" | "size" | "styles" | "strokeColor">): React__default.JSX.Element;
+        ({ strokeColor, styles, size, role, alt, ...props }: Pick<IconProps$1, "styles" | "role" | "fill" | "alt" | "size" | "strokeColor">): React.JSX.Element;
         displayName: string;
         style: {
             fill: string;
@@ -155,7 +284,7 @@ declare const Icon: {
         };
     };
     PauseSolid: {
-        ({ strokeColor, styles, size, role, alt, ...props }: Pick<IconProps$1, "role" | "fill" | "alt" | "size" | "styles" | "strokeColor">): React__default.JSX.Element;
+        ({ strokeColor, styles, size, role, alt, ...props }: Pick<IconProps$1, "styles" | "role" | "fill" | "alt" | "size" | "strokeColor">): React.JSX.Element;
         displayName: string;
         style: {
             fill: string;
@@ -166,7 +295,7 @@ declare const Icon: {
         };
     };
     Play: {
-        ({ strokeColor, styles, size, role, alt, ...props }: Pick<IconProps$1, "role" | "fill" | "alt" | "size" | "styles" | "strokeColor">): React__default.JSX.Element;
+        ({ strokeColor, styles, size, role, alt, ...props }: Pick<IconProps$1, "styles" | "role" | "fill" | "alt" | "size" | "strokeColor">): React.JSX.Element;
         displayName: string;
         style: {
             fill: string;
@@ -177,7 +306,7 @@ declare const Icon: {
         };
     };
     PlaySolid: {
-        ({ strokeColor, styles, size, role, alt, ...props }: Pick<IconProps$1, "role" | "fill" | "alt" | "size" | "styles" | "strokeColor">): React__default.JSX.Element;
+        ({ strokeColor, styles, size, role, alt, ...props }: Pick<IconProps$1, "styles" | "role" | "fill" | "alt" | "size" | "strokeColor">): React.JSX.Element;
         displayName: string;
         style: {
             fill: string;
@@ -188,14 +317,14 @@ declare const Icon: {
         };
     };
     Remove: {
-        ({ size, fill, styles, role, alt, ...props }: Pick<IconProps$1, "role" | "fill" | "alt" | "size" | "styles" | "strokeColor">): React__default.JSX.Element;
+        ({ size, fill, styles, role, alt, ...props }: Pick<IconProps$1, "styles" | "role" | "fill" | "alt" | "size" | "strokeColor">): React.JSX.Element;
         displayName: string;
         styles: {
             fill: string;
         };
     };
     Resume: {
-        ({ strokeColor, styles, size, role, alt, ...props }: Pick<IconProps$1, "role" | "fill" | "alt" | "size" | "styles" | "strokeColor">): React__default.JSX.Element;
+        ({ strokeColor, styles, size, role, alt, ...props }: Pick<IconProps$1, "styles" | "role" | "fill" | "alt" | "size" | "strokeColor">): React.JSX.Element;
         displayName: string;
         style: {
             fill: string;
@@ -206,7 +335,7 @@ declare const Icon: {
         };
     };
     ResumeSolid: {
-        ({ strokeColor, styles, size, role, alt, ...props }: Pick<IconProps$1, "role" | "fill" | "alt" | "size" | "styles" | "strokeColor">): React__default.JSX.Element;
+        ({ strokeColor, styles, size, role, alt, ...props }: Pick<IconProps$1, "styles" | "role" | "fill" | "alt" | "size" | "strokeColor">): React.JSX.Element;
         displayName: string;
         style: {
             fill: string;
@@ -217,7 +346,7 @@ declare const Icon: {
         };
     };
     Right: {
-        ({ size, fill, styles, role, alt, ...props }: Pick<IconProps$1, "role" | "fill" | "alt" | "size" | "styles" | "strokeColor">): React__default.JSX.Element;
+        ({ size, fill, styles, role, alt, ...props }: Pick<IconProps$1, "styles" | "role" | "fill" | "alt" | "size" | "strokeColor">): React.JSX.Element;
         displayName: string;
         styles: {
             fill: string;
@@ -225,7 +354,7 @@ declare const Icon: {
     };
     Star: typeof Star;
     Stop: {
-        ({ strokeColor, styles, size, role, alt, ...props }: Pick<IconProps$1, "role" | "fill" | "alt" | "size" | "styles" | "strokeColor">): React__default.JSX.Element;
+        ({ strokeColor, styles, size, role, alt, ...props }: Pick<IconProps$1, "styles" | "role" | "fill" | "alt" | "size" | "strokeColor">): React.JSX.Element;
         displayName: string;
         style: {
             fill: string;
@@ -233,10 +362,25 @@ declare const Icon: {
             display: string;
             alignItems: string;
             width: string;
-        };
+        }; /**
+         * Controls screen reader visibility.
+         * - `true` (default): Hides icon from screen readers (decorative icon)
+         * - `false`: Makes icon visible to screen readers (semantic icon)
+         *
+         * **When to use decorative (aria-hidden="true", default):**
+         * - Icon accompanies visible text (e.g., button with icon + label)
+         * - Icon is purely visual decoration
+         *
+         * **When to use semantic (aria-hidden="false"):**
+         * - Icon is the only content (e.g., icon-only button)
+         * - Must provide `aria-label` or `aria-labelledby` for accessible name
+         *
+         * @default true
+         * @see https://www.w3.org/WAI/WCAG21/Understanding/non-text-content.html
+         */
     };
     StopSolid: {
-        ({ strokeColor, styles, size, role, alt, ...props }: Pick<IconProps$1, "role" | "fill" | "alt" | "size" | "styles" | "strokeColor">): React__default.JSX.Element;
+        ({ strokeColor, styles, size, role, alt, ...props }: Pick<IconProps$1, "styles" | "role" | "fill" | "alt" | "size" | "strokeColor">): React.JSX.Element;
         displayName: string;
         style: {
             fill: string;
@@ -247,7 +391,7 @@ declare const Icon: {
         };
     };
     Up: {
-        ({ size, fill, styles, role, alt, ...props }: Pick<IconProps$1, "role" | "fill" | "alt" | "size" | "styles" | "strokeColor">): React__default.JSX.Element;
+        ({ size, fill, styles, role, alt, ...props }: Pick<IconProps$1, "styles" | "role" | "fill" | "alt" | "size" | "strokeColor">): React.JSX.Element;
         displayName: string;
         styles: {
             display: string;
@@ -256,7 +400,7 @@ declare const Icon: {
         };
     };
     User: {
-        ({ size, fill, strokeColor, styles, alt, role, ...props }: Pick<IconProps$1, "role" | "fill" | "alt" | "size" | "styles" | "strokeColor">): React__default.JSX.Element;
+        ({ size, fill, strokeColor, styles, alt, role, ...props }: Pick<IconProps$1, "styles" | "role" | "fill" | "alt" | "size" | "strokeColor">): React.JSX.Element;
         styles: {
             fill: string;
             stroke: string;
@@ -274,23 +418,23 @@ declare const Icon: {
         width: string;
     };
     QuestionSolid: {
-        ({ fill, size, role, alt, ...props }: Pick<IconProps$1, "role" | "fill" | "alt" | "size" | "styles" | "strokeColor">): JSX.Element;
+        ({ fill, size, role, alt, ...props }: Pick<IconProps$1, "styles" | "role" | "fill" | "alt" | "size" | "strokeColor">): JSX.Element;
         displayName: string;
     };
     WarnSolid: {
-        ({ fill, size, role, alt, ...props }: Pick<IconProps$1, "role" | "fill" | "alt" | "size" | "styles" | "strokeColor">): JSX.Element;
+        ({ fill, size, role, alt, ...props }: Pick<IconProps$1, "styles" | "role" | "fill" | "alt" | "size" | "strokeColor">): JSX.Element;
         displayName: string;
     };
     SuccessSolid: {
-        ({ fill, size, role, alt, ...props }: Pick<IconProps$1, "role" | "fill" | "alt" | "size" | "styles" | "strokeColor">): JSX.Element;
+        ({ fill, size, role, alt, ...props }: Pick<IconProps$1, "styles" | "role" | "fill" | "alt" | "size" | "strokeColor">): JSX.Element;
         displayName: string;
     };
     AlertSquareSolid: {
-        ({ fill, size, role, alt, ...props }: Pick<IconProps$1, "role" | "fill" | "alt" | "size" | "styles" | "strokeColor">): JSX.Element;
+        ({ fill, size, role, alt, ...props }: Pick<IconProps$1, "styles" | "role" | "fill" | "alt" | "size" | "strokeColor">): JSX.Element;
         displayName: string;
     };
     Close: {
-        ({ size, fill, styles, role, alt, ...props }: Pick<IconProps$1, "role" | "fill" | "alt" | "size" | "styles" | "strokeColor">): React__default.JSX.Element;
+        ({ size, fill, styles, role, alt, ...props }: Pick<IconProps$1, "styles" | "role" | "fill" | "alt" | "size" | "strokeColor">): React.JSX.Element;
         displayName: string;
         styles: {
             fill: string;