@ankhorage/zora 3.0.1 → 3.1.0

package/src/metadata/bindableComponentMeta.ts

@@ -1,6 +1,7 @@
 import type { UiComponentMetaRegistry } from '@ankhorage/contracts';
 
 import { imageMeta } from '../components/image/meta';
+import { readerSurfaceMeta } from '../patterns/reader/meta';
 
 export const ZORA_BINDABLE_COMPONENT_META = {
   Text: {
@@ -462,6 +463,107 @@ export const ZORA_BINDABLE_COMPONENT_META = {
       },
     },
   },
+  ReaderSurface: {
+    ...readerSurfaceMeta,
+    bindings: {
+      props: {
+        location: {
+          label: 'Location',
+          description: 'Opaque adapter locator to restore.',
+          value: { type: 'string' },
+          acceptsFallback: true,
+          acceptsTransforms: true,
+        },
+        page: {
+          label: 'Page',
+          description: 'One-based visible page.',
+          value: { type: 'number' },
+          acceptsFallback: true,
+          acceptsTransforms: true,
+        },
+        pageCount: {
+          label: 'Page count',
+          description: 'Current number of logical pages.',
+          value: { type: 'number' },
+          acceptsFallback: true,
+          acceptsTransforms: true,
+        },
+        progress: {
+          label: 'Progress',
+          description: 'Reading progression clamped from zero to one.',
+          value: { type: 'number' },
+          acceptsFallback: true,
+          acceptsTransforms: true,
+        },
+        status: {
+          label: 'Status',
+          description: 'Current reader loading status.',
+          value: { type: 'string' },
+          acceptsFallback: true,
+          acceptsTransforms: true,
+        },
+      },
+      events: {
+        previousPage: {
+          label: 'Previous page',
+          description: 'Requests navigation to the previous page.',
+          payload: { eventType: 'reader.previousPage', fields: [] },
+        },
+        nextPage: {
+          label: 'Next page',
+          description: 'Requests navigation to the next page.',
+          payload: { eventType: 'reader.nextPage', fields: [] },
+        },
+        locationChange: {
+          label: 'Location change',
+          description: 'Runs after the adapter displays a destination.',
+          payload: {
+            eventType: 'reader.locationChange',
+            fields: [
+              { path: 'format', type: 'string', label: 'Format' },
+              { path: 'locator', type: 'string', label: 'Opaque locator' },
+              { path: 'page', type: 'number', label: 'Page' },
+              { path: 'pageCount', type: 'number', label: 'Page count' },
+              { path: 'progression', type: 'number', label: 'Progression' },
+              { path: 'chapterId', type: 'string', label: 'Chapter ID' },
+              { path: 'chapterTitle', type: 'string', label: 'Chapter title' },
+              { path: 'trigger', type: 'string', label: 'Navigation trigger' },
+            ],
+          },
+        },
+        openContents: {
+          label: 'Open contents',
+          payload: { eventType: 'reader.openContents', fields: [] },
+        },
+        openAppearance: {
+          label: 'Open appearance',
+          payload: { eventType: 'reader.openAppearance', fields: [] },
+        },
+        toggleHighlight: {
+          label: 'Toggle highlight',
+          payload: { eventType: 'reader.toggleHighlight', fields: [] },
+        },
+        openExternalLink: {
+          label: 'Open external link',
+          payload: {
+            eventType: 'reader.openExternalLink',
+            fields: [{ path: 'url', type: 'string', label: 'URL' }],
+          },
+        },
+        readerError: {
+          label: 'Reader error',
+          payload: {
+            eventType: 'reader.error',
+            fields: [
+              { path: 'code', type: 'string', label: 'Error code' },
+              { path: 'format', type: 'string', label: 'Format' },
+              { path: 'message', type: 'string', label: 'Message' },
+            ],
+          },
+        },
+      },
+    },
+  },
 } as const satisfies UiComponentMetaRegistry;
 
 export type ZoraBindableComponentType = keyof typeof ZORA_BINDABLE_COMPONENT_META;

package/src/metadata/componentMeta.test.ts

@@ -88,6 +88,12 @@ describe('ZORA_COMPONENT_META requirement metadata', () => {
     });
   });
 
+  test('declares ebook reader capability metadata for ReaderSurface', () => {
+    expect(ZORA_COMPONENT_META.ReaderSurface.requirements).toEqual({
+      capabilities: [{ capability: 'ebookReader' }],
+    });
+  });
+
   test('does not declare runtime requirements for the camera-agnostic scan overlay', () => {
     expect(ZORA_COMPONENT_META.ScanOverlay.requirements).toBeUndefined();
   });
