@ankhorage/zora 7.0.0 → 8.0.0

package/src/features/data-table/adapters/inbound/DataTable.tsx

@@ -0,0 +1,411 @@
+import type { InteractionPolicy } from '@ankhorage/surface';
+import React from 'react';
+import { ScrollView, type ViewStyle } from 'react-native';
+
+import { DropdownMenu, type MenuAction } from '../../../../components/menu';
+import { SkeletonList } from '../../../../components/skeleton';
+import { Show } from '../../../../foundation';
+import { EmptyState } from '../../../../patterns/empty-state';
+import { withZoraThemeScope } from '../../../../theme/withZoraThemeScope';
+import type {
+  DataTableCellContext,
+  DataTableColumn,
+  DataTableColumnAlign,
+  DataTableDensity,
+  DataTableProps,
+  DataTableRowAction,
+  DataTableSortDirection,
+} from '../../../../types/data-table';
+import { Button } from '../../../button/public';
+import { IconButton } from '../../../button/public';
+import { Card } from '../../../card/public';
+import { Box, Stack } from '../../../layout/public';
+import { Text, type TextAlign } from '../../../typography/public';
+import { resolveDataTableRowKey } from '../../utils/resolveDataTableRowKey';
+/***
+ * Displays structured tabular data with responsive desktop/mobile layouts.
+ */
+export const DataTable = withZoraThemeScope(DataTableInner);
+
+function resolveTextAlign(align: DataTableColumnAlign | undefined): TextAlign {
+  switch (align) {
+    case 'center':
+      return 'center';
+    case 'end':
+      return 'right';
+    case 'start':
+    default:
+      return 'left';
+  }
+}
+
+function resolveCellJustify(align: DataTableColumnAlign | undefined): ViewStyle['alignItems'] {
+  switch (align) {
+    case 'center':
+      return 'center';
+    case 'end':
+      return 'flex-end';
+    case 'start':
+    default:
+      return 'flex-start';
+  }
+}
+
+function resolveCellStyle<TRow extends object>(column: DataTableColumn<TRow>): ViewStyle {
+  return {
+    alignItems: resolveCellJustify(column.align),
+    flexGrow: column.width === undefined ? 1 : 0,
+    flexShrink: 0,
+    minWidth: column.minWidth ?? 140,
+    width: column.width,
+  };
+}
+
+function resolveRowPadding(density: DataTableDensity) {
+  return density === 'compact'
+    ? { px: 'm' as const, py: 's' as const }
+    : { px: 'm' as const, py: 'm' as const };
+}
+
+function resolveAccessorValue<TRow extends object>(row: TRow, column: DataTableColumn<TRow>) {
+  if (column.accessor === undefined) {
+    return undefined;
+  }
+
+  return row[column.accessor];
+}
+
+function renderDefaultCell(value: unknown): React.ReactNode {
+  if (value === null || value === undefined) {
+    return '—';
+  }
+
+  if (typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean') {
+    return String(value);
+  }
+
+  if (typeof value === 'bigint') {
+    return value.toString();
+  }
+
+  if (value instanceof Date) {
+    return value.toLocaleDateString();
+  }
+
+  return '—';
+}
+
+function createCellContext<TRow extends object>(
+  column: DataTableColumn<TRow>,
+  row: TRow,
+  rowIndex: number,
+): DataTableCellContext<TRow> {
+  return {
+    column,
+    row,
+    rowIndex,
+    value: resolveAccessorValue(row, column),
+  };
+}
+
+function renderCell<TRow extends object>(
+  column: DataTableColumn<TRow>,
+  row: TRow,
+  rowIndex: number,
+) {
+  const context = createCellContext(column, row, rowIndex);
+  return column.renderCell ? column.renderCell(context) : renderDefaultCell(context.value);
+}
+
+function renderTableCell<TRow extends object>(
+  column: DataTableColumn<TRow>,
+  row: TRow,
+  rowIndex: number,
+) {
+  if (column.renderCell) {
+    return column.renderCell(createCellContext(column, row, rowIndex));
+  }
+
+  return (
+    <Text align={resolveTextAlign(column.align)} variant="bodySmall">
+      {renderDefaultCell(resolveAccessorValue(row, column))}
+    </Text>
+  );
+}
+
+function resolveNextSortDirection(
+  current: DataTableSortDirection | undefined,
+): DataTableSortDirection {
+  return current === 'asc' ? 'desc' : 'asc';
+}
+
+function mapRowActions<TRow extends object>(
+  row: TRow,
+  actions: readonly DataTableRowAction<TRow>[],
+): readonly MenuAction[] {
+  return actions.map((action) => ({
+    description: action.description,
+    disabled: action.disabled,
+    icon: action.icon,
+    id: action.id,
+    intent: action.intent,
+    onPress: action.onPress ? () => action.onPress?.(row) : undefined,
+    title: action.title,
+  }));
+}
+
+function renderRowActions<TRow extends object>({
+  row,
+  rowIndex,
+  rowActions,
+  testID,
+  interactionPolicy,
+}: {
+  row: TRow;
+  rowIndex: number;
+  rowActions: DataTableProps<TRow>['rowActions'];
+  testID?: string;
+  interactionPolicy?: InteractionPolicy;
+}): React.ReactNode {
+  const actions = rowActions?.(row, rowIndex) ?? [];
+
+  if (actions.length === 0) {
+    return null;
+  }
+
+  return (
+    <DropdownMenu
+      actions={mapRowActions(row, actions)}
+      interactionPolicy={interactionPolicy}
+      testID={testID ? `${testID}-row-actions-${rowIndex}` : undefined}
+      trigger={
+        <IconButton
+          icon={{ name: 'ellipsis-horizontal' }}
+          label="Row actions"
+          size="s"
+          variant="ghost"
+        />
+      }
+    />
+  );
+}
+
+function DataTableHeader<TRow extends object>({
+  columns,
+  sort,
+  onSortChange,
+  density,
+  interactionPolicy,
+}: Pick<DataTableProps<TRow>, 'columns' | 'density' | 'onSortChange' | 'sort'> & {
+  interactionPolicy?: InteractionPolicy;
+}) {
+  const padding = resolveRowPadding(density ?? 'comfortable');
+  const passive = interactionPolicy === 'passive';
+
+  return (
+    <Box bg="subtle" borderColor="border" borderWidth={1} radius="m">
+      <Stack direction="row" align="center">
+        {columns.map((column) => {
+          const currentDirection = sort?.columnId === column.id ? sort.direction : undefined;
+          const sortable = Boolean(column.sortable && onSortChange);
+          const directionLabel =
+            currentDirection === undefined ? '' : currentDirection === 'asc' ? ' ↑' : ' ↓';
+
+          return (
+            <Box key={column.id} px={padding.px} py={padding.py} style={resolveCellStyle(column)}>
+              {sortable ? (
+                <Button
+                  color="primary"
+                  interactionPolicy={interactionPolicy}
+                  onPress={() => {
+                    if (passive) return;
+
+                    onSortChange?.({
+                      columnId: column.id,
+                      direction: resolveNextSortDirection(currentDirection),
+                    });
+                  }}
+                  size="s"
+                  variant="ghost"
+                >
+                  {column.header}
+                  {directionLabel}
+                </Button>
+              ) : (
+                <Text
+                  align={resolveTextAlign(column.align)}
+                  emphasis="muted"
+                  variant="caption"
+                  weight="semiBold"
+                >
+                  {column.header}
+                </Text>
+              )}
+            </Box>
+          );
+        })}
+        <Box px={padding.px} py={padding.py} style={{ minWidth: 56, width: 56 }}>
+          <Text align="right" emphasis="muted" variant="caption" weight="semiBold">
+            Actions
+          </Text>
+        </Box>
+      </Stack>
+    </Box>
+  );
+}
+
+function DataTableDesktop<TRow extends object>({
+  columns,
+  rows,
+  rowActions,
+  rowId,
+  rowKey,
+  sort,
+  onSortChange,
+  density,
+  testID,
+  interactionPolicy,
+}: DataTableProps<TRow>) {
+  const padding = resolveRowPadding(density ?? 'comfortable');
+
+  return (
+    <ScrollView horizontal showsHorizontalScrollIndicator={false}>
+      <Box minWidth={720} style={{ width: '100%' }}>
+        <Stack gap="xs">
+          <DataTableHeader
+            columns={columns}
+            density={density}
+            interactionPolicy={interactionPolicy}
+            onSortChange={onSortChange}
+            sort={sort}
+          />
+          <Stack gap="xs">
+            {rows.map((row, rowIndex) => (
+              <Box
+                bg="surface"
+                borderColor="border"
+                borderWidth={1}
+                key={resolveDataTableRowKey(row, rowIndex, rowKey, rowId)}
+                radius="m"
+                testID={testID ? `${testID}-row-${rowIndex}` : undefined}
+              >
+                <Stack direction="row" align="center">
+                  {columns.map((column) => (
+                    <Box
+                      key={column.id}
+                      px={padding.px}
+                      py={padding.py}
+                      style={resolveCellStyle(column)}
+                    >
+                      {renderTableCell(column, row, rowIndex)}
+                    </Box>
+                  ))}
+                  <Box
+                    px={padding.px}
+                    py={padding.py}
+                    style={{ alignItems: 'flex-end', minWidth: 56, width: 56 }}
+                  >
+                    {renderRowActions({ row, rowActions, rowIndex, testID, interactionPolicy })}
+                  </Box>
+                </Stack>
+              </Box>
+            ))}
+          </Stack>
+        </Stack>
+      </Box>
+    </ScrollView>
+  );
+}
+
+function DataTableMobile<TRow extends object>({
+  columns,
+  rows,
+  rowActions,
+  rowId,
+  rowKey,
+  testID,
+  interactionPolicy,
+}: DataTableProps<TRow>) {
+  const [primaryColumn, ...detailColumns] = columns;
+
+  return (
+    <Stack gap="s">
+      {rows.map((row, rowIndex) => {
+        const title = primaryColumn
+          ? renderCell(primaryColumn, row, rowIndex)
+          : `Row ${rowIndex + 1}`;
+        const actions = renderRowActions({ row, rowActions, rowIndex, testID, interactionPolicy });
+
+        return (
+          <Card
+            actions={actions}
+            compact
+            interactionPolicy={interactionPolicy}
+            key={resolveDataTableRowKey(row, rowIndex, rowKey, rowId)}
+            testID={testID ? `${testID}-card-${rowIndex}` : undefined}
+            title={title}
+          >
+            <Stack gap="s">
+              {detailColumns.map((column) => (
+                <Stack gap="xxs" key={column.id}>
+                  <Text emphasis="muted" variant="caption" weight="semiBold">
+                    {column.header}
+                  </Text>
+                  {column.renderCell ? (
+                    renderCell(column, row, rowIndex)
+                  ) : (
+                    <Text variant="bodySmall">
+                      {renderDefaultCell(resolveAccessorValue(row, column))}
+                    </Text>
+                  )}
+                </Stack>
+              ))}
+            </Stack>
+          </Card>
+        );
+      })}
+    </Stack>
+  );
+}
+
+function DataTableInner<TRow extends object>({
+  themeId: _themeId,
+  mode: _mode,
+  rows,
+  loading = false,
+  loadingRows = 5,
+  emptyTitle = 'No data',
+  emptyDescription = 'There are no rows to display.',
+  testID,
+  density = 'comfortable',
+  interactionPolicy,
+  ...props
+}: DataTableProps<TRow>) {
+  if (loading) {
+    return <SkeletonList rows={loadingRows} variant="card" testID={testID} />;
+  }
+
+  if (rows.length === 0) {
+    return <EmptyState title={emptyTitle} description={emptyDescription} />;
+  }
+
+  const tableProps: DataTableProps<TRow> = {
+    ...props,
+    density,
+    emptyDescription,
+    emptyTitle,
+    interactionPolicy,
+    loading,
+    loadingRows,
+    rows,
+    testID,
+  };
+
+  return (
+    <Box testID={testID}>
+      <Show when={{ base: false, md: true }} fallback={<DataTableMobile {...tableProps} />}>
+        <DataTableDesktop {...tableProps} />
+      </Show>
+    </Box>
+  );
+}

