@ankhorage/zora 3.2.0 → 3.3.1

package/src/patterns/content-rail/ContentRail.tsx

@@ -0,0 +1,245 @@
+import React from 'react';
+import {
+  I18nManager,
+  type NativeScrollEvent,
+  type NativeSyntheticEvent,
+  ScrollView,
+  type ViewStyle,
+} from 'react-native';
+
+import { IconButton } from '../../components/icon-button';
+import { Text } from '../../components/text';
+import { Box, Inline, Stack } from '../../foundation';
+import { useZoraTheme } from '../../theme/useZoraTheme';
+import { withZoraThemeScope } from '../../theme/withZoraThemeScope';
+import { resolveContentRailItemWidth } from './resolveContentRailItemWidth';
+import { resolveContentRailPhysicalOffset } from './resolveContentRailPhysicalOffset';
+import { resolveContentRailState } from './resolveContentRailState';
+import type { ContentRailProps, ContentRailVisibleRangeChangeEvent } from './types';
+import { useContentRailReducedMotion } from './useContentRailReducedMotion';
+
+function ContentRailInner({
+  themeId: _themeId,
+  mode: _mode,
+  interactionPolicy,
+  children,
+  itemSize = 'responsive',
+  gap = 'm',
+  padding = 'm',
+  peek = 32,
+  showControls = true,
+  direction = 'auto',
+  motion = 'system',
+  accessibilityLabel = 'Content rail',
+  previousLabel = 'Previous items',
+  nextLabel = 'Next items',
+  onControlPress,
+  onVisibleRangeChange,
+  testID,
+}: ContentRailProps) {
+  const { theme } = useZoraTheme();
+  const items = React.Children.toArray(children);
+  const scrollViewRef = React.useRef<ScrollView>(null);
+  const lastRangeRef = React.useRef<ContentRailVisibleRangeChangeEvent | null>(null);
+  const logicalOffsetRef = React.useRef(0);
+  const rtlInitializedRef = React.useRef(false);
+  const [viewportWidth, setViewportWidth] = React.useState(0);
+  const [contentWidth, setContentWidth] = React.useState(0);
+  const [logicalOffset, setLogicalOffset] = React.useState(0);
+  const reducedMotion = useContentRailReducedMotion(motion);
+  const isRtl = direction === 'rtl' || (direction === 'auto' && I18nManager.isRTL);
+  const gapValue = resolveSpacingValue(theme.spacing, gap);
+  const paddingValue = resolveSpacingValue(theme.spacing, padding);
+  const itemWidth = resolveContentRailItemWidth({
+    gap: gapValue,
+    itemCount: items.length,
+    itemSize,
+    padding: paddingValue,
+    peek,
+    viewportWidth,
+  });
+  const railState = resolveContentRailState({
+    contentWidth,
+    gap: gapValue,
+    itemCount: items.length,
+    itemWidth,
+    logicalOffset,
+    viewportWidth,
+  });
+  const passive = interactionPolicy === 'passive';
+  const hasOverflow = railState.maxOffset > 1;
+
+  const emitVisibleRange = React.useCallback(
+    (nextOffset: number) => {
+      const next = resolveContentRailState({
+        contentWidth,
+        gap: gapValue,
+        itemCount: items.length,
+        itemWidth,
+        logicalOffset: nextOffset,
+        viewportWidth,
+      });
+      const event = {
+        firstVisibleIndex: next.firstVisibleIndex,
+        lastVisibleIndex: next.lastVisibleIndex,
+        itemCount: items.length,
+      };
+      const previous = lastRangeRef.current;
+      if (
+        previous?.firstVisibleIndex === event.firstVisibleIndex &&
+        previous.lastVisibleIndex === event.lastVisibleIndex &&
+        previous.itemCount === event.itemCount
+      ) {
+        return;
+      }
+      lastRangeRef.current = event;
+      void onVisibleRangeChange?.(event);
+    },
+    [contentWidth, gapValue, itemWidth, items.length, onVisibleRangeChange, viewportWidth],
+  );
+
+  React.useEffect(() => {
+    emitVisibleRange(railState.offset);
+  }, [emitVisibleRange, railState.offset]);
+
+  React.useEffect(() => {
+    rtlInitializedRef.current = !isRtl;
+  }, [isRtl]);
+
+  React.useEffect(() => {
+    if (viewportWidth === 0 || contentWidth === 0) return;
+    const nextOffset = Math.min(logicalOffsetRef.current, railState.maxOffset);
+    scrollViewRef.current?.scrollTo({
+      animated: false,
+      x: resolveContentRailPhysicalOffset({
+        isRtl,
+        logicalOffset: nextOffset,
+        maxOffset: railState.maxOffset,
+      }),
+      y: 0,
+    });
+    rtlInitializedRef.current = true;
+  }, [contentWidth, isRtl, itemWidth, railState.maxOffset, viewportWidth]);
+
+  const scrollToIndex = (targetIndex: number, controlDirection: 'previous' | 'next') => {
+    if (passive || !hasOverflow) return;
+    const clampedIndex = Math.min(Math.max(0, targetIndex), Math.max(0, items.length - 1));
+    const targetOffset = Math.min(clampedIndex * railState.stride, railState.maxOffset);
+    logicalOffsetRef.current = targetOffset;
+    setLogicalOffset(targetOffset);
+    scrollViewRef.current?.scrollTo({
+      animated: !reducedMotion,
+      x: resolveContentRailPhysicalOffset({
+        isRtl,
+        logicalOffset: targetOffset,
+        maxOffset: railState.maxOffset,
+      }),
+      y: 0,
+    });
+    emitVisibleRange(targetOffset);
+    void onControlPress?.({ direction: controlDirection, targetIndex: clampedIndex });
+  };
+
+  const handleScroll = (event: NativeSyntheticEvent<NativeScrollEvent>) => {
+    if (isRtl && !rtlInitializedRef.current) return;
+    const physicalOffset = event.nativeEvent.contentOffset.x;
+    const nextOffset = resolveContentRailPhysicalOffset({
+      isRtl,
+      logicalOffset: physicalOffset,
+      maxOffset: railState.maxOffset,
+    });
+    const clampedOffset = Math.min(Math.max(0, nextOffset), railState.maxOffset);
+    logicalOffsetRef.current = clampedOffset;
+    setLogicalOffset(clampedOffset);
+    emitVisibleRange(clampedOffset);
+  };
+
+  const rangeLabel =
+    items.length === 0
+      ? 'No items'
+      : `Items ${railState.firstVisibleIndex + 1}–${railState.lastVisibleIndex + 1} of ${items.length}`;
+  const contentStyle: ViewStyle = {
+    direction: isRtl ? 'rtl' : 'ltr',
+    flexDirection: 'row',
+    gap: gapValue,
+    paddingHorizontal: paddingValue,
+  };
+
+  return (
+    <Stack gap="s" testID={testID}>
+      {showControls && hasOverflow ? (
+        <Inline justify="space-between" wrap="nowrap">
+          <Text accessibilityLiveRegion="polite" emphasis="muted" variant="caption">
+            {rangeLabel}
+          </Text>
+          <Inline gap="xs" wrap="nowrap">
+            <IconButton
+              disabled={passive || !railState.canGoPrevious}
+              icon={{ name: isRtl ? 'chevron-forward' : 'chevron-back' }}
+              interactionPolicy={interactionPolicy}
+              label={previousLabel}
+              onPress={() => scrollToIndex(railState.anchorIndex - 1, 'previous')}
+              size="l"
+            />
+            <IconButton
+              disabled={passive || !railState.canGoNext}
+              icon={{ name: isRtl ? 'chevron-back' : 'chevron-forward' }}
+              interactionPolicy={interactionPolicy}
+              label={nextLabel}
+              onPress={() => scrollToIndex(railState.anchorIndex + 1, 'next')}
+              size="l"
+            />
+          </Inline>
+        </Inline>
+      ) : null}
+      <ScrollView
+        accessibilityLabel={accessibilityLabel}
+        accessibilityRole="list"
+        contentContainerStyle={contentStyle}
+        decelerationRate="fast"
+        disableIntervalMomentum
+        horizontal
+        onContentSizeChange={(width) => {
+          if (isRtl) rtlInitializedRef.current = false;
+          setContentWidth(width);
+        }}
+        onLayout={(event) => {
+          if (isRtl) rtlInitializedRef.current = false;
+          setViewportWidth(event.nativeEvent.layout.width);
+        }}
+        onScroll={handleScroll}
+        ref={scrollViewRef}
+        scrollEnabled={!passive}
+        scrollEventThrottle={16}
+        showsHorizontalScrollIndicator={false}
+        snapToInterval={itemWidth > 0 ? itemWidth + gapValue : undefined}
+      >
+        {items.map((item, index) => (
+          <Box key={index} style={{ flexShrink: 0, width: itemWidth || undefined }}>
+            {item}
+          </Box>
+        ))}
+      </ScrollView>
+    </Stack>
+  );
+}
+
+/**
+ * Horizontally browsable, manifest-authorable content with responsive item sizing.
+ *
+ * ContentRail owns only presentation and scrolling. Apps retain ownership of item data,
+ * navigation, recommendations, and route behavior.
+ */
+export const ContentRail = withZoraThemeScope(ContentRailInner);
+
+function resolveSpacingValue(
+  spacing: { none: number; xs: number; s: number; m: number; l: number; xl: number },
+  token: NonNullable<ContentRailProps['gap']>,
+): number {
+  if (token === 'none') return spacing.none;
+  if (token === 'xs') return spacing.xs;
+  if (token === 's') return spacing.s;
+  if (token === 'l') return spacing.l;
+  if (token === 'xl') return spacing.xl;
+  return spacing.m;
+}

