@ankhorage/zora 3.1.0 → 3.2.0

package/src/components/progress/ProgressRing.test.ts

@@ -0,0 +1,48 @@
+import { describe, expect, test } from 'bun:test';
+
+import { progressRingMeta } from './meta';
+
+describe('ProgressRing public contract', () => {
+  test('is exported from the component and package entrypoints', async () => {
+    const [componentIndex, rootIndex] = await Promise.all([
+      Bun.file('src/components/progress/index.ts').text(),
+      Bun.file('src/index.ts').text(),
+    ]);
+
+    expect(componentIndex).toContain("export { ProgressRing } from './ProgressRing';");
+    expect(componentIndex).toContain('ProgressRingProps');
+    expect(rootIndex).toContain("export { Progress, ProgressRing } from './components/progress';");
+    expect(rootIndex).toContain('ProgressProps, ProgressRingProps');
+  });
+
+  test('exposes native progress semantics and uses canonical normalization and colors', async () => {
+    const source = await Bun.file('src/components/progress/ProgressRing.tsx').text();
+
+    expect(source).toContain('accessibilityRole="progressbar"');
+    expect(source).toContain('accessibilityValue={{');
+    expect(source).toContain('resolveProgressFraction({ max, value })');
+    expect(source).toContain('resolveProgressRole(theme, color)');
+    expect(source).not.toMatch(/#[0-9A-Fa-f]{3,8}|rgba?\(|hsla?\(/);
+  });
+
+  test('declares a complete serializable manifest blueprint', () => {
+    expect(progressRingMeta.directManifestNode).toBe(true);
+    expect(progressRingMeta.allowedChildren).toEqual([]);
+    expect(progressRingMeta.blueprint.defaultProps).toEqual({
+      value: 68,
+      max: 100,
+      color: 'primary',
+      trackColor: 'neutral',
+      size: 120,
+      thickness: 10,
+      centerValue: '68%',
+      centerLabel: 'Complete',
+      accessibilityLabel: 'Progress',
+      accessibilityValueText: '68% complete',
+    });
+    expect(Object.keys(progressRingMeta.props).sort()).toEqual(
+      Object.keys(progressRingMeta.blueprint.defaultProps).sort(),
+    );
+    expect(JSON.parse(JSON.stringify(progressRingMeta))).toEqual(progressRingMeta);
+  });
+});

package/src/components/progress/ProgressRing.tsx

@@ -0,0 +1,151 @@
+import React from 'react';
+import { StyleSheet, View } from 'react-native';
+
+import { Stack } from '../../foundation';
+import { useZoraTheme } from '../../theme/useZoraTheme';
+import { withZoraThemeScope } from '../../theme/withZoraThemeScope';
+import { Text } from '../text';
+import { resolveProgressFraction } from './resolveProgressFraction';
+import { resolveProgressRingGeometry } from './resolveProgressRingGeometry';
+import { type ProgressRingProps, resolveProgressRole } from './types';
+
+function ProgressRingInner({
+  themeId: _themeId,
+  mode: _mode,
+  interactionPolicy: _interactionPolicy,
+  accessibilityLabel = 'Progress',
+  accessibilityValueText,
+  centerLabel,
+  centerValue,
+  color = 'primary',
+  max = 100,
+  size = 120,
+  testID,
+  thickness = 10,
+  trackColor = 'neutral',
+  value,
+}: ProgressRingProps) {
+  const { theme } = useZoraTheme();
+  const fraction = resolveProgressFraction({ max, value });
+  const geometry = resolveProgressRingGeometry({ fraction, size, thickness });
+  const progressRole = resolveProgressRole(theme, color);
+  const trackRole = resolveProgressRole(theme, trackColor);
+  const accessibilityMaximum = Number.isFinite(max) && max > 0 ? max : 1;
+  const accessibilityValue = fraction * accessibilityMaximum;
+  const valueText = accessibilityValueText ?? `${Math.round(fraction * 100)}%`;
+  const segments = Array.from({ length: geometry.filledSegmentCount });
+
+  return (
+    <View
+      accessibilityLabel={accessibilityLabel}
+      accessibilityRole="progressbar"
+      accessibilityValue={{
+        max: accessibilityMaximum,
+        min: 0,
+        now: accessibilityValue,
+        text: valueText,
+      }}
+      accessible
+      style={{ height: geometry.diameter, width: geometry.diameter }}
+      testID={testID}
+    >
+      <View
+        importantForAccessibility="no-hide-descendants"
+        pointerEvents="none"
+        style={styles.visual}
+      >
+        <View
+          style={[
+            styles.track,
+            {
+              borderColor: trackRole.softBg,
+              borderRadius: geometry.diameter / 2,
+              borderWidth: geometry.strokeWidth,
+            },
+          ]}
+        />
+
+        {segments.map((_, index) => (
+          <View
+            key={index}
+            style={[
+              styles.segmentLayer,
+              { transform: [{ rotate: `${index * (360 / geometry.segmentCount)}deg` }] },
+            ]}
+          >
+            <View
+              style={{
+                backgroundColor: progressRole.base,
+                borderRadius: geometry.strokeWidth / 2,
+                height: geometry.strokeWidth,
+                left: (geometry.diameter - geometry.segmentWidth) / 2,
+                position: 'absolute',
+                top: 0,
+                width: geometry.segmentWidth,
+              }}
+            />
+          </View>
+        ))}
+      </View>
+
+      {centerValue !== undefined || centerLabel !== undefined ? (
+        <View
+          importantForAccessibility="no-hide-descendants"
+          pointerEvents="none"
+          style={styles.center}
+        >
+          <Stack align="center" gap="xxs" px="s">
+            {centerValue !== undefined ? (
+              <Text align="center" variant="lead" weight="bold">
+                {centerValue}
+              </Text>
+            ) : null}
+            {centerLabel !== undefined ? (
+              <Text align="center" emphasis="muted" numberOfLines={2} variant="caption">
+                {centerLabel}
+              </Text>
+            ) : null}
+          </Stack>
+        </View>
+      ) : null}
+    </View>
+  );
+}
+
+const styles = StyleSheet.create({
+  center: {
+    alignItems: 'center',
+    bottom: 0,
+    justifyContent: 'center',
+    left: 0,
+    position: 'absolute',
+    right: 0,
+    top: 0,
+  },
+  segmentLayer: {
+    bottom: 0,
+    left: 0,
+    position: 'absolute',
+    right: 0,
+    top: 0,
+  },
+  track: {
+    bottom: 0,
+    left: 0,
+    position: 'absolute',
+    right: 0,
+    top: 0,
+  },
+  visual: {
+    bottom: 0,
+    left: 0,
+    position: 'absolute',
+    right: 0,
+    top: 0,
+  },
+});
+
+/***
+ * Circular determinate progress with optional serializable center value and label content.
+ */
+export const ProgressRing = withZoraThemeScope(ProgressRingInner);

package/src/components/progress/index.ts

@@ -1,2 +1,3 @@
 export { Progress } from './Progress';
-export type { ProgressProps } from './types';
+export { ProgressRing } from './ProgressRing';
+export type { ProgressProps, ProgressRingProps } from './types';

package/src/components/progress/meta.ts

@@ -44,3 +44,102 @@ export const progressMeta = {
     },
   },
 } as const satisfies ZoraComponentMeta;
