@tallyui/components 1.0.0 → 3.0.0-next.0

package/src/layout/store-settings-choice-screen.tsx

@@ -0,0 +1,142 @@
+import { useState } from 'react';
+import { Pressable, Text, View, type ViewProps } from 'react-native';
+
+import { cn } from '@tallyui/theme';
+import type { StoreSettingsChoice, StoreSettingsChoices } from '@tallyui/core';
+
+export interface StoreSettingsChoiceScreenProps extends Omit<ViewProps, 'children'> {
+  /** From `StoreSettingsError.choices`. Only the sections present are shown. */
+  choices: StoreSettingsChoices;
+  /** A previous choice to pre-select (for example, a stale stored one); fields that aren't in `choices` are ignored. */
+  initial?: StoreSettingsChoice;
+  /** Called with the full choice when the user confirms. The app persists it per store and retries `storeSettings`. */
+  onSubmit: (choice: StoreSettingsChoice) => void;
+  /** Display name for an ISO 3166-1 alpha-2 code. Default: `Intl.DisplayNames` in `locale`, falling back to the upper-cased code. */
+  countryName?: (code: string) => string;
+  locale?: string;
+  title?: string;
+  body?: string;
+  regionLabel?: string;
+  countryLabel?: string;
+  channelLabel?: string;
+  submitLabel?: string;
+  className?: string;
+}
+
+type Option = { value: string; label: string };
+
+/** The single option if there is only one, else a matching `initial` value, else none. */
+function useSectionSelection(options: Option[], initialValue: string | undefined) {
+  const preset = options.length === 1 ? options[0].value : options.find((o) => o.value === initialValue)?.value;
+  return useState<string | undefined>(preset);
+}
+
+function defaultCountryName(code: string, locale?: string): string {
+  try {
+    return new Intl.DisplayNames([locale ?? 'en'], { type: 'region' }).of(code.toUpperCase()) ?? code.toUpperCase();
+  } catch {
+    return code.toUpperCase();
+  }
+}
+
+/**
+ * TV4: shown when `storeSettings` rejects with `choice_required`. The app
+ * persists the returned choice per store and calls `storeSettings(context,
+ * choice)` again; a stored choice that no longer resolves raises
+ * `choice_required` again, and this screen pre-selects what still matches.
+ */
+export function StoreSettingsChoiceScreen({
+  choices,
+  initial,
+  onSubmit,
+  countryName,
+  locale,
+  title = 'Set up this till',
+  body = 'This store sells in more than one place. Choose where this till is.',
+  regionLabel = 'Region',
+  countryLabel = 'Country',
+  channelLabel = 'Sales channel',
+  submitLabel = 'Continue',
+  className,
+  ...viewProps
+}: StoreSettingsChoiceScreenProps) {
+  const regionOptions: Option[] = (choices.regions ?? []).map((r) => ({ value: r.id, label: r.name }));
+  const channelOptions: Option[] = (choices.channels ?? []).map((c) => ({ value: c.id, label: c.name }));
+  const nameForCountry = countryName ?? ((code: string) => defaultCountryName(code, locale));
+  const countryOptions: Option[] = (choices.countries ?? []).map((code) => ({ value: code, label: nameForCountry(code) }));
+
+  const [region, setRegion] = useSectionSelection(regionOptions, initial?.region);
+  const [country, setCountry] = useSectionSelection(countryOptions, initial?.country);
+  const [channel, setChannel] = useSectionSelection(channelOptions, initial?.channel);
+
+  const showRegions = regionOptions.length > 0;
+  const showCountries = countryOptions.length > 0;
+  const showChannels = channelOptions.length > 0;
+  const complete =
+    (!showRegions || region !== undefined) &&
+    (!showCountries || country !== undefined) &&
+    (!showChannels || channel !== undefined);
+
+  const handleSubmit = () => {
+    if (!complete) return;
+    const choice: StoreSettingsChoice = {};
+    if (showRegions) choice.region = region;
+    else if (initial?.region !== undefined) choice.region = initial.region;
+    if (showCountries) choice.country = country?.toLowerCase();
+    else if (initial?.country !== undefined) choice.country = initial.country;
+    if (showChannels) choice.channel = channel;
+    else if (initial?.channel !== undefined) choice.channel = initial.channel;
+    onSubmit(choice);
+  };
+
+  return (
+    <View className={cn('w-full max-w-[560px] flex-1 self-center gap-6 bg-bg p-6', className)} {...viewProps}>
+      <View className="gap-2">
+        <Text className="text-lg font-bold text-foreground">{title}</Text>
+        <Text className="text-sm text-muted-foreground">{body}</Text>
+      </View>
+      {showRegions && <ChoiceSection label={regionLabel} options={regionOptions} selected={region} onSelect={setRegion} />}
+      {showCountries && <ChoiceSection label={countryLabel} options={countryOptions} selected={country} onSelect={setCountry} />}
+      {showChannels && <ChoiceSection label={channelLabel} options={channelOptions} selected={channel} onSelect={setChannel} />}
+      <Pressable
+        onPress={handleSubmit}
+        disabled={!complete}
+        // Dim the whole button when disabled, so the label keeps its contrast in both themes.
+        className={cn('items-center rounded-lg bg-primary px-4 py-3', !complete && 'opacity-50')}
+      >
+        <Text className="text-sm font-semibold text-primary-foreground">{submitLabel}</Text>
+      </Pressable>
+    </View>
+  );
+}
+
+type ChoiceSectionProps = { label: string; options: Option[]; selected: string | undefined; onSelect: (value: string) => void };
+
+function ChoiceSection({ label, options, selected, onSelect }: ChoiceSectionProps) {
+  return (
+    <View className="gap-1.5">
+      <Text className="text-xs font-semibold text-muted-foreground">{label}</Text>
+      <View className="rounded-lg border border-border">
+        {options.map((option, index) => {
+          const checked = option.value === selected;
+          return (
+            <Pressable
+              key={option.value}
+              onPress={() => onSelect(option.value)}
+              accessibilityRole="radio"
+              aria-checked={checked}
+              testID={`choice-option-${option.value}`}
+              className={cn('flex-row items-center gap-3 px-4 py-3', index > 0 && 'border-t border-border', checked && 'bg-primary/10')}
+            >
+              {/* Same radio visual as @tallyui/components/ui/radio-group: ring + dot, so the choice reads without colour. */}
+              <View className="h-4 w-4 items-center justify-center rounded-full border border-primary">
+                {checked && <View testID={`choice-option-${option.value}-dot`} className="h-2.5 w-2.5 rounded-full bg-primary" />}
+              </View>
+              <Text className={cn('text-sm', checked ? 'font-semibold text-primary' : 'text-foreground')}>{option.label}</Text>
+            </Pressable>
+          );
+        })}
+      </View>
+    </View>
+  );
+}

