@ankhorage/zora 1.0.6 → 1.0.8

package/src/components/metric-card/MetricCard.tsx

@@ -0,0 +1,84 @@
+import React from 'react';
+
+import { Box, Inline, Stack } from '../../foundation';
+import { resolveBadgeRecipe, resolveIconSize } from '../../internal/recipes';
+import { useZoraTheme } from '../../theme/useZoraTheme';
+import { withZoraThemeScope } from '../../theme/withZoraThemeScope';
+import { Badge } from '../badge';
+import { Card } from '../card';
+import { Heading } from '../heading';
+import { Icon } from '../icon';
+import { Text } from '../text';
+import type { MetricCardProps } from './types';
+
+function MetricCardInner({
+  themeId: _themeId,
+  mode: _mode,
+  testID,
+  label,
+  value,
+  description,
+  icon,
+  delta,
+  deltaTone = 'neutral',
+  actions,
+  tone = 'default',
+  compact = false,
+  onPress,
+}: MetricCardProps) {
+  const { theme } = useZoraTheme();
+  const isInteractive = Boolean(onPress) && !actions;
+
+  const badgeRecipe = resolveBadgeRecipe({ tone: deltaTone, emphasis: 'soft', size: 's' });
+  const iconColor = theme.semantics.content.muted;
+
+  return (
+    <Card
+      compact={compact}
+      onPress={isInteractive ? onPress : undefined}
+      testID={testID}
+      tone={tone}
+    >
+      <Stack gap={compact ? 's' : 'm'}>
+        <Inline align="flex-start" gap="m" justify="space-between">
+          <Stack flex={1} gap="xs">
+            <Inline align="center" gap="xs" wrap="wrap">
+              {icon ? (
+                <Icon
+                  color={iconColor}
+                  name={icon.name}
+                  provider={icon.provider}
+                  size={resolveIconSize('s')}
+                />
+              ) : null}
+              <Text tone="muted" variant="caption" weight="semiBold">
+                {label}
+              </Text>
+              {delta != null ? (
+                <Badge
+                  emphasis={badgeRecipe.variant}
+                  size={badgeRecipe.size}
+                  tone={badgeRecipe.tone}
+                >
+                  {delta}
+                </Badge>
+              ) : null}
+            </Inline>
+
+            <Heading level={compact ? 3 : 2}>{value}</Heading>
+
+            {description ? (
+              <Text tone="muted" variant="bodySmall">
+                {description}
+              </Text>
+            ) : null}
+          </Stack>
+
+          {actions ? <Box>{actions}</Box> : null}
+        </Inline>
+      </Stack>
+    </Card>
+  );
+}
+
+export const MetricCard = withZoraThemeScope(MetricCardInner);

package/src/components/metric-card/index.ts

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

package/src/components/metric-card/types.ts

@@ -0,0 +1,18 @@
+import type { ButtonIconSpec } from '@ankhorage/surface';
+import type React from 'react';
+
+import type { ZoraCardTone, ZoraTone } from '../../internal/recipes';
+import type { ZoraBaseProps } from '../../theme/ZoraBaseProps';
+
+export interface MetricCardProps extends ZoraBaseProps {
+  label: React.ReactNode;
+  value: React.ReactNode;
+  description?: React.ReactNode;
+  icon?: ButtonIconSpec;
+  delta?: React.ReactNode;
+  deltaTone?: ZoraTone;
+  actions?: React.ReactNode;
+  tone?: ZoraCardTone;
+  compact?: boolean;
+  onPress?: () => void;
+}

package/src/components/progress/Progress.tsx

