@ankhorage/zora 18.0.1 → 19.0.1

package/src/features/plugin/pluginComposition.test.ts

@@ -0,0 +1,139 @@
+import { describe, expect, test } from 'bun:test';
+
+import type { ZoraComponentMeta } from '../../types/authoring';
+import type { ZoraPluginDescriptor } from '../../types/plugin';
+import { composeZoraPlugins } from './application/use-cases/composeZoraPlugins';
+import { ZoraPluginCompositionError } from './domain/ZoraPluginCompositionError';
+
+const pluginLeafMeta: ZoraComponentMeta = {
+  name: 'PluginLeaf',
+  category: 'component',
+  directManifestNode: true,
+  allowedChildren: [],
+  blueprint: { label: 'Plugin leaf' },
+  bindings: {
+    props: {
+      value: { value: { type: 'string' } },
+    },
+  },
+  props: {
+    value: { type: 'string', category: 'Content', authoring: { authority: 'instance' } },
+  },
+};
+
+const PluginLeaf = () => null;
+
+const Host = () => null;
+
+const core = {
+  packageName: '@example/core',
+  componentRegistry: { Host },
+  componentMeta: {
+    Host: {
+      name: 'Host',
+      category: 'layout',
+      directManifestNode: true,
+      allowedChildren: [],
+      props: {},
+    },
+  },
+  extensionHosts: ['Host'],
+} satisfies ZoraPluginDescriptor;
+
+const plugin = {
+  packageName: '@example/zora-plugin',
+  displayName: 'Example plugin',
+  componentRegistry: { PluginLeaf },
+  componentMeta: { PluginLeaf: pluginLeafMeta },
+  placements: [{ child: 'PluginLeaf', parents: ['Host'] }],
+} satisfies ZoraPluginDescriptor;
+
+describe('composeZoraPlugins', () => {
+  test('composes runtime, authoring, binding, package, and placement projections', () => {
+    const catalog = composeZoraPlugins([core, plugin]);
+
+    expect(catalog.componentRegistry.PluginLeaf).toBe(PluginLeaf);
+    expect(catalog.componentMeta.PluginLeaf).toBe(pluginLeafMeta);
+    expect(catalog.bindableComponentMeta.PluginLeaf?.bindings).toEqual(pluginLeafMeta.bindings);
+    expect(catalog.componentMeta.Host.allowedChildren).toContain('PluginLeaf');
+    expect(catalog.packageManifests.map((entry) => entry.packageName)).toEqual([
+      '@example/core',
+      '@example/zora-plugin',
+    ]);
+  });
+
+  test('is deterministic regardless of plugin input order', () => {
+    const Alpha = () => null;
+    const alpha = createPlugin('@example/alpha', 'Alpha', Alpha);
+    const beta = createPlugin('@example/beta', 'Beta', () => null);
+
+    expect(Object.keys(composeZoraPlugins([core, beta, alpha]).componentMeta)).toEqual(
+      Object.keys(composeZoraPlugins([alpha, core, beta]).componentMeta),
+    );
+  });
+
+  test('rejects duplicate component ownership with a stable diagnostic code', () => {
+    const duplicate = createPlugin('@example/duplicate', 'Host', () => null);
+
+    expect(() => composeZoraPlugins([core, duplicate])).toThrow(ZoraPluginCompositionError);
+    try {
+      composeZoraPlugins([core, duplicate]);
+    } catch (error) {
+      expect(error).toMatchObject({
+        code: 'duplicate-component',
+        packageName: '@example/duplicate',
+        componentName: 'Host',
+      });
+    }
+  });
+
+  test('rejects runtime and metadata mismatches', () => {
+    const invalid = {
+      ...plugin,
+      packageName: '@example/invalid',
+      componentMeta: {},
+    } satisfies ZoraPluginDescriptor;
+
+    expectCompositionError(invalid, 'missing-component-meta');
+  });
+
+  test('rejects placement into components that did not opt in as extension hosts', () => {
+    const invalid = {
+      ...plugin,
+      packageName: '@example/invalid-placement',
+      placements: [{ child: 'PluginLeaf', parents: ['PluginLeaf'] }],
+    } satisfies ZoraPluginDescriptor;
+
+    expectCompositionError(invalid, 'invalid-placement-parent');
+  });
+});
+
+function createPlugin(
+  packageName: string,
+  componentName: string,
+  component: ZoraPluginDescriptor['componentRegistry'][string],
+): ZoraPluginDescriptor {
+  return {
+    packageName,
+    componentRegistry: { [componentName]: component },
+    componentMeta: {
+      [componentName]: {
+        ...pluginLeafMeta,
+        name: componentName,
+      },
+    },
+  };
+}
+
+function expectCompositionError(
+  descriptor: ZoraPluginDescriptor,
+  code: ZoraPluginCompositionError['code'],
+): void {
+  try {
+    composeZoraPlugins([core, descriptor]);
+    throw new Error('Expected plugin composition to fail.');
+  } catch (error) {
+    expect(error).toBeInstanceOf(ZoraPluginCompositionError);
+    expect(error).toMatchObject({ code });
+  }
+}

