@ankhorage/zora 6.0.0 → 8.0.0

package/src/features/layout/contentRailMeta.ts

@@ -0,0 +1,134 @@
+import type { ZoraComponentMeta } from '../../metadata';
+import { CONTENT_RAIL_ALLOWED_CHILDREN } from '../../metadata/allowedChildren';
+import { CONTENT_RAIL_SPACING_VALUES } from './constants';
+
+export const contentRailMeta = {
+  name: 'ContentRail',
+  category: 'pattern',
+  description:
+    'Native horizontal ScrollView: sized cards with controls, or intrinsic-width content with itemSize="content". The content mode has no snapping, controls, or visible-range events. Use ChipGroup wrap=false for a single scrolling row.',
+  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: {
+    bounces: { type: 'boolean', category: 'Behavior', label: 'Bounce (iOS)' },
+    showsScrollIndicator: { type: 'boolean', category: 'Style', label: 'Show scroll indicator' },
+    itemSize: {
+      type: 'enum',
+      category: 'Layout',
+      label: 'Item size',
+      enum: ['compact', 'regular', 'wide', 'responsive', 'content'],
+      default: 'responsive',
+    },
+    gap: {
+      type: 'enum',
+      category: 'Layout',
+      label: 'Gap',
+      enum: CONTENT_RAIL_SPACING_VALUES,
+      default: 'm',
+    },
+    padding: {
+      type: 'enum',
+      category: 'Layout',
+      label: 'Horizontal padding',
+      enum: CONTENT_RAIL_SPACING_VALUES,
+      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/features/layout/dividerMeta.ts

@@ -0,0 +1,17 @@
+import type { ZoraComponentMeta } from '../../metadata/types';
+import { LAYOUT_PROPS } from './constants';
+
+export const dividerMeta = {
+  name: 'Divider',
+  category: 'foundation',
+  directManifestNode: true,
+  allowedChildren: [],
+  props: {
+    ...Object.fromEntries(
+      Object.entries(LAYOUT_PROPS).filter(([key]) => key !== 'width' && key !== 'height'),
+    ),
+    orientation: { type: 'enum', category: 'Layout', enum: ['horizontal', 'vertical'] },
+    color: { type: 'color', category: 'Style' },
+    thickness: { type: 'number', category: 'Layout' },
+  },
+} as const satisfies ZoraComponentMeta;

package/src/features/layout/gridMeta.ts

@@ -0,0 +1,18 @@
+import { CONTAINER_ALLOWED_CHILDREN } from '../../metadata/allowedChildren';
+import type { ZoraComponentMeta } from '../../metadata/types';
+import { LAYOUT_PROPS } from './constants';
+
+export const gridMeta = {
+  name: 'Grid',
+  category: 'foundation',
+  directManifestNode: true,
+  allowedChildren: [...CONTAINER_ALLOWED_CHILDREN],
+  props: {
+    ...LAYOUT_PROPS,
+    cols: { type: 'number', category: 'Layout', default: 1 },
+    gap: { type: 'spacing', category: 'Spacing' },
+    rowGap: { type: 'spacing', category: 'Spacing' },
+    colGap: { type: 'spacing', category: 'Spacing' },
+    minItemWidth: { type: 'number', category: 'Layout' },
+  },
+} as const satisfies ZoraComponentMeta;

package/src/features/layout/public.ts

@@ -0,0 +1,22 @@
+export type {
+  ContentRailControlPressEvent,
+  ContentRailDirection,
+  ContentRailItemSize,
+  ContentRailMotion,
+  ContentRailProps,
+  ContentRailSpacing,
+  ContentRailVisibleRangeChangeEvent,
+} from '../../types/content-rail';
+export type {
+  BoxProps,
+  ContainerProps,
+  DividerProps,
+  GridProps,
+  StackProps,
+} from '../../types/layout';
+export { Box } from './adapters/inbound/Box';
+export { Container } from './adapters/inbound/Container';
+export { ContentRail } from './adapters/inbound/ContentRail';
+export { Divider } from './adapters/inbound/Divider';
+export { Grid } from './adapters/inbound/Grid';
+export { Stack } from './adapters/inbound/Stack';

package/src/features/layout/stackMeta.ts

@@ -0,0 +1,26 @@
+import { CONTAINER_ALLOWED_CHILDREN } from '../../metadata/allowedChildren';
+import type { ZoraComponentMeta } from '../../metadata/types';
+import { LAYOUT_PROPS } from './constants';
+
+export const stackMeta = {
+  name: 'Stack',
+  category: 'foundation',
+  directManifestNode: true,
+  allowedChildren: [...CONTAINER_ALLOWED_CHILDREN],
+  props: {
+    ...LAYOUT_PROPS,
+    direction: { type: 'enum', category: 'Layout', enum: ['row', 'column'] },
+    gap: { type: 'spacing', category: 'Spacing' },
+    align: {
+      type: 'enum',
+      category: 'Layout',
+      enum: ['flex-start', 'center', 'flex-end', 'stretch', 'baseline'],
+    },
+    justify: {
+      type: 'enum',
+      category: 'Layout',
+      enum: ['flex-start', 'center', 'flex-end', 'space-between', 'space-around', 'space-evenly'],
+    },
+    wrap: { type: 'enum', category: 'Layout', enum: ['nowrap', 'wrap'] },
+  },
+} as const satisfies ZoraComponentMeta;

package/src/features/layout/utils/resolveContentRailItemWidth.ts

@@ -0,0 +1,40 @@
+import type { ContentRailItemSize } from '../../../types/content-rail';
+
+export function resolveContentRailItemWidth({
+  gap,
+  itemCount,
+  itemSize,
+  padding,
+  peek,
+  viewportWidth,
+}: {
+  gap: number;
+  itemCount: number;
+  itemSize: ContentRailItemSize;
+  padding: number;
+  peek: number;
+  viewportWidth: number;
+}): number {
+  if (itemSize === 'content') return 0;
+  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/features/layout/utils/useContentRailReducedMotion.ts

@@ -0,0 +1,28 @@
+import React from 'react';
+import { AccessibilityInfo } from 'react-native';
+
+import type { ContentRailMotion } from '../../../types/content-rail';
+
+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/features/list/adapters/inbound/FlatList.tsx

@@ -0,0 +1,69 @@
+import React from 'react';
+import { FlatList as NativeFlatList } from 'react-native';
+
+import { withZoraThemeScope } from '../../../../theme/withZoraThemeScope';
+import type { ManifestListProps } from '../../../../types/manifest-list';
+import { Text } from '../../../typography/public';
+import { HorizontalListSeparator } from './HorizontalListSeparator';
+import { useListVisibility } from './useListVisibility';
+import { VerticalListSeparator } from './VerticalListSeparator';
+
+/*** Virtualizes keyed manifest children using React Native FlatList and the Runtime repeat contract. */
+export const FlatList = withZoraThemeScope(FlatListInner);
+
+/*** Maps serializable list options to the native virtualized list. */
+function FlatListInner({
+  mode: _mode,
+  themeId: _themeId,
+  children,
+  horizontal,
+  refreshing = false,
+  initialNumToRender,
+  maxToRenderPerBatch,
+  windowSize,
+  onEndReachedThreshold,
+  showsScrollIndicator = true,
+  bounces,
+  showSeparators,
+  headerText,
+  footerText,
+  emptyText,
+  onRefresh,
+  onEndReached,
+  onVisibleItemsChange,
+  interactionPolicy,
+  testID,
+}: ManifestListProps) {
+  const items = React.Children.toArray(children);
+  const passive = interactionPolicy === 'passive';
+  const onViewableItemsChanged = useListVisibility(onVisibleItemsChange, passive);
+  return (
+    <NativeFlatList
+      data={items}
+      renderItem={({ item }) => <>{item}</>}
+      keyExtractor={(item, index) =>
+        React.isValidElement(item) && item.key !== null ? String(item.key) : String(index)
+      }
+      horizontal={horizontal}
+      refreshing={refreshing}
+      onRefresh={passive ? undefined : onRefresh}
+      onEndReached={passive ? undefined : onEndReached}
+      onEndReachedThreshold={onEndReachedThreshold}
+      initialNumToRender={initialNumToRender}
+      maxToRenderPerBatch={maxToRenderPerBatch}
+      windowSize={windowSize}
+      scrollEnabled={!passive}
+      bounces={bounces}
+      onViewableItemsChanged={onViewableItemsChanged}
+      ItemSeparatorComponent={
+        showSeparators ? (horizontal ? HorizontalListSeparator : VerticalListSeparator) : undefined
+      }
+      showsHorizontalScrollIndicator={showsScrollIndicator}
+      showsVerticalScrollIndicator={showsScrollIndicator}
+      ListHeaderComponent={headerText ? <Text>{headerText}</Text> : null}
+      ListFooterComponent={footerText ? <Text>{footerText}</Text> : null}
+      ListEmptyComponent={emptyText ? <Text>{emptyText}</Text> : null}
+      testID={testID}
+    />
+  );
+}

package/src/features/list/adapters/inbound/HorizontalListSeparator.tsx

@@ -0,0 +1,8 @@
+import React from 'react';
+
+import { Divider } from '../../../layout/public';
+
+/*** Separates adjacent items in a horizontal native list. */
+export function HorizontalListSeparator() {
+  return <Divider orientation="vertical" />;
+}

package/src/features/list/adapters/inbound/SectionList.tsx

@@ -0,0 +1,76 @@
+import React from 'react';
+import { SectionList as NativeSectionList } from 'react-native';
+
+import { withZoraThemeScope } from '../../../../theme/withZoraThemeScope';
+import type { ManifestSectionListProps } from '../../../../types/manifest-list';
+import { Text } from '../../../typography/public';
+import { partitionListSections } from '../../application/use-cases/partitionListSections';
+import { HorizontalListSeparator } from './HorizontalListSeparator';
+import { useListVisibility } from './useListVisibility';
+import { VerticalListSeparator } from './VerticalListSeparator';
+
+/*** Virtualizes manifest children grouped by explicit section identities and child counts. */
+export const SectionList = withZoraThemeScope(SectionListInner);
+
+/*** Maps section identities and native scroll options to a virtualized section list. */
+function SectionListInner({
+  mode: _mode,
+  themeId: _themeId,
+  children,
+  sections,
+  horizontal,
+  refreshing = false,
+  initialNumToRender,
+  maxToRenderPerBatch,
+  windowSize,
+  onEndReachedThreshold,
+  showsScrollIndicator = true,
+  bounces,
+  showSeparators,
+  headerText,
+  footerText,
+  emptyText,
+  onRefresh,
+  onEndReached,
+  onVisibleItemsChange,
+  stickySectionHeadersEnabled = true,
+  interactionPolicy,
+  testID,
+}: ManifestSectionListProps) {
+  const grouped = partitionListSections(React.Children.toArray(children), sections);
+  const passive = interactionPolicy === 'passive';
+  const onViewableItemsChanged = useListVisibility(onVisibleItemsChange, passive);
+  return (
+    <NativeSectionList
+      sections={grouped}
+      renderItem={({ item }) => <>{item}</>}
+      keyExtractor={(item, index) =>
+        React.isValidElement(item) && item.key !== null ? String(item.key) : String(index)
+      }
+      renderSectionHeader={({ section }) =>
+        section.title ? <Text weight="semiBold">{section.title}</Text> : null
+      }
+      horizontal={horizontal}
+      refreshing={refreshing}
+      onRefresh={passive ? undefined : onRefresh}
+      onEndReached={passive ? undefined : onEndReached}
+      onEndReachedThreshold={onEndReachedThreshold}
+      initialNumToRender={initialNumToRender}
+      maxToRenderPerBatch={maxToRenderPerBatch}
+      windowSize={windowSize}
+      stickySectionHeadersEnabled={!horizontal && stickySectionHeadersEnabled}
+      scrollEnabled={!passive}
+      bounces={bounces}
+      onViewableItemsChanged={onViewableItemsChanged}
+      ItemSeparatorComponent={
+        showSeparators ? (horizontal ? HorizontalListSeparator : VerticalListSeparator) : undefined
+      }
+      showsHorizontalScrollIndicator={showsScrollIndicator}
+      showsVerticalScrollIndicator={showsScrollIndicator}
+      ListHeaderComponent={headerText ? <Text>{headerText}</Text> : null}
+      ListFooterComponent={footerText ? <Text>{footerText}</Text> : null}
+      ListEmptyComponent={emptyText ? <Text>{emptyText}</Text> : null}
+      testID={testID}
+    />
+  );
+}

package/src/features/list/adapters/inbound/VerticalListSeparator.tsx

@@ -0,0 +1,8 @@
+import React from 'react';
+
+import { Divider } from '../../../layout/public';
+
+/*** Separates adjacent items in a vertical native list. */
+export function VerticalListSeparator() {
+  return <Divider orientation="horizontal" />;
+}

package/src/features/list/adapters/inbound/useListVisibility.ts

@@ -0,0 +1,25 @@
+import React from 'react';
+import type { ViewToken } from 'react-native';
+
+import type { ManifestListProps } from '../../../../types/manifest-list';
+
+/*** Keeps the native visibility callback stable and emits only serializable item identities. */
+export function useListVisibility(
+  onVisibleItemsChange: ManifestListProps['onVisibleItemsChange'],
+  passive: boolean,
+) {
+  const handler = React.useRef(onVisibleItemsChange);
+  const disabled = React.useRef(passive);
+  React.useEffect(() => {
+    handler.current = onVisibleItemsChange;
+    disabled.current = passive;
+  }, [onVisibleItemsChange, passive]);
+  return React.useCallback(({ viewableItems }: { viewableItems: ViewToken[] }) => {
+    if (!disabled.current)
+      handler.current?.({
+        keys: viewableItems
+          .filter((item) => item.isViewable && item.index !== null && item.index >= 0)
+          .map((item) => item.key),
+      });
+  }, []);
+}

package/src/features/list/application/use-cases/partitionListSections.test.ts

@@ -0,0 +1,30 @@
+import { expect, test } from 'bun:test';
+
+import { partitionListSections } from './partitionListSections';
+
+test('partitions children without changing item identity or order', () => {
+  const items = [{ id: 'a' }, { id: 'b' }, { id: 'c' }];
+  const sections = partitionListSections(items, [
+    { key: 'first', title: 'First', itemCount: 2 },
+    { key: 'second', itemCount: 1 },
+  ]);
+  expect(sections[0]?.data).toEqual(items.slice(0, 2));
+  expect(sections[1]?.data[0]).toBe(items[2]);
+});
+
+test('rejects duplicate identities, invalid counts, and omitted or overflowing children', () => {
+  expect(() =>
+    partitionListSections(
+      [],
+      [
+        { key: 'a', itemCount: 0 },
+        { key: 'a', itemCount: 0 },
+      ],
+    ),
+  ).toThrow('unique');
+  expect(() => partitionListSections([], [{ key: 'a', itemCount: -1 }])).toThrow('non-negative');
+  expect(() => partitionListSections([], [{ key: 'a', itemCount: 0.5 }])).toThrow('integer');
+  expect(() => partitionListSections(['a'], [])).toThrow('cover');
+  expect(() => partitionListSections(['a'], [{ key: 'a', itemCount: 2 }])).toThrow('cover');
+  expect(partitionListSections([], [])).toEqual([]);
+});

package/src/features/list/application/use-cases/partitionListSections.ts

@@ -0,0 +1,23 @@
+import type { ManifestListSection } from '../../../../types/manifest-list';
+
+/*** Partitions ordered list children into declared sections while enforcing complete coverage and identity. */
+export function partitionListSections<T>(
+  items: readonly T[],
+  sections: readonly ManifestListSection[],
+) {
+  const keys = new Set<string>();
+  let offset = 0;
+  const result = sections.map((section) => {
+    if (!section.key || keys.has(section.key))
+      throw new Error('SectionList requires unique non-empty section keys.');
+    if (!Number.isInteger(section.itemCount) || section.itemCount < 0)
+      throw new Error('SectionList itemCount must be a non-negative integer.');
+    keys.add(section.key);
+    const data = items.slice(offset, offset + section.itemCount);
+    offset += section.itemCount;
+    return { ...section, data };
+  });
+  if (offset !== items.length)
+    throw new Error('SectionList section item counts must cover every child exactly once.');
+  return result;
+}

package/src/features/list/flatListMeta.ts

@@ -0,0 +1,39 @@
+import { CONTAINER_ALLOWED_CHILDREN } from '../../metadata/allowedChildren';
+import type { ZoraComponentMeta } from '../../metadata/types';
+
+export const flatListMeta = {
+  name: 'FlatList',
+  category: 'layout',
+  directManifestNode: true,
+  blueprint: { label: 'Flat list' },
+  allowedChildren: [...CONTAINER_ALLOWED_CHILDREN],
+  description:
+    'Virtualized children. Put node.repeat on this list for keyed data and item bindings; bind selection on the child Button/Card press event. Bound the list viewport and avoid nesting in a same-direction ScrollView.',
+  events: {
+    visibleItemsChange: {
+      label: 'Visible items change',
+      eventType: 'flatList.visibleItemsChange',
+      payloadFields: [{ path: 'keys', type: 'unknown' }],
+    },
+    refresh: { label: 'Refresh', eventType: 'flatList.refresh', payloadFields: [] },
+    endReached: {
+      label: 'End reached',
+      eventType: 'flatList.endReached',
+      payloadFields: [{ path: 'distanceFromEnd', type: 'number' }],
+    },
+  },
+  props: {
+    horizontal: { type: 'boolean', category: 'Layout' },
+    refreshing: { type: 'boolean', category: 'State' },
+    initialNumToRender: { type: 'number', category: 'Virtualization' },
+    maxToRenderPerBatch: { type: 'number', category: 'Virtualization' },
+    windowSize: { type: 'number', category: 'Virtualization' },
+    onEndReachedThreshold: { type: 'number', category: 'Behavior' },
+    showsScrollIndicator: { type: 'boolean', category: 'Style' },
+    bounces: { type: 'boolean', category: 'Behavior' },
+    showSeparators: { type: 'boolean', category: 'Style' },
+    headerText: { type: 'string', category: 'Content' },
+    footerText: { type: 'string', category: 'Content' },
+    emptyText: { type: 'string', category: 'Content' },
+  },
+} as const satisfies ZoraComponentMeta;

package/src/features/list/public.ts

@@ -0,0 +1,7 @@
+export type {
+  ManifestListProps,
+  ManifestListSection,
+  ManifestSectionListProps,
+} from '../../types/manifest-list';
+export { FlatList } from './adapters/inbound/FlatList';
+export { SectionList } from './adapters/inbound/SectionList';

package/src/features/list/sectionListMeta.ts

@@ -0,0 +1,31 @@
+import type { ZoraComponentMeta } from '../../metadata/types';
+import { flatListMeta } from './flatListMeta';
+
+export const sectionListMeta = {
+  ...flatListMeta,
+  name: 'SectionList',
+  blueprint: { label: 'Section list', defaultProps: { sections: [] } },
+  description:
+    'Virtualized sections of ordered children. Section counts must cover every child exactly once.',
+  events: {
+    visibleItemsChange: {
+      ...flatListMeta.events.visibleItemsChange,
+      eventType: 'sectionList.visibleItemsChange',
+    },
+    refresh: { ...flatListMeta.events.refresh, eventType: 'sectionList.refresh' },
+    endReached: { ...flatListMeta.events.endReached, eventType: 'sectionList.endReached' },
+  },
+  props: {
+    ...flatListMeta.props,
+    sections: {
+      type: 'array',
+      category: 'Data',
+      itemSchema: [
+        { key: 'key', schema: { type: 'string', category: 'Identity' } },
+        { key: 'title', schema: { type: 'string', category: 'Content' } },
+        { key: 'itemCount', schema: { type: 'number', category: 'Data' } },
+      ],
+    },
+    stickySectionHeadersEnabled: { type: 'boolean', category: 'Behavior' },
+  },
+} as const satisfies ZoraComponentMeta;