@@ -0,0 +1,50 @@
+import React from 'react';
+
+import { Box } from '../../foundation';
+import { useZoraTheme } from '../../theme/useZoraTheme';
+import { withZoraThemeScope } from '../../theme/withZoraThemeScope';
+import { resolveProgressFraction } from './resolveProgressFraction';
+import { type ProgressProps, resolveProgressRole } from './types';
+
+function resolveProgressHeight(size: NonNullable<ProgressProps['size']>): number {
+  switch (size) {
+    case 's':
+      return 4;
+    case 'm':
+      return 6;
+    case 'l':
+    default:
+      return 8;
+  }
+}
+
+function ProgressInner({
+  themeId: _themeId,
+  mode: _mode,
+  testID,
+  value,
+  max = 100,
+  tone = 'primary',
+  size = 'm',
+}: ProgressProps) {
+  const { theme } = useZoraTheme();
+  const fraction = resolveProgressFraction({ value, max });
+  const height = resolveProgressHeight(size);
+  const role = resolveProgressRole(theme, tone);
+
+  return (
+    <Box
+      accessibilityRole="progressbar"
+      bg={theme.semantics.neutral.surface}
+      borderColor={theme.semantics.neutral.divider}
+      borderWidth={1}
+      radius="full"
+      testID={testID}
+      style={{ height, overflow: 'hidden' }}
+    >
+      <Box bg={role.base} style={{ height: '100%', width: `${fraction * 100}%` }} />
+    </Box>
+  );
+}
+
+export const Progress = withZoraThemeScope(ProgressInner);

package/src/components/progress/index.ts

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

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

@@ -0,0 +1,23 @@
+import { describe, expect, test } from 'bun:test';
+
+import { resolveProgressFraction } from './resolveProgressFraction';
+
+describe('resolveProgressFraction', () => {
+  test('clamps values to [0, 1]', () => {
+    expect(resolveProgressFraction({ value: -5, max: 10 })).toBe(0);
+    expect(resolveProgressFraction({ value: 0, max: 10 })).toBe(0);
+    expect(resolveProgressFraction({ value: 5, max: 10 })).toBe(0.5);
+    expect(resolveProgressFraction({ value: 10, max: 10 })).toBe(1);
+    expect(resolveProgressFraction({ value: 15, max: 10 })).toBe(1);
+  });
+
+  test('returns 0 for invalid max', () => {
+    expect(resolveProgressFraction({ value: 5, max: 0 })).toBe(0);
+    expect(resolveProgressFraction({ value: 5, max: -3 })).toBe(0);
+    expect(resolveProgressFraction({ value: 5, max: Number.NaN })).toBe(0);
+  });
+
+  test('returns 0 for invalid value', () => {
+    expect(resolveProgressFraction({ value: Number.NaN, max: 10 })).toBe(0);
+  });
+});

package/src/components/progress/resolveProgressFraction.ts

@@ -0,0 +1,17 @@
+export function resolveProgressFraction({ value, max }: { value: number; max: number }): number {
+  if (!Number.isFinite(value) || !Number.isFinite(max) || max <= 0) {
+    return 0;
+  }
+
+  const fraction = value / max;
+
+  if (fraction <= 0) {
+    return 0;
+  }
+
+  if (fraction >= 1) {
+    return 1;
+  }
+
+  return fraction;
+}

package/src/components/progress/types.ts

@@ -0,0 +1,27 @@
+import type { RoleSemantics, SurfaceTheme } from '@ankhorage/surface';
+
+import type { ZoraControlSize, ZoraTone } from '../../internal/recipes';
+import type { ZoraBaseProps } from '../../theme/ZoraBaseProps';
+
+export interface ProgressProps extends ZoraBaseProps {
+  value: number;
+  max?: number;
+  tone?: ZoraTone;
+  size?: ZoraControlSize;
+}
+
+export function resolveProgressRole(theme: SurfaceTheme, tone: ZoraTone): RoleSemantics {
+  switch (tone) {
+    case 'primary':
+      return theme.semantics.action.primary;
+    case 'danger':
+      return theme.semantics.action.danger;
+    case 'success':
+      return theme.semantics.success;
+    case 'warning':
+      return theme.semantics.warning;
+    case 'neutral':
+    default:
+      return theme.semantics.action.neutral;
+  }
+}

package/src/components/rating/Rating.tsx