package/src/features/plugin/public.ts

@@ -0,0 +1,3 @@
+export { composeZoraPluginMetadata } from './application/use-cases/composeZoraPluginMetadata';
+export { ZoraPluginCompositionError } from './domain/ZoraPluginCompositionError';
+export { ZORA_CORE_PLUGIN_METADATA } from './ZORA_CORE_PLUGIN_METADATA';

package/src/features/plugin/runtime.ts

@@ -0,0 +1,2 @@
+export { composeZoraPlugins } from './application/use-cases/composeZoraPlugins';
+export { ZORA_CORE_PLUGIN } from './ZORA_CORE_PLUGIN';

package/src/features/popover-menu/adapters/inbound/PopoverMenu.tsx

@@ -4,12 +4,12 @@ import {
 } from '@ankhorage/surface';
 import React from 'react';
 
-import { resolveIconSize } from '../../../../internal/recipes';
-import { useZoraTheme } from '../../../../theme/useZoraTheme';
-import { withZoraThemeScope } from '../../../../theme/withZoraThemeScope';
 import type { PopoverMenuAction, PopoverMenuProps } from '../../../../types/popover-menu';
 import { Icon } from '../../../icon/public';
+import { resolveIconSize } from '../../../icon/utils/resolveIconSize';
 import { View } from '../../../layout/public';
+import { withZoraThemeScope } from '../../../theme/adapters/inbound/withZoraThemeScope';
+import { useZoraTheme } from '../../../theme/composition/useZoraTheme';
 
 /*** Presents a ZORA-styled action list through the Surface PopoverMenu capability. */
 export const PopoverMenu = withZoraThemeScope(PopoverMenuInner);

package/src/features/popover-menu/popoverMenuMeta.ts

