@ankhorage/zora 1.0.5 → 1.0.7

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';
@@ -146,6 +154,15 @@ export type { FilterBarProps } from './patterns/filter-bar';
 export { FilterBar } from './patterns/filter-bar';
 export type { InspectorFieldProps } from './patterns/inspector-field';
 export { InspectorField } from './patterns/inspector-field';
+export type {
+  ListChildrenProps,
+  ListItemsProps,
+  ListProps,
+  ListRowProps,
+  ListRowVariant,
+  ListSectionProps,
+} from './patterns/list';
+export { List, ListRow, ListSection } from './patterns/list';
 export type { NoticeProps } from './patterns/notice';
 export { Notice } from './patterns/notice';
 export type { PanelProps } from './patterns/panel';
@@ -162,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/list/List.tsx

@@ -0,0 +1,72 @@
+import React from 'react';
+
+import { Divider, Spacer, Stack } from '../../foundation';
+import { withZoraThemeScope } from '../../theme/withZoraThemeScope';
+import { ListRow } from './ListRow';
+import { resolveListSeparator } from './resolveListSeparator';
+import type { ListItemsProps, ListProps, ListRowProps, ListRowVariant } from './types';
+
+function resolveRowVariant({
+  item,
+  defaultVariant,
+}: {
+  item: ListRowProps;
+  defaultVariant: ListRowVariant;
+}): ListRowVariant {
+  return item.variant ?? defaultVariant;
+}
+
+function resolveRowCompact({
+  item,
+  compact,
+}: {
+  item: ListRowProps;
+  compact: boolean | undefined;
+}): boolean {
+  return item.compact ?? compact ?? false;
+}
+
+function ListItemsInner({
+  themeId: _themeId,
+  mode: _mode,
+  testID,
+  items,
+  rowVariant = 'divider',
+  compact,
+}: ListItemsProps) {
+  return (
+    <Stack gap="none" testID={testID}>
+      {items.map((item, index) => {
+        const effectiveVariant = resolveRowVariant({ item, defaultVariant: rowVariant });
+        const separator = resolveListSeparator(effectiveVariant, index);
+
+        return (
+          <React.Fragment key={`${index}`}>
+            {separator === 'divider' ? <Divider /> : null}
+            {separator === 'spacer' ? <Spacer size="s" /> : null}
+            <ListRow
+              {...item}
+              compact={resolveRowCompact({ item, compact })}
+              variant={effectiveVariant}
+            />
+          </React.Fragment>
+        );
+      })}
+    </Stack>
+  );
+}
+
+function ListInner(props: ListProps) {
+  if ('items' in props) {
+    return <ListItemsInner {...props} />;
+  }
+
+  const { themeId: _themeId, mode: _mode, children, testID } = props;
+  return (
+    <Stack gap="none" testID={testID}>
+      {children}
+    </Stack>
+  );
+}
+
+export const List = withZoraThemeScope(ListInner);

package/src/patterns/list/ListRow.tsx