@@ -0,0 +1,38 @@
+import React from 'react';
+
+import { Inline } from '../../foundation';
+import { resolveIconSize } from '../../internal/recipes';
+import { useZoraTheme } from '../../theme/useZoraTheme';
+import { withZoraThemeScope } from '../../theme/withZoraThemeScope';
+import { Icon } from '../icon';
+import { resolveRatingSegments } from './resolveRatingSegments';
+import { type RatingProps, resolveRatingRole } from './types';
+
+function RatingInner({
+  themeId: _themeId,
+  mode: _mode,
+  testID,
+  value,
+  max = 5,
+  tone = 'warning',
+  size = 'm',
+}: RatingProps) {
+  const { theme } = useZoraTheme();
+  const role = resolveRatingRole(theme, tone);
+  const segments = resolveRatingSegments({ value, max });
+  const iconSize = resolveIconSize(size);
+
+  return (
+    <Inline align="center" gap="xxs" testID={testID} wrap="nowrap">
+      {segments.map((segment, index) => {
+        const name =
+          segment === 'full' ? 'star' : segment === 'half' ? 'star-half' : 'star-outline';
+        const color = segment === 'empty' ? theme.semantics.content.muted : role.base;
+
+        return <Icon key={index} color={color} name={name} size={iconSize} />;
+      })}
+    </Inline>
+  );
+}
+
+export const Rating = withZoraThemeScope(RatingInner);

package/src/components/rating/index.ts

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

package/src/components/rating/resolveRatingSegments.test.ts

@@ -0,0 +1,60 @@
+import { describe, expect, test } from 'bun:test';
+
+import { resolveRatingSegments } from './resolveRatingSegments';
+
+describe('resolveRatingSegments', () => {
+  test('returns empty segments for invalid input', () => {
+    expect(resolveRatingSegments({ value: 3, max: 0 })).toEqual([]);
+    expect(resolveRatingSegments({ value: Number.NaN, max: 5 })).toEqual([]);
+  });
+
+  test('clamps and rounds to nearest half-step', () => {
+    expect(resolveRatingSegments({ value: -1, max: 5 })).toEqual([
+      'empty',
+      'empty',
+      'empty',
+      'empty',
+      'empty',
+    ]);
+
+    expect(resolveRatingSegments({ value: 3, max: 5 })).toEqual([
+      'full',
+      'full',
+      'full',
+      'empty',
+      'empty',
+    ]);
+
+    expect(resolveRatingSegments({ value: 3.2, max: 5 })).toEqual([
+      'full',
+      'full',
+      'full',
+      'empty',
+      'empty',
+    ]);
+
+    expect(resolveRatingSegments({ value: 3.25, max: 5 })).toEqual([
+      'full',
+      'full',
+      'full',
+      'half',
+      'empty',
+    ]);
+
+    expect(resolveRatingSegments({ value: 5, max: 5 })).toEqual([
+      'full',
+      'full',
+      'full',
+      'full',
+      'full',
+    ]);
+
+    expect(resolveRatingSegments({ value: 6, max: 5 })).toEqual([
+      'full',
+      'full',
+      'full',
+      'full',
+      'full',
+    ]);
+  });
+});

package/src/components/rating/resolveRatingSegments.ts

@@ -0,0 +1,34 @@
+type RatingSegment = 'full' | 'half' | 'empty';
+
+export function resolveRatingSegments({
+  value,
+  max,
+}: {
+  value: number;
+  max: number;
+}): RatingSegment[] {
+  if (!Number.isFinite(value) || !Number.isFinite(max) || max <= 0) {
+    return [];
+  }
+
+  const clamped = Math.max(0, Math.min(value, max));
+  const halfSteps = Math.round(clamped * 2);
+  const segments: RatingSegment[] = [];
+
+  for (let index = 0; index < max; index += 1) {
+    const threshold = (index + 1) * 2;
+    if (halfSteps >= threshold) {
+      segments.push('full');
+      continue;
+    }
+
+    if (halfSteps === threshold - 1) {
+      segments.push('half');
+      continue;
+    }
+
+    segments.push('empty');
+  }
+
+  return segments;
+}

