@fpkit/acss 6.1.0 → 6.3.0

package/src/components/buttons/icon-button.test.tsx

@@ -0,0 +1,132 @@
+import React from "react";
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { vi } from "vitest";
+import { IconButton } from "./icon-button";
+
+const TestIcon = () => <svg data-testid="test-icon" aria-hidden="true" />;
+
+describe("IconButton", () => {
+  it("renders a button element with aria-label", () => {
+    render(<IconButton type="button" aria-label="Close" icon={<TestIcon />} />);
+    const button = screen.getByRole("button", { name: "Close" });
+    expect(button).toBeInTheDocument();
+    expect(button).toHaveAttribute("aria-label", "Close");
+  });
+
+  it("renders a button element with aria-labelledby", () => {
+    render(
+      <>
+        <span id="lbl">Delete item</span>
+        <IconButton type="button" aria-labelledby="lbl" icon={<TestIcon />} />
+      </>
+    );
+    const button = screen.getByRole("button", { name: "Delete item" });
+    expect(button).toBeInTheDocument();
+    expect(button).toHaveAttribute("aria-labelledby", "lbl");
+  });
+
+  it("renders the icon as a child of the button", () => {
+    render(<IconButton type="button" aria-label="Close" icon={<TestIcon />} />);
+    expect(screen.getByTestId("test-icon")).toBeInTheDocument();
+  });
+
+  it("renders label text when label prop is provided", () => {
+    render(
+      <IconButton
+        type="button"
+        aria-label="Settings"
+        icon={<TestIcon />}
+        label="Settings"
+      />
+    );
+    expect(screen.getByText("Settings")).toBeInTheDocument();
+  });
+
+  it("applies data-icon-label attribute to the label span", () => {
+    render(
+      <IconButton
+        type="button"
+        aria-label="Settings"
+        icon={<TestIcon />}
+        label="Settings"
+      />
+    );
+    const labelSpan = screen.getByText("Settings");
+    expect(labelSpan).toHaveAttribute("data-icon-label");
+  });
+
+  it("applies data-icon-btn='has-label' to the button when label is provided", () => {
+    render(
+      <IconButton
+        type="button"
+        aria-label="Settings"
+        icon={<TestIcon />}
+        label="Settings"
+      />
+    );
+    const button = screen.getByRole("button", { name: "Settings" });
+    expect(button).toHaveAttribute("data-icon-btn", "has-label");
+  });
+
+  it("does not render a label span when label prop is omitted", () => {
+    render(<IconButton type="button" aria-label="Close" icon={<TestIcon />} />);
+    expect(document.querySelector("[data-icon-label]")).toBeNull();
+  });
+
+  it("sets data-icon-btn to 'icon' when label is omitted", () => {
+    render(<IconButton type="button" aria-label="Close" icon={<TestIcon />} />);
+    const button = screen.getByRole("button", { name: "Close" });
+    expect(button).toHaveAttribute("data-icon-btn", "icon");
+  });
+
+  it("fires the click handler when clicked", async () => {
+    const handleClick = vi.fn();
+    render(
+      <IconButton
+        type="button"
+        aria-label="Close"
+        icon={<TestIcon />}
+        onClick={handleClick}
+      />
+    );
+    await userEvent.click(screen.getByRole("button", { name: "Close" }));
+    expect(handleClick).toHaveBeenCalledTimes(1);
+  });
+
+  it("does not fire click handler when disabled", async () => {
+    const handleClick = vi.fn();
+    render(
+      <IconButton
+        type="button"
+        aria-label="Close"
+        icon={<TestIcon />}
+        disabled
+        onClick={handleClick}
+      />
+    );
+    const button = screen.getByRole("button", { name: "Close" });
+    expect(button).toHaveAttribute("aria-disabled", "true");
+    await userEvent.click(button);
+    expect(handleClick).toHaveBeenCalledTimes(0);
+  });
+
+  it("defaults variant to 'icon'", () => {
+    render(<IconButton type="button" aria-label="Close" icon={<TestIcon />} />);
+    const button = screen.getByRole("button", { name: "Close" });
+    expect(button).toHaveAttribute("data-style", "icon");
+  });
+
+  it("accepts a variant override", () => {
+    render(
+      <IconButton
+        type="button"
+        aria-label="Settings"
+        icon={<TestIcon />}
+        variant="outline"
+      />
+    );
+    const button = screen.getByRole("button", { name: "Settings" });
+    expect(button).toHaveAttribute("data-style", "outline");
+  });
+});

package/src/components/buttons/icon-button.tsx