+
+const instanceAuthoring = { authority: 'instance' } as const;
+
+export const progressRingMeta = {
+  name: 'ProgressRing',
+  category: 'component',
+  description: 'Displays circular determinate progress with optional center value and label text.',
+  directManifestNode: true,
+  allowedChildren: [],
+  blueprint: {
+    label: 'Progress ring',
+    defaultProps: {
+      value: 68,
+      max: 100,
+      color: 'primary',
+      trackColor: 'neutral',
+      size: 120,
+      thickness: 10,
+      centerValue: '68%',
+      centerLabel: 'Complete',
+      accessibilityLabel: 'Progress',
+      accessibilityValueText: '68% complete',
+    },
+  },
+  props: {
+    value: {
+      type: 'number',
+      category: 'State',
+      label: 'Value',
+      default: 68,
+      authoring: instanceAuthoring,
+    },
+    max: {
+      type: 'number',
+      category: 'State',
+      label: 'Maximum',
+      default: 100,
+      authoring: instanceAuthoring,
+    },
+    centerValue: {
+      type: 'string',
+      category: 'Content',
+      label: 'Center value',
+      default: '68%',
+      authoring: instanceAuthoring,
+    },
+    centerLabel: {
+      type: 'string',
+      category: 'Content',
+      label: 'Center label',
+      default: 'Complete',
+      authoring: instanceAuthoring,
+    },
+    accessibilityLabel: {
+      type: 'string',
+      category: 'Accessibility',
+      label: 'Accessibility label',
+      default: 'Progress',
+      authoring: instanceAuthoring,
+    },
+    accessibilityValueText: {
+      type: 'string',
+      category: 'Accessibility',
+      label: 'Accessibility value text',
+      default: '68% complete',
+      authoring: instanceAuthoring,
+    },
+    color: {
+      type: 'enum',
+      category: 'Style',
+      label: 'Progress color',
+      enum: [...ZORA_COLORS],
+      default: 'primary',
+      authoring: instanceAuthoring,
+    },
+    trackColor: {
+      type: 'enum',
+      category: 'Style',
+      label: 'Track color',
+      enum: [...ZORA_COLORS],
+      default: 'neutral',
+      authoring: instanceAuthoring,
+    },
+    size: {
+      type: 'number',
+      category: 'Layout',
+      label: 'Diameter',
+      default: 120,
+      authoring: instanceAuthoring,
+    },
+    thickness: {
+      type: 'number',
+      category: 'Style',
+      label: 'Thickness',
+      default: 10,
+      authoring: instanceAuthoring,
+    },
+  },
+} as const satisfies ZoraComponentMeta;