package/src/features/data-table/dataTableMeta.ts

@@ -0,0 +1,58 @@
+import type { ZoraComponentMeta } from '../../metadata/types';
+
+export const dataTableMeta = {
+  name: 'DataTable',
+  category: 'component',
+  directManifestNode: true,
+  allowedChildren: [],
+  blueprint: { label: 'Data table', defaultProps: { rows: [], columns: [], rowKey: 'id' } },
+  events: {
+    sortChange: {
+      label: 'Sort change',
+      eventType: 'dataTable.sortChange',
+      payloadFields: [
+        { path: 'columnId', type: 'string' },
+        { path: 'direction', type: 'string' },
+      ],
+    },
+  },
+  bindings: {
+    props: {
+      sort: {
+        value: {
+          type: 'object',
+          fields: [
+            { path: 'columnId', type: 'string' },
+            { path: 'direction', type: 'string' },
+          ],
+        },
+        acceptsFallback: true,
+      },
+    },
+  },
+  props: {
+    rows: { type: 'array', category: 'Data' },
+    rowKey: { type: 'string', category: 'Identity', label: 'Row identity field' },
+    columns: {
+      type: 'array',
+      category: 'Data',
+      itemSchema: [
+        { key: 'id', schema: { type: 'string', category: 'Identity' } },
+        { key: 'header', schema: { type: 'string', category: 'Content' } },
+        { key: 'accessor', schema: { type: 'string', category: 'Data' } },
+        {
+          key: 'align',
+          schema: { type: 'enum', category: 'Layout', enum: ['start', 'center', 'end'] },
+        },
+        { key: 'width', schema: { type: 'number', category: 'Layout' } },
+        { key: 'minWidth', schema: { type: 'number', category: 'Layout' } },
+        { key: 'sortable', schema: { type: 'boolean', category: 'Behavior' } },
+      ],
+    },
+    loading: { type: 'boolean', category: 'State' },
+    loadingRows: { type: 'number', category: 'State' },
+    emptyTitle: { type: 'string', category: 'Content' },
+    emptyDescription: { type: 'string', category: 'Content' },
+    density: { type: 'enum', category: 'Layout', enum: ['comfortable', 'compact'] },
+  },
+} as const satisfies ZoraComponentMeta;

