@fpkit/acss 3.1.0 → 3.2.0

package/src/components/stack/stack.test.tsx

@@ -0,0 +1,426 @@
+import React from "react";
+import { render, screen } from "@testing-library/react";
+import { Stack } from "./stack";
+
+describe("Stack", () => {
+  // ============================================================================
+  // Rendering Tests
+  // ============================================================================
+
+  it("renders with default props", () => {
+    render(<Stack>Content</Stack>);
+    expect(screen.getByText("Content")).toBeInTheDocument();
+  });
+
+  it("renders children correctly", () => {
+    render(
+      <Stack>
+        <span>Child 1</span>
+        <span>Child 2</span>
+      </Stack>
+    );
+    expect(screen.getByText("Child 1")).toBeInTheDocument();
+    expect(screen.getByText("Child 2")).toBeInTheDocument();
+  });
+
+  it("renders as div by default", () => {
+    render(<Stack data-testid="stack">Content</Stack>);
+    const stack = screen.getByTestId("stack");
+    expect(stack.tagName).toBe("DIV");
+  });
+
+  it("always has base stack class", () => {
+    render(<Stack data-testid="stack">Content</Stack>);
+    const stack = screen.getByTestId("stack");
+    expect(stack).toHaveClass("stack");
+  });
+
+  // ============================================================================
+  // Polymorphic Rendering Tests
+  // ============================================================================
+
+  it("renders as different elements via as prop", () => {
+    render(<Stack as="section" data-testid="stack">Content</Stack>);
+    const stack = screen.getByTestId("stack");
+    expect(stack.tagName).toBe("SECTION");
+  });
+
+  it("renders as article", () => {
+    render(<Stack as="article" data-testid="stack">Content</Stack>);
+    const stack = screen.getByTestId("stack");
+    expect(stack.tagName).toBe("ARTICLE");
+  });
+
+  it("renders as nav", () => {
+    render(<Stack as="nav" data-testid="stack">Content</Stack>);
+    const stack = screen.getByTestId("stack");
+    expect(stack.tagName).toBe("NAV");
+  });
+
+  it("renders as ul", () => {
+    render(<Stack as="ul" data-testid="stack">Content</Stack>);
+    const stack = screen.getByTestId("stack");
+    expect(stack.tagName).toBe("UL");
+  });
+
+  it("renders as ol", () => {
+    render(<Stack as="ol" data-testid="stack">Content</Stack>);
+    const stack = screen.getByTestId("stack");
+    expect(stack.tagName).toBe("OL");
+  });
+
+  // ============================================================================
+  // Direction Class Tests
+  // ============================================================================
+
+  it("applies vertical direction class by default", () => {
+    render(<Stack data-testid="stack">Content</Stack>);
+    const stack = screen.getByTestId("stack");
+    expect(stack).toHaveClass("stack-vertical");
+  });
+
+  it("applies vertical direction class explicitly", () => {
+    render(<Stack direction="vertical" data-testid="stack">Content</Stack>);
+    const stack = screen.getByTestId("stack");
+    expect(stack).toHaveClass("stack-vertical");
+  });
+
+  it("applies horizontal direction class", () => {
+    render(<Stack direction="horizontal" data-testid="stack">Content</Stack>);
+    const stack = screen.getByTestId("stack");
+    expect(stack).toHaveClass("stack-horizontal");
+  });
+
+  // ============================================================================
+  // Gap Class Tests
+  // ============================================================================
+
+  it("applies gap-0 class", () => {
+    render(<Stack gap="0" data-testid="stack">Content</Stack>);
+    const stack = screen.getByTestId("stack");
+    expect(stack).toHaveClass("stack-gap-0");
+  });
+
+  it("applies gap-xs class", () => {
+    render(<Stack gap="xs" data-testid="stack">Content</Stack>);
+    const stack = screen.getByTestId("stack");
+    expect(stack).toHaveClass("stack-gap-xs");
+  });
+
+  it("applies gap-sm class", () => {
+    render(<Stack gap="sm" data-testid="stack">Content</Stack>);
+    const stack = screen.getByTestId("stack");
+    expect(stack).toHaveClass("stack-gap-sm");
+  });
+
+  it("applies gap-md class", () => {
+    render(<Stack gap="md" data-testid="stack">Content</Stack>);
+    const stack = screen.getByTestId("stack");
+    expect(stack).toHaveClass("stack-gap-md");
+  });
+
+  it("applies gap-lg class", () => {
+    render(<Stack gap="lg" data-testid="stack">Content</Stack>);
+    const stack = screen.getByTestId("stack");
+    expect(stack).toHaveClass("stack-gap-lg");
+  });
+
+  it("applies gap-xl class", () => {
+    render(<Stack gap="xl" data-testid="stack">Content</Stack>);
+    const stack = screen.getByTestId("stack");
+    expect(stack).toHaveClass("stack-gap-xl");
+  });
+
+  // ============================================================================
+  // Align Class Tests (Cross-Axis)
+  // ============================================================================
+
+  it("applies align-start class", () => {
+    render(<Stack align="start" data-testid="stack">Content</Stack>);
+    const stack = screen.getByTestId("stack");
+    expect(stack).toHaveClass("stack-align-start");
+  });
+
+  it("applies align-center class", () => {
+    render(<Stack align="center" data-testid="stack">Content</Stack>);
+    const stack = screen.getByTestId("stack");
+    expect(stack).toHaveClass("stack-align-center");
+  });
+
+  it("applies align-end class", () => {
+    render(<Stack align="end" data-testid="stack">Content</Stack>);
+    const stack = screen.getByTestId("stack");
+    expect(stack).toHaveClass("stack-align-end");
+  });
+
+  it("applies align-stretch class", () => {
+    render(<Stack align="stretch" data-testid="stack">Content</Stack>);
+    const stack = screen.getByTestId("stack");
+    expect(stack).toHaveClass("stack-align-stretch");
+  });
+
+  // ============================================================================
+  // Justify Class Tests (Main-Axis)
+  // ============================================================================
+
+  it("applies justify-start class", () => {
+    render(<Stack justify="start" data-testid="stack">Content</Stack>);
+    const stack = screen.getByTestId("stack");
+    expect(stack).toHaveClass("stack-justify-start");
+  });
+
+  it("applies justify-center class", () => {
+    render(<Stack justify="center" data-testid="stack">Content</Stack>);
+    const stack = screen.getByTestId("stack");
+    expect(stack).toHaveClass("stack-justify-center");
+  });
+
+  it("applies justify-end class", () => {
+    render(<Stack justify="end" data-testid="stack">Content</Stack>);
+    const stack = screen.getByTestId("stack");
+    expect(stack).toHaveClass("stack-justify-end");
+  });
+
+  it("applies justify-between class", () => {
+    render(<Stack justify="between" data-testid="stack">Content</Stack>);
+    const stack = screen.getByTestId("stack");
+    expect(stack).toHaveClass("stack-justify-between");
+  });
+
+  // ============================================================================
+  // Wrap Class Tests
+  // ============================================================================
+
+  it("applies wrap class", () => {
+    render(<Stack wrap="wrap" data-testid="stack">Content</Stack>);
+    const stack = screen.getByTestId("stack");
+    expect(stack).toHaveClass("stack-wrap");
+  });
+
+  it("applies nowrap class", () => {
+    render(<Stack wrap="nowrap" data-testid="stack">Content</Stack>);
+    const stack = screen.getByTestId("stack");
+    expect(stack).toHaveClass("stack-nowrap");
+  });
+
+  // ============================================================================
+  // Multiple Props Tests
+  // ============================================================================
+
+  it("applies multiple utility classes", () => {
+    render(
+      <Stack
+        direction="horizontal"
+        gap="lg"
+        align="center"
+        justify="between"
+        wrap="wrap"
+        data-testid="stack"
+      >
+        Content
+      </Stack>
+    );
+    const stack = screen.getByTestId("stack");
+    expect(stack).toHaveClass("stack");
+    expect(stack).toHaveClass("stack-horizontal");
+    expect(stack).toHaveClass("stack-gap-lg");
+    expect(stack).toHaveClass("stack-align-center");
+    expect(stack).toHaveClass("stack-justify-between");
+    expect(stack).toHaveClass("stack-wrap");
+  });
+
+  it("combines vertical direction with other props", () => {
+    render(
+      <Stack
+        direction="vertical"
+        gap="md"
+        align="start"
+        justify="center"
+        data-testid="stack"
+      >
+        Content
+      </Stack>
+    );
+    const stack = screen.getByTestId("stack");
+    expect(stack).toHaveClass("stack-vertical");
+    expect(stack).toHaveClass("stack-gap-md");
+    expect(stack).toHaveClass("stack-align-start");
+    expect(stack).toHaveClass("stack-justify-center");
+  });
+
+  // ============================================================================
+  // Custom Class Tests
+  // ============================================================================
+
+  it("merges custom className with utility classes", () => {
+    render(
+      <Stack gap="md" className="custom-class" data-testid="stack">
+        Content
+      </Stack>
+    );
+    const stack = screen.getByTestId("stack");
+    expect(stack).toHaveClass("stack");
+    expect(stack).toHaveClass("stack-vertical");
+    expect(stack).toHaveClass("stack-gap-md");
+    expect(stack).toHaveClass("custom-class");
+  });
+
+  it("merges custom classes prop with utility classes", () => {
+    render(
+      <Stack gap="md" classes="legacy-class" data-testid="stack">
+        Content
+      </Stack>
+    );
+    const stack = screen.getByTestId("stack");
+    expect(stack).toHaveClass("stack");
+    expect(stack).toHaveClass("stack-gap-md");
+    expect(stack).toHaveClass("legacy-class");
+  });
+
+  it("merges both className and classes with utility classes", () => {
+    render(
+      <Stack
+        gap="md"
+        className="custom-class"
+        classes="legacy-class"
+        data-testid="stack"
+      >
+        Content
+      </Stack>
+    );
+    const stack = screen.getByTestId("stack");
+    expect(stack).toHaveClass("stack");
+    expect(stack).toHaveClass("stack-gap-md");
+    expect(stack).toHaveClass("custom-class");
+    expect(stack).toHaveClass("legacy-class");
+  });
+
+  // ============================================================================
+  // Inline Styles Tests
+  // ============================================================================
+
+  it("applies custom styles", () => {
+    render(
+      <Stack
+        gap="md"
+        styles={{ backgroundColor: "red", color: "white" }}
+        data-testid="stack"
+      >
+        Content
+      </Stack>
+    );
+    const stack = screen.getByTestId("stack");
+    expect(stack).toHaveStyle({ backgroundColor: "rgb(255, 0, 0)" });
+    expect(stack).toHaveStyle({ color: "rgb(255, 255, 255)" });
+  });
+
+  it("accepts CSS custom properties in styles", () => {
+    render(
+      <Stack
+        gap="md"
+        styles={{ "--spacing-md": "2rem" } as React.CSSProperties}
+        data-testid="stack"
+      >
+        Content
+      </Stack>
+    );
+    const stack = screen.getByTestId("stack");
+    expect(stack).toHaveAttribute("style");
+  });
+
+  // ============================================================================
+  // Ref Forwarding Tests
+  // ============================================================================
+
+  it("forwards ref correctly", () => {
+    const ref = React.createRef<HTMLDivElement>();
+    render(
+      <Stack ref={ref} data-testid="stack">
+        Content
+      </Stack>
+    );
+    expect(ref.current).toBeInstanceOf(HTMLDivElement);
+  });
+
+  it("forwards ref with polymorphic as prop", () => {
+    const ref = React.createRef<HTMLElement>();
+    render(
+      <Stack as="section" ref={ref} data-testid="stack">
+        Content
+      </Stack>
+    );
+    expect(ref.current).toBeInstanceOf(HTMLElement);
+    expect(ref.current?.tagName).toBe("SECTION");
+  });
+
+  // ============================================================================
+  // Accessibility Tests
+  // ============================================================================
+
+  it("forwards ARIA attributes", () => {
+    render(
+      <Stack aria-label="Test Stack" role="region" data-testid="stack">
+        Content
+      </Stack>
+    );
+    const stack = screen.getByTestId("stack");
+    expect(stack).toHaveAttribute("aria-label", "Test Stack");
+    expect(stack).toHaveAttribute("role", "region");
+  });
+
+  it("forwards data attributes", () => {
+    render(
+      <Stack data-testid="stack" data-custom="value">
+        Content
+      </Stack>
+    );
+    const stack = screen.getByTestId("stack");
+    expect(stack).toHaveAttribute("data-custom", "value");
+  });
+
+  // ============================================================================
+  // Edge Cases
+  // ============================================================================
+
+  it("handles empty children", () => {
+    render(<Stack data-testid="stack" />);
+    const stack = screen.getByTestId("stack");
+    expect(stack).toBeInTheDocument();
+    expect(stack).toBeEmptyDOMElement();
+  });
+
+  it("handles no optional props gracefully", () => {
+    render(<Stack data-testid="stack">Content</Stack>);
+    const stack = screen.getByTestId("stack");
+    expect(stack).toBeInTheDocument();
+    expect(stack).toHaveClass("stack");
+    expect(stack).toHaveClass("stack-vertical");
+    expect(stack.tagName).toBe("DIV");
+  });
+
+  it("handles only direction prop", () => {
+    render(<Stack direction="horizontal" data-testid="stack">Content</Stack>);
+    const stack = screen.getByTestId("stack");
+    expect(stack).toHaveClass("stack");
+    expect(stack).toHaveClass("stack-horizontal");
+    // Should not have gap, align, justify, or wrap classes when not provided
+    expect(stack.className.split(" ").length).toBe(2); // only "stack" and "stack-horizontal"
+  });
+
+  // ============================================================================
+  // Layout Behavior Tests
+  // ============================================================================
+
+  it("creates vertical flex container by default", () => {
+    render(<Stack data-testid="stack">Content</Stack>);
+    const stack = screen.getByTestId("stack");
+    // Base stack class ensures display: flex is applied
+    expect(stack).toHaveClass("stack");
+  });
+
+  it("creates horizontal flex container when direction is horizontal", () => {
+    render(<Stack direction="horizontal" data-testid="stack">Content</Stack>);
+    const stack = screen.getByTestId("stack");
+    expect(stack).toHaveClass("stack-horizontal");
+  });
+});