package/src/components/progress/resolveProgressRingGeometry.test.ts

@@ -0,0 +1,30 @@
+import { describe, expect, test } from 'bun:test';
+
+import { resolveProgressRingGeometry } from './resolveProgressRingGeometry';
+
+describe('resolveProgressRingGeometry', () => {
+  test('normalizes invalid dimensions and fractions deterministically', () => {
+    expect(
+      resolveProgressRingGeometry({ fraction: Number.NaN, size: Number.NaN, thickness: -1 }),
+    ).toMatchObject({
+      diameter: 120,
+      filledSegmentCount: 0,
+      strokeWidth: 10,
+    });
+  });
+
+  test('clamps size, thickness, and progress to renderable bounds', () => {
+    const empty = resolveProgressRingGeometry({ fraction: -1, size: 4, thickness: 30 });
+    const complete = resolveProgressRingGeometry({ fraction: 2, size: 80, thickness: 8 });
+
+    expect(empty).toMatchObject({ diameter: 24, filledSegmentCount: 0, strokeWidth: 12 });
+    expect(complete.filledSegmentCount).toBe(complete.segmentCount);
+  });
+
+  test('maps determinate progress to the ring segments', () => {
+    const geometry = resolveProgressRingGeometry({ fraction: 0.68, size: 120, thickness: 10 });
+
+    expect(geometry.filledSegmentCount).toBe(Math.round(geometry.segmentCount * 0.68));
+    expect(geometry.segmentWidth).toBeGreaterThan(0);
+  });
+});

package/src/components/progress/resolveProgressRingGeometry.ts

@@ -0,0 +1,44 @@
+export function resolveProgressRingGeometry({
+  fraction,
+  size,
+  thickness,
+}: {
+  fraction: number;
+  size: number;
+  thickness: number;
+}) {
+  const diameter = normalizePositiveNumber(size, DEFAULT_SIZE, MINIMUM_SIZE);
+  const strokeWidth = Math.min(
+    normalizePositiveNumber(thickness, DEFAULT_THICKNESS, MINIMUM_THICKNESS),
+    diameter / 2,
+  );
+  const centerlineRadius = (diameter - strokeWidth) / 2;
+  const segmentCount = Math.max(
+    MINIMUM_SEGMENT_COUNT,
+    Math.min(MAXIMUM_SEGMENT_COUNT, Math.round(Math.PI * centerlineRadius)),
+  );
+  const normalizedFraction = Math.min(Math.max(Number.isFinite(fraction) ? fraction : 0, 0), 1);
+
+  return {
+    diameter,
+    filledSegmentCount: Math.round(normalizedFraction * segmentCount),
+    segmentCount,
+    segmentWidth: Math.max(1, (2 * Math.PI * centerlineRadius) / segmentCount + 0.5),
+    strokeWidth,
+  };
+}
+
+const DEFAULT_SIZE = 120;
+const DEFAULT_THICKNESS = 10;
+const MAXIMUM_SEGMENT_COUNT = 120;
+const MINIMUM_SEGMENT_COUNT = 32;
+const MINIMUM_SIZE = 24;
+const MINIMUM_THICKNESS = 1;
+
+function normalizePositiveNumber(value: number, fallback: number, minimum: number): number {
+  if (!Number.isFinite(value) || value <= 0) {
+    return fallback;
+  }
+
+  return Math.max(value, minimum);
+}