package/src/patterns/content-rail/index.ts

@@ -0,0 +1,10 @@
+export { ContentRail } from './ContentRail';
+export type {
+  ContentRailControlPressEvent,
+  ContentRailDirection,
+  ContentRailItemSize,
+  ContentRailMotion,
+  ContentRailProps,
+  ContentRailSpacing,
+  ContentRailVisibleRangeChangeEvent,
+} from './types';

package/src/patterns/content-rail/meta.ts

@@ -0,0 +1,133 @@
+import type { ZoraComponentMeta } from '../../metadata';
+import { CONTENT_RAIL_ALLOWED_CHILDREN } from '../../metadata/allowedChildren';
+
+const spacingValues = ['none', 'xs', 's', 'm', 'l', 'xl'] as const;
+
+export const contentRailMeta = {
+  name: 'ContentRail',
+  category: 'pattern',
+  description:
+    'Horizontally browsable child content with responsive sizing, partial-next affordance, and accessible controls.',
+  directManifestNode: true,
+  allowedChildren: [...CONTENT_RAIL_ALLOWED_CHILDREN],
+  blueprint: {
+    label: 'Content rail',
+    icon: { name: 'albums-outline' },
+    defaultProps: {
+      itemSize: 'responsive',
+      gap: 'm',
+      padding: 'm',
+      peek: 32,
+      showControls: true,
+      direction: 'auto',
+      motion: 'system',
+      accessibilityLabel: 'Content rail',
+      previousLabel: 'Previous items',
+      nextLabel: 'Next items',
+    },
+  },
+  events: {
+    controlPress: {
+      label: 'Control press',
+      eventType: 'contentRail.controlPress',
+      description: 'Emitted after a previous or next control requests a target item.',
+      payloadFields: [
+        { path: 'direction', type: 'string', label: 'Direction' },
+        { path: 'targetIndex', type: 'number', label: 'Target index' },
+      ],
+    },
+    visibleRangeChange: {
+      label: 'Visible range change',
+      eventType: 'contentRail.visibleRangeChange',
+      description: 'Emitted when the zero-based visible item range changes.',
+      payloadFields: [
+        { path: 'firstVisibleIndex', type: 'number', label: 'First visible index' },
+        { path: 'lastVisibleIndex', type: 'number', label: 'Last visible index' },
+        { path: 'itemCount', type: 'number', label: 'Item count' },
+      ],
+    },
+  },
+  slots: {
+    children: {
+      label: 'Rail items',
+      allowedChildren: [...CONTENT_RAIL_ALLOWED_CHILDREN],
+    },
+  },
+  props: {
+    itemSize: {
+      type: 'enum',
+      category: 'Layout',
+      label: 'Item size',
+      enum: ['compact', 'regular', 'wide', 'responsive'],
+      default: 'responsive',
+    },
+    gap: {
+      type: 'enum',
+      category: 'Layout',
+      label: 'Gap',
+      enum: spacingValues,
+      default: 'm',
+    },
+    padding: {
+      type: 'enum',
+      category: 'Layout',
+      label: 'Horizontal padding',
+      enum: spacingValues,
+      default: 'm',
+    },
+    peek: {
+      type: 'number',
+      category: 'Layout',
+      label: 'Partial next item',
+      default: 32,
+    },
+    showControls: {
+      type: 'boolean',
+      category: 'Controls',
+      label: 'Show controls',
+      default: true,
+    },
+    direction: {
+      type: 'enum',
+      category: 'Layout',
+      label: 'Reading direction',
+      enum: ['auto', 'ltr', 'rtl'],
+      default: 'auto',
+    },
+    motion: {
+      type: 'enum',
+      category: 'Accessibility',
+      label: 'Motion',
+      enum: ['system', 'animated', 'reduced'],
+      default: 'system',
+    },
+    accessibilityLabel: {
+      type: 'string',
+      category: 'Accessibility',
+      label: 'Rail label',
+      default: 'Content rail',
+    },
+    previousLabel: {
+      type: 'string',
+      category: 'Accessibility',
+      label: 'Previous control label',
+      default: 'Previous items',
+    },
+    nextLabel: {
+      type: 'string',
+      category: 'Accessibility',
+      label: 'Next control label',
+      default: 'Next items',
+    },
+    onControlPress: {
+      type: 'action',
+      category: 'Events',
+      label: 'Control press action',
+    },
+    onVisibleRangeChange: {
+      type: 'action',
+      category: 'Events',
+      label: 'Visible range change action',
+    },
+  },
+} as const satisfies ZoraComponentMeta;

