@astryxdesign/core 0.6.0 → 0.6.1

package/src/ScrollableArea/ScrollableArea.test.tsx

@@ -0,0 +1,299 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+import {readFileSync} from 'node:fs';
+import {act, render, screen} from '@testing-library/react';
+import {afterEach, beforeEach, describe, expect, it, vi} from 'vitest';
+import {ScrollableArea} from './ScrollableArea';
+
+function setGeometry(
+  element: HTMLElement,
+  values: Partial<
+    Pick<
+      HTMLElement,
+      'clientWidth' | 'clientHeight' | 'scrollWidth' | 'scrollHeight'
+    >
+  >,
+) {
+  for (const [key, value] of Object.entries(values)) {
+    Object.defineProperty(element, key, {
+      configurable: true,
+      value,
+      writable: true,
+    });
+  }
+}
+
+describe('ScrollableArea', () => {
+  let frames: FrameRequestCallback[];
+
+  beforeEach(() => {
+    frames = [];
+    vi.stubGlobal(
+      'requestAnimationFrame',
+      vi.fn((callback: FrameRequestCallback) => {
+        frames.push(callback);
+        return frames.length;
+      }),
+    );
+    vi.stubGlobal('cancelAnimationFrame', vi.fn());
+    vi.stubGlobal(
+      'ResizeObserver',
+      vi.fn(function () {
+        return {observe: vi.fn(), unobserve: vi.fn(), disconnect: vi.fn()};
+      }),
+    );
+  });
+
+  afterEach(() => vi.unstubAllGlobals());
+
+  function flushFrame() {
+    void act(() => {
+      const pending = frames.splice(0);
+      pending.forEach(callback => callback(performance.now()));
+    });
+  }
+
+  it('renders one native viewport and one real content box', () => {
+    render(
+      <ScrollableArea label="Messages" data-testid="viewport">
+        <p>Message history</p>
+      </ScrollableArea>,
+    );
+
+    const viewport = screen.getByTestId('viewport');
+    expect(viewport).toHaveAccessibleName('Messages');
+    expect(viewport).toHaveAttribute('role', 'group');
+    expect(viewport).toHaveAttribute('data-scroll-axis', 'block');
+    expect(viewport).not.toHaveAttribute('tabindex');
+    expect(viewport.children).toHaveLength(1);
+    expect(viewport.firstElementChild).toHaveAttribute('data-scroll-content');
+    expect(viewport).toHaveTextContent('Message history');
+  });
+
+  it('becomes keyboard reachable only when the requested axis is effective', () => {
+    render(
+      <ScrollableArea
+        axis="block"
+        label="Messages"
+        data-testid="viewport"
+        style={{height: 100}}>
+        <p>Message history</p>
+      </ScrollableArea>,
+    );
+    const viewport = screen.getByTestId('viewport');
+    // jsdom does not resolve StyleX's dynamic CSS variables. Mirror the
+    // generated class values so this integration test can exercise measurement.
+    viewport.style.overflowX = 'hidden';
+    viewport.style.overflowY = 'auto';
+    setGeometry(viewport, {
+      clientWidth: 100,
+      clientHeight: 100,
+      scrollWidth: 100,
+      scrollHeight: 180,
+    });
+
+    void act(() => viewport.dispatchEvent(new Event('scroll')));
+    flushFrame();
+    expect(viewport).toHaveAttribute('tabindex', '0');
+    expect(viewport).toHaveAttribute('data-scrollable-block', 'true');
+
+    setGeometry(viewport, {scrollHeight: 100});
+    viewport.focus();
+    void act(() => viewport.dispatchEvent(new Event('scroll')));
+    flushFrame();
+    expect(viewport).toHaveAttribute('tabindex', '-1');
+    expect(document.activeElement).toBe(viewport);
+  });
+
+  it('keeps viewport props, styles, class names, events, and refs', () => {
+    const onClick = vi.fn();
+    const ref = vi.fn();
+    render(
+      <ScrollableArea
+        label="Results"
+        role="region"
+        ref={ref}
+        onClick={onClick}
+        className="consumer-class"
+        style={{maxHeight: 200}}
+        data-testid="viewport">
+        Results
+      </ScrollableArea>,
+    );
+
+    const viewport = screen.getByTestId('viewport');
+    viewport.click();
+    expect(onClick).toHaveBeenCalledTimes(1);
+    expect(ref).toHaveBeenCalledWith(viewport);
+    expect(viewport).toHaveClass('astryx-scrollable-area', 'consumer-class');
+    expect(viewport.style.maxHeight).toBe('200px');
+    expect(viewport).toHaveAttribute('role', 'region');
+  });
+
+  it('reflects logical axis and chaining intent without containing a fitting area', () => {
+    render(
+      <ScrollableArea
+        axis="both"
+        label="Canvas"
+        overscroll="contain"
+        data-testid="viewport">
+        Canvas
+      </ScrollableArea>,
+    );
+    const viewport = screen.getByTestId('viewport');
+    expect(viewport).toHaveAttribute('data-axis', 'both');
+    expect(viewport).toHaveAttribute('data-scroll-axis', 'both');
+    expect(viewport.style.overscrollBehaviorX).toBe('auto');
+    expect(viewport.style.overscrollBehaviorY).toBe('auto');
+  });
+
+  it('keeps logical overflow and content sizing for writing-mode changes', () => {
+    const {rerender} = render(
+      <ScrollableArea axis="inline" label="Timeline" data-testid="viewport">
+        Timeline
+      </ScrollableArea>,
+    );
+    const viewport = screen.getByTestId('viewport');
+    const content = viewport.firstElementChild as HTMLElement;
+    const inlineViewportClass = viewport.className;
+    expect(viewport.style.overflowInline).toBe('');
+    expect(viewport.style.overflowBlock).toBe('');
+    const inlineContentClass = content.className;
+    expect(content.style.inlineSize).toBe('');
+    expect(content.style.minInlineSize).toBe('');
+
+    rerender(
+      <ScrollableArea axis="block" label="Timeline" data-testid="viewport">
+        Timeline
+      </ScrollableArea>,
+    );
+    expect(viewport.className).not.toBe(inlineViewportClass);
+    expect(viewport.style.overflowInline).toBe('');
+    expect(viewport.style.overflowBlock).toBe('');
+    expect(content.className).not.toBe(inlineContentClass);
+    expect(content.style.inlineSize).toBe('');
+    const source = stylesSource();
+    expect(source).not.toContain('dynamicStyles.overflow(');
+    expect(source).not.toContain('logicalOverflowStyle');
+    expect(hookSource()).toContain('styles.overflow(');
+    expect(source).toContain("minInlineSize: '100%'");
+    expect(source).toContain("inlineSize: 'max-content'");
+  });
+
+  it('uses clip while fitting and makes fitting Sticky containment explicit', () => {
+    const {rerender} = render(
+      <ScrollableArea label="Messages" data-testid="viewport">
+        Messages
+      </ScrollableArea>,
+    );
+    const viewport = screen.getByTestId('viewport');
+    expect(viewport.getAttribute('style')).toContain('clip');
+    expect(viewport).not.toHaveAttribute('tabindex');
+
+    rerender(
+      <ScrollableArea
+        label="Messages"
+        stickyContainment="always"
+        data-testid="viewport">
+        Messages
+      </ScrollableArea>,
+    );
+    expect(viewport.getAttribute('style')).toContain('auto');
+    expect(viewport.getAttribute('style')).toContain('hidden');
+    expect(viewport).not.toHaveAttribute('tabindex');
+  });
+
+  it('accepts standard container sizing props on the viewport', () => {
+    render(
+      <ScrollableArea
+        label="Messages"
+        width={320}
+        height="50vh"
+        maxWidth="100%"
+        minHeight={120}
+        data-testid="viewport">
+        Messages
+      </ScrollableArea>,
+    );
+
+    expect(screen.getByTestId('viewport')).toBeInTheDocument();
+    expect(stylesSource()).toContain('dynamicStyles.sizing(');
+  });
+
+  it('publishes content padding without changing the viewport default', () => {
+    const {rerender} = render(
+      <ScrollableArea label="Messages" data-testid="viewport">
+        Messages
+      </ScrollableArea>,
+    );
+    const viewport = screen.getByTestId('viewport');
+    const content = viewport.firstElementChild as HTMLElement;
+    const defaultViewportClass = viewport.className;
+    const defaultContentClass = content.className;
+
+    rerender(
+      <ScrollableArea
+        label="Messages"
+        padding={4}
+        paddingInlineEnd={2}
+        data-testid="viewport">
+        Messages
+      </ScrollableArea>,
+    );
+
+    expect(viewport.className).toBe(defaultViewportClass);
+    expect(content.className).not.toBe(defaultContentClass);
+    const source = stylesSource();
+    expect(source).toContain('containerPaddingInlineVarStyles[padding]');
+    expect(source).toContain(
+      'containerPaddingInlineEndVarStyles[paddingInlineEnd]',
+    );
+  });
+
+  it('keeps inherited container bleed opt-in on the viewport', () => {
+    const {rerender} = render(
+      <ScrollableArea label="Messages" data-testid="viewport">
+        Messages
+      </ScrollableArea>,
+    );
+    const viewport = screen.getByTestId('viewport');
+    const containedClass = viewport.className;
+
+    rerender(
+      <ScrollableArea label="Messages" isFullBleed data-testid="viewport">
+        Messages
+      </ScrollableArea>,
+    );
+
+    expect(viewport.className).not.toBe(containedClass);
+    const source = stylesSource();
+    expect(source).toContain('var(--container-padding-inline-start, 0px)');
+    expect(source).toContain('isFullBleed && styles.fullBleed');
+  });
+
+  it('uses the neutral token for native scrollbar color with a transparent track', () => {
+    const source = stylesSource();
+    expect(source).toContain("colorVars['--color-neutral']");
+    expect(source).toContain('transparent');
+    expect(source).toContain("'@media (forced-colors: active)': 'auto'");
+  });
+
+  it('guards scroll-state query containment as a progressive enhancement', () => {
+    const source = stylesSource();
+    expect(source).toContain("'@supports (container-type: scroll-state)'");
+    expect(source).toContain("'scroll-state'");
+  });
+});
+
+function hookSource(): string {
+  return readFileSync('packages/core/src/hooks/useScrollableArea.ts', 'utf8');
+}
+
+function stylesSource(): string {
+  // This focused source assertion complements the built-CSS browser probe: it
+  // keeps the capability guard and token reference reviewable at unit-test speed.
+  return readFileSync(
+    'packages/core/src/ScrollableArea/ScrollableArea.tsx',
+    'utf8',
+  );
+}

