@fpkit/acss 0.5.12 → 0.6.0

package/src/components/details/details.test.tsx

@@ -0,0 +1,385 @@
+import { describe, it, expect, vi } from "vitest";
+import { render, screen } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import Details from "./details";
+import React from "react";
+
+describe("Details Component", () => {
+  describe("Rendering", () => {
+    it("should render with summary and children", () => {
+      render(
+        <Details summary="Test Summary">
+          <p>Test Content</p>
+        </Details>
+      );
+
+      expect(screen.getByText("Test Summary")).toBeInTheDocument();
+      expect(screen.getByText("Test Content")).toBeInTheDocument();
+    });
+
+    it("should render with icon", () => {
+      const TestIcon = () => <svg data-testid="test-icon" />;
+      render(
+        <Details summary="Test Summary" icon={<TestIcon />}>
+          <p>Content</p>
+        </Details>
+      );
+
+      expect(screen.getByTestId("test-icon")).toBeInTheDocument();
+    });
+
+    it("should apply custom classes", () => {
+      render(
+        <Details summary="Test" classes="custom-class">
+          <p>Content</p>
+        </Details>
+      );
+
+      const detailsElement = screen.getByText("Test").closest("details");
+      expect(detailsElement).toHaveClass("custom-class");
+    });
+
+    it("should apply custom styles", () => {
+      render(
+        <Details summary="Test" styles={{ backgroundColor: "red" }}>
+          <p>Content</p>
+        </Details>
+      );
+
+      const detailsElement = screen.getByText("Test").closest("details");
+      // Check that style attribute contains the property
+      const styleAttr = detailsElement?.getAttribute("style") || "";
+      expect(styleAttr).toContain("background-color");
+    });
+
+    it("should render with aria-label when provided", () => {
+      render(
+        <Details summary="Test" ariaLabel="Custom label">
+          <p>Content</p>
+        </Details>
+      );
+
+      const detailsElement = screen.getByText("Test").closest("details");
+      expect(detailsElement).toHaveAttribute("aria-label", "Custom label");
+    });
+  });
+
+  describe("Open/Close State", () => {
+    it("should be closed by default", () => {
+      render(
+        <Details summary="Test">
+          <p>Content</p>
+        </Details>
+      );
+
+      const detailsElement = screen.getByText("Test").closest("details");
+      expect(detailsElement).not.toHaveAttribute("open");
+    });
+
+    it("should be open when open prop is true", () => {
+      render(
+        <Details summary="Test" open>
+          <p>Content</p>
+        </Details>
+      );
+
+      const detailsElement = screen.getByText("Test").closest("details");
+      expect(detailsElement).toHaveAttribute("open");
+    });
+
+    it("should toggle open state on summary click", async () => {
+      const user = userEvent.setup();
+      render(
+        <Details summary="Test">
+          <p>Content</p>
+        </Details>
+      );
+
+      const summaryElement = screen.getByText("Test");
+      const detailsElement = summaryElement.closest("details")!;
+
+      // Initially closed
+      expect(detailsElement).not.toHaveAttribute("open");
+
+      // Click to open
+      await user.click(summaryElement);
+      expect(detailsElement).toHaveAttribute("open");
+
+      // Click to close
+      await user.click(summaryElement);
+      expect(detailsElement).not.toHaveAttribute("open");
+    });
+  });
+
+  describe("Keyboard Interaction", () => {
+    it("should be keyboard accessible with focusable summary", () => {
+      render(
+        <Details summary="Test">
+          <p>Content</p>
+        </Details>
+      );
+
+      const summaryElement = screen.getByText("Test");
+      summaryElement.focus();
+
+      // Summary element should be focusable for keyboard navigation
+      expect(summaryElement).toHaveFocus();
+      expect(summaryElement.tagName).toBe("SUMMARY");
+    });
+
+    it("should support keyboard interaction through native browser behavior", () => {
+      // Note: Keyboard interaction (Space, Enter) on <summary> is handled
+      // natively by the browser and is part of the HTML5 spec.
+      // These interactions are tested in Storybook interaction tests
+      // where the browser's native behavior is fully available.
+      render(
+        <Details summary="Test">
+          <p>Content</p>
+        </Details>
+      );
+
+      const summaryElement = screen.getByText("Test");
+      const detailsElement = summaryElement.closest("details");
+
+      // Verify semantic HTML structure that enables keyboard support
+      expect(summaryElement.tagName).toBe("SUMMARY");
+      expect(detailsElement?.tagName).toBe("DETAILS");
+    });
+
+    it("should call onToggle callback when interaction occurs", async () => {
+      const user = userEvent.setup();
+      const handleToggle = vi.fn();
+
+      render(
+        <Details summary="Test" onToggle={handleToggle}>
+          <p>Content</p>
+        </Details>
+      );
+
+      const summaryElement = screen.getByText("Test");
+
+      // Click interaction
+      await user.click(summaryElement);
+
+      // Callback should be invoked
+      expect(handleToggle).toHaveBeenCalled();
+    });
+  });
+
+  describe("Event Handlers", () => {
+    it("should call onToggle when toggled", async () => {
+      const user = userEvent.setup();
+      const handleToggle = vi.fn();
+
+      render(
+        <Details summary="Test" onToggle={handleToggle}>
+          <p>Content</p>
+        </Details>
+      );
+
+      const summaryElement = screen.getByText("Test");
+      await user.click(summaryElement);
+
+      expect(handleToggle).toHaveBeenCalledTimes(1);
+      expect(handleToggle).toHaveBeenCalledWith(
+        expect.objectContaining({
+          type: "toggle",
+        })
+      );
+    });
+
+    it("should call onPointerDown on summary pointer down", async () => {
+      const user = userEvent.setup();
+      const handlePointerDown = vi.fn();
+
+      render(
+        <Details summary="Test" onPointerDown={handlePointerDown}>
+          <p>Content</p>
+        </Details>
+      );
+
+      const summaryElement = screen.getByText("Test");
+      await user.pointer({ target: summaryElement, keys: "[MouseLeft>]" });
+
+      expect(handlePointerDown).toHaveBeenCalled();
+    });
+
+    it("should not call onToggle multiple times incorrectly", async () => {
+      const user = userEvent.setup();
+      const handleToggle = vi.fn();
+
+      render(
+        <Details summary="Test" onToggle={handleToggle}>
+          <p>Content</p>
+        </Details>
+      );
+
+      const summaryElement = screen.getByText("Test");
+      await user.click(summaryElement);
+
+      // Should only be called once per toggle
+      expect(handleToggle).toHaveBeenCalledTimes(1);
+    });
+  });
+
+  describe("Accordion Behavior", () => {
+    it("should support name attribute for accordion groups", () => {
+      render(
+        <>
+          <Details summary="First" name="accordion-group">
+            <p>Content 1</p>
+          </Details>
+          <Details summary="Second" name="accordion-group">
+            <p>Content 2</p>
+          </Details>
+        </>
+      );
+
+      const firstDetails = screen.getByText("First").closest("details");
+      const secondDetails = screen.getByText("Second").closest("details");
+
+      expect(firstDetails).toHaveAttribute("name", "accordion-group");
+      expect(secondDetails).toHaveAttribute("name", "accordion-group");
+    });
+
+    it("should configure accordion group with name attribute", () => {
+      // Note: The exclusive open/close behavior of accordion groups
+      // is handled natively by browsers and tested in Storybook.
+      // Here we verify the name attribute is correctly applied.
+      render(
+        <>
+          <Details summary="First" name="test-accordion">
+            <p>Content 1</p>
+          </Details>
+          <Details summary="Second" name="test-accordion">
+            <p>Content 2</p>
+          </Details>
+        </>
+      );
+
+      const firstDetails = screen.getByText("First").closest("details");
+      const secondDetails = screen.getByText("Second").closest("details");
+
+      // Both should have the same name for accordion grouping
+      expect(firstDetails).toHaveAttribute("name", "test-accordion");
+      expect(secondDetails).toHaveAttribute("name", "test-accordion");
+    });
+  });
+
+  describe("Accessibility", () => {
+    it("should use semantic details element", () => {
+      render(
+        <Details summary="Test">
+          <p>Content</p>
+        </Details>
+      );
+
+      const detailsElement = screen.getByText("Test").closest("details");
+      expect(detailsElement?.tagName).toBe("DETAILS");
+    });
+
+    it("should use semantic summary element", () => {
+      render(
+        <Details summary="Test">
+          <p>Content</p>
+        </Details>
+      );
+
+      const summaryElement = screen.getByText("Test");
+      expect(summaryElement.tagName).toBe("SUMMARY");
+    });
+
+    it("should wrap content in section element", () => {
+      render(
+        <Details summary="Test">
+          <p data-testid="content">Content</p>
+        </Details>
+      );
+
+      const contentElement = screen.getByTestId("content");
+      const sectionElement = contentElement.closest("section");
+      expect(sectionElement).toBeInTheDocument();
+    });
+
+    it("should support ref forwarding", () => {
+      const ref = React.createRef<HTMLDetailsElement>();
+      render(
+        <Details summary="Test" ref={ref}>
+          <p>Content</p>
+        </Details>
+      );
+
+      expect(ref.current).toBeInstanceOf(HTMLDetailsElement);
+    });
+  });
+
+  describe("Complex Content", () => {
+    it("should render React nodes as summary", () => {
+      render(
+        <Details
+          summary={
+            <>
+              <span>Icon</span>
+              <span>Text</span>
+            </>
+          }
+        >
+          <p>Content</p>
+        </Details>
+      );
+
+      expect(screen.getByText("Icon")).toBeInTheDocument();
+      expect(screen.getByText("Text")).toBeInTheDocument();
+    });
+
+    it("should render complex children", () => {
+      render(
+        <Details summary="Test">
+          <div>
+            <h3>Heading</h3>
+            <p>Paragraph</p>
+            <ul>
+              <li>Item 1</li>
+              <li>Item 2</li>
+            </ul>
+          </div>
+        </Details>
+      );
+
+      expect(screen.getByText("Heading")).toBeInTheDocument();
+      expect(screen.getByText("Paragraph")).toBeInTheDocument();
+      expect(screen.getByText("Item 1")).toBeInTheDocument();
+      expect(screen.getByText("Item 2")).toBeInTheDocument();
+    });
+  });
+
+  describe("Edge Cases", () => {
+    it("should handle undefined optional props", () => {
+      render(
+        <Details summary="Test">
+          <p>Content</p>
+        </Details>
+      );
+
+      const detailsElement = screen.getByText("Test").closest("details");
+      expect(detailsElement).toBeInTheDocument();
+    });
+
+    it("should handle empty children", () => {
+      render(<Details summary="Test">{null}</Details>);
+
+      expect(screen.getByText("Test")).toBeInTheDocument();
+    });
+
+    it("should pass through additional HTML attributes", () => {
+      render(
+        <Details summary="Test" data-testid="custom-details" id="details-id">
+          <p>Content</p>
+        </Details>
+      );
+
+      const detailsElement = screen.getByTestId("custom-details");
+      expect(detailsElement).toHaveAttribute("id", "details-id");
+    });
+  });
+});