package/src/features/data-table/public.ts

@@ -0,0 +1,11 @@
+export type {
+  DataTableCellContext,
+  DataTableColumn,
+  DataTableColumnAlign,
+  DataTableDensity,
+  DataTableProps,
+  DataTableRowAction,
+  DataTableSortDirection,
+  DataTableSortState,
+} from '../../types/data-table';
+export { DataTable } from './adapters/inbound/DataTable';

package/src/features/data-table/utils/resolveDataTableRowKey.test.ts

@@ -0,0 +1,11 @@
+import { expect, test } from 'bun:test';
+
+import { resolveDataTableRowKey } from './resolveDataTableRowKey';
+
+test('retains row identity across reordering using a serializable field name', () => {
+  expect(resolveDataTableRowKey({ id: 'a' }, 0, 'id')).toBe('a');
+  expect(resolveDataTableRowKey({ id: 'a' }, 12, 'id')).toBe('a');
+  expect(resolveDataTableRowKey({ id: 0 }, 2, 'id')).toBe('0');
+  expect(resolveDataTableRowKey({ id: 'a' }, 2, undefined, (row) => row.id)).toBe('a');
+  expect(() => resolveDataTableRowKey({ id: null }, 0, 'id')).toThrow('rowKey');
+});

package/src/features/data-table/utils/resolveDataTableRowKey.ts