package/src/patterns/content-rail/resolveContentRailItemWidth.test.ts

@@ -0,0 +1,77 @@
+import { describe, expect, test } from 'bun:test';
+
+import { resolveContentRailItemWidth } from './resolveContentRailItemWidth';
+
+describe('resolveContentRailItemWidth', () => {
+  test('keeps fixed item sizes within the available viewport', () => {
+    expect(
+      resolveContentRailItemWidth({
+        gap: 16,
+        itemCount: 4,
+        itemSize: 'regular',
+        padding: 16,
+        peek: 32,
+        viewportWidth: 500,
+      }),
+    ).toBe(200);
+    expect(
+      resolveContentRailItemWidth({
+        gap: 16,
+        itemCount: 4,
+        itemSize: 'wide',
+        padding: 16,
+        peek: 32,
+        viewportWidth: 240,
+      }),
+    ).toBe(208);
+  });
+
+  test('reserves a deterministic partial-next affordance at responsive breakpoints', () => {
+    expect(
+      resolveContentRailItemWidth({
+        gap: 16,
+        itemCount: 5,
+        itemSize: 'responsive',
+        padding: 16,
+        peek: 32,
+        viewportWidth: 500,
+      }),
+    ).toBe(202);
+    expect(
+      resolveContentRailItemWidth({
+        gap: 16,
+        itemCount: 5,
+        itemSize: 'responsive',
+        padding: 16,
+        peek: 32,
+        viewportWidth: 800,
+      }),
+    ).toBe(229);
+  });
+
+  test('removes the peek and distributes items predictably when content fits', () => {
+    expect(
+      resolveContentRailItemWidth({
+        gap: 16,
+        itemCount: 2,
+        itemSize: 'responsive',
+        padding: 16,
+        peek: 32,
+        viewportWidth: 800,
+      }),
+    ).toBe(280);
+  });
+
+  test('handles empty and unmeasured rails', () => {
+    expect(
+      resolveContentRailItemWidth({
+        gap: 16,
+        itemCount: 0,
+        itemSize: 'responsive',
+        padding: 16,
+        peek: 32,
+        viewportWidth: 500,
+      }),
+    ).toBe(0);
+  });
+});