package/src/components/details/details.tsx

@@ -1,78 +1,110 @@
 import UI from "#components/ui";
-import React from "react";
+import React, { useCallback } from "react";
+import type { DetailsProps } from "./details.types";
 
-type DetailsProps = {
-  /**
-   * The summary text shown for the details.
-   * Required.
-   */
-  summary: React.ReactNode;
-
-  /**
-   * The aria-label  element for accessibility.
-   */
-  ariaLabel: string;
-} & React.ComponentProps<"details"> &
-  Partial<React.ComponentProps<typeof UI>>;
-
-/**3
- * Details component props interface.
+/**
+ * Details - A progressive disclosure component using native HTML `<details>` element.
+ *
+ * This component wraps the native `<details>` and `<summary>` elements to provide
+ * an accessible, semantic way to show and hide content. It supports accordion behavior
+ * through the `name` attribute and includes proper keyboard navigation out of the box.
+ *
+ * ## Key Features:
+ * - **Semantic HTML**: Uses native `<details>` for built-in accessibility
+ * - **Keyboard Support**: Space/Enter to toggle, fully accessible by default
+ * - **Accordion Mode**: Group multiple details with `name` for exclusive expansion
+ * - **Customizable**: Supports icons, custom styles, and event handlers
+ *
+ * ## Accessibility:
+ * - ✅ WCAG 2.1 AA compliant using semantic HTML
+ * - ✅ Native keyboard support (Space, Enter)
+ * - ✅ Screen reader compatible (announced as "disclosure" or "expandable")
+ * - ✅ Focus indicators automatically applied via CSS
+ * - ✅ `aria-expanded` managed automatically by browser
  *
- * @param {React.CSSProperties} [styles] - CSS styles object.
- * @param {string} [classes] - Classnames string.
- * @param {boolean} [open] - Whether the details is open.
- * @param {(e: React.PointerEvent<HTMLDetailsElement>) => void} [onToggle] - onToggle callback.
- * @param {(e: React.PointerEvent<HTMLDetailsElement>) => void} [onPointerDown] - onPointerDown callback.
- * @param {ReactNode} children - The content inside the details.
- * @param {string} [ariaLabel] - aria-label for accessibility.
- * @param {React.Ref<any>} [ref] - Ref object.
- * @param {Object} props - Other props.
+ * @example
+ * ```tsx
+ * // Basic usage
+ * <Details summary="Click to expand">
+ *   <p>Hidden content here</p>
+ * </Details>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // With icon and custom styling
+ * <Details
+ *   summary="Shipping Information"
+ *   icon={<ChevronDownIcon />}
+ *   classes="custom-details"
+ *   onToggle={(e) => console.log('Open:', e.currentTarget.open)}
+ * >
+ *   <p>Ships within 2-3 business days</p>
+ * </Details>
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Accordion mode - only one open at a time
+ * <Details name="faq" summary="Question 1">Answer 1</Details>
+ * <Details name="faq" summary="Question 2">Answer 2</Details>
+ * <Details name="faq" summary="Question 3">Answer 3</Details>
+ * ```
  */
