@pharos-ds/core 0.1.9

package/src/Stack/Stack.test.tsx

@@ -0,0 +1,317 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Stack.test.tsx
+ * @input Uses vitest, @testing-library/react, Stack component
+ * @output Unit tests for Stack component behavior
+ * @position Testing; validates Stack.tsx implementation
+ *
+ * SYNC: When Stack.tsx changes, update tests to match new behavior
+ */
+
+import {describe, it, expect, vi} from 'vitest';
+import {render, screen} from '@testing-library/react';
+import {Stack} from './Stack';
+
+describe('Stack', () => {
+  it('defaults to vertical direction', () => {
+    render(
+      <Stack data-testid="stack">
+        <div>Item 1</div>
+        <div>Item 2</div>
+      </Stack>,
+    );
+    expect(screen.getByTestId('stack')).toBeInTheDocument();
+  });
+
+  it('renders children correctly', () => {
+    render(
+      <Stack direction="vertical">
+        <div>Item 1</div>
+        <div>Item 2</div>
+      </Stack>,
+    );
+    expect(screen.getByText('Item 1')).toBeInTheDocument();
+    expect(screen.getByText('Item 2')).toBeInTheDocument();
+  });
+
+  it('renders as div by default', () => {
+    render(
+      <Stack direction="vertical" data-testid="stack">
+        Content
+      </Stack>,
+    );
+    const element = screen.getByTestId('stack');
+    expect(element.tagName).toBe('DIV');
+  });
+
+  it('renders with horizontal direction', () => {
+    render(
+      <Stack direction="horizontal" data-testid="stack">
+        <div>Item 1</div>
+        <div>Item 2</div>
+      </Stack>,
+    );
+    expect(screen.getByTestId('stack')).toBeInTheDocument();
+  });
+
+  it('renders with vertical direction', () => {
+    render(
+      <Stack direction="vertical" data-testid="stack">
+        <div>Item 1</div>
+        <div>Item 2</div>
+      </Stack>,
+    );
+    expect(screen.getByTestId('stack')).toBeInTheDocument();
+  });
+
+  it('renders with polymorphic as prop', () => {
+    render(
+      <Stack direction="vertical" as="nav" data-testid="stack">
+        Content
+      </Stack>,
+    );
+    const element = screen.getByTestId('stack');
+    expect(element.tagName).toBe('NAV');
+  });
+
+  it('renders with polymorphic as section', () => {
+    render(
+      <Stack direction="vertical" as="section" data-testid="stack">
+        Content
+      </Stack>,
+    );
+    const element = screen.getByTestId('stack');
+    expect(element.tagName).toBe('SECTION');
+  });
+
+  it('renders with gap prop', () => {
+    render(
+      <Stack direction="vertical" gap={4}>
+        <div>Item 1</div>
+        <div>Item 2</div>
+      </Stack>,
+    );
+    expect(screen.getByText('Item 1')).toBeInTheDocument();
+  });
+
+  it('renders with hAlign prop', () => {
+    render(
+      <Stack direction="vertical" hAlign="center">
+        <div>Item 1</div>
+      </Stack>,
+    );
+    expect(screen.getByText('Item 1')).toBeInTheDocument();
+  });
+
+  it('renders with vAlign prop', () => {
+    render(
+      <Stack direction="vertical" vAlign="center">
+        <div>Item 1</div>
+      </Stack>,
+    );
+    expect(screen.getByText('Item 1')).toBeInTheDocument();
+  });
+
+  it('renders with wrap prop', () => {
+    render(
+      <Stack direction="vertical" wrap="wrap">
+        <div>Item 1</div>
+        <div>Item 2</div>
+      </Stack>,
+    );
+    expect(screen.getByText('Item 1')).toBeInTheDocument();
+  });
+
+  it('renders horizontal with hAlign and vAlign', () => {
+    render(
+      <Stack direction="horizontal" hAlign="between" vAlign="center">
+        <div>Item 1</div>
+        <div>Item 2</div>
+      </Stack>,
+    );
+    expect(screen.getByText('Item 1')).toBeInTheDocument();
+    expect(screen.getByText('Item 2')).toBeInTheDocument();
+  });
+
+  it('renders vertical with hAlign and vAlign', () => {
+    render(
+      <Stack direction="vertical" hAlign="center" vAlign="between">
+        <div>Item 1</div>
+        <div>Item 2</div>
+      </Stack>,
+    );
+    expect(screen.getByText('Item 1')).toBeInTheDocument();
+    expect(screen.getByText('Item 2')).toBeInTheDocument();
+  });
+
+  it('forwards ref correctly', () => {
+    const ref = vi.fn();
+    render(
+      <Stack direction="vertical" ref={ref}>
+        <div>Test</div>
+      </Stack>,
+    );
+    expect(ref).toHaveBeenCalledWith(expect.any(HTMLElement));
+  });
+
+  it('forwards ref with polymorphic as', () => {
+    const ref = vi.fn();
+    render(
+      <Stack direction="vertical" as="section" ref={ref}>
+        <div>Test</div>
+      </Stack>,
+    );
+    expect(ref).toHaveBeenCalledWith(expect.any(HTMLElement));
+  });
+
+  it('passes through additional props', () => {
+    render(
+      <Stack
+        direction="vertical"
+        data-testid="stack"
+        aria-label="Stack container">
+        <div>Item</div>
+      </Stack>,
+    );
+    const element = screen.getByTestId('stack');
+    expect(element).toHaveAttribute('aria-label', 'Stack container');
+  });
+
+  it('accepts justify as main-axis alias (horizontal)', () => {
+    const {container} = render(
+      <Stack direction="horizontal" justify="between">
+        <div>A</div>
+        <div>B</div>
+      </Stack>,
+    );
+    expect(container.firstChild).toBeInTheDocument();
+  });
+
+  it('accepts align as cross-axis alias (horizontal)', () => {
+    const {container} = render(
+      <Stack direction="horizontal" align="center">
+        <div>A</div>
+      </Stack>,
+    );
+    expect(container.firstChild).toBeInTheDocument();
+  });
+
+  it('accepts justify as main-axis alias (vertical)', () => {
+    const {container} = render(
+      <Stack direction="vertical" justify="center">
+        <div>A</div>
+      </Stack>,
+    );
+    expect(container.firstChild).toBeInTheDocument();
+  });
+
+  it('prefers explicit hAlign/vAlign over aliases', () => {
+    const {container} = render(
+      <Stack direction="horizontal" hAlign="center" justify="end">
+        <div>A</div>
+      </Stack>,
+    );
+    expect(container.firstChild).toBeInTheDocument();
+  });
+
+  it('applies numeric width as pixels', () => {
+    render(
+      <Stack direction="vertical" width={300} data-testid="stack">
+        <div>Item</div>
+      </Stack>,
+    );
+    expect(screen.getByTestId('stack')).toHaveStyle({width: '300px'});
+  });
+
+  it('applies string width as-is', () => {
+    render(
+      <Stack direction="vertical" width="100%" data-testid="stack">
+        <div>Item</div>
+      </Stack>,
+    );
+    expect(screen.getByTestId('stack')).toHaveStyle({width: '100%'});
+  });
+
+  it('applies numeric height as pixels', () => {
+    render(
+      <Stack direction="horizontal" height={200} data-testid="stack">
+        <div>Item</div>
+      </Stack>,
+    );
+    expect(screen.getByTestId('stack')).toHaveStyle({height: '200px'});
+  });
+
+  it('applies string height as-is', () => {
+    render(
+      <Stack direction="horizontal" height="50vh" data-testid="stack">
+        <div>Item</div>
+      </Stack>,
+    );
+    expect(screen.getByTestId('stack')).toHaveStyle({height: '50vh'});
+  });
+
+  it('applies both width and height together', () => {
+    render(
+      <Stack direction="vertical" width={400} height="100%" data-testid="stack">
+        <div>Item</div>
+      </Stack>,
+    );
+    const el = screen.getByTestId('stack');
+    expect(el).toHaveStyle({width: '400px', height: '100%'});
+  });
+
+  it('applies a class when padding is set', () => {
+    render(
+      <Stack padding={3} data-testid="stack">
+        <div>Item</div>
+      </Stack>,
+    );
+    expect(screen.getByTestId('stack').className).not.toBe('');
+  });
+
+  it('accepts paddingInline and paddingBlock without error', () => {
+    render(
+      <Stack paddingInline={4} paddingBlock={2} data-testid="stack">
+        <div>Item</div>
+      </Stack>,
+    );
+    expect(screen.getByTestId('stack')).toBeInTheDocument();
+  });
+
+  it('lets paddingInline/paddingBlock override padding on their axis', () => {
+    // padding sets both axes; paddingInline overrides the inline axis. The
+    // component should render without conflict and carry a class.
+    render(
+      <Stack padding={2} paddingInline={5} data-testid="stack">
+        <div>Item</div>
+      </Stack>,
+    );
+    expect(screen.getByTestId('stack').className).not.toBe('');
+  });
+
+  it('applies a class when isScrollable is set', () => {
+    render(
+      <Stack isScrollable data-testid="stack">
+        <div>Item</div>
+      </Stack>,
+    );
+    expect(screen.getByTestId('stack').className).not.toBe('');
+  });
+
+  it('does not set overflow class when isScrollable is false', () => {
+    const {rerender} = render(
+      <Stack data-testid="stack">
+        <div>Item</div>
+      </Stack>,
+    );
+    const withoutScroll = screen.getByTestId('stack').className;
+    rerender(
+      <Stack isScrollable data-testid="stack">
+        <div>Item</div>
+      </Stack>,
+    );
+    const withScroll = screen.getByTestId('stack').className;
+    expect(withScroll).not.toBe(withoutScroll);
+  });
+});