@@ -0,0 +1,193 @@
+import { ButtonBase } from '@ankhorage/surface';
+import React from 'react';
+
+import { Text } from '../../components/text';
+import { Box, Inline, Spacer, Stack } from '../../foundation';
+import { useZoraTheme } from '../../theme/useZoraTheme';
+import { withZoraThemeScope } from '../../theme/withZoraThemeScope';
+import type { ListRowProps, ListRowVariant } from './types';
+
+function resolvePadding(compact: boolean) {
+  return compact ? { px: 'm' as const, py: 's' as const } : { px: 'm' as const, py: 'm' as const };
+}
+
+function resolveContainerStyles({
+  variant,
+  theme,
+  selected,
+  pressed,
+  hovered,
+  disabled,
+}: {
+  variant: ListRowVariant;
+  theme: ReturnType<typeof useZoraTheme>['theme'];
+  selected: boolean;
+  pressed: boolean;
+  hovered: boolean;
+  disabled: boolean;
+}) {
+  const borderColor = selected ? theme.semantics.border.focus : theme.semantics.border.default;
+  const dividerBorderColor = selected ? theme.semantics.border.focus : 'transparent';
+
+  if (variant === 'card') {
+    return {
+      bg: pressed
+        ? theme.semantics.neutral.surfaceActive
+        : hovered
+          ? theme.semantics.neutral.surfaceHover
+          : theme.semantics.surface.raised,
+      borderColor,
+      borderWidth: 1,
+      radius: 'l' as const,
+      opacity: disabled ? 0.72 : 1,
+    };
+  }
+
+  return {
+    bg: pressed
+      ? theme.semantics.neutral.surfaceActive
+      : hovered
+        ? theme.semantics.neutral.surfaceHover
+        : selected
+          ? theme.semantics.neutral.surface
+          : 'transparent',
+    borderColor: dividerBorderColor,
+    borderWidth: selected ? 1 : 0,
+    radius: 'm' as const,
+    opacity: disabled ? 0.72 : 1,
+  };
+}
+
+function ListRowInner({
+  themeId: _themeId,
+  mode: _mode,
+  testID,
+  title,
+  description,
+  meta,
+  leading,
+  trailing,
+  action,
+  onPress,
+  selected = false,
+  disabled = false,
+  compact = false,
+  variant = 'divider',
+}: ListRowProps) {
+  const { theme } = useZoraTheme();
+  const padding = resolvePadding(compact);
+  const isInteractive = Boolean(onPress) && !action;
+
+  const content = (
+    <Stack
+      align="center"
+      direction="row"
+      style={{
+        flex: 1,
+      }}
+    >
+      {leading ? (
+        <>
+          <Box>{leading}</Box>
+          <Spacer axis="horizontal" size="m" />
+        </>
+      ) : null}
+
+      <Box flex={1}>
+        <Stack gap="xxs">
+          <Text variant="body" weight={selected ? 'semiBold' : 'medium'}>
+            {title}
+          </Text>
+          {description ? (
+            <Text tone="muted" variant="bodySmall">
+              {description}
+            </Text>
+          ) : null}
+          {meta ? (
+            <Text tone="subtle" variant="caption">
+              {meta}
+            </Text>
+          ) : null}
+        </Stack>
+      </Box>
+
+      {trailing || action ? (
+        <>
+          <Spacer axis="horizontal" size="m" />
+          <Inline align="center" gap="s" wrap="nowrap">
+            {trailing}
+            {action}
+          </Inline>
+        </>
+      ) : null}
+    </Stack>
+  );
+
+  if (!isInteractive) {
+    const styles = resolveContainerStyles({
+      variant,
+      theme,
+      selected,
+      pressed: false,
+      hovered: false,
+      disabled,
+    });
+
+    return (
+      <Box
+        bg={styles.bg}
+        borderColor={styles.borderColor}
+        borderWidth={styles.borderWidth}
+        px={padding.px}
+        py={padding.py}
+        radius={styles.radius}
+        testID={testID}
+        style={{
+          opacity: styles.opacity,
+        }}
+      >
+        {content}
+      </Box>
+    );
+  }
+
+  return (
+    <ButtonBase
+      accessibilityRole="button"
+      accessibilityState={{ disabled, selected }}
+      disabled={disabled}
+      onPress={onPress}
+      radius={variant === 'card' ? 'l' : 'm'}
+      testID={testID}
+    >
+      {(state) => {
+        const styles = resolveContainerStyles({
+          variant,
+          theme,
+          selected,
+          pressed: state.pressed,
+          hovered: state.hovered,
+          disabled: state.disabled,
+        });
+
+        return (
+          <Box
+            bg={styles.bg}
+            borderColor={styles.borderColor}
+            borderWidth={styles.borderWidth}
+            px={padding.px}
+            py={padding.py}
+            radius={styles.radius}
+            style={{
+              opacity: styles.opacity,
+            }}
+          >
+            {content}
+          </Box>
+        );
+      }}
+    </ButtonBase>
+  );
+}
+
+export const ListRow = withZoraThemeScope(ListRowInner);

package/src/patterns/list/ListSection.tsx