-export const Details = ({
-  summary,
-  icon,
-  styles,
-  classes,
-  ariaLabel,
-  name,
-  open,
-  onPointerDown,
-  onToggle,
-  children,
-  ref,
-  ...props
-}: DetailsProps) => {
-  const defaultStyles: React.CSSProperties = { ...styles };
+export const Details = React.forwardRef<HTMLDetailsElement, DetailsProps>(
+  (
+    {
+      summary,
+      icon,
+      styles,
+      classes,
+      ariaLabel,
+      name,
+      open,
+      onPointerDown,
+      onToggle,
+      children,
+      ...props
+    },
+    ref
+  ) => {
+    // Memoize callbacks to prevent unnecessary re-renders of child components
+    const handlePointerDown = useCallback(
+      (e: React.PointerEvent<HTMLElement>) => {
+        onPointerDown?.(e as React.PointerEvent<HTMLDetailsElement>);
+      },
+      [onPointerDown]
+    );
 
-  const onPointerDownCallback = (e: React.PointerEvent<HTMLDetailsElement>) => {
-    if (onPointerDown) onPointerDown?.(e);
-    if (onPointerDown) onPointerDown?.(e);
-  };
+    const handleToggle = useCallback(
+      (e: React.SyntheticEvent<HTMLDetailsElement>) => {
+        onToggle?.(e);
+      },
+      [onToggle]
+    );
 
-  const onToggleCallback = (e: React.PointerEvent<HTMLDetailsElement>) => {
-    if (onToggle) onPointerDown?.(e);
-  };
-  return (
-    <UI
-      as="details"
-      style={defaultStyles}
-      className={classes}
-      onToggle={onToggleCallback}
-      ref={ref}
-      open={open}
-      aria-label={ariaLabel || "Details dropdown"}
-      // aria-roledescription="detail accordion"
-      name={name}
-      {...props}
-    >
-      <UI as="summary" onPointerDown={onPointerDownCallback}>
-        {icon}
-        {summary}
+    return (
+      <UI
+        as="details"
+        styles={styles}
+        classes={classes}
+        onToggle={handleToggle}
+        ref={ref}
+        open={open}
+        aria-label={ariaLabel}
+        name={name}
+        {...props}
+      >
+        <UI as="summary" onPointerDown={handlePointerDown}>
+          {icon}
+          {summary}
+        </UI>
+        <UI as="section">{children}</UI>
       </UI>
-      <UI as="section">{children}</UI>
-    </UI>
-  );
-};
+    );
+  }
+);
 
