@ankhorage/zora 7.0.0 → 9.0.0

package/src/features/progress/adapters/inbound/ProgressRing.test.ts

@@ -0,0 +1,51 @@
+import { describe, expect, test } from 'bun:test';
+
+import { progressRingMeta } from '../../progressMeta';
+
+describe('ProgressRing public contract', () => {
+  test('is exported from the component and package entrypoints', async () => {
+    const [componentIndex, rootIndex] = await Promise.all([
+      Bun.file('src/features/progress/public.ts').text(),
+      Bun.file('src/index.ts').text(),
+    ]);
+
+    expect(componentIndex).toContain(
+      "export { ProgressRing } from './adapters/inbound/ProgressRing';",
+    );
+    expect(componentIndex).toContain('ProgressRingProps');
+    expect(rootIndex).toContain("} from './features/progress/public';");
+    expect(rootIndex).toContain('type ProgressProps');
+    expect(rootIndex).toContain('type ProgressRingProps');
+  });
+
+  test('exposes native progress semantics and uses canonical normalization and colors', async () => {
+    const source = await Bun.file('src/features/progress/adapters/inbound/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/features/progress/adapters/inbound/ProgressRing.tsx

@@ -0,0 +1,151 @@
+import React from 'react';
+import { StyleSheet, View } from 'react-native';
+
+import { useZoraTheme } from '../../../../theme/useZoraTheme';
+import { withZoraThemeScope } from '../../../../theme/withZoraThemeScope';
+import { type ProgressRingProps, resolveProgressRole } from '../../../../types/progress';
+import { Stack } from '../../../layout/public';
+import { Text } from '../../../typography/public';
+import { resolveProgressFraction } from '../../utils/resolveProgressFraction';
+import { resolveProgressRingGeometry } from '../../utils/resolveProgressRingGeometry';
+
+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/features/progress/public.ts

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

package/src/features/splash-screen/adapters/inbound/SplashScreen.tsx

@@ -0,0 +1,98 @@
+import React from 'react';
+
+import { Center } from '../../../../foundation';
+import { useZoraTheme } from '../../../../theme/useZoraTheme';
+import { withZoraThemeScope } from '../../../../theme/withZoraThemeScope';
+import type { SplashScreenLogoShape, SplashScreenProps } from '../../../../types/splash-screen';
+import { Box, Stack } from '../../../layout/public';
+import { Heading } from '../../../typography/public';
+import { Text } from '../../../typography/public';
+/***
+ * Branded launch/loading surface for previews, web fallbacks, and app bootstrap states.
+ *
+ * `SplashScreen` is a React-rendered component. It intentionally does not manage
+ * Expo's native splash screen lifecycle or replace generated `expo-splash-screen`
+ * configuration.
+ */
+export const SplashScreen = withZoraThemeScope(SplashScreenInner);
+
+interface PlaceholderLogoProps {
+  label: string;
+  shape: SplashScreenLogoShape;
+  size: number;
+}
+
+function resolveLogoRadius(shape: SplashScreenLogoShape): number {
+  switch (shape) {
+    case 'circle':
+      return 9999;
+    case 'square':
+      return 0;
+    case 'rounded':
+    default:
+      return 28;
+  }
+}
+
+function PlaceholderLogo({ label, shape, size }: PlaceholderLogoProps) {
+  const { theme } = useZoraTheme();
+  const radius = resolveLogoRadius(shape);
+
+  return (
+    <Center
+      accessibilityLabel={label}
+      bg={theme.semantics.action.primary.base}
+      height={size}
+      width={size}
+      style={{ borderRadius: radius }}
+    >
+      <Text emphasis="inverse" variant="eyebrow" weight="bold">
+        {label.slice(0, 2).toUpperCase()}
+      </Text>
+    </Center>
+  );
+}
+
+function SplashScreenInner({
+  themeId: _themeId,
+  mode: _mode,
+  logo,
+  title,
+  subtitle,
+  children,
+  minHeight = '100%',
+  backgroundColor,
+  logoSize = 96,
+  logoLabel = 'ZORA',
+  logoShape = 'rounded',
+  testID,
+}: SplashScreenProps) {
+  const { theme } = useZoraTheme();
+  const background = backgroundColor ?? theme.semantics.neutral.surface;
+  const renderedLogo = logo ?? (
+    <PlaceholderLogo label={logoLabel} shape={logoShape} size={logoSize} />
+  );
+
+  return (
+    <Center bg={background} minHeight={minHeight} p="xl" testID={testID} width="100%">
+      <Stack align="center" gap="l" style={{ maxWidth: 360 }}>
+        {renderedLogo}
+        {title || subtitle ? (
+          <Stack align="center" gap="xs">
+            {title ? (
+              <Heading align="center" level={1} size="h1">
+                {title}
+              </Heading>
+            ) : null}
+            {subtitle ? (
+              <Text align="center" emphasis="muted" variant="bodySmall">
+                {subtitle}
+              </Text>
+            ) : null}
+          </Stack>
+        ) : null}
+        {children ? <Box width="100%">{children}</Box> : null}
+      </Stack>
+    </Center>
+  );
+}

package/src/features/splash-screen/public.ts

@@ -0,0 +1,2 @@
+export type { SplashScreenLogoShape, SplashScreenProps } from '../../types/splash-screen';
+export { SplashScreen } from './adapters/inbound/SplashScreen';

package/src/features/splash-screen/splashScreenMeta.ts

@@ -0,0 +1,41 @@
+import { CONTAINER_ALLOWED_CHILDREN } from '../../metadata/allowedChildren';
+import type { ZoraComponentMeta } from '../../metadata/types';
+
+export const splashScreenMeta = {
+  name: 'SplashScreen',
+  category: 'component',
+  directManifestNode: true,
+  allowedChildren: [...CONTAINER_ALLOWED_CHILDREN],
+  description: 'App content splash presentation; does not control the native launch screen.',
+  props: {
+    title: {
+      type: 'string',
+      category: 'Content',
+    },
+    subtitle: {
+      type: 'string',
+      category: 'Content',
+    },
+    minHeight: {
+      type: 'number',
+      category: 'Layout',
+    },
+    backgroundColor: {
+      type: 'color',
+      category: 'Style',
+    },
+    logoSize: {
+      type: 'number',
+      category: 'Layout',
+    },
+    logoLabel: {
+      type: 'string',
+      category: 'Accessibility',
+    },
+    logoShape: {
+      type: 'enum',
+      category: 'Style',
+      enum: ['circle', 'square', 'rounded'],
+    },
+  },
+} as const satisfies ZoraComponentMeta;

package/src/features/surface/adapters/inbound/Surface.tsx

@@ -0,0 +1,18 @@
+import { Surface as SurfaceSurface } from '@ankhorage/surface';
+import React from 'react';
+
+import { withZoraThemeScope } from '../../../../theme/withZoraThemeScope';
+import type { SurfaceProps } from '../../../../types/surface';
+
+/*** Adapts the themed Surface Surface primitive to ZORA scope and interaction props. */
+export const Surface = withZoraThemeScope(SurfaceInner);
+
+/*** Forwards presentation props to the published Surface boundary. */
+function SurfaceInner({
+  themeId: _themeId,
+  mode: _mode,
+  interactionPolicy: _interactionPolicy,
+  ...props
+}: SurfaceProps) {
+  return <SurfaceSurface {...props} />;
+}

package/src/features/surface/public.ts

@@ -0,0 +1,2 @@
+export type { SurfaceProps, SurfaceVariant } from '../../types/surface';
+export { Surface } from './adapters/inbound/Surface';

package/src/features/surface/surfaceMeta.ts

@@ -0,0 +1,14 @@
+import { CONTAINER_ALLOWED_CHILDREN } from '../../metadata/allowedChildren';
+import type { ZoraComponentMeta } from '../../metadata/types';
+import { LAYOUT_PROPS } from '../layout/constants';
+
+export const surfaceMeta = {
+  name: 'Surface',
+  category: 'foundation',
+  directManifestNode: true,
+  allowedChildren: [...CONTAINER_ALLOWED_CHILDREN],
+  props: {
+    ...LAYOUT_PROPS,
+    variant: { type: 'enum', category: 'Style', enum: ['default', 'subtle', 'raised', 'outline'] },
+  },
+} as const satisfies ZoraComponentMeta;

package/src/features/typography/adapters/inbound/Heading.tsx

@@ -0,0 +1,114 @@
+import { resolveResponsive, useResponsiveRuntime } from '@ankhorage/surface';
+import React from 'react';
+import { Platform, Text as ReactNativeText, type TextStyle } from 'react-native';
+
+import { useZoraTheme } from '../../../../theme/useZoraTheme';
+import { useZoraThemeRecipe } from '../../../../theme/useZoraThemeRecipe';
+import { withZoraThemeScope } from '../../../../theme/withZoraThemeScope';
+import type { HeadingProps } from '../../../../types/heading';
+import { resolveHeadingRecipe } from '../../utils/resolveHeadingRecipe';
+import { resolveHeadingSizeFromLevel } from '../../utils/resolveHeadingSizeFromLevel';
+import { resolveHeadingThemeRecipe } from '../../utils/resolveHeadingThemeRecipe';
+/***
+ * Structured title primitive for accessible page, section, and card headings.
+ *
+ * `Heading` gives consumers a ZORA-owned title API with semantic levels,
+ * responsive sizes, and theme-aware emphasis while preserving header semantics.
+ *
+ * @example Section title
+ * ```tsx
+ * <Heading level={2} size="xl">Account settings</Heading>
+ * ```
+ */
+export const Heading = withZoraThemeScope(HeadingInner);
+
+const headingLayoutStyle: TextStyle = {
+  flexShrink: 1,
+  maxWidth: '100%',
+  minWidth: 0,
+  ...(Platform.OS === 'web'
+    ? {
+        overflowWrap: 'break-word',
+        whiteSpace: 'normal',
+        wordBreak: 'normal',
+      }
+    : null),
+};
+
+function resolveHeadingContent({
+  children,
+  text,
+  i18nKey,
+}: Pick<HeadingProps, 'children' | 'text' | 'i18nKey'>) {
+  if (children !== undefined) return children;
+  if (text !== undefined) return text;
+  if (i18nKey === undefined || i18nKey === '') return null;
+  return i18nKey;
+}
+
+function HeadingInner({
+  themeId: _themeId,
+  mode: _mode,
+  children,
+  text,
+  i18nKey,
+  level = 2,
+  size,
+  color,
+  emphasis,
+  align,
+  weight,
+  italic,
+  numberOfLines,
+  ellipsizeMode,
+  selectable,
+  style,
+  accessibilityLabel,
+  accessibilityHint,
+  accessibilityRole,
+  nativeID,
+  testID,
+  interactionPolicy: _interactionPolicy,
+}: HeadingProps) {
+  const { theme } = useZoraTheme();
+  const { breakpoint } = useResponsiveRuntime();
+  const themeRecipe = resolveHeadingThemeRecipe(useZoraThemeRecipe('Heading'));
+  const content = resolveHeadingContent({ children, text, i18nKey });
+  const resolvedSize =
+    resolveResponsive(size ?? themeRecipe.size, breakpoint) ?? resolveHeadingSizeFromLevel(level);
+  const resolvedColor = resolveResponsive(color ?? themeRecipe.color, breakpoint);
+  const resolvedEmphasis =
+    resolveResponsive(emphasis ?? themeRecipe.emphasis, breakpoint) ?? 'default';
+  const resolvedAlign = resolveResponsive(align ?? themeRecipe.align, breakpoint);
+  const resolvedWeight = resolveResponsive(weight ?? themeRecipe.weight, breakpoint);
+
+  if (content === null) return null;
+
+  return (
+    <ReactNativeText
+      accessibilityHint={accessibilityHint}
+      accessibilityLabel={accessibilityLabel}
+      accessibilityRole={accessibilityRole ?? 'header'}
+      ellipsizeMode={ellipsizeMode}
+      nativeID={nativeID}
+      numberOfLines={numberOfLines}
+      selectable={selectable}
+      testID={testID}
+      style={[
+        headingLayoutStyle,
+        resolveHeadingRecipe(theme, {
+          align: resolvedAlign,
+          italic: italic ?? themeRecipe.italic ?? false,
+          level,
+          size: resolvedSize,
+          color: resolvedColor,
+          emphasis: resolvedEmphasis,
+          weight: resolvedWeight,
+        }),
+        style,
+      ]}
+    >
+      {content}
+    </ReactNativeText>
+  );
+}

package/src/features/typography/adapters/inbound/Text.tsx

@@ -0,0 +1,110 @@
+import { resolveResponsive, useResponsiveRuntime } from '@ankhorage/surface';
+import React from 'react';
+import { Platform, Text as ReactNativeText, type TextStyle } from 'react-native';
+
+import { useZoraTheme } from '../../../../theme/useZoraTheme';
+import { useZoraThemeRecipe } from '../../../../theme/useZoraThemeRecipe';
+import { withZoraThemeScope } from '../../../../theme/withZoraThemeScope';
+import type { TextProps } from '../../../../types/text';
+import { resolveTextStyle } from '../../utils/resolveTextStyle';
+import { resolveTextThemeRecipe } from '../../utils/resolveTextThemeRecipe';
+/***
+ * Structured copy primitive for theme-aware app text.
+ *
+ * `Text` owns normal body, caption, label, code, and supporting-copy variants so
+ * consumers do not need to import lower-level Surface typography directly.
+ *
+ * @example Muted supporting copy
+ * ```tsx
+ * <Text variant="bodySmall" emphasis="muted">Updated just now</Text>
+ * ```
+ */
+export const Text = withZoraThemeScope(TextInner);
+
+const textLayoutStyle: TextStyle = {
+  flexShrink: 1,
+  maxWidth: '100%',
+  minWidth: 0,
+  ...(Platform.OS === 'web'
+    ? {
+        overflowWrap: 'break-word',
+        whiteSpace: 'normal',
+        wordBreak: 'normal',
+      }
+    : null),
+};
+
+function resolveTextContent({
+  children,
+  text,
+  i18nKey,
+}: {
+  children: TextProps['children'];
+  text: TextProps['text'];
+  i18nKey: TextProps['i18nKey'];
+}): React.ReactNode {
+  if (children !== undefined) return children;
+  if (text !== undefined) return text;
+  if (i18nKey === undefined || i18nKey === '') return null;
+  return i18nKey;
+}
+
+function TextInner({
+  themeId: _themeId,
+  mode: _mode,
+  children,
+  text,
+  i18nKey,
+  variant,
+  color,
+  emphasis,
+  align,
+  weight,
+  italic,
+  numberOfLines,
+  ellipsizeMode,
+  selectable,
+  style,
+  accessibilityLabel,
+  accessibilityHint,
+  accessibilityRole,
+  accessibilityLiveRegion,
+  nativeID,
+  testID,
+  interactionPolicy: _interactionPolicy,
+}: TextProps) {
+  const { theme } = useZoraTheme();
+  const { breakpoint } = useResponsiveRuntime();
+  const themeRecipe = resolveTextThemeRecipe(useZoraThemeRecipe('Text'));
+  const content = resolveTextContent({ children, text, i18nKey });
+  const resolvedVariant = resolveResponsive(variant ?? themeRecipe.variant, breakpoint) ?? 'body';
+  const resolvedStyle = resolveTextStyle({
+    theme,
+    breakpoint,
+    variant: resolvedVariant,
+    color: color ?? themeRecipe.color,
+    emphasis: emphasis ?? themeRecipe.emphasis,
+    align: align ?? themeRecipe.align,
+    weight: weight ?? themeRecipe.weight,
+    italic: italic ?? themeRecipe.italic ?? false,
+  });
+
+  if (content === null || content === undefined) return null;
+
+  return (
+    <ReactNativeText
+      accessibilityHint={accessibilityHint}
+      accessibilityLabel={accessibilityLabel}
+      accessibilityLiveRegion={accessibilityLiveRegion}
+      accessibilityRole={accessibilityRole}
+      ellipsizeMode={ellipsizeMode}
+      nativeID={nativeID}
+      numberOfLines={numberOfLines}
+      selectable={selectable}
+      testID={testID}
+      style={[textLayoutStyle, resolvedStyle, style]}
+    >
+      {content}
+    </ReactNativeText>
+  );
+}