@@ -0,0 +1,72 @@
+import React from "react";
+import { Button, type ButtonProps } from "./button";
+
+/**
+ * XOR constraint: exactly one of aria-label or aria-labelledby is required.
+ * Passing both or neither is a TypeScript compile-time error.
+ * Satisfies WCAG 2.1 SC 1.1.1 (Non-text Content).
+ */
+type WithAriaLabel = { "aria-label": string; "aria-labelledby"?: never };
+type WithAriaLabelledBy = { "aria-labelledby": string; "aria-label"?: never };
+
+export type IconButtonProps = Omit<ButtonProps, "children"> &
+  (WithAriaLabel | WithAriaLabelledBy) & {
+    /** The icon element rendered inside the button. */
+    icon: React.ReactNode;
+    /**
+     * Optional text shown alongside the icon at desktop widths.
+     * Hidden visually below the `$icon-label-bp` SCSS breakpoint (default 48rem / 768px),
+     * but remains in the accessibility tree — screen readers always announce it.
+     *
+     * NOTE: When `label` is used, the default `variant="icon"` removes padding.
+     * Override with a different variant (e.g. `variant="outline"`) for a padded layout.
+     */
+    label?: string;
+    /** Button type: button, submit, or reset. Required. */
+    type: "button" | "submit" | "reset";
+  };
+
+/**
+ * Accessible icon button component. Wraps `Button` with:
+ * - Required accessible label via `aria-label` or `aria-labelledby` (XOR enforced)
+ * - Optional visible `label` text that hides on mobile (visual only — always in a11y tree)
+ * - `variant="icon"` default (square, no padding)
+ *
+ * @example
+ * // Icon only
+ * <IconButton type="button" aria-label="Close menu" icon={<CloseIcon />} />
+ *
+ * @example
+ * // Icon + label (label hides on mobile)
+ * <IconButton
+ *   type="button"
+ *   aria-label="Settings"
+ *   icon={<SettingsIcon />}
+ *   label="Settings"
+ *   variant="outline"
+ * />
+ *
+ * @example
+ * // Labelled by external element
+ * <span id="btn-label">Delete item</span>
+ * <IconButton type="button" aria-labelledby="btn-label" icon={<TrashIcon />} />
+ */
+export const IconButton = ({
+  icon,
+  label,
+  variant = "icon",
+  type = "button",
+  ...props
+}: IconButtonProps) => (
+  <Button
+    variant={variant}
+    data-icon-btn={label ? "has-label" : "icon"}
+    {...props}
+    type={type}
+  >
+    {icon}
+    {label && <span data-icon-label>{label}</span>}
+  </Button>
+);
+
+IconButton.displayName = "IconButton";

package/src/components/form/select.tsx

@@ -1,9 +1,9 @@
-import UI from '../ui'
-import React from 'react'
-import { useDisabledState } from '../../hooks/use-disabled-state'
+import UI from "../ui";
+import React from "react";
+import { useDisabledState } from "../../hooks/use-disabled-state";
 
-export type { SelectProps } from './form.types'
-import type { SelectProps } from './form.types'
+export type { SelectProps } from "./form.types";
+import type { SelectProps } from "./form.types";
 
 /**
  * Option component props interface
@@ -11,56 +11,57 @@ import type { SelectProps } from './form.types'
  *
  * @interface OptionProps
  */
-export interface OptionProps extends Omit<React.ComponentPropsWithoutRef<'option'>, 'className'> {
+export interface OptionProps
+  extends Omit<React.ComponentPropsWithoutRef<"option">, "className"> {
   /**
    * Value for the select option (required, unless using legacy selectValue)
    */
-  value?: string | number
+  value?: string | number;
 
   /**
    * Display label for the option (defaults to value if not provided)
    */
-  label?: string
+  label?: string;
 
   /**
    * CSS class names (preferred over 'className' for consistency with fpkit components)
    */
-  classes?: string
+  classes?: string;
 
   /**
    * Inline CSS styles object
    */
-  styles?: React.CSSProperties
+  styles?: React.CSSProperties;
 
   /**
    * Disabled state for the option
    * @default false
    */
-  disabled?: boolean
+  disabled?: boolean;
 
   /**
    * Children content (overrides label if provided)
    */
-  children?: React.ReactNode
+  children?: React.ReactNode;
 
   /**
    * Visual variant for styling via data-option attribute
    * Use with CSS: option[data-option="primary"] { ... }
    * @example 'primary' | 'secondary' | 'success' | 'error'
    */
-  variant?: string
+  variant?: string;
 
   /**
    * Size variant for styling via data-size attribute
    * @example 'sm' | 'md' | 'lg'
    */
-  size?: string
+  size?: string;
 
   /**
    * Additional data attributes for custom styling
    * @example { 'data-highlighted': true, 'data-category': 'premium' }
    */
-  dataAttributes?: Record<string, string | boolean | number>
+  dataAttributes?: Record<string, string | boolean | number>;
 }
 
 /**
@@ -88,7 +89,10 @@ export interface OptionProps extends Omit<React.ComponentPropsWithoutRef<'option
  * @param {OptionProps} props - Component props
  * @returns {JSX.Element} Option element
  */
-export const Option = React.forwardRef<HTMLOptionElement, OptionProps & Partial<SelectOptionsProps>>(
+export const Option = React.forwardRef<
+  HTMLOptionElement,
+  OptionProps & Partial<SelectOptionsProps>
+>(
   (
     {
       value,
@@ -105,18 +109,18 @@ export const Option = React.forwardRef<HTMLOptionElement, OptionProps & Partial<
       selectLabel,
       ...props
     },
-    ref
+    ref,
   ) => {
     // Map legacy props to new props
-    const optionValue = value ?? selectValue
-    const optionLabel = label ?? selectLabel
+    const optionValue = value ?? selectValue;
+    const optionLabel = label ?? selectLabel;
 
     // Build data attributes object for styling
     const combinedDataAttrs = {
-      ...(variant && { 'data-option': variant }),
-      ...(size && { 'data-size': size }),
+      ...(variant && { "data-option": variant }),
+      ...(size && { "data-size": size }),
       ...dataAttributes,
-    }
+    };
 
     return (
       <UI
@@ -131,17 +135,17 @@ export const Option = React.forwardRef<HTMLOptionElement, OptionProps & Partial<
       >
         {children || optionLabel || optionValue}
       </UI>
-    )
-  }
-)
+    );
+  },
+);
 