package/src/ScrollableArea/ScrollableArea.tsx

@@ -0,0 +1,259 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+'use client';
+
+/**
+ * @file ScrollableArea.tsx
+ * @input Logical scroll intent, accessible name, overscroll policy, viewport sizing, content padding, and content
+ * @output Native scroll viewport with an observed real content box
+ * @position Reference composition over useScrollableArea
+ *
+ * SYNC: When modified, update:
+ * - /packages/core/src/ScrollableArea/ScrollableArea.test.tsx
+ * - /packages/core/src/ScrollableArea/ScrollableArea.doc.mjs
+ * - /apps/storybook/stories/ScrollableArea.stories.tsx
+ */
+
+import type {ReactNode} from 'react';
+import * as stylex from '@stylexjs/stylex';
+import type {BaseProps} from '../BaseProps';
+import {
+  paddingStyles,
+  paddingInlineStyles,
+  paddingInlineStartStyles,
+  paddingInlineEndStyles,
+  paddingBlockStyles,
+  paddingBlockStartStyles,
+  paddingBlockEndStyles,
+  containerPaddingInlineVarStyles,
+  containerPaddingInlineStartVarStyles,
+  containerPaddingInlineEndVarStyles,
+  containerPaddingBlockStartVarStyles,
+  containerPaddingBlockEndVarStyles,
+} from '../Layout/padding.stylex';
+import type {SizeValue, SpacingStep} from '../utils/types';
+import {
+  useScrollableArea,
+  type ScrollAxis,
+  type ScrollOverscroll,
+  type ScrollStickyContainment,
+} from '../hooks/useScrollableArea';
+import {colorVars} from '../theme/tokens.stylex';
+import {focusOutlineStyles} from '../utils/focusOutline.stylex';
+import {mergeProps} from '../utils/mergeProps';
+import {themeProps} from '../utils/themeProps';
+
+const styles = stylex.create({
+  viewport: {
+    boxSizing: 'border-box',
+    maxInlineSize: '100%',
+    maxBlockSize: '100%',
+    WebkitOverflowScrolling: 'touch',
+    scrollbarColor: {
+      default: `${colorVars['--color-neutral']} transparent`,
+      '@media (forced-colors: active)': 'auto',
+    },
+    scrollbarWidth: 'auto',
+    scrollbarGutter: 'auto',
+    // Chromium can resolve CSS-only stuck/edge presentation for descendants.
+    // Unsupported engines keep the hook state as the behavior source of truth.
+    containerType: {
+      default: null,
+      '@supports (container-type: scroll-state)': 'scroll-state',
+    },
+  },
+  fullBleed: {
+    marginInlineStart: 'calc(-1 * var(--container-padding-inline-start, 0px))',
+    marginInlineEnd: 'calc(-1 * var(--container-padding-inline-end, 0px))',
+    maxInlineSize:
+      'calc(100% + var(--container-padding-inline-start, 0px) + var(--container-padding-inline-end, 0px))',
+    marginBlockStart: {
+      default: null,
+      ':first-child': 'calc(-1 * var(--container-padding-block-start, 0px))',
+    },
+    marginBlockEnd: {
+      default: null,
+      ':last-child': 'calc(-1 * var(--container-padding-block-end, 0px))',
+    },
+  },
+  content: {
+    boxSizing: 'border-box',
+    minInlineSize: '100%',
+    minBlockSize: '100%',
+  },
+  contentWithInlineOverflow: {
+    inlineSize: 'max-content',
+  },
+});
+
+const dynamicStyles = stylex.create({
+  sizing: (
+    width: SizeValue | null,
+    height: SizeValue | null,
+    maxWidth: SizeValue | null,
+    minHeight: SizeValue | null,
+  ) => ({width, height, maxWidth, minHeight}),
+});
+
+export type ScrollableAreaStickyContainment = ScrollStickyContainment;
+
+export interface ScrollableAreaProps extends Omit<
+  BaseProps<HTMLDivElement>,
+  'aria-label' | 'children' | 'role' | 'tabIndex'
+> {
+  /** Content rendered inside the observed content box. */
+  children?: ReactNode;
+  /** Logical axis or axes where scrolling is allowed. @default 'block' */
+  axis?: ScrollAxis;
+  /** Accessible name used when an effective viewport enters the tab order. */
+  label: string;
+  /** Semantics for the named scroll viewport. @default 'group' */
+  role?: 'group' | 'region';
+  /** Whether effective axes pass scroll gestures to ancestors at an edge. @default 'allow' */
+  overscroll?: ScrollOverscroll;
+  /** Width of the viewport; numbers are interpreted as pixels. */
+  width?: SizeValue;
+  /** Height of the viewport; numbers are interpreted as pixels. */
+  height?: SizeValue;
+  /** Maximum width of the viewport. */
+  maxWidth?: SizeValue;
+  /** Minimum height of the viewport. */
+  minHeight?: SizeValue;
+  /** Whether a fitting viewport deliberately remains a Sticky containing boundary. @default 'whenScrollable' */
+  stickyContainment?: ScrollableAreaStickyContainment;
+  /** Content padding using the shared spacing scale. @default 0 */
+  padding?: SpacingStep;
+  /** Logical inline-axis content padding; overrides `padding` on that axis. */
+  paddingInline?: SpacingStep;
+  /** Logical inline-start content padding; overrides broader padding values. */
+  paddingInlineStart?: SpacingStep;
+  /** Logical inline-end content padding; overrides broader padding values. */
+  paddingInlineEnd?: SpacingStep;
+  /** Logical block-axis content padding; overrides `padding` on that axis. */
+  paddingBlock?: SpacingStep;
+  /** Logical block-start content padding; overrides broader padding values. */
+  paddingBlockStart?: SpacingStep;
+  /** Logical block-end content padding; overrides broader padding values. */
+  paddingBlockEnd?: SpacingStep;
+  /** Let the viewport escape inherited container padding. @default false */
+  isFullBleed?: boolean;
+  /** Ref connected to the native scroll viewport. */
+  ref?: React.Ref<HTMLDivElement>;
+}
+
+/**
+ * A native scroll viewport with axis-aware accessibility and chaining.
+ *
+ * The root is the viewport. Its single child is a normal block content box with
+ * a 100% minimum size; children participate in that box rather than directly in
+ * viewport flex/grid layout. Inline scrolling gives the box max-content inline
+ * sizing, and its minimum block size deliberately does not create a definite
+ * percentage-height basis. Use the hook on owned structure when those formatting
+ * semantics must stay unchanged. Native scrolling and platform scrollbars remain
+ * authoritative.
+ *
+ * @example
+ * ```
+ * <ScrollableArea axis="block" label="Activity history">
+ *   <ActivityList />
+ * </ScrollableArea>
+ * ```
+ */
+export function ScrollableArea({
+  children,
+  axis = 'block',
+  label,
+  role = 'group',
+  overscroll = 'allow',
+  width,
+  height,
+  maxWidth,
+  minHeight,
+  stickyContainment = 'whenScrollable',
+  padding = 0,
+  paddingInline,
+  paddingInlineStart,
+  paddingInlineEnd,
+  paddingBlock,
+  paddingBlockStart,
+  paddingBlockEnd,
+  isFullBleed = false,
+  ref,
+  xstyle,
+  className,
+  style,
+  ...props
+}: ScrollableAreaProps) {
+  const {getViewportProps, getContentProps} = useScrollableArea({
+    axis,
+    keyboardAccess: {owner: 'viewport', label, role},
+    overscroll,
+    stickyContainment,
+  });
+
+  const mergedViewportProps = mergeProps(
+    themeProps('scrollable-area', {axis}),
+    stylex.props(
+      styles.viewport,
+      isFullBleed && styles.fullBleed,
+      focusOutlineStyles.focusVisible,
+      dynamicStyles.sizing(
+        width ?? null,
+        height ?? null,
+        maxWidth ?? null,
+        minHeight ?? null,
+      ),
+      xstyle,
+    ),
+    className,
+    style,
+  );
+  const viewportProps = getViewportProps<HTMLDivElement>({
+    ...props,
+    ref,
+    ...mergedViewportProps,
+  });
+
+  return (
+    <div {...viewportProps}>
+      <div
+        {...getContentProps<HTMLDivElement>({
+          ...stylex.props(
+            styles.content,
+            axis !== 'block' && styles.contentWithInlineOverflow,
+            paddingStyles[padding],
+            containerPaddingInlineVarStyles[padding],
+            containerPaddingBlockStartVarStyles[padding],
+            containerPaddingBlockEndVarStyles[padding],
+            paddingInline != null && paddingInlineStyles[paddingInline],
+            paddingInline != null &&
+              containerPaddingInlineVarStyles[paddingInline],
+            paddingBlock != null && paddingBlockStyles[paddingBlock],
+            paddingBlock != null &&
+              containerPaddingBlockStartVarStyles[paddingBlock],
+            paddingBlock != null &&
+              containerPaddingBlockEndVarStyles[paddingBlock],
+            paddingInlineStart != null &&
+              paddingInlineStartStyles[paddingInlineStart],
+            paddingInlineStart != null &&
+              containerPaddingInlineStartVarStyles[paddingInlineStart],
+            paddingInlineEnd != null &&
+              paddingInlineEndStyles[paddingInlineEnd],
+            paddingInlineEnd != null &&
+              containerPaddingInlineEndVarStyles[paddingInlineEnd],
+            paddingBlockStart != null &&
+              paddingBlockStartStyles[paddingBlockStart],
+            paddingBlockStart != null &&
+              containerPaddingBlockStartVarStyles[paddingBlockStart],
+            paddingBlockEnd != null && paddingBlockEndStyles[paddingBlockEnd],
+            paddingBlockEnd != null &&
+              containerPaddingBlockEndVarStyles[paddingBlockEnd],
+          ),
+        })}>
+        {children}
+      </div>
+    </div>
+  );
+}
+
+ScrollableArea.displayName = 'ScrollableArea';

package/src/ScrollableArea/index.ts

@@ -0,0 +1,26 @@
+// Copyright (c) Meta Platforms, Inc. and affiliates.
+
+/**
+ * @file index.ts
+ * @input ScrollableArea implementation and shared hook types
+ * @output Public ScrollableArea package surface
+ * @position Package entry point for ScrollableArea
+ */
+
+export {ScrollableArea} from './ScrollableArea';
+export type {
+  ScrollableAreaProps,
+  ScrollableAreaStickyContainment,
+} from './ScrollableArea';
+export {useScrollableArea} from '../hooks/useScrollableArea';
+export type {
+  ScrollAxis,
+  ScrollAxisState,
+  ScrollOverscroll,
+  ScrollStickyContainment,
+  ScrollKeyboardAccess,
+  ScrollableAreaState,
+  ScrollableElementProps,
+  UseScrollableAreaOptions,
+  UseScrollableAreaResult,
+} from '../hooks/useScrollableArea';