package/src/Stack/Stack.tsx

@@ -0,0 +1,296 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file Stack.tsx
+ * @input Uses React, ElementType, stack utility
+ * @output Exports Stack polymorphic component and StackProps
+ * @position Layout/Stack component; uses stack.stylex.ts
+ *
+ * SYNC: When modified, update these files to stay in sync:
+ * - /packages/core/src/Stack/Stack.doc.mjs
+ * - /apps/storybook/stories/Stack.stories.tsx
+ * - /packages/cli/templates/blocks/components/Stack/ (showcase blocks)
+ */
+
+import {createElement, type ElementType, type ReactNode, type Ref} from 'react';
+import type {BaseProps} from '../BaseProps';
+import * as stylex from '@stylexjs/stylex';
+import {
+  stack,
+  type StackCrossAlignment,
+  type StackDirection,
+  type StackMainAlignment,
+  type StackWrap,
+  type SpacingStep,
+} from './stack.stylex';
+import type {SizeValue} from '../utils/types';
+import {
+  paddingInlineStyles,
+  paddingBlockStyles,
+} from '../Layout/padding.stylex';
+import {mergeProps} from '../utils';
+import {themeProps} from '../utils/themeProps';
+
+const overflowStyles = stylex.create({
+  scrollable: {
+    overflow: 'auto',
+  },
+});
+
+/**
+ * Alignment values accepted by Stack.
+ *
+ * The full union of main-axis and cross-axis alignment values.
+ * Which values are valid depends on direction and axis:
+ * - Main axis (hAlign for horizontal, vAlign for vertical):
+ *   `'start' | 'center' | 'end' | 'between' | 'around' | 'evenly'`
+ * - Cross axis (vAlign for horizontal, hAlign for vertical):
+ *   `'start' | 'center' | 'end' | 'stretch'`
+ */
+export type StackAlignment = StackMainAlignment | StackCrossAlignment;
+
+export interface StackProps extends BaseProps<HTMLElement> {
+  /** Ref forwarded to the root element */
+  ref?: React.Ref<HTMLElement>;
+  /**
+   * Direction of the stack layout.
+   * - `horizontal`: Items flow left-to-right (like HStack)
+   * - `vertical`: Items flow top-to-bottom (like VStack)
+   * @default 'vertical'
+   */
+  direction?: StackDirection;
+
+  /**
+   * Horizontal alignment of items.
+   * - When `direction='horizontal'`: controls main-axis (justify-content).
+   *   Accepts: `'start' | 'center' | 'end' | 'between' | 'around' | 'evenly'`
+   * - When `direction='vertical'`: controls cross-axis (align-items).
+   *   Accepts: `'start' | 'center' | 'end' | 'stretch'`
+   */
+  hAlign?: StackAlignment;
+
+  /**
+   * Vertical alignment of items.
+   * - When `direction='horizontal'`: controls cross-axis (align-items).
+   *   Accepts: `'start' | 'center' | 'end' | 'stretch'`
+   * - When `direction='vertical'`: controls main-axis (justify-content).
+   *   Accepts: `'start' | 'center' | 'end' | 'between' | 'around' | 'evenly'`
+   */
+  vAlign?: StackAlignment;
+
+  /**
+   * Main-axis alignment alias. Resolves based on `direction`:
+   * - `horizontal` → `hAlign` (justify-content)
+   * - `vertical` → `vAlign` (justify-content)
+   *
+   * Mirrors CSS `justify-content` / Tailwind `justify-*`.
+   */
+  justify?: StackMainAlignment;
+
+  /**
+   * Cross-axis alignment alias. Resolves based on `direction`:
+   * - `horizontal` → `vAlign` (align-items)
+   * - `vertical` → `hAlign` (align-items)
+   *
+   * Mirrors CSS `align-items` / Tailwind `items-*`.
+   */
+  align?: StackCrossAlignment;
+
+  /**
+   * Width of the stack container.
+   * Numbers are treated as pixels, strings are used as-is (e.g., '100%').
+   */
+  width?: SizeValue;
+
+  /**
+   * Height of the stack container.
+   * Numbers are treated as pixels, strings are used as-is (e.g., '100%').
+   */
+  height?: SizeValue;
+
+  /**
+   * Maximum width of the stack container.
+   * Numbers are treated as pixels, strings are used as-is (e.g., '100%').
+   */
+  maxWidth?: SizeValue;
+
+  /**
+   * Minimum height of the stack container.
+   * Numbers are treated as pixels, strings are used as-is (e.g., '100%').
+   */
+  minHeight?: SizeValue;
+
+  /**
+   * Spacing between items.
+   * Accepts numeric spacing steps: 0, 0.5, 1, 1.5, 2, 3, 4, 5, 6, 8, 10.
+   */
+  gap?: SpacingStep;
+
+  /**
+   * Inner padding on all sides, using the spacing scale.
+   * Accepts numeric spacing steps: 0, 0.5, 1, 1.5, 2, 3, 4, 5, 6, 8, 10.
+   *
+   * Matches the `padding` prop on `Card`, `LayoutContent`, and `LayoutPanel`.
+   */
+  padding?: SpacingStep;
+
+  /**
+   * Inline (horizontal) padding, using the spacing scale.
+   * Overrides `padding` on the inline axis when both are set.
+   */
+  paddingInline?: SpacingStep;
+
+  /**
+   * Block (vertical) padding, using the spacing scale.
+   * Overrides `padding` on the block axis when both are set.
+   */
+  paddingBlock?: SpacingStep;
+
+  /**
+   * Enables scrollable overflow (`overflow: auto`) for the stack.
+   *
+   * Matches the `isScrollable` prop on `LayoutContent` and `LayoutPanel`.
+   * When the stack is itself a flex child that should scroll, pair it with
+   * a parent `StackItem size="fill" isScrollable` (StackItem applies the
+   * `min-height: 0` reset that flex scroll regions require).
+   * @default false
+   */
+  isScrollable?: boolean;
+
+  /**
+   * Whether items should wrap.
+   * - `nowrap`: Items stay on one line (default)
+   * - `wrap`: Items wrap to next line
+   * - `wrap-reverse`: Items wrap to previous line
+   * @default 'nowrap'
+   */
+  wrap?: StackWrap;
+
+  /**
+   * The element type to render.
+   * @default 'div'
+   */
+  as?: ElementType;
+
+  /**
+   * Content to render inside the stack.
+   */
+  children?: ReactNode;
+}
+
+/**
+ * Unified stack component for arranging items in a horizontal or vertical layout.
+ *
+ * Replaces `HStack` and `VStack` with a single component that accepts
+ * a `direction` prop. Defaults to `'vertical'` since most layouts stack
+ * top-to-bottom.
+ *
+ * The `hAlign` and `vAlign` props automatically map to the correct CSS axis
+ * based on the direction:
+ * - `direction='horizontal'`: hAlign → justify-content, vAlign → align-items
+ * - `direction='vertical'`: hAlign → align-items, vAlign → justify-content
+ *
+ * @example
+ * ```
+ * <Stack gap={2}>
+ *   <Item />
+ *   <Item />
+ * </Stack>
+ * <Stack direction="horizontal" gap={4} vAlign="center">
+ *   <Item />
+ *   <Item />
+ * </Stack>
+ * ```
+ */
+export function Stack({
+  direction = 'vertical',
+  hAlign,
+  vAlign,
+  justify,
+  align,
+  gap,
+  padding,
+  paddingInline,
+  paddingBlock,
+  isScrollable,
+  width,
+  height,
+  maxWidth,
+  minHeight,
+  wrap,
+  as: element = 'div',
+  xstyle,
+  className,
+  style,
+  children,
+  ref,
+  ...props
+}: StackProps) {
+  // Resolve align/justify aliases based on direction
+  const resolvedHAlign =
+    hAlign ?? (direction === 'horizontal' ? justify : align);
+  const resolvedVAlign =
+    vAlign ?? (direction === 'horizontal' ? align : justify);
+
+  // Map hAlign/vAlign to mainAlign/crossAlign based on direction
+  const mainAlign =
+    direction === 'horizontal'
+      ? (resolvedHAlign as StackMainAlignment | undefined)
+      : (resolvedVAlign as StackMainAlignment | undefined);
+  const crossAlign =
+    direction === 'horizontal'
+      ? (resolvedVAlign as StackCrossAlignment | undefined)
+      : (resolvedHAlign as StackCrossAlignment | undefined);
+
+  // Resolve padding to per-axis values: `padding` sets both axes; `paddingInline`
+  // / `paddingBlock` take precedence on their own axis when provided.
+  const resolvedPaddingInline = paddingInline ?? padding;
+  const resolvedPaddingBlock = paddingBlock ?? padding;
+
+  const stylexProps = stylex.props(
+    ...stack({
+      direction,
+      crossAlign,
+      mainAlign,
+      gap,
+      wrap,
+    }),
+    resolvedPaddingInline != null && paddingInlineStyles[resolvedPaddingInline],
+    resolvedPaddingBlock != null && paddingBlockStyles[resolvedPaddingBlock],
+    isScrollable && overflowStyles.scrollable,
+    xstyle,
+  );
+
+  // Build inline style for dynamic sizing values
+  const sizingStyle: React.CSSProperties = {
+    ...(width != null && {
+      width: typeof width === 'number' ? `${width}px` : width,
+    }),
+    ...(height != null && {
+      height: typeof height === 'number' ? `${height}px` : height,
+    }),
+    ...(maxWidth != null && {
+      maxWidth: typeof maxWidth === 'number' ? `${maxWidth}px` : maxWidth,
+    }),
+    ...(minHeight != null && {
+      minHeight: typeof minHeight === 'number' ? `${minHeight}px` : minHeight,
+    }),
+  };
+
+  return createElement(
+    element,
+    {
+      ref: ref as Ref<Element>,
+      ...mergeProps(
+        themeProps('stack', {direction, gap, wrap}),
+        stylexProps,
+        className,
+        {...style, ...sizingStyle},
+      ),
+      ...props,
+    },
+    children,
+  );
+}
+
+Stack.displayName = 'Stack';