package/src/components/progress/types.ts

@@ -10,6 +10,19 @@ export interface ProgressProps extends ZoraBaseProps {
   size?: ZoraControlSize;
 }
 
+export interface ProgressRingProps extends ZoraBaseProps {
+  value: number;
+  max?: number;
+  color?: ZoraColor;
+  trackColor?: ZoraColor;
+  size?: number;
+  thickness?: number;
+  centerValue?: string;
+  centerLabel?: string;
+  accessibilityLabel?: string;
+  accessibilityValueText?: string;
+}
+
 export function resolveProgressRole(theme: SurfaceTheme, color: ZoraColor): RoleSemantics {
   switch (color) {
     case 'secondary':

package/src/index.ts

@@ -115,8 +115,8 @@ export type { NavigationListProps, ZoraNavigationRouteMap } from './components/n
 export { NavigationList } from './components/navigation-list';
 export type { PaginationProps } from './components/pagination';
 export { Pagination } from './components/pagination';
-export type { ProgressProps } from './components/progress';
-export { Progress } from './components/progress';
+export type { ProgressProps, ProgressRingProps } from './components/progress';
+export { Progress, ProgressRing } from './components/progress';
 export type { RadioGroupOption, RadioGroupProps, RadioProps } from './components/radio';
 export { Radio, RadioGroup } from './components/radio';
 export type { RatingProps } from './components/rating';

package/src/metadata/allowedChildren.ts

@@ -21,6 +21,7 @@ export const CONTAINER_ALLOWED_CHILDREN = [
   'PostCard',
   'ChatListItem',
   'MessageBubble',
+  'ProgressRing',
   'ReaderSurface',
 ] as const;
 

package/src/metadata/componentMeta.test.ts

@@ -138,6 +138,7 @@ describe('ZORA_COMPONENT_META invariants', () => {
       'ScanOverlay',
       'ProductCard',
       'Progress',
+      'ProgressRing',
       'ReaderSurface',
     ]);
 
@@ -211,6 +212,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;
 

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';
@@ -134,6 +134,7 @@ export const ZORA_COMPONENT_META: ZoraComponentMetaRegistry = {
   NavigationList: navigationListMeta,
   Pagination: paginationMeta,
   Progress: progressMeta,
+  ProgressRing: progressRingMeta,
   Radio: radioMeta,
   RadioGroup: radioGroupMeta,
   Rating: ratingMeta,

package/src/registry.ts

@@ -30,7 +30,7 @@ import { Modal } from './components/modal';
 import { NavigationItem } from './components/navigation-item';
 import { NavigationList } from './components/navigation-list';
 import { Pagination } from './components/pagination';
-import { Progress } from './components/progress';
+import { Progress, ProgressRing } from './components/progress';
 import { Radio, RadioGroup } from './components/radio';
 import { Rating } from './components/rating';
 import { SearchBar } from './components/search-bar';
@@ -162,6 +162,7 @@ const _ZORA_COMPONENT_REGISTRY = {
   NavigationList,
   Pagination,
   Progress,
+  ProgressRing,
   Radio,
   RadioGroup,
   Rating,

package/src/showcaseCoverage.test.ts

@@ -44,6 +44,7 @@ const REQUIRED_SHOWCASE_COVERAGE = {
     'NavigationItem',
     'NavigationList',
     'Progress',
+    'ProgressRing',
     'Radio',
     'RadioGroup',
     'Rating',