-export default Details;
 Details.displayName = "Details";
+
+export default Details;

package/src/components/details/details.types.ts

@@ -0,0 +1,76 @@
+import React from "react";
+import UI from "#components/ui";
+
+/**
+ * Props for the Details component.
+ *
+ * Combines native HTML details element props with custom styling and interaction handlers.
+ * The Details component uses the native `<details>` element for progressive disclosure,
+ * providing built-in keyboard support and semantic HTML.
+ *
+ * @example
+ * ```tsx
+ * <Details
+ *   summary="Click to expand"
+ *   icon={<ChevronIcon />}
+ *   onToggle={(e) => console.log('Toggled:', e.currentTarget.open)}
+ * >
+ *   <p>Hidden content revealed when opened</p>
+ * </Details>
+ * ```
+ */
+export type DetailsProps = {
+  /**
+   * The summary text or element shown in the clickable header.
+   * This is always visible and acts as the toggle control.
+   *
+   * @required
+   * @example
+   * ```tsx
+   * summary="Shipping Information"
+   * // or
+   * summary={<><Icon /> Shipping Information</>}
+   * ```
+   */
+  summary: React.ReactNode;
+
+  /**
+   * Optional icon displayed before the summary text.
+   * Commonly used for chevron/arrow indicators.
+   *
+   * @example
+   * ```tsx
+   * icon={<ChevronDownIcon />}
+   * ```
+   */
+  icon?: React.ReactNode;
+
+  /**
+   * Accessible label for screen readers.
+   * If not provided, the native `<details>` semantic will be used.
+   *
+   * Note: Native `<details>` elements are already semantic and announced properly
+   * by screen readers. Only provide this if you need to override the default behavior.
+   *
+   * @optional
+   * @example
+   * ```tsx
+   * ariaLabel="Product details section"
+   * ```
+   */
+  ariaLabel?: string;
+
+  /**
+   * Groups multiple details elements into an accordion where only one can be open.
+   * Multiple details elements with the same `name` will behave as a mutually exclusive group.
+   *
+   * @optional
+   * @example
+   * ```tsx
+   * <Details name="faq-accordion" summary="Question 1">...</Details>
+   * <Details name="faq-accordion" summary="Question 2">...</Details>
+   * ```
+   */
+  name?: string;
+} & React.ComponentProps<"details"> &
+  Partial<React.ComponentProps<typeof UI>>;