@ankhorage/zora 3.2.0 → 3.3.2

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

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

@@ -0,0 +1,28 @@
+import React from 'react';
+import { AccessibilityInfo } from 'react-native';
+
+import type { ContentRailMotion } from './types';
+
+export function useContentRailReducedMotion(motion: ContentRailMotion): boolean {
+  const [systemReducedMotion, setSystemReducedMotion] = React.useState(false);
+
+  React.useEffect(() => {
+    if (motion !== 'system') return;
+
+    let active = true;
+    void AccessibilityInfo.isReduceMotionEnabled().then((enabled) => {
+      if (active) setSystemReducedMotion(enabled);
+    });
+    const subscription = AccessibilityInfo.addEventListener(
+      'reduceMotionChanged',
+      setSystemReducedMotion,
+    );
+
+    return () => {
+      active = false;
+      subscription.remove();
+    };
+  }, [motion]);
+
+  return motion === 'reduced' || (motion === 'system' && systemReducedMotion);
+}

package/src/patterns/missing-element/MissingElement.test.ts

@@ -0,0 +1,66 @@
+import { describe, expect, test } from 'bun:test';
+
+import { ZORA_BINDABLE_COMPONENT_META, ZORA_COMPONENT_META } from '../../metadata';
+import { missingElementMeta } from './meta';
+
+describe('MissingElement draft contract', () => {
+  test('is a release-blocking manifest leaf distinct from completed states', () => {
+    expect(ZORA_COMPONENT_META.MissingElement).toBe(missingElementMeta);
+    expect(missingElementMeta.directManifestNode).toBe(true);
+    expect(missingElementMeta.allowedChildren).toEqual([]);
+    expect(missingElementMeta.manifestPolicy).toEqual({
+      kind: 'unresolved-element',
+      availability: 'draft-only',
+      releaseGate: 'blocked',
+    });
+    expect(ZORA_COMPONENT_META.Notice.manifestPolicy).toBeUndefined();
+    expect(ZORA_COMPONENT_META.EmptyState.manifestPolicy).toBeUndefined();
+  });
+
+  test('captures only stable serializable gap and layout data', () => {
+    expect(Object.keys(missingElementMeta.props)).toEqual([
+      'requestedCapability',
+      'reason',
+      'evidenceId',
+      'minimumWidth',
+      'minimumHeight',
+    ]);
+    expect(missingElementMeta.blueprint.defaultProps).toEqual({
+      requestedCapability: 'Unresolved interface capability',
+      reason: 'No matching ZORA element is available.',
+      minimumWidth: 240,
+      minimumHeight: 160,
+    });
+    expect(() => JSON.stringify(missingElementMeta)).not.toThrow();
+  });
+
+  test('has no event, data-binding, runtime-requirement, or fallback contract', () => {
+    expect(missingElementMeta.events).toBeUndefined();
+    expect(missingElementMeta.requirements).toBeUndefined();
+    expect(ZORA_BINDABLE_COMPONENT_META).not.toHaveProperty('MissingElement');
+  });
+
+  test('visibly and accessibly identifies the gap while preserving its minimum dimensions', async () => {
+    const source = await Bun.file('src/patterns/missing-element/MissingElement.tsx').text();
+
+    expect(source).toContain('accessibilityLabel={accessibilityLabel}');
+    expect(source).toContain('accessibilityRole="text"');
+    expect(source).toContain('accessible');
+    expect(source).toContain('minHeight={minimumHeight}');
+    expect(source).toContain('minWidth={minimumWidth}');
+    expect(source).toContain('{requestedCapability}');
+    expect(source).toContain('{reason}');
+  });
+
+  test('accepts the canonical interaction policy without owning interactive behavior', async () => {
+    const [source, types] = await Promise.all([
+      Bun.file('src/patterns/missing-element/MissingElement.tsx').text(),
+      Bun.file('src/patterns/missing-element/types.ts').text(),
+    ]);
+
+    expect(types).toContain('MissingElementProps extends ZoraBaseProps');
+    expect(source).toContain('interactionPolicy: _interactionPolicy');
+    expect(source).not.toMatch(/onPress|onLongPress|onChange|onSubmit/);
+    expect(source).not.toMatch(/<Button|<IconButton|<Notice|<EmptyState/);
+  });
+});

package/src/patterns/missing-element/MissingElement.tsx