@@ -0,0 +1,13 @@
+/*** Resolves a table row's identity from its declared field or explicit React callback. */
+export function resolveDataTableRowKey<TRow extends object>(
+  row: TRow,
+  index: number,
+  rowKey?: keyof TRow,
+  rowId?: (row: TRow, index: number) => string,
+): string {
+  if (rowId) return rowId(row, index);
+  const key: unknown =
+    rowKey === undefined ? undefined : new Map(Object.entries(row)).get(String(rowKey));
+  if (typeof key === 'string' || typeof key === 'number') return String(key);
+  throw new Error('DataTable requires a rowKey field containing a string or number for every row.');
+}

package/src/features/icon/adapters/inbound/Icon.tsx

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

package/src/features/icon/public.ts

@@ -0,0 +1,2 @@
+export type { IconProps } from '../../types/icon';
+export { Icon } from './adapters/inbound/Icon';

package/src/features/icon/utils/meta.test.ts

@@ -0,0 +1,22 @@
+import { expect, test } from 'bun:test';
+
+import { ZORA_COMPONENT_META } from '../../../metadata/componentMeta';
+
+test('permits media-backed Icon and Image content in ordinary screen containers', () => {
+  const icon = ZORA_COMPONENT_META.Icon;
+  expect(icon.directManifestNode).toBe(true);
+  expect(icon.allowedChildren).toEqual([]);
+  expect(icon.props.source).toMatchObject({ type: 'media', mediaKinds: ['image'] });
+  for (const container of [
+    ZORA_COMPONENT_META.Box,
+    ZORA_COMPONENT_META.Stack,
+    ZORA_COMPONENT_META.Grid,
+    ZORA_COMPONENT_META.Container,
+    ZORA_COMPONENT_META.Card,
+    ZORA_COMPONENT_META.Screen,
+    ZORA_COMPONENT_META.ScreenSection,
+  ]) {
+    expect(container.allowedChildren).toContain('Icon');
+    expect(container.allowedChildren).toContain('Image');
+  }
+});

package/src/features/image/adapters/inbound/Image.tsx

@@ -0,0 +1,149 @@
+import { Image as SurfaceImage, type SurfaceImageSource } from '@ankhorage/surface';
+import React from 'react';
+
+import { useZoraTheme } from '../../../../theme/useZoraTheme';
+import { withZoraThemeScope } from '../../../../theme/withZoraThemeScope';
+import type { ImageProps } from '../../../../types/image';
+import type { UploadAsset } from '../../../../types/upload';
+import { Icon } from '../../../icon/public';
+import { Box } from '../../../layout/public';
+
+/*** Displays an image asset and owns its missing, unrenderable, and failed presentation states. */
+export const Image = withZoraThemeScope(ImageInner);
+
+/*** Renders the resolved image source or the canonical ZORA image placeholder. */
+function ImageInner({
+  themeId: _themeId,
+  mode: _mode,
+  interactionPolicy: _interactionPolicy,
+  source,
+  fallbackSource,
+  alt,
+  accessibilityLabel,
+  width,
+  height,
+  aspectRatio,
+  radius,
+  style,
+  testID,
+  onError,
+  ...props
+}: ImageProps) {
+  const { theme } = useZoraTheme();
+  const resolvedSource = resolveImageSource(source);
+  const sourceKey = resolveImageSourceKey(source);
+  const firstFailureKeyRef = React.useRef<string | null>(null);
+  const [failedSourceKey, setFailedSourceKey] = React.useState<string | null>(null);
+  const showPlaceholder = resolvedSource === null || failedSourceKey === sourceKey;
+  const resolvedAlt = alt ?? (isUploadAsset(source) ? source.alt : undefined);
+  const placeholderLabel = accessibilityLabel ?? resolvedAlt;
+
+  if (showPlaceholder) {
+    return (
+      <Box
+        accessibilityLabel={placeholderLabel}
+        accessibilityRole={placeholderLabel ? 'image' : undefined}
+        accessible={Boolean(placeholderLabel)}
+        bg={theme.semantics.neutral.surface}
+        borderColor={theme.semantics.neutral.divider}
+        borderWidth={1}
+        height={height}
+        overflow="hidden"
+        radius={radius}
+        testID={testID}
+        width={width}
+        style={[
+          {
+            alignItems: 'center',
+            aspectRatio: aspectRatio ?? 1,
+            justifyContent: 'center',
+          },
+          style,
+        ]}
+      >
+        <Icon color={theme.semantics.content.muted} name="image-outline" size={24} />
+      </Box>
+    );
+  }
+
+  return (
+    <SurfaceImage
+      {...props}
+      accessibilityLabel={accessibilityLabel}
+      alt={resolvedAlt}
+      aspectRatio={aspectRatio}
+      fallbackSource={fallbackSource}
+      height={height}
+      onError={(event) => {
+        onError?.(event);
+
+        if (!sourceKey) {
+          return;
+        }
+
+        if (fallbackSource && firstFailureKeyRef.current !== sourceKey) {
+          firstFailureKeyRef.current = sourceKey;
+          return;
+        }
+
+        setFailedSourceKey(sourceKey);
+      }}
+      radius={radius}
+      source={resolvedSource}
+      style={style}
+      testID={testID}
+      width={width}
+    />
+  );
+}
+
+/*** Resolves a generic upload asset into a source understood by the Surface Image primitive. */
+function resolveImageSource(source: ImageProps['source']): SurfaceImageSource | null | undefined {
+  if (!isUploadAsset(source)) {
+    return source;
+  }
+
+  switch (source.kind) {
+    case 'local':
+      return source.uri;
+    case 'url':
+      return source.url;
+    case 'storage':
+      return source.publicUrl ?? null;
+  }
+}
+
+/*** Produces a stable-enough key for tracking image failures across source changes. */
+function resolveImageSourceKey(source: ImageProps['source']): string | null {
+  if (source === null || source === undefined) {
+    return null;
+  }
+
+  if (isUploadAsset(source)) {
+    switch (source.kind) {
+      case 'local':
+        return `local:${source.uri}`;
+      case 'url':
+        return `url:${source.url}`;
+      case 'storage':
+        return `storage:${source.bucket}:${source.path}:${source.publicUrl ?? ''}`;
+    }
+  }
+
+  if (typeof source === 'string' || typeof source === 'number') {
+    return `source:${String(source)}`;
+  }
+
+  if (!Array.isArray(source) && 'uri' in source && typeof source.uri === 'string') {
+    return `source:${source.uri}`;
+  }
+
+  return 'source:opaque';
+}
+
+/*** Identifies the generic ZORA upload asset shape without leaking picker-specific types. */
+function isUploadAsset(source: ImageProps['source']): source is UploadAsset {
+  return (
+    typeof source === 'object' && source !== null && !Array.isArray(source) && 'kind' in source
+  );
+}