package/src/components/rating/types.ts

@@ -0,0 +1,27 @@
+import type { RoleSemantics, SurfaceTheme } from '@ankhorage/surface';
+
+import type { ZoraControlSize, ZoraTone } from '../../internal/recipes';
+import type { ZoraBaseProps } from '../../theme/ZoraBaseProps';
+
+export interface RatingProps extends ZoraBaseProps {
+  value: number;
+  max?: number;
+  tone?: ZoraTone;
+  size?: ZoraControlSize;
+}
+
+export function resolveRatingRole(theme: SurfaceTheme, tone: ZoraTone): RoleSemantics {
+  switch (tone) {
+    case 'primary':
+      return theme.semantics.action.primary;
+    case 'danger':
+      return theme.semantics.action.danger;
+    case 'success':
+      return theme.semantics.success;
+    case 'warning':
+      return theme.semantics.warning;
+    case 'neutral':
+    default:
+      return theme.semantics.action.neutral;
+  }
+}

package/src/index.ts

@@ -60,10 +60,18 @@ export type { IconButtonProps } from './components/icon-button';
 export { IconButton } from './components/icon-button';
 export type { InputProps, InputTrailingAction } from './components/input';
 export { Input } from './components/input';
+export type { MediaCardImageProps, MediaCardProps } from './components/media-card';
+export { MediaCard } from './components/media-card';
+export type { MetricCardProps } from './components/metric-card';
+export { MetricCard } from './components/metric-card';
 export type { ModalProps } from './components/modal';
 export { Modal } from './components/modal';
+export type { ProgressProps } from './components/progress';
+export { Progress } from './components/progress';
 export type { RadioGroupOption, RadioGroupProps, RadioProps } from './components/radio';
 export { Radio, RadioGroup } from './components/radio';
+export type { RatingProps } from './components/rating';
+export { Rating } from './components/rating';
 export type { SearchBarProps } from './components/search-bar';
 export { SearchBar } from './components/search-bar';
 export type { SelectOption, SelectProps } from './components/select';
@@ -171,6 +179,8 @@ export type { ThemeComposerProps } from './patterns/theme-composer';
 export { ThemeComposer } from './patterns/theme-composer';
 export type { PaletteItemProps, TileGridProps } from './patterns/tile-grid';
 export { PaletteItem, TileGrid } from './patterns/tile-grid';
+export type { TimelineItem, TimelineProps } from './patterns/timeline';
+export { Timeline } from './patterns/timeline';
 export type { TreeItemNode, TreeItemRenderProps, TreeViewProps } from './patterns/tree-view';
 export { TreeItem, TreeView } from './patterns/tree-view';
 export * from './theme';

package/src/patterns/timeline/Timeline.tsx