@@ -1,4 +1,4 @@
-import type { ZoraComponentMeta } from '../../metadata';
+import type { ZoraComponentMeta } from '../authoring';
 
 export const popoverMenuMeta = {
   name: 'PopoverMenu',

package/src/features/progress/adapters/inbound/Progress.tsx

@@ -1,9 +1,9 @@
 import React from 'react';
 
-import { useZoraTheme } from '../../../../theme/useZoraTheme';
-import { withZoraThemeScope } from '../../../../theme/withZoraThemeScope';
 import { type ProgressProps, resolveProgressRole } from '../../../../types/progress';
 import { View } from '../../../layout/public';
+import { withZoraThemeScope } from '../../../theme/adapters/inbound/withZoraThemeScope';
+import { useZoraTheme } from '../../../theme/composition/useZoraTheme';
 import { resolveProgressFraction } from '../../utils/resolveProgressFraction';
 
 function resolveProgressHeight(size: NonNullable<ProgressProps['size']>): number {

package/src/features/progress/adapters/inbound/ProgressRing.tsx

@@ -1,10 +1,10 @@
 import React from 'react';
 import { StyleSheet, View as ReactNativeView } from 'react-native';
 
-import { useZoraTheme } from '../../../../theme/useZoraTheme';
-import { withZoraThemeScope } from '../../../../theme/withZoraThemeScope';
 import { type ProgressRingProps, resolveProgressRole } from '../../../../types/progress';
 import { View } from '../../../layout/public';
+import { withZoraThemeScope } from '../../../theme/adapters/inbound/withZoraThemeScope';
+import { useZoraTheme } from '../../../theme/composition/useZoraTheme';
 import { Text } from '../../../typography/public';
 import { resolveProgressFraction } from '../../utils/resolveProgressFraction';
 import { resolveProgressRingGeometry } from '../../utils/resolveProgressRingGeometry';

package/src/features/progress/progressMeta.ts

@@ -1,5 +1,5 @@
-import { ZORA_COLORS } from '../../internal/colorModel';
-import type { ZoraComponentMeta } from '../../metadata';
+import type { ZoraComponentMeta } from '../authoring';
+import { ZORA_COLORS } from '../theme/colorModel';
 
 export const progressMeta = {
   name: 'Progress',

package/src/features/rating/adapters/inbound/Rating.tsx

@@ -1,12 +1,12 @@
 import type { RoleSemantics, SurfaceTheme } from '@ankhorage/surface';
 
-import type { ZoraColor } from '../../../../internal/recipes';
-import { resolveIconSize } from '../../../../internal/recipes';
-import { useZoraTheme } from '../../../../theme/useZoraTheme';
-import { withZoraThemeScope } from '../../../../theme/withZoraThemeScope';
 import type { RatingProps } from '../../../../types/rating';
+import type { ZoraColor } from '../../../../types/theme';
 import { Icon } from '../../../icon/public';
+import { resolveIconSize } from '../../../icon/utils/resolveIconSize';
 import { View } from '../../../layout/public';
+import { withZoraThemeScope } from '../../../theme/adapters/inbound/withZoraThemeScope';
+import { useZoraTheme } from '../../../theme/composition/useZoraTheme';
 import { resolveRatingSegments } from '../../utils/resolveRatingSegments';
 
 /*** Displays a read-only star rating with optional half steps. */

package/src/features/rating/ratingMeta.ts

@@ -1,4 +1,4 @@
-import type { ZoraComponentMeta } from '../../metadata/types';
+import type { ZoraComponentMeta } from '../../types/authoring';
 
 export const ratingMeta = {
   name: 'Rating',

package/src/features/reader/adapters/inbound/ReaderSurface.test.ts

@@ -0,0 +1,46 @@
+import { describe, expect, test } from 'bun:test';
+
+import type { ReaderErrorEvent, ReaderLocationChangeEvent, ReaderSurfaceProps } from '../../../..';
+
+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 './features/reader/public';");
+    expect(source).toContain('ReaderSurface, resolveReaderProgress');
+  });
+
+  test('keeps parsing, fetching, persistence, and platform APIs outside ZORA', async () => {
+    const source = await Bun.file('src/features/reader/adapters/inbound/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/features/reader/adapters/inbound/ReaderSurface.tsx

@@ -0,0 +1,349 @@
+import React from 'react';
+
+import type { ReaderStatus, ReaderSurfaceProps } from '../../../../types/reader';
+import { AppBar } from '../../../app-bar/public';
+import { IconButton } from '../../../button/public';
+import { View } from '../../../layout/public';
+import { Progress } from '../../../progress/public';
+import { Surface } from '../../../surface/public';
+import { withZoraThemeScope } from '../../../theme/adapters/inbound/withZoraThemeScope';
+import { useZoraTheme } from '../../../theme/composition/useZoraTheme';
+import { Text } from '../../../typography/public';
+import { resolveReaderProgress } from '../../utils/resolveReaderProgress';
+
+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 (
+    <View align="center" justify="center" flex={1} minHeight={360} p="l">
+      <Text align="center" emphasis="muted" variant="bodySmall">
+        {title}
+      </Text>
+    </View>
+  );
+}
+
+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 ? (
+      <View direction="row" 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}
+      </View>
+    ) : 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 (
+    <View
+      bg={theme.semantics.surface.raised}
+      borderColor={theme.semantics.neutral.divider}
+      borderWidth={1}
+      gap="s"
+      p="m"
+    >
+      <Progress value={resolvedProgress} max={1} size="s" />
+      <View 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"
+        />
+        <View flex={1} minWidth={0}>
+          <View 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}
+          </View>
+        </View>
+        <IconButton
+          disabled={!nextEnabled}
+          icon={{ name: 'chevron-forward' }}
+          interactionPolicy={interactionPolicy}
+          label={nextPageLabel ?? 'Next page'}
+          onPress={() => invokeReaderAction(onNextPage)}
+          size="l"
+        />
+      </View>
+      {footerActions ? <View>{footerActions}</View> : null}
+    </View>
+  );
+}
+
+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' }}
+    >
+      <View 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}
+
+        <View bg={theme.semantics.surface.default} flex={1} minHeight={360} overflow="hidden">
+          {viewportContent}
+        </View>
+
+        {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}
+      </View>
+    </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);