package/src/order/index.ts

@@ -0,0 +1,4 @@
+export { OrderStatusBadge, type OrderStatusBadgeProps, type OrderStatus } from './order-status-badge';
+export { OrderCard, type OrderCardProps } from './order-card';
+export { OrderList, type OrderListProps } from './order-list';
+export { OrderDetail, type OrderDetailProps, type OrderDetailLineItem } from './order-detail';

package/src/order/order-card.tsx

@@ -0,0 +1,48 @@
+import { Pressable, Text, View, type ViewProps } from 'react-native';
+
+import { cn } from '@tallyui/theme';
+
+import { OrderStatusBadge, type OrderStatus } from './order-status-badge';
+
+export interface OrderCardProps extends Omit<ViewProps, 'children'> {
+  orderNumber: string;
+  date: string;
+  total: string;
+  status: OrderStatus;
+  customerName?: string;
+  onPress?: () => void;
+  className?: string;
+}
+
+export function OrderCard({
+  orderNumber,
+  date,
+  total,
+  status,
+  customerName,
+  onPress,
+  className,
+  ...viewProps
+}: OrderCardProps) {
+  const Wrapper = onPress ? Pressable : View;
+
+  return (
+    <Wrapper
+      onPress={onPress}
+      className={cn('gap-2 rounded-lg border border-border bg-card p-3', className)}
+      {...viewProps}
+    >
+      <View className="flex-row items-center justify-between">
+        <Text className="text-sm font-semibold text-foreground">{orderNumber}</Text>
+        <OrderStatusBadge status={status} />
+      </View>
+      <View className="flex-row items-center justify-between">
+        <View className="gap-0.5">
+          <Text className="text-xs text-muted-foreground">{date}</Text>
+          {customerName && <Text className="text-xs text-muted-foreground">{customerName}</Text>}
+        </View>
+        <Text className="text-sm font-semibold text-foreground">{total}</Text>
+      </View>
+    </Wrapper>
+  );
+}

package/src/order/order-detail.tsx