package/src/patterns/content-rail/resolveContentRailItemWidth.ts

@@ -0,0 +1,39 @@
+import type { ContentRailItemSize } from './types';
+
+export function resolveContentRailItemWidth({
+  gap,
+  itemCount,
+  itemSize,
+  padding,
+  peek,
+  viewportWidth,
+}: {
+  gap: number;
+  itemCount: number;
+  itemSize: ContentRailItemSize;
+  padding: number;
+  peek: number;
+  viewportWidth: number;
+}): number {
+  const availableWidth = Math.max(0, viewportWidth - padding * 2);
+  if (availableWidth === 0 || itemCount === 0) return 0;
+
+  const fixedWidth = resolveFixedItemWidth(itemSize);
+  if (fixedWidth !== undefined) return Math.min(fixedWidth, availableWidth);
+
+  const slots = viewportWidth >= 1024 ? 4 : viewportWidth >= 768 ? 3 : viewportWidth >= 480 ? 2 : 1;
+  const fullItems = Math.min(slots, itemCount);
+  const overflows = itemCount > fullItems;
+  const resolvedPeek = overflows ? Math.min(Math.max(0, peek), availableWidth / 2) : 0;
+  const gaps = overflows ? fullItems : Math.max(0, fullItems - 1);
+  const resolved = (availableWidth - resolvedPeek - gap * gaps) / fullItems;
+
+  return Math.min(280, Math.max(Math.min(96, availableWidth), Math.floor(resolved)));
+}
+
+function resolveFixedItemWidth(itemSize: ContentRailItemSize): number | undefined {
+  if (itemSize === 'compact') return 144;
+  if (itemSize === 'regular') return 200;
+  if (itemSize === 'wide') return 280;
+  return undefined;
+}