package/src/components/stack/stack.tsx

@@ -0,0 +1,141 @@
+import React from "react";
+import UI from "../ui";
+import type { StackProps } from "./stack.types";
+
+// Re-export types for convenience
+export type { StackProps } from "./stack.types";
+
+/**
+ * Stack - A simplified layout primitive for vertical or horizontal spacing between children.
+ *
+ * The Stack component provides an easy-to-use flexbox-based layout for creating vertical or
+ * horizontal arrangements with consistent gap spacing. It's designed to be simpler than the
+ * full Flex component, focusing on the most common stacking patterns.
+ *
+ * ## Key Features
+ * - **Simple API**: Fewer props than Flex for common use cases
+ * - **Fluid Spacing**: Responsive gap using CSS clamp()
+ * - **Flexbox-Based**: Reliable cross-browser layout
+ * - **Polymorphic**: Render as any semantic HTML element
+ * - **Type-Safe**: Full TypeScript support
+ *
+ * ## Accessibility
+ * - Uses semantic HTML elements when appropriate via `as` prop
+ * - Supports all ARIA attributes via spread props
+ * - Proper focus order maintained (visual order matches DOM order)
+ *
+ * ## Use Cases
+ * - Vertical spacing between content sections
+ * - Horizontal button groups
+ * - Navigation menus
+ * - Form layouts
+ * - Centered content (vertical/horizontal)
+ *
+ * @example
+ * // Vertical stack with medium gap (default)
+ * <Stack gap="md">
+ *   <h1>Title</h1>
+ *   <p>Paragraph 1</p>
+ *   <p>Paragraph 2</p>
+ * </Stack>
+ *
+ * @example
+ * // Horizontal button group
+ * <Stack direction="horizontal" gap="sm">
+ *   <Button>Cancel</Button>
+ *   <Button variant="primary">Submit</Button>
+ * </Stack>
+ *
+ * @example
+ * // Centered vertical stack
+ * <Stack
+ *   gap="lg"
+ *   align="center"
+ *   justify="center"
+ *   style={{ minHeight: '100vh' }}
+ * >
+ *   <Logo />
+ *   <h1>Welcome</h1>
+ *   <Button>Get Started</Button>
+ * </Stack>
+ *
+ * @example
+ * // Navigation with horizontal layout
+ * <Stack
+ *   as="nav"
+ *   direction="horizontal"
+ *   gap="md"
+ *   justify="between"
+ *   align="center"
+ * >
+ *   <Logo />
+ *   <Stack direction="horizontal" gap="sm">
+ *     <a href="/about">About</a>
+ *     <a href="/contact">Contact</a>
+ *   </Stack>
+ * </Stack>
+ *
+ * @see {@link StackProps} for complete props documentation
+ */
+export const Stack = React.forwardRef<HTMLElement, StackProps>(
+  (
+    {
+      gap,
+      direction = "vertical",
+      align,
+      justify,
+      wrap,
+      as = "div",
+      className,
+      classes,
+      children,
+      ...props
+    },
+    ref
+  ) => {
+    // Build utility classes array based on props
+    const utilityClasses: string[] = ["stack"];
+
+    // Direction utilities (default is vertical/column)
+    if (direction === "horizontal") {
+      utilityClasses.push("stack-horizontal");
+    } else {
+      utilityClasses.push("stack-vertical");
+    }
+
+    // Gap utilities
+    if (gap) {
+      utilityClasses.push(`stack-gap-${gap}`);
+    }
+
+    // Align utilities (cross-axis)
+    if (align) {
+      utilityClasses.push(`stack-align-${align}`);
+    }
+
+    // Justify utilities (main-axis)
+    if (justify) {
+      utilityClasses.push(`stack-justify-${justify}`);
+    }
+
+    // Wrap utilities
+    if (wrap) {
+      utilityClasses.push(`stack-${wrap}`);
+    }
+
+    // Merge all classes: utility classes, className prop, and classes prop
+    const allClasses = [...utilityClasses, className, classes]
+      .filter(Boolean)
+      .join(" ");
+
+    return (
+      <UI as={as} ref={ref} classes={allClasses} {...props}>
+        {children}
+      </UI>
+    );
+  }
+);
+
+Stack.displayName = "Stack";
+
+export default Stack;

