@ankhorage/zora 3.1.1 → 3.3.1

package/src/metadata/componentMeta.test.ts

@@ -138,6 +138,7 @@ describe('ZORA_COMPONENT_META invariants', () => {
       'ScanOverlay',
       'ProductCard',
       'Progress',
+      'ProgressRing',
       'ReaderSurface',
     ]);
 
@@ -157,6 +158,7 @@ describe('ZORA_COMPONENT_META invariants', () => {
       'Grid',
       'Container',
       'BarcodeScannerView',
+      'ContentRail',
     ]);
 
     for (const [key, meta] of Object.entries(ZORA_COMPONENT_META)) {
@@ -211,6 +213,22 @@ describe('ZORA_COMPONENT_META invariants', () => {
     });
   });
 
+  test('ProgressRing is a direct manifest leaf with serializable center content', () => {
+    const progressRing = ZORA_COMPONENT_META.ProgressRing;
+
+    expect(progressRing.directManifestNode).toBe(true);
+    expect(progressRing.allowedChildren).toEqual([]);
+    expect(progressRing.blueprint?.defaultProps).toMatchObject({
+      centerLabel: 'Complete',
+      centerValue: '68%',
+      max: 100,
+      value: 68,
+    });
+    expect(progressRing.props.centerValue?.type).toBe('string');
+    expect(progressRing.props.centerLabel?.type).toBe('string');
+    expect(progressRing.props.accessibilityValueText?.type).toBe('string');
+  });
+
   test('ReaderSurface exposes a safe file-media blueprint and normalized events', () => {
     const reader = ZORA_COMPONENT_META.ReaderSurface;
 
@@ -240,6 +258,39 @@ describe('ZORA_COMPONENT_META invariants', () => {
     expect(reader.events?.readerError?.eventType).toBe('reader.error');
   });
 
+  test('ContentRail exposes manifest children, serializable controls, and normalized events', () => {
+    const rail = ZORA_COMPONENT_META.ContentRail;
+
+    expect(rail.directManifestNode).toBe(true);
+    expect(rail.allowedChildren).toEqual([
+      'Box',
+      'Stack',
+      'Card',
+      'Panel',
+      'Image',
+      'ProductCard',
+      'PostCard',
+      'ChatListItem',
+      'MessageBubble',
+    ]);
+    expect(rail.slots?.children?.allowedChildren).toEqual(rail.allowedChildren);
+    expect(rail.blueprint?.defaultProps).toEqual({
+      itemSize: 'responsive',
+      gap: 'm',
+      padding: 'm',
+      peek: 32,
+      showControls: true,
+      direction: 'auto',
+      motion: 'system',
+      accessibilityLabel: 'Content rail',
+      previousLabel: 'Previous items',
+      nextLabel: 'Next items',
+    });
+    expect(rail.events?.controlPress?.eventType).toBe('contentRail.controlPress');
+    expect(rail.events?.visibleRangeChange?.eventType).toBe('contentRail.visibleRangeChange');
+    expect(rail.requirements).toBeUndefined();
+  });
+
   test('non-direct manifest nodes include an explicit note', () => {
     for (const [key, meta] of Object.entries(ZORA_COMPONENT_META)) {
       if (meta.directManifestNode) continue;

package/src/metadata/componentMeta.ts

@@ -27,7 +27,7 @@ import { modalMeta } from '../components/modal/meta';
 import { navigationItemMeta } from '../components/navigation-item/meta';
 import { navigationListMeta } from '../components/navigation-list/meta';
 import { paginationMeta } from '../components/pagination/meta';
-import { progressMeta } from '../components/progress/meta';
+import { progressMeta, progressRingMeta } from '../components/progress/meta';
 import { radioGroupMeta, radioMeta } from '../components/radio/meta';
 import { ratingMeta } from '../components/rating/meta';
 import { searchBarMeta } from '../components/search-bar/meta';
@@ -63,6 +63,7 @@ import {
 import { chatListItemMeta } from '../patterns/chat-list-item/meta';
 import { collectionEditorMeta } from '../patterns/collection-editor/meta';
 import { confirmDialogMeta } from '../patterns/confirm-dialog/meta';
+import { contentRailMeta } from '../patterns/content-rail/meta';
 import { disclosureSectionMeta } from '../patterns/disclosure-section/meta';
 import { emptyStateMeta } from '../patterns/empty-state/meta';
 import { filterBarMeta } from '../patterns/filter-bar/meta';
@@ -134,6 +135,7 @@ export const ZORA_COMPONENT_META: ZoraComponentMetaRegistry = {
   NavigationList: navigationListMeta,
   Pagination: paginationMeta,
   Progress: progressMeta,
+  ProgressRing: progressRingMeta,
   Radio: radioMeta,
   RadioGroup: radioGroupMeta,
   Rating: ratingMeta,
@@ -168,6 +170,7 @@ export const ZORA_COMPONENT_META: ZoraComponentMetaRegistry = {
   ChatListItem: chatListItemMeta,
   CollectionEditor: collectionEditorMeta,
   ConfirmDialog: confirmDialogMeta,
+  ContentRail: contentRailMeta,
   DisclosureSection: disclosureSectionMeta,
   EmptyState: emptyStateMeta,
   FilterBar: filterBarMeta,

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

@@ -0,0 +1,44 @@
+import { describe, expect, test } from 'bun:test';
+
+import type {
+  ContentRailControlPressEvent,
+  ContentRailProps,
+  ContentRailVisibleRangeChangeEvent,
+} from '../../index';
+
+describe('ContentRail public contract', () => {
+  test('exports serializable manifest and event inputs from the package root', () => {
+    const props: ContentRailProps = {
+      direction: 'rtl',
+      gap: 'm',
+      itemSize: 'responsive',
+      motion: 'reduced',
+      padding: 'm',
+      peek: 32,
+      showControls: true,
+    };
+    const control: ContentRailControlPressEvent = { direction: 'next', targetIndex: 2 };
+    const range: ContentRailVisibleRangeChangeEvent = {
+      firstVisibleIndex: 1,
+      lastVisibleIndex: 3,
+      itemCount: 6,
+    };
+
+    expect(() => JSON.stringify(props)).not.toThrow();
+    expect(() => JSON.stringify(control)).not.toThrow();
+    expect(() => JSON.stringify(range)).not.toThrow();
+  });
+
+  test('keeps product data, navigation, and platform coupling outside the pattern', async () => {
+    const source = await Bun.file('src/patterns/content-rail/ContentRail.tsx').text();
+
+    expect(source).toContain('ScrollView');
+    expect(source).toContain('I18nManager.isRTL');
+    expect(source).toContain('accessibilityRole="list"');
+    expect(source).toContain('reducedMotion');
+    expect(source).toContain('accessibilityLiveRegion="polite"');
+    expect(source).not.toContain('expo-');
+    expect(source).not.toContain('fetch(');
+    expect(source).not.toContain('router');
+  });
+});

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);
+  });
+});