@@ -0,0 +1,104 @@
+import type { RoleSemantics, SurfaceTheme } from '@ankhorage/surface';
+import React from 'react';
+
+import { Heading } from '../../components/heading';
+import { Icon } from '../../components/icon';
+import { Text } from '../../components/text';
+import { Box, Inline, Stack } from '../../foundation';
+import type { ZoraTone } from '../../internal/recipes';
+import { resolveIconSize } from '../../internal/recipes';
+import { useZoraTheme } from '../../theme/useZoraTheme';
+import { withZoraThemeScope } from '../../theme/withZoraThemeScope';
+import type { TimelineItem, TimelineProps } from './types';
+
+function resolveRoleSemantics(theme: SurfaceTheme, tone: ZoraTone): RoleSemantics {
+  switch (tone) {
+    case 'primary':
+      return theme.semantics.action.primary;
+    case 'danger':
+      return theme.semantics.action.danger;
+    case 'success':
+      return theme.semantics.success;
+    case 'warning':
+      return theme.semantics.warning;
+    case 'neutral':
+    default:
+      return theme.semantics.action.neutral;
+  }
+}
+
+function TimelineInner({
+  themeId: _themeId,
+  mode: _mode,
+  testID,
+  items,
+  compact = false,
+}: TimelineProps) {
+  const { theme } = useZoraTheme();
+  const gap = compact ? 'm' : 'l';
+
+  const renderItem = (item: TimelineItem, index: number) => {
+    const status = item.status ?? 'neutral';
+    const role = resolveRoleSemantics(theme, status);
+    const showConnector = index < items.length - 1;
+    const iconSize = Math.max(12, resolveIconSize('s'));
+
+    return (
+      <Inline key={item.id} align="flex-start" gap="m" testID={item.testID} wrap="nowrap">
+        <Stack align="center" flexShrink={0} gap="xs" style={{ width: 24 }}>
+          <Box
+            bg={status === 'neutral' ? theme.semantics.neutral.surface : role.softBg}
+            borderColor={status === 'neutral' ? theme.semantics.neutral.divider : role.base}
+            borderWidth={1}
+            height={20}
+            radius="full"
+            width={20}
+            style={{ alignItems: 'center', justifyContent: 'center' }}
+          >
+            {item.icon ? (
+              <Icon
+                color={status === 'neutral' ? theme.semantics.content.muted : role.base}
+                name={item.icon.name}
+                provider={item.icon.provider}
+                size={iconSize}
+              />
+            ) : null}
+          </Box>
+
+          {showConnector ? (
+            <Box
+              bg={theme.semantics.neutral.divider}
+              flex={1}
+              radius="full"
+              style={{ minHeight: 16, width: 2 }}
+            />
+          ) : null}
+        </Stack>
+
+        <Stack flex={1} gap="xs" testID={testID}>
+          <Inline align="flex-start" gap="s" justify="space-between" wrap="wrap">
+            <Heading level={compact ? 4 : 3}>{item.title}</Heading>
+            {item.meta ? (
+              <Text tone="muted" variant="caption">
+                {item.meta}
+              </Text>
+            ) : null}
+          </Inline>
+          {item.description ? (
+            <Text tone="muted" variant="bodySmall">
+              {item.description}
+            </Text>
+          ) : null}
+        </Stack>
+      </Inline>
+    );
+  };
+
+  return (
+    <Stack gap={gap} testID={testID}>
+      {items.map(renderItem)}
+    </Stack>
+  );
+}
+
+export const Timeline = withZoraThemeScope(TimelineInner);

package/src/patterns/timeline/index.ts

@@ -0,0 +1,2 @@
+export { Timeline } from './Timeline';
+export type { TimelineItem, TimelineProps } from './types';

package/src/patterns/timeline/types.ts

@@ -0,0 +1,20 @@
+import type { ButtonIconSpec } from '@ankhorage/surface';
+import type React from 'react';
+
+import type { ZoraTone } from '../../internal/recipes';
+import type { ZoraBaseProps } from '../../theme/ZoraBaseProps';
+
+export interface TimelineItem {
+  id: string;
+  title: React.ReactNode;
+  description?: React.ReactNode;
+  meta?: React.ReactNode;
+  status?: ZoraTone;
+  icon?: ButtonIconSpec;
+  testID?: string;
+}
+
+export interface TimelineProps extends ZoraBaseProps {
+  items: readonly TimelineItem[];
+  compact?: boolean;
+}

package/src/showcaseCoverage.test.ts