package/src/components/stack/stack.types.ts

@@ -0,0 +1,133 @@
+import type { ComponentProps } from "../../types/component-props";
+import type { SpacingScale, StackElement } from "../../types/layout-primitives";
+import type React from "react";
+
+/**
+ * Props for the Stack component - a simplified layout primitive for vertical or horizontal spacing.
+ *
+ * Stack provides an easy-to-use flexbox-based layout for creating vertical or horizontal arrangements
+ * with consistent spacing between children. It's simpler than the full Flex component, ideal for
+ * common stacking patterns.
+ *
+ * ## Design Principles
+ * - **Simplified API**: Fewer props than Flex for common use cases
+ * - **Fluid Spacing**: Uses unified spacing scale with responsive values
+ * - **Flexbox-Based**: Built on CSS flexbox for reliable layouts
+ * - **Semantic HTML**: Defaults to `div` but supports semantic elements
+ *
+ * @example
+ * // Vertical stack (default)
+ * <Stack gap="md">
+ *   <h1>Title</h1>
+ *   <p>Paragraph 1</p>
+ *   <p>Paragraph 2</p>
+ * </Stack>
+ *
+ * @example
+ * // Horizontal stack for buttons
+ * <Stack direction="horizontal" gap="sm">
+ *   <Button>Cancel</Button>
+ *   <Button variant="primary">Submit</Button>
+ * </Stack>
+ *
+ * @example
+ * // Centered vertical stack
+ * <Stack
+ *   gap="lg"
+ *   align="center"
+ *   justify="center"
+ *   style={{ minHeight: '100vh' }}
+ * >
+ *   <Logo />
+ *   <h1>Welcome</h1>
+ * </Stack>
+ */
+export interface StackProps
+  extends Partial<ComponentProps>,
+    Omit<React.HTMLAttributes<HTMLElement>, "className"> {
+  /**
+   * Gap between children.
+   * Uses unified spacing scale: '0' | 'xs' | 'sm' | 'md' | 'lg' | 'xl'
+   * Maps to CSS custom properties (--spacing-*)
+   * @default 'md'
+   * @example
+   * <Stack gap="lg">Content</Stack>
+   */
+  gap?: SpacingScale;
+
+  /**
+   * Layout direction.
+   * - 'vertical': Stack children vertically (column)
+   * - 'horizontal': Stack children horizontally (row)
+   * @default 'vertical'
+   * @example
+   * <Stack direction="horizontal" gap="sm">
+   *   <Button>Cancel</Button>
+   *   <Button>Submit</Button>
+   * </Stack>
+   */
+  direction?: "vertical" | "horizontal";
+
+  /**
+   * Alignment on cross axis.
+   * - 'start': Align items to start (left in horizontal, top in vertical)
+   * - 'center': Center items
+   * - 'end': Align items to end (right in horizontal, bottom in vertical)
+   * - 'stretch': Stretch items to fill cross axis
+   * @default 'stretch'
+   * @example
+   * <Stack align="center">Centered items</Stack>
+   */
+  align?: "start" | "center" | "end" | "stretch";
+
+  /**
+   * Alignment on main axis.
+   * - 'start': Items at start
+   * - 'center': Items centered
+   * - 'end': Items at end
+   * - 'between': Space between items
+   * @example
+   * <Stack justify="between">
+   *   <Header />
+   *   <Footer />
+   * </Stack>
+   */
+  justify?: "start" | "center" | "end" | "between";
+
+  /**
+   * Allow items to wrap to next line/column.
+   * - 'wrap': Items wrap when they exceed container
+   * - 'nowrap': Items stay on single line/column (default)
+   * @default 'nowrap'
+   * @example
+   * <Stack direction="horizontal" wrap="wrap">
+   *   {items.map(item => <Item key={item.id} />)}
+   * </Stack>
+   */
+  wrap?: "wrap" | "nowrap";
+
+  /**
+   * Polymorphic element type to render.
+   * Defaults to 'div' but supports semantic HTML elements.
+   * @default 'div'
+   * @example
+   * <Stack as="nav" direction="horizontal" gap="md">
+   *   <a href="/">Home</a>
+   *   <a href="/about">About</a>
+   * </Stack>
+   */
+  as?: StackElement;
+
+  /**
+   * Additional CSS classes to apply.
+   * Merged with generated utility classes.
+   * @example
+   * <Stack className="custom-stack" gap="md">Content</Stack>
+   */
+  className?: string;
+
+  /**
+   * Children elements to render inside the Stack.
+   */
+  children?: React.ReactNode;
+}