@@ -0,0 +1,82 @@
+import type { ReactNode } from 'react';
+import { ScrollView, Text, View, type ViewProps } from 'react-native';
+
+import { cn } from '@tallyui/theme';
+
+import { OrderStatusBadge, type OrderStatus } from './order-status-badge';
+
+export interface OrderDetailLineItem {
+  name: string;
+  quantity: number;
+  total: string;
+}
+
+export interface OrderDetailProps extends Omit<ViewProps, 'children'> {
+  orderNumber: string;
+  status: OrderStatus;
+  lineItems: OrderDetailLineItem[];
+  subtotal: string;
+  tax: string;
+  total: string;
+  customerSlot?: ReactNode;
+  paymentSlot?: ReactNode;
+  footerSlot?: ReactNode;
+  className?: string;
+}
+
+export function OrderDetail({
+  orderNumber,
+  status,
+  lineItems,
+  subtotal,
+  tax,
+  total,
+  customerSlot,
+  paymentSlot,
+  footerSlot,
+  className,
+  ...viewProps
+}: OrderDetailProps) {
+  return (
+    <ScrollView className={cn('flex-1', className)} {...viewProps}>
+      <View className="gap-4 p-4">
+        <View className="flex-row items-center justify-between">
+          <Text className="text-lg font-bold text-foreground">{orderNumber}</Text>
+          <OrderStatusBadge status={status} />
+        </View>
+
+        {customerSlot && <View className="border-b border-border pb-3">{customerSlot}</View>}
+
+        <View className="gap-1">
+          <Text className="text-xs font-semibold text-muted-foreground">Items</Text>
+          {lineItems.map((item, i) => (
+            <View key={i} className="flex-row items-center justify-between py-1">
+              <Text className="flex-1 text-sm text-foreground">
+                {item.name} x{item.quantity}
+              </Text>
+              <Text className="text-sm text-foreground">{item.total}</Text>
+            </View>
+          ))}
+        </View>
+
+        <View className="gap-1 border-t border-border pt-3">
+          <View className="flex-row justify-between">
+            <Text className="text-sm text-muted-foreground">Subtotal</Text>
+            <Text className="text-sm text-foreground">{subtotal}</Text>
+          </View>
+          <View className="flex-row justify-between">
+            <Text className="text-sm text-muted-foreground">Tax</Text>
+            <Text className="text-sm text-foreground">{tax}</Text>
+          </View>
+          <View className="flex-row justify-between pt-1">
+            <Text className="text-sm font-bold text-foreground">Total</Text>
+            <Text className="text-sm font-bold text-foreground">{total}</Text>
+          </View>
+        </View>
+
+        {paymentSlot && <View className="border-t border-border pt-3">{paymentSlot}</View>}
+        {footerSlot && <View className="border-t border-border pt-3">{footerSlot}</View>}
+      </View>
+    </ScrollView>
+  );
+}

package/src/order/order-list.tsx

@@ -0,0 +1,39 @@
+import type { ReactNode } from 'react';
+import { ScrollView, View, type ViewProps } from 'react-native';
+
+import { cn } from '@tallyui/theme';
+
+export interface OrderListProps extends Omit<ViewProps, 'children'> {
+  items: any[];
+  renderItem: (item: any, index: number) => ReactNode;
+  headerSlot?: ReactNode;
+  emptyState?: ReactNode;
+  className?: string;
+}
+
+export function OrderList({
+  items,
+  renderItem,
+  headerSlot,
+  emptyState,
+  className,
+  ...viewProps
+}: OrderListProps) {
+  const hasItems = items.length > 0;
+
+  return (
+    <View className={cn('flex-1', className)} {...viewProps}>
+      {headerSlot && <View className="px-3 py-2">{headerSlot}</View>}
+
+      {hasItems ? (
+        <ScrollView contentContainerClassName="gap-2 p-3">
+          {items.map((item, index) => (
+            <View key={item.id ?? index}>{renderItem(item, index)}</View>
+          ))}
+        </ScrollView>
+      ) : (
+        emptyState ?? null
+      )}
+    </View>
+  );
+}

package/src/order/order-status-badge.tsx