-Option.displayName = 'Select.Option'
+Option.displayName = "Select.Option";
 
 // Legacy type export for backwards compatibility
-export type SelectOptionsProps = Omit<OptionProps, 'classes' | 'styles'> & {
-  selectValue: string | number
-  selectLabel?: string
-}
+export type SelectOptionsProps = Omit<OptionProps, "classes" | "styles"> & {
+  selectValue: string | number;
+  selectLabel?: string;
+};
 
 /**
  * Select component - Accessible dropdown selection input with validation support
@@ -187,7 +191,7 @@ export const Select = React.forwardRef<HTMLSelectElement, SelectProps>(
       children,
       required,
       selected,
-      validationState = 'none',
+      validationState = "none",
       errorMessage,
       hintText,
       onBlur,
@@ -197,7 +201,7 @@ export const Select = React.forwardRef<HTMLSelectElement, SelectProps>(
       onEnter,
       ...props
     },
-    ref
+    ref,
   ) => {
     // Use the disabled state hook with enhanced API for automatic className merging
     const { disabledProps, handlers } = useDisabledState<HTMLSelectElement>(
@@ -210,33 +214,33 @@ export const Select = React.forwardRef<HTMLSelectElement, SelectProps>(
           onKeyDown: (e: React.KeyboardEvent<HTMLSelectElement>) => {
             // Handle Enter key press for accessibility
             // Enables keyboard-only users to trigger actions after selection
-            if (e.key === 'Enter' && onEnter) {
-              onEnter(e)
+            if (e.key === "Enter" && onEnter) {
+              onEnter(e);
             }
             // Always call consumer's onKeyDown if provided
             if (onKeyDown) {
-              onKeyDown(e)
+              onKeyDown(e);
             }
           },
         },
         // Automatic className merging - hook combines disabled class with user classes
         className: classes,
-      }
-    )
+      },
+    );
 
     // Determine aria-invalid based on validation state
-    const isInvalid = validationState === 'invalid'
+    const isInvalid = validationState === "invalid";
 
     // Generate describedby IDs for error and hint text
-    const describedByIds: string[] = []
+    const describedByIds: string[] = [];
     if (errorMessage && id) {
-      describedByIds.push(`${id}-error`)
+      describedByIds.push(`${id}-error`);
     }
     if (hintText && id) {
-      describedByIds.push(`${id}-hint`)
+      describedByIds.push(`${id}-hint`);
     }
     const ariaDescribedBy =
-      describedByIds.length > 0 ? describedByIds.join(' ') : undefined
+      describedByIds.length > 0 ? describedByIds.join(" ") : undefined;
 
     return (
       <UI
@@ -249,7 +253,7 @@ export const Select = React.forwardRef<HTMLSelectElement, SelectProps>(
         {...handlers}
         required={required}
         aria-required={required}
-        aria-disabled={disabledProps['aria-disabled']}
+        aria-disabled={disabledProps["aria-disabled"]}
         aria-invalid={isInvalid}
         aria-describedby={ariaDescribedBy}
         style={styles}
@@ -257,19 +261,19 @@ export const Select = React.forwardRef<HTMLSelectElement, SelectProps>(
       >
         {children || <option value="" />}
       </UI>
-    )
-  }
-)
+    );
+  },
+);
 
-Select.displayName = 'Select'
+Select.displayName = "Select";
 
 // Create a compound component with proper typing
 type SelectComponent = typeof Select & {
-  Option: typeof Option
-}
+  Option: typeof Option;
+};
 
 // Type assertion to allow adding static property to ForwardRefExoticComponent
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
-;(Select as any).Option = Option
+(Select as any).Option = Option;
 
-export default Select as SelectComponent
+export default Select as SelectComponent;