package/src/patterns/content-rail/resolveContentRailPhysicalOffset.test.ts

@@ -0,0 +1,29 @@
+import { describe, expect, test } from 'bun:test';
+
+import { resolveContentRailPhysicalOffset } from './resolveContentRailPhysicalOffset';
+
+describe('resolveContentRailPhysicalOffset', () => {
+  test('keeps logical and physical offsets aligned for LTR content', () => {
+    expect(
+      resolveContentRailPhysicalOffset({ isRtl: false, logicalOffset: 216, maxOffset: 648 }),
+    ).toBe(216);
+  });
+
+  test('inverts offsets for RTL while preserving logical boundaries', () => {
+    expect(
+      resolveContentRailPhysicalOffset({ isRtl: true, logicalOffset: 0, maxOffset: 648 }),
+    ).toBe(648);
+    expect(
+      resolveContentRailPhysicalOffset({ isRtl: true, logicalOffset: 216, maxOffset: 648 }),
+    ).toBe(432);
+    expect(
+      resolveContentRailPhysicalOffset({ isRtl: true, logicalOffset: 648, maxOffset: 648 }),
+    ).toBe(0);
+  });
+
+  test('clamps offsets rather than wrapping', () => {
+    expect(
+      resolveContentRailPhysicalOffset({ isRtl: true, logicalOffset: 900, maxOffset: 648 }),
+    ).toBe(0);
+  });
+});

package/src/patterns/content-rail/resolveContentRailPhysicalOffset.ts

@@ -0,0 +1,12 @@
+export function resolveContentRailPhysicalOffset({
+  isRtl,
+  logicalOffset,
+  maxOffset,
+}: {
+  isRtl: boolean;
+  logicalOffset: number;
+  maxOffset: number;
+}): number {
+  const clampedOffset = Math.min(Math.max(0, logicalOffset), Math.max(0, maxOffset));
+  return isRtl ? Math.max(0, maxOffset) - clampedOffset : clampedOffset;
+}

package/src/patterns/content-rail/resolveContentRailState.test.ts