@@ -0,0 +1,32 @@
+import { Text, View, type ViewProps } from 'react-native';
+
+import { cn } from '@tallyui/theme';
+
+export type OrderStatus = 'pending' | 'processing' | 'completed' | 'refunded' | 'cancelled';
+
+export interface OrderStatusBadgeProps extends Omit<ViewProps, 'children'> {
+  status: OrderStatus;
+  className?: string;
+}
+
+const STATUS_CONFIG: Record<OrderStatus, { label: string; badge: string; dot: string; text: string }> = {
+  pending: { label: 'Pending', badge: 'bg-warning/15', dot: 'bg-warning', text: 'text-foreground' },
+  processing: { label: 'Processing', badge: 'bg-info/15', dot: 'bg-info', text: 'text-foreground' },
+  completed: { label: 'Completed', badge: 'bg-success/15', dot: 'bg-success', text: 'text-foreground' },
+  refunded: { label: 'Refunded', badge: 'bg-destructive/15', dot: 'bg-destructive', text: 'text-foreground' },
+  cancelled: { label: 'Cancelled', badge: 'bg-muted/15', dot: 'bg-muted', text: 'text-muted-foreground' },
+};
+
+export function OrderStatusBadge({ status, className, ...viewProps }: OrderStatusBadgeProps) {
+  const config = STATUS_CONFIG[status] ?? STATUS_CONFIG.pending;
+
+  return (
+    <View
+      className={cn('flex-row items-center self-start gap-1.5 rounded-xl px-2 py-1', config.badge, className)}
+      {...viewProps}
+    >
+      <View className={cn('h-1.5 w-1.5 rounded-full', config.dot)} />
+      <Text className={cn('text-xs font-semibold', config.text)}>{config.label}</Text>
+    </View>
+  );
+}

package/src/product/category-nav.tsx

@@ -0,0 +1,70 @@
+import { Pressable, ScrollView, Text, View, type ViewProps } from 'react-native';
+
+import { cn } from '@tallyui/theme';
+
+export interface CategoryItem {
+  id: string;
+  name: string;
+}
+
+export interface CategoryNavProps extends Omit<ViewProps, 'children'> {
+  categories: CategoryItem[];
+  selectedId: string;
+  onSelect: (id: string) => void;
+  orientation?: 'horizontal' | 'vertical';
+  className?: string;
+}
+
+export function CategoryNav({
+  categories,
+  selectedId,
+  onSelect,
+  orientation = 'horizontal',
+  className,
+  ...viewProps
+}: CategoryNavProps) {
+  const isHorizontal = orientation === 'horizontal';
+
+  const content = categories.map((cat) => {
+    const active = cat.id === selectedId;
+    return (
+      <Pressable
+        key={cat.id}
+        onPress={() => onSelect(cat.id)}
+        className={cn(
+          'rounded-full px-3 py-1.5',
+          active ? 'bg-primary' : 'bg-muted',
+        )}
+      >
+        <Text
+          className={cn(
+            'text-sm font-medium',
+            active ? 'text-primary-foreground' : 'text-foreground',
+          )}
+        >
+          {cat.name}
+        </Text>
+      </Pressable>
+    );
+  });
+
+  if (isHorizontal) {
+    return (
+      <ScrollView
+        horizontal
+        showsHorizontalScrollIndicator={false}
+        contentContainerClassName="flex-row gap-2 px-3 py-2"
+        className={className}
+        {...viewProps}
+      >
+        {content}
+      </ScrollView>
+    );
+  }
+
+  return (
+    <View className={cn('gap-1 p-2', className)} {...viewProps}>
+      {content}
+    </View>
+  );
+}

package/src/product/index.ts

@@ -5,3 +5,6 @@ export { ProductSku, type ProductSkuProps } from './product-sku';
 export { ProductStockBadge, type ProductStockBadgeProps } from './product-stock-badge';
 export { ProductCard, type ProductCardProps } from './product-card';
 export { ProductGrid, type ProductGridProps } from './product-grid';
+export { ProductList, type ProductListProps } from './product-list';
+export { CategoryNav, type CategoryNavProps, type CategoryItem } from './category-nav';
+export { ProductVariantPicker, type ProductVariantPickerProps, type VariantOption } from './product-variant-picker';

package/src/product/product-card.tsx

@@ -1,26 +1,54 @@
-import { Pressable, View, type ViewProps } from 'react-native';
+import { Pressable } from 'react-native';
 import { cn } from '@tallyui/theme';
+import { useProductTraits } from '@tallyui/core';
+import { VStack, Text, type VStackProps } from '../ui';
 import { ProductImage } from './product-image';
 import { ProductTitle } from './product-title';
 import { ProductPrice } from './product-price';
 