@@ -0,0 +1,73 @@
+import React from 'react';
+import { StyleSheet } from 'react-native';
+
+import { Badge } from '../../components/badge';
+import { Text } from '../../components/text';
+import { Box, Stack } from '../../foundation';
+import { useZoraTheme } from '../../theme/useZoraTheme';
+import { withZoraThemeScope } from '../../theme/withZoraThemeScope';
+import type { MissingElementProps } from './types';
+
+/***
+ * Renders the visible, non-interactive body of a draft missing-element marker.
+ */
+function MissingElementInner({
+  themeId: _themeId,
+  mode: _mode,
+  interactionPolicy: _interactionPolicy,
+  requestedCapability,
+  reason,
+  evidenceId,
+  minimumWidth,
+  minimumHeight,
+  testID,
+}: MissingElementProps) {
+  const { theme } = useZoraTheme();
+  const accessibilityLabel = `Missing element: ${requestedCapability}. ${reason}`;
+
+  return (
+    <Box
+      accessibilityLabel={accessibilityLabel}
+      accessibilityRole="text"
+      accessible
+      bg={theme.semantics.warning.softBg}
+      borderColor={theme.semantics.warning.base}
+      borderWidth={1}
+      minHeight={minimumHeight}
+      minWidth={minimumWidth}
+      p="m"
+      radius="m"
+      style={styles.root}
+      testID={testID}
+    >
+      <Stack gap="xs">
+        <Badge color="warning">Missing element</Badge>
+        <Text variant="label" weight="semiBold">
+          {requestedCapability}
+        </Text>
+        <Text emphasis="muted" variant="bodySmall">
+          {reason}
+        </Text>
+        {evidenceId ? (
+          <Text emphasis="subtle" variant="caption">
+            Evidence: {evidenceId}
+          </Text>
+        ) : null}
+      </Stack>
+    </Box>
+  );
+}
+
+const styles = StyleSheet.create({
+  root: {
+    borderStyle: 'dashed',
+  },
+});
+
+/***
+ * Draft-only marker that preserves an unsupported manifest region without faking its capability.
+ *
+ * `MissingElement` is intentionally non-interactive and release-blocking in component metadata.
+ * Replace it with a released semantic ZORA element before publishing a production template.
+ */
+export const MissingElement = withZoraThemeScope(MissingElementInner);

package/src/patterns/missing-element/index.ts

@@ -0,0 +1,2 @@
+export { MissingElement } from './MissingElement';
+export type { MissingElementProps } from './types';

package/src/patterns/missing-element/meta.ts

@@ -0,0 +1,62 @@
+import type { ZoraComponentMeta } from '../../metadata';
+
+const instanceAuthoring = { authority: 'instance' } as const;
+
+export const missingElementMeta = {
+  name: 'MissingElement',
+  category: 'pattern',
+  description:
+    'Draft-only marker for an unresolved semantic ZORA capability that must be replaced before release.',
+  directManifestNode: true,
+  allowedChildren: [],
+  manifestPolicy: {
+    kind: 'unresolved-element',
+    availability: 'draft-only',
+    releaseGate: 'blocked',
+  },
+  blueprint: {
+    label: 'Missing element',
+    defaultProps: {
+      requestedCapability: 'Unresolved interface capability',
+      reason: 'No matching ZORA element is available.',
+      minimumWidth: 240,
+      minimumHeight: 160,
+    },
+  },
+  props: {
+    requestedCapability: {
+      type: 'string',
+      category: 'Gap',
+      label: 'Requested capability',
+      default: 'Unresolved interface capability',
+      authoring: instanceAuthoring,
+    },
+    reason: {
+      type: 'string',
+      category: 'Gap',
+      label: 'Reason',
+      default: 'No matching ZORA element is available.',
+      authoring: instanceAuthoring,
+    },
+    evidenceId: {
+      type: 'string',
+      category: 'Evidence',
+      label: 'Evidence ID',
+      authoring: instanceAuthoring,
+    },
+    minimumWidth: {
+      type: 'number',
+      category: 'Layout',
+      label: 'Minimum width',
+      default: 240,
+      authoring: instanceAuthoring,
+    },
+    minimumHeight: {
+      type: 'number',
+      category: 'Layout',
+      label: 'Minimum height',
+      default: 160,
+      authoring: instanceAuthoring,
+    },
+  },
+} as const satisfies ZoraComponentMeta;

package/src/patterns/missing-element/types.ts

@@ -0,0 +1,9 @@
+import type { ZoraBaseProps } from '../../theme/ZoraBaseProps';
+
+export interface MissingElementProps extends ZoraBaseProps {
+  requestedCapability: string;
+  reason: string;
+  evidenceId?: string;
+  minimumWidth?: number;
+  minimumHeight?: number;
+}

package/src/registry.ts

@@ -72,6 +72,7 @@ import {
 import { ChatListItem } from './patterns/chat-list-item';
 import { CollectionEditor } from './patterns/collection-editor';
 import { ConfirmDialog } from './patterns/confirm-dialog';
+import { ContentRail } from './patterns/content-rail';
 import { DisclosureSection } from './patterns/disclosure-section';
 import { EmptyState } from './patterns/empty-state';
 import { FilterBar } from './patterns/filter-bar';
@@ -81,6 +82,7 @@ import { ImageUploadField } from './patterns/image-upload-field';
 import { InspectorField } from './patterns/inspector-field';
 import { List, ListRow, ListSection } from './patterns/list';
 import { MessageBubble } from './patterns/message-bubble';
+import { MissingElement } from './patterns/missing-element';
 import { Notice } from './patterns/notice';
 import { Panel } from './patterns/panel';
 import { PostCard } from './patterns/post-card';
@@ -206,6 +208,7 @@ const _ZORA_COMPONENT_REGISTRY = {
   ChatListItem,
   CollectionEditor,
   ConfirmDialog,
+  ContentRail,
   DisclosureSection,
   EmptyState,
   FilterBar,
@@ -217,6 +220,7 @@ const _ZORA_COMPONENT_REGISTRY = {
   ListRow,
   ListSection,
   MessageBubble,
+  MissingElement,
   Notice,
   Panel,
   PostCard,