@@ -0,0 +1,68 @@
+import { describe, expect, test } from 'bun:test';
+
+import { resolveContentRailState } from './resolveContentRailState';
+
+describe('resolveContentRailState', () => {
+  test('resolves overflow, visible items, and the nearest navigation anchor', () => {
+    expect(
+      resolveContentRailState({
+        contentWidth: 848,
+        gap: 16,
+        itemCount: 4,
+        itemWidth: 200,
+        logicalOffset: 216,
+        viewportWidth: 432,
+      }),
+    ).toEqual({
+      anchorIndex: 1,
+      canGoNext: true,
+      canGoPrevious: true,
+      firstVisibleIndex: 1,
+      lastVisibleIndex: 2,
+      maxOffset: 416,
+      offset: 216,
+      stride: 216,
+    });
+  });
+
+  test('clamps boundaries without wrapping', () => {
+    const start = resolveContentRailState({
+      contentWidth: 848,
+      gap: 16,
+      itemCount: 4,
+      itemWidth: 200,
+      logicalOffset: -100,
+      viewportWidth: 432,
+    });
+    const end = resolveContentRailState({
+      contentWidth: 848,
+      gap: 16,
+      itemCount: 4,
+      itemWidth: 200,
+      logicalOffset: 1000,
+      viewportWidth: 432,
+    });
+
+    expect(start).toMatchObject({ offset: 0, canGoPrevious: false, canGoNext: true });
+    expect(end).toMatchObject({ offset: 416, canGoPrevious: true, canGoNext: false });
+  });
+
+  test('degrades to a non-overflowing empty range', () => {
+    expect(
+      resolveContentRailState({
+        contentWidth: 0,
+        gap: 16,
+        itemCount: 0,
+        itemWidth: 0,
+        logicalOffset: 0,
+        viewportWidth: 432,
+      }),
+    ).toMatchObject({
+      canGoNext: false,
+      canGoPrevious: false,
+      firstVisibleIndex: -1,
+      lastVisibleIndex: -1,
+      maxOffset: 0,
+    });
+  });
+});

package/src/patterns/content-rail/resolveContentRailState.ts

@@ -0,0 +1,36 @@
+export function resolveContentRailState({
+  contentWidth,
+  gap,
+  itemCount,
+  itemWidth,
+  logicalOffset,
+  viewportWidth,
+}: {
+  contentWidth: number;
+  gap: number;
+  itemCount: number;
+  itemWidth: number;
+  logicalOffset: number;
+  viewportWidth: number;
+}) {
+  const maxOffset = Math.max(0, contentWidth - viewportWidth);
+  const offset = Math.min(Math.max(0, logicalOffset), maxOffset);
+  const stride = itemWidth + gap;
+  const firstVisibleIndex = stride > 0 ? Math.min(itemCount - 1, Math.floor(offset / stride)) : 0;
+  const lastVisibleIndex =
+    stride > 0
+      ? Math.min(itemCount - 1, Math.max(0, Math.ceil((offset + viewportWidth) / stride) - 1))
+      : 0;
+  const anchorIndex = stride > 0 ? Math.round(offset / stride) : 0;
+
+  return {
+    anchorIndex: Math.min(Math.max(0, anchorIndex), Math.max(0, itemCount - 1)),
+    canGoNext: itemCount > 0 && offset < maxOffset - 1,
+    canGoPrevious: itemCount > 0 && offset > 1,
+    firstVisibleIndex: itemCount === 0 ? -1 : firstVisibleIndex,
+    lastVisibleIndex: itemCount === 0 ? -1 : lastVisibleIndex,
+    maxOffset,
+    offset,
+    stride,
+  };
+}

package/src/patterns/content-rail/types.ts

@@ -0,0 +1,35 @@
+import type { ReactNode } from 'react';
+
+import type { ZoraBaseProps } from '../../theme/ZoraBaseProps';
+
+export type ContentRailDirection = 'auto' | 'ltr' | 'rtl';
+export type ContentRailItemSize = 'compact' | 'regular' | 'wide' | 'responsive';
+export type ContentRailMotion = 'system' | 'animated' | 'reduced';
+export type ContentRailSpacing = 'none' | 'xs' | 's' | 'm' | 'l' | 'xl';
+
+export interface ContentRailControlPressEvent {
+  direction: 'previous' | 'next';
+  targetIndex: number;
+}
+
+export interface ContentRailVisibleRangeChangeEvent {
+  firstVisibleIndex: number;
+  lastVisibleIndex: number;
+  itemCount: number;
+}
+
+export interface ContentRailProps extends ZoraBaseProps {
+  children?: ReactNode;
+  itemSize?: ContentRailItemSize;
+  gap?: ContentRailSpacing;
+  padding?: ContentRailSpacing;
+  peek?: number;
+  showControls?: boolean;
+  direction?: ContentRailDirection;
+  motion?: ContentRailMotion;
+  accessibilityLabel?: string;
+  previousLabel?: string;
+  nextLabel?: string;
+  onControlPress?: (event: ContentRailControlPressEvent) => void | Promise<void>;
+  onVisibleRangeChange?: (event: ContentRailVisibleRangeChangeEvent) => void | Promise<void>;
+}