@@ -35,9 +35,13 @@ const REQUIRED_SHOWCASE_COVERAGE = {
     'Icon',
     'IconButton',
     'Input',
+    'MediaCard',
+    'MetricCard',
     'Modal',
+    'Progress',
     'Radio',
     'RadioGroup',
+    'Rating',
     'SearchBar',
     'Select',
     'Tabs',
@@ -88,6 +92,7 @@ const REQUIRED_SHOWCASE_COVERAGE = {
     'SectionHeader',
     'SettingsRow',
     'SwitchField',
+    'Timeline',
     'ThemeComposer',
     'PaletteItem',
     'TileGrid',

package/src/theme/themeScopeStructure.test.ts

@@ -56,6 +56,8 @@ const scopedComponentFiles = [
   join(srcDir, 'components', 'badge', 'Badge.tsx'),
   join(srcDir, 'components', 'button', 'Button.tsx'),
   join(srcDir, 'components', 'card', 'Card.tsx'),
+  join(srcDir, 'components', 'media-card', 'MediaCard.tsx'),
+  join(srcDir, 'components', 'metric-card', 'MetricCard.tsx'),
   join(srcDir, 'components', 'checkbox', 'Checkbox.tsx'),
   join(srcDir, 'components', 'checkbox', 'CheckboxGroup.tsx'),
   join(srcDir, 'components', 'drawer', 'Drawer.tsx'),
@@ -68,8 +70,10 @@ const scopedComponentFiles = [
   join(srcDir, 'components', 'icon-button', 'IconButton.tsx'),
   join(srcDir, 'components', 'input', 'Input.tsx'),
   join(srcDir, 'components', 'modal', 'Modal.tsx'),
+  join(srcDir, 'components', 'progress', 'Progress.tsx'),
   join(srcDir, 'components', 'radio', 'Radio.tsx'),
   join(srcDir, 'components', 'radio', 'RadioGroup.tsx'),
+  join(srcDir, 'components', 'rating', 'Rating.tsx'),
   join(srcDir, 'components', 'select', 'Select.tsx'),
   join(srcDir, 'components', 'tabs', 'Tabs.tsx'),
   join(srcDir, 'components', 'text', 'Text.tsx'),
@@ -105,6 +109,7 @@ const scopedComponentFiles = [
   join(srcDir, 'patterns', 'section-header', 'SectionHeader.tsx'),
   join(srcDir, 'patterns', 'settings-row', 'SettingsRow.tsx'),
   join(srcDir, 'patterns', 'switch-field', 'SwitchField.tsx'),
+  join(srcDir, 'patterns', 'timeline', 'Timeline.tsx'),
   join(srcDir, 'patterns', 'tile-grid', 'PaletteItem.tsx'),
   join(srcDir, 'patterns', 'tile-grid', 'TileGrid.tsx'),
   join(srcDir, 'patterns', 'tree-view', 'TreeItem.tsx'),
@@ -126,6 +131,8 @@ const scopedPropTypeFiles = [
   join(srcDir, 'components', 'badge', 'types.ts'),
   join(srcDir, 'components', 'button', 'types.ts'),
   join(srcDir, 'components', 'card', 'types.ts'),
+  join(srcDir, 'components', 'media-card', 'types.ts'),
+  join(srcDir, 'components', 'metric-card', 'types.ts'),
   join(srcDir, 'components', 'checkbox', 'types.ts'),
   join(srcDir, 'components', 'drawer', 'types.ts'),
   join(srcDir, 'components', 'form', 'types.ts'),
@@ -134,7 +141,9 @@ const scopedPropTypeFiles = [
   join(srcDir, 'components', 'icon-button', 'types.ts'),
   join(srcDir, 'components', 'input', 'types.ts'),
   join(srcDir, 'components', 'modal', 'types.ts'),
+  join(srcDir, 'components', 'progress', 'types.ts'),
   join(srcDir, 'components', 'radio', 'types.ts'),
+  join(srcDir, 'components', 'rating', 'types.ts'),
   join(srcDir, 'components', 'select', 'types.ts'),
   join(srcDir, 'components', 'tabs', 'types.ts'),
   join(srcDir, 'components', 'text', 'types.ts'),
@@ -164,6 +173,7 @@ const scopedPropTypeFiles = [
   join(srcDir, 'patterns', 'section-header', 'types.ts'),
   join(srcDir, 'patterns', 'settings-row', 'types.ts'),
   join(srcDir, 'patterns', 'switch-field', 'types.ts'),
+  join(srcDir, 'patterns', 'timeline', 'types.ts'),
   join(srcDir, 'patterns', 'tile-grid', 'types.ts'),
   join(srcDir, 'patterns', 'tree-view', 'types.ts'),
 ] as const;