@@ -0,0 +1,36 @@
+import React from 'react';
+
+import { Stack } from '../../foundation';
+import { withZoraThemeScope } from '../../theme/withZoraThemeScope';
+import { SectionHeader } from '../section-header';
+import { List } from './List';
+import type { ListSectionProps } from './types';
+
+function ListSectionInner({
+  themeId: _themeId,
+  mode: _mode,
+  testID,
+  title,
+  description,
+  eyebrow,
+  actions,
+  ...props
+}: ListSectionProps) {
+  const hasHeader = title !== undefined;
+
+  return (
+    <Stack gap="s" testID={testID}>
+      {hasHeader ? (
+        <SectionHeader
+          actions={actions}
+          description={description}
+          eyebrow={eyebrow}
+          title={title}
+        />
+      ) : null}
+      <List {...props} />
+    </Stack>
+  );
+}
+
+export const ListSection = withZoraThemeScope(ListSectionInner);

package/src/patterns/list/index.ts

@@ -0,0 +1,11 @@
+export { List } from './List';
+export { ListRow } from './ListRow';
+export { ListSection } from './ListSection';
+export type {
+  ListChildrenProps,
+  ListItemsProps,
+  ListProps,
+  ListRowProps,
+  ListRowVariant,
+  ListSectionProps,
+} from './types';

package/src/patterns/list/resolveListSeparator.test.ts

@@ -0,0 +1,18 @@
+import { describe, expect, it } from 'bun:test';
+
+import { resolveListSeparator } from './resolveListSeparator';
+
+describe('resolveListSeparator', () => {
+  it('returns none for the first item', () => {
+    expect(resolveListSeparator('divider', 0)).toBe('none');
+    expect(resolveListSeparator('card', 0)).toBe('none');
+  });
+
+  it('returns divider for divider rows', () => {
+    expect(resolveListSeparator('divider', 1)).toBe('divider');
+  });
+
+  it('returns spacer for card rows', () => {
+    expect(resolveListSeparator('card', 1)).toBe('spacer');
+  });
+});

package/src/patterns/list/resolveListSeparator.ts

@@ -0,0 +1,8 @@
+import type { ListRowVariant } from './types';
+
+type ListSeparatorKind = 'none' | 'divider' | 'spacer';
+
+export function resolveListSeparator(variant: ListRowVariant, index: number): ListSeparatorKind {
+  if (index === 0) return 'none';
+  return variant === 'divider' ? 'divider' : 'spacer';
+}

package/src/patterns/list/types.ts

@@ -0,0 +1,67 @@
+import type React from 'react';
+
+import type { ZoraBaseProps } from '../../theme/ZoraBaseProps';
+
+export type ListRowVariant = 'divider' | 'card';
+
+interface ListRowBaseProps extends ZoraBaseProps {
+  title: React.ReactNode;
+  description?: React.ReactNode;
+  meta?: React.ReactNode;
+  leading?: React.ReactNode;
+  trailing?: React.ReactNode;
+  selected?: boolean;
+  disabled?: boolean;
+  compact?: boolean;
+  variant?: ListRowVariant;
+}
+
+interface ListRowPressableProps {
+  onPress: () => void;
+  action?: never;
+}
+
+interface ListRowActionProps {
+  action: React.ReactNode;
+  onPress?: never;
+}
+
+interface ListRowStaticProps {
+  action?: never;
+  onPress?: never;
+}
+
+export type ListRowProps = ListRowBaseProps &
+  (ListRowPressableProps | ListRowActionProps | ListRowStaticProps);
+
+export interface ListItemsProps extends ZoraBaseProps {
+  items: readonly ListRowProps[];
+  rowVariant?: ListRowVariant;
+  compact?: boolean;
+}
+
+export interface ListChildrenProps extends ZoraBaseProps {
+  children: React.ReactNode;
+}
+
+export type ListProps = ListItemsProps | ListChildrenProps;
+
+export interface ListSectionItemsProps extends ZoraBaseProps {
+  title?: React.ReactNode;
+  description?: React.ReactNode;
+  eyebrow?: React.ReactNode;
+  actions?: React.ReactNode;
+  items: readonly ListRowProps[];
+  rowVariant?: ListRowVariant;
+  compact?: boolean;
+}
+
+export interface ListSectionChildrenProps extends ZoraBaseProps {
+  title?: React.ReactNode;
+  description?: React.ReactNode;
+  eyebrow?: React.ReactNode;
+  actions?: React.ReactNode;
+  children: React.ReactNode;
+}
+
+export type ListSectionProps = ListSectionItemsProps | ListSectionChildrenProps;