@@ -132,6 +138,7 @@ describe('ZORA_COMPONENT_META invariants', () => {
       'ScanOverlay',
       'ProductCard',
       'Progress',
+      'ReaderSurface',
     ]);
 
     const expectedContainerNodes = new Set([
@@ -204,6 +211,35 @@ describe('ZORA_COMPONENT_META invariants', () => {
     });
   });
 
+  test('ReaderSurface exposes a safe file-media blueprint and normalized events', () => {
+    const reader = ZORA_COMPONENT_META.ReaderSurface;
+
+    expect(reader.directManifestNode).toBe(true);
+    expect(reader.allowedChildren).toEqual([]);
+    expect(reader.props.source).toMatchObject({ type: 'media', mediaKinds: ['file'] });
+    expect(reader.props.format.enum).toEqual(['epub', 'pdf']);
+    expect(reader.blueprint?.defaultProps).toEqual({
+      format: 'epub',
+      status: 'idle',
+      showChrome: true,
+      readerColorScheme: 'system',
+      fontScale: 1,
+      lineHeight: 'normal',
+    });
+    expect(reader.blueprint?.defaultProps).not.toHaveProperty('source');
+    expect(reader.events?.locationChange?.payloadFields?.map((field) => field.path)).toEqual([
+      'format',
+      'locator',
+      'page',
+      'pageCount',
+      'progression',
+      'chapterId',
+      'chapterTitle',
+      'trigger',
+    ]);
+    expect(reader.events?.readerError?.eventType).toBe('reader.error');
+  });
+
   test('non-direct manifest nodes include an explicit note', () => {
     for (const [key, meta] of Object.entries(ZORA_COMPONENT_META)) {
       if (meta.directManifestNode) continue;

package/src/metadata/componentMeta.ts

@@ -76,6 +76,7 @@ import { noticeMeta } from '../patterns/notice/meta';
 import { panelMeta } from '../patterns/panel/meta';
 import { postCardMeta } from '../patterns/post-card/meta';
 import { productCardMeta } from '../patterns/product-card/meta';
+import { readerSurfaceMeta } from '../patterns/reader/meta';
 import { responsivePanelMeta } from '../patterns/responsive-panel/meta';
 import {
   barcodeScannerViewMeta,
@@ -183,6 +184,7 @@ export const ZORA_COMPONENT_META: ZoraComponentMetaRegistry = {
   PostCard: postCardMeta,
   ProductCard: productCardMeta,
   ResponsivePanel: responsivePanelMeta,
+  ReaderSurface: readerSurfaceMeta,
   BarcodeScannerView: barcodeScannerViewMeta,
   CameraPermissionView: cameraPermissionViewMeta,
   ScanOverlay: scanOverlayMeta,

package/src/metadata/themeRecipeTypes.ts

@@ -33,9 +33,7 @@ export interface ZoraThemeRecipeBooleanFieldMeta extends ZoraThemeRecipeFieldBas
 }
 
 export type ZoraThemeRecipeFieldMeta =
-  | ZoraThemeRecipeTokenFieldMeta
-  | ZoraThemeRecipeChoiceFieldMeta
-  | ZoraThemeRecipeBooleanFieldMeta;
+  ZoraThemeRecipeTokenFieldMeta | ZoraThemeRecipeChoiceFieldMeta | ZoraThemeRecipeBooleanFieldMeta;
 
 export interface ZoraThemeRecipeMeta {
   readonly name: string;

package/src/metadata/types.ts

@@ -53,12 +53,7 @@ export interface ZoraComponentI18nMeta {
 
 export type ZoraComponentEventPayloadKind = ComponentEventDtoKind | (string & {});
 export type ZoraComponentEventPayloadFieldType =
-  | 'boolean'
-  | 'number'
-  | 'object'
-  | 'record'
-  | 'string'
-  | 'unknown';
+  'boolean' | 'number' | 'object' | 'record' | 'string' | 'unknown';
 
 export interface ZoraComponentEventPayloadFieldMeta {
   readonly path: string;

package/src/patterns/reader/ReaderSurface.test.ts

@@ -0,0 +1,46 @@
+import { describe, expect, test } from 'bun:test';
+
+import type { ReaderErrorEvent, ReaderLocationChangeEvent, ReaderSurfaceProps } from '../../index';
+
+describe('ReaderSurface public contract', () => {
+  test('exports the component and serializable adapter events from the package root', () => {
+    const props: ReaderSurfaceProps = { format: 'epub' };
+    const location: ReaderLocationChangeEvent = {
+      format: 'epub',
+      locator: 'epubcfi(/6/4!/4/2)',
+      page: 2,
+      pageCount: 8,
+      progression: 1 / 7,
+      chapterId: 'chapter-1',
+      chapterTitle: 'A beginning',
+      trigger: 'swipe',
+    };
+    const error: ReaderErrorEvent = {
+      code: 'protected-document',
+      format: 'pdf',
+      message: 'This document is protected.',
+    };
+
+    expect(props.format).toBe('epub');
+    expect(() => JSON.stringify(location)).not.toThrow();
+    expect(() => JSON.stringify(error)).not.toThrow();
+  });
+
+  test('exports the reader API from the package root', async () => {
+    const source = await Bun.file('src/index.ts').text();
+
+    expect(source).toContain("from './patterns/reader';");
+    expect(source).toContain('ReaderSurface, resolveReaderProgress');
+  });
+
+  test('keeps parsing, fetching, persistence, and platform APIs outside ZORA', async () => {
+    const source = await Bun.file('src/patterns/reader/ReaderSurface.tsx').text();
+
+    expect(source).not.toContain('expo-');
+    expect(source).not.toContain('pdfjs');
+    expect(source).not.toContain('epubjs');
+    expect(source).not.toContain('fetch(');
+    expect(source).not.toContain('AsyncStorage');
+    expect(source).toContain('accessibilityLiveRegion="polite"');
+  });
+});

package/src/patterns/reader/ReaderSurface.tsx

@@ -0,0 +1,348 @@
+import React from 'react';
+
+import { AppBar } from '../../components/app-bar';
+import { IconButton } from '../../components/icon-button';
+import { Progress } from '../../components/progress';
+import { Text } from '../../components/text';
+import { Box, Center, Inline, Stack, Surface } from '../../foundation';
+import { useZoraTheme } from '../../theme/useZoraTheme';
+import { withZoraThemeScope } from '../../theme/withZoraThemeScope';
+import { resolveReaderProgress } from './resolveReaderProgress';
+import type { ReaderStatus, ReaderSurfaceProps } from './types';
+
+function resolvePageLabel(page: number | undefined, pageCount: number | undefined): string | null {
+  if (page === undefined || !Number.isFinite(page)) return null;
+  if (pageCount === undefined || !Number.isFinite(pageCount)) return `Page ${page}`;
+  return `Page ${page} of ${pageCount}`;
+}
+
+function resolveCanGoPrevious({
+  canGoPrevious,
+  page,
+}: Pick<ReaderSurfaceProps, 'canGoPrevious' | 'page'>): boolean {
+  if (canGoPrevious !== undefined) return canGoPrevious;
+  return page === undefined || page > 1;
+}
+
+function resolveCanGoNext({
+  canGoNext,
+  page,
+  pageCount,
+}: Pick<ReaderSurfaceProps, 'canGoNext' | 'page' | 'pageCount'>): boolean {
+  if (canGoNext !== undefined) return canGoNext;
+  return page === undefined || pageCount === undefined || page < pageCount;
+}
+
+function ReaderEmptyState({
+  status,
+  loadingLabel,
+  errorTitle,
+  unavailableTitle,
+}: {
+  status: ReaderStatus;
+  loadingLabel: string;
+  errorTitle: string;
+  unavailableTitle: string;
+}) {
+  const title =
+    status === 'loading' ? loadingLabel : status === 'error' ? errorTitle : unavailableTitle;
+
+  return (
+    <Center flex={1} minHeight={360} p="l">
+      <Text align="center" emphasis="muted" variant="bodySmall">
+        {title}
+      </Text>
+    </Center>
+  );
+}
+
+function invokeReaderAction(action: (() => void | Promise<void>) | undefined): void {
+  void action?.();
+}
+
+function ReaderHeader({
+  interactionPolicy,
+  title,
+  subtitle,
+  contentsLabel,
+  appearanceLabel,
+  highlightLabel,
+  highlighted,
+  headerActions,
+  onOpenContents,
+  onOpenAppearance,
+  onToggleHighlight,
+}: Pick<
+  ReaderSurfaceProps,
+  | 'interactionPolicy'
+  | 'title'
+  | 'subtitle'
+  | 'contentsLabel'
+  | 'appearanceLabel'
+  | 'highlightLabel'
+  | 'highlighted'
+  | 'headerActions'
+  | 'onOpenContents'
+  | 'onOpenAppearance'
+  | 'onToggleHighlight'
+>) {
+  const actions =
+    onOpenContents || onOpenAppearance || onToggleHighlight || headerActions ? (
+      <Inline align="center" gap="xs" wrap="nowrap">
+        {onOpenContents ? (
+          <IconButton
+            icon={{ name: 'list-outline' }}
+            interactionPolicy={interactionPolicy}
+            label={contentsLabel ?? 'Table of contents'}
+            onPress={() => invokeReaderAction(onOpenContents)}
+            size="l"
+          />
+        ) : null}
+        {onOpenAppearance ? (
+          <IconButton
+            icon={{ name: 'text-outline' }}
+            interactionPolicy={interactionPolicy}
+            label={appearanceLabel ?? 'Reading appearance'}
+            onPress={() => invokeReaderAction(onOpenAppearance)}
+            size="l"
+          />
+        ) : null}
+        {onToggleHighlight ? (
+          <IconButton
+            color={highlighted ? 'primary' : 'neutral'}
+            icon={{ name: highlighted ? 'bookmark' : 'bookmark-outline' }}
+            interactionPolicy={interactionPolicy}
+            label={highlightLabel ?? 'Toggle highlight'}
+            onPress={() => invokeReaderAction(onToggleHighlight)}
+            size="l"
+          />
+        ) : null}
+        {headerActions}
+      </Inline>
+    ) : undefined;
+
+  return (
+    <AppBar
+      actions={actions}
+      divider
+      interactionPolicy={interactionPolicy}
+      safeAreaTop
+      subtitle={subtitle}
+      title={title}
+    />
+  );
+}
+
+function ReaderFooter({
+  interactionPolicy,
+  status,
+  page,
+  pageCount,
+  progress,
+  canGoPrevious,
+  canGoNext,
+  chapterLabel,
+  pageLabel,
+  previousPageLabel,
+  nextPageLabel,
+  footerActions,
+  onPreviousPage,
+  onNextPage,
+}: Pick<
+  ReaderSurfaceProps,
+  | 'interactionPolicy'
+  | 'status'
+  | 'page'
+  | 'pageCount'
+  | 'progress'
+  | 'canGoPrevious'
+  | 'canGoNext'
+  | 'chapterLabel'
+  | 'pageLabel'
+  | 'previousPageLabel'
+  | 'nextPageLabel'
+  | 'footerActions'
+  | 'onPreviousPage'
+  | 'onNextPage'
+>) {
+  const { theme } = useZoraTheme();
+  const resolvedProgress = resolveReaderProgress({ progress, page, pageCount });
+  const resolvedPageLabel = pageLabel ?? resolvePageLabel(page, pageCount);
+  const previousEnabled =
+    status === 'ready' && Boolean(onPreviousPage) && resolveCanGoPrevious({ canGoPrevious, page });
+  const nextEnabled =
+    status === 'ready' && Boolean(onNextPage) && resolveCanGoNext({ canGoNext, page, pageCount });
+
+  return (
+    <Stack
+      bg={theme.semantics.surface.raised}
+      borderColor={theme.semantics.neutral.divider}
+      borderWidth={1}
+      gap="s"
+      p="m"
+    >
+      <Progress value={resolvedProgress} max={1} size="s" />
+      <Stack align="center" direction="row" gap="m" justify="space-between" wrap="nowrap">
+        <IconButton
+          disabled={!previousEnabled}
+          icon={{ name: 'chevron-back' }}
+          interactionPolicy={interactionPolicy}
+          label={previousPageLabel ?? 'Previous page'}
+          onPress={() => invokeReaderAction(onPreviousPage)}
+          size="l"
+        />
+        <Box flex={1} minWidth={0}>
+          <Stack align="center" gap="xs">
+            {chapterLabel ? (
+              <Text
+                align="center"
+                ellipsizeMode="tail"
+                numberOfLines={1}
+                variant="label"
+                weight="semiBold"
+              >
+                {chapterLabel}
+              </Text>
+            ) : null}
+            {resolvedPageLabel ? (
+              <Text
+                accessibilityLiveRegion="polite"
+                align="center"
+                emphasis="muted"
+                variant="caption"
+              >
+                {resolvedPageLabel}
+              </Text>
+            ) : null}
+          </Stack>
+        </Box>
+        <IconButton
+          disabled={!nextEnabled}
+          icon={{ name: 'chevron-forward' }}
+          interactionPolicy={interactionPolicy}
+          label={nextPageLabel ?? 'Next page'}
+          onPress={() => invokeReaderAction(onNextPage)}
+          size="l"
+        />
+      </Stack>
+      {footerActions ? <Box>{footerActions}</Box> : null}
+    </Stack>
+  );
+}
+
+function ReaderSurfaceInner({
+  themeId: _themeId,
+  mode: _mode,
+  interactionPolicy,
+  source: _source,
+  format: _format,
+  location: _location,
+  status = 'idle',
+  page,
+  pageCount,
+  progress,
+  canGoPrevious,
+  canGoNext,
+  title,
+  subtitle,
+  chapterLabel,
+  pageLabel,
+  previousPageLabel = 'Previous page',
+  nextPageLabel = 'Next page',
+  contentsLabel = 'Table of contents',
+  appearanceLabel = 'Reading appearance',
+  highlightLabel = 'Toggle highlight',
+  loadingLabel = 'Loading document…',
+  errorTitle = 'Unable to open this document.',
+  unavailableTitle = 'Reader preview unavailable.',
+  showChrome = true,
+  readerColorScheme: _readerColorScheme = 'system',
+  fontScale: _fontScale = 1,
+  lineHeight: _lineHeight = 'normal',
+  highlighted = false,
+  viewport,
+  headerActions,
+  footerActions,
+  onPreviousPage,
+  onNextPage,
+  onLocationChange: _onLocationChange,
+  onOpenContents,
+  onOpenAppearance,
+  onToggleHighlight,
+  onOpenExternalLink: _onOpenExternalLink,
+  onReaderError: _onReaderError,
+  testID,
+}: ReaderSurfaceProps) {
+  const { theme } = useZoraTheme();
+
+  const viewportContent =
+    viewport && status !== 'error' ? (
+      viewport
+    ) : (
+      <ReaderEmptyState
+        errorTitle={errorTitle}
+        loadingLabel={loadingLabel}
+        status={status}
+        unavailableTitle={unavailableTitle}
+      />
+    );
+
+  return (
+    <Surface
+      radius="l"
+      testID={testID}
+      variant="default"
+      style={{ minHeight: 480, overflow: 'hidden' }}
+    >
+      <Stack flex={1} gap={0}>
+        {showChrome ? (
+          <ReaderHeader
+            appearanceLabel={appearanceLabel}
+            contentsLabel={contentsLabel}
+            headerActions={headerActions}
+            highlightLabel={highlightLabel}
+            highlighted={highlighted}
+            interactionPolicy={interactionPolicy}
+            onOpenAppearance={onOpenAppearance}
+            onOpenContents={onOpenContents}
+            onToggleHighlight={onToggleHighlight}
+            subtitle={subtitle}
+            title={title}
+          />
+        ) : null}
+
+        <Box bg={theme.semantics.surface.default} flex={1} minHeight={360} overflow="hidden">
+          {viewportContent}
+        </Box>
+
+        {showChrome ? (
+          <ReaderFooter
+            canGoNext={canGoNext}
+            canGoPrevious={canGoPrevious}
+            chapterLabel={chapterLabel}
+            footerActions={footerActions}
+            interactionPolicy={interactionPolicy}
+            nextPageLabel={nextPageLabel}
+            onNextPage={onNextPage}
+            onPreviousPage={onPreviousPage}
+            page={page}
+            pageCount={pageCount}
+            pageLabel={pageLabel}
+            previousPageLabel={previousPageLabel}
+            progress={progress}
+            status={status}
+          />
+        ) : null}
+      </Stack>
+    </Surface>
+  );
+}
+
+/***
+ * Adapter-neutral reader shell for EPUB and PDF experiences.
+ *
+ * Supply the actual renderer through `viewport`; ZORA owns only the reader
+ * chrome, controlled state, progress, accessible controls, and normalized
+ * adapter callbacks.
+ */
+export const ReaderSurface = withZoraThemeScope(ReaderSurfaceInner);

package/src/patterns/reader/index.ts

@@ -0,0 +1,15 @@
+export { ReaderSurface } from './ReaderSurface';
+export { resolveReaderProgress } from './resolveReaderProgress';
+export type {
+  ReaderColorScheme,
+  ReaderDocumentFormat,
+  ReaderErrorCode,
+  ReaderErrorEvent,
+  ReaderExternalLinkEvent,
+  ReaderLineHeight,
+  ReaderLocationChangeEvent,
+  ReaderNavigationTrigger,
+  ReaderResolvedSource,
+  ReaderStatus,
+  ReaderSurfaceProps,
+} from './types';