-export interface ProductCardProps extends Omit<ViewProps, 'children'> {
+export interface ProductCardProps extends Omit<VStackProps, 'children'> {
   doc: any;
   onPress?: () => void;
   imageSize?: number;
   currencySymbol?: string;
+  /** Shown in place of the price when the channel doesn't sell this product. */
+  notSoldLabel?: string;
   className?: string;
 }
 
-export function ProductCard({ doc, onPress, imageSize = 80, currencySymbol, className, ...viewProps }: ProductCardProps) {
+export function ProductCard({ doc, onPress, imageSize = 80, currencySymbol, notSoldLabel = 'Not sold here', className, ...props }: ProductCardProps) {
+  // No <ConnectorProvider> above: traits are unavailable, so the card
+  // renders as an ordinary, sellable product.
+  let traits: ReturnType<typeof useProductTraits> | undefined;
+  try {
+    traits = useProductTraits();
+  } catch {
+    traits = undefined;
+  }
+  const sellable = !traits || traits.isSellable(doc);
+
   const content = (
-    <View className={cn('items-center gap-2 rounded-lg bg-surface p-3', className)} {...viewProps}>
-      <ProductImage doc={doc} size={imageSize} className="rounded-md" />
-      <ProductTitle doc={doc} className="text-sm" numberOfLines={2} />
-      <ProductPrice doc={doc} currencySymbol={currencySymbol} />
-    </View>
+    <VStack
+      space="sm"
+      className={cn('items-center rounded-lg border border-border bg-card p-3', className)}
+      {...props}
+    >
+      {/* Unsellable: the card keeps its opaque surface and only its contents dim, so
+          it reads as lower contrast than its neighbours on any backdrop, in both themes. */}
+      <ProductImage doc={doc} size={imageSize} className={cn('rounded-md', !sellable && 'opacity-50')} />
+      <ProductTitle doc={doc} className={cn('text-sm', !sellable && 'opacity-50')} numberOfLines={2} />
+      {sellable ? (
+        <ProductPrice doc={doc} currencySymbol={currencySymbol} />
+      ) : (
+        <Text className="text-sm text-muted-foreground">{notSoldLabel}</Text>
+      )}
+    </VStack>
   );
 
+  // Not sold in this channel: shown for awareness only (opt-in or the demo), never tappable.
+  if (!sellable) {
+    return <Pressable disabled aria-disabled onPress={undefined}>{content}</Pressable>;
+  }
   if (onPress) {
     return <Pressable onPress={onPress}>{content}</Pressable>;
   }

package/src/product/product-grid.tsx

@@ -1,8 +1,17 @@
 import type { ReactNode } from 'react';
-import { ScrollView, View, type ViewProps } from 'react-native';
+import { FlatList, View } from 'react-native';
 import { cn } from '@tallyui/theme';
+import { useProductTraits } from '@tallyui/core';
+import { VStack, type VStackProps } from '../ui';
 
-export interface ProductGridProps extends Omit<ViewProps, 'children'> {
+// Limit initial mounts for a 2,000-product catalogue to eight rows.
+const INITIAL_ROWS = 8;
+// Keep each render batch small for a 2,000-product catalogue.
+const BATCH_ROWS = 8;
+// Keep nearby rows mounted without rendering the whole 2,000-product catalogue.
+const WINDOW_SIZE = 5;
+
+export interface ProductGridProps extends Omit<VStackProps, 'children'> {
   /** Array of product documents to render */
   items: any[];
   /** Render function for each product */
@@ -15,14 +24,19 @@ export interface ProductGridProps extends Omit<ViewProps, 'children'> {
   filterSlot?: ReactNode;
   /** Content shown when items is empty */
   emptyState?: ReactNode;
+  /**
+   * Products the channel doesn't sell (`traits.product.isSellable` false,
+   * for example a Medusa product outside the sales channel) are hidden
+   * unless `showUnsellable`.
+   */
+  showUnsellable?: boolean;
   className?: string;
 }
 
 /**
- * A scrollable product grid with optional search and filter slots.
+ * A virtualized product grid with optional search and filter slots.
  *
- * Uses ScrollView + flexWrap for cross-platform grid layout rather than
- * FlatList numColumns, which keeps things predictable in both native and web.
+ * Uses FlatList numColumns to render rows near the viewport on native and web.
  *
  * ```tsx
  * <ProductGrid
@@ -40,27 +54,46 @@ export function ProductGrid({
   searchSlot,
   filterSlot,
   emptyState,
+  showUnsellable = false,
   className,
   ...viewProps
 }: ProductGridProps) {
-  const hasItems = items.length > 0;
+  // No <ConnectorProvider> above (e.g. a fixture with no connector): traits
+  // are unavailable, so nothing is filtered.
+  let traits: ReturnType<typeof useProductTraits> | undefined;
+  try {
+    traits = useProductTraits();
+  } catch {
+    traits = undefined;
+  }
+
+  const visibleItems = showUnsellable || !traits ? items : items.filter((item) => traits!.isSellable(item));
+  const hasItems = visibleItems.length > 0;
 
   return (
-    <View className={cn('flex-1', className)} {...viewProps}>
+    <VStack space="none" className={cn('flex-1', className)} {...viewProps}>
       {searchSlot && <View className="px-3 py-2">{searchSlot}</View>}
       {filterSlot && <View className="px-3 pb-2">{filterSlot}</View>}
 
       {hasItems ? (
-        <ScrollView contentContainerClassName="flex-row flex-wrap p-1">
-          {items.map((item, index) => (
-            <View key={item.id ?? index} style={{ width: `${100 / numColumns}%` }} className="p-1">
+        <FlatList
+          key={numColumns}
+          data={visibleItems}
+          numColumns={numColumns}
+          keyExtractor={(item, index) => String(item.id ?? index)}
+          contentContainerClassName="p-1"
+          initialNumToRender={INITIAL_ROWS}
+          maxToRenderPerBatch={BATCH_ROWS}
+          windowSize={WINDOW_SIZE}
+          renderItem={({ item, index }) => (
+            <View style={{ width: `${100 / numColumns}%` }} className="p-1">
               {renderItem(item, index)}
             </View>
-          ))}
-        </ScrollView>
+          )}
+        />
       ) : (
         emptyState ?? null
       )}
-    </View>
+    </VStack>
   );
 }

package/src/product/product-image.tsx

@@ -1,15 +1,22 @@
-import { Image, type ImageProps, type ImageStyle, type StyleProp } from 'react-native';
+import { View, type ImageStyle, type StyleProp } from 'react-native';
+import { Image } from '@tallyui/primitives';
 
 import { useProductTraits } from '@tallyui/core';
 import { cn } from '@tallyui/theme';
+import { Text } from '../ui';
 
-export interface ProductImageProps extends Omit<ImageProps, 'source'> {
+export interface ProductImageProps extends Omit<React.ComponentPropsWithoutRef<typeof Image.Root>, 'source'> {
   /** The raw RxDB product document */
   doc: any;
   /** Image dimensions */
   size?: number;
   /** Style overrides (for dynamic sizing) */
   style?: StyleProp<ImageStyle>;
+  /**
+   * Render a same-size tile with the product's initial when there is no
+   * image, so rows and grids stay aligned. Defaults to false (render nothing).
+   */
+  showPlaceholder?: boolean;
   className?: string;
 }
 
@@ -22,18 +29,32 @@ export interface ProductImageProps extends Omit<ImageProps, 'source'> {
  * <ProductImage doc={productDocument} size={80} className="rounded-lg" />
  * ```
  */
-export function ProductImage({ doc, size = 60, style, className, ...imageProps }: ProductImageProps) {
-  const { getImageUrl } = useProductTraits();
+export function ProductImage({ doc, size = 60, style, showPlaceholder = false, className, ...imageProps }: ProductImageProps) {
+  const { getImageUrl, getName } = useProductTraits();
   const imageUrl = getImageUrl(doc);
 
   if (!imageUrl) {
-    return null; // TODO: placeholder image
+    if (!showPlaceholder) return null;
+    const name = getName(doc);
+    return (
+      <View
+        role="img"
+        aria-label={name}
+        className={cn('items-center justify-center rounded border border-border bg-primary/10', className)}
+        style={{ width: size, height: size }}
+      >
+        <Text className="font-semibold text-primary" style={{ fontSize: size * 0.4 }}>
+          {name.trim().charAt(0).toUpperCase() || '?'}
+        </Text>
+      </View>
+    );
   }
 
   return (
-    <Image
+    <Image.Root
       source={{ uri: imageUrl }}
-      className={cn('rounded', className)}
+      alt={getName(doc)}
+      className={cn('rounded border border-border bg-card', className)}
       style={[{ width: size, height: size }, style]}
       {...imageProps}
     />