@ankhorage/zora 18.0.1 → 19.0.1

package/src/features/reader/meta.ts

@@ -0,0 +1,296 @@
+import type { ZoraComponentMeta } from '../authoring';
+import { CONTAINER_ALLOWED_CHILDREN } from '../authoring/allowedChildren';
+
+const EMPTY_EVENT_FIELDS = [] as const;
+
+export const readerSurfaceMeta = {
+  name: 'ReaderSurface',
+  category: 'pattern',
+  description:
+    'Adapter-neutral EPUB and PDF reader shell with controlled chrome, progress, and navigation events.',
+  directManifestNode: true,
+  requirements: {
+    capabilities: [{ capability: 'ebookReader' }],
+  },
+  allowedChildren: [],
+  blueprint: {
+    label: 'Reader',
+    defaultProps: {
+      format: 'epub',
+      status: 'idle',
+      showChrome: true,
+      readerColorScheme: 'system',
+      fontScale: 1,
+      lineHeight: 'normal',
+    },
+  },
+  events: {
+    previousPage: {
+      label: 'Previous page',
+      eventType: 'reader.previousPage',
+      description: 'Requests navigation to the previous page.',
+      payloadFields: EMPTY_EVENT_FIELDS,
+    },
+    nextPage: {
+      label: 'Next page',
+      eventType: 'reader.nextPage',
+      description: 'Requests navigation to the next page.',
+      payloadFields: EMPTY_EVENT_FIELDS,
+    },
+    locationChange: {
+      label: 'Location change',
+      eventType: 'reader.locationChange',
+      description: 'Emitted by the adapter after the destination has been displayed.',
+      payloadFields: [
+        { 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',
+      eventType: 'reader.openContents',
+      description: 'Requests the app-owned table of contents.',
+      payloadFields: EMPTY_EVENT_FIELDS,
+    },
+    openAppearance: {
+      label: 'Open appearance',
+      eventType: 'reader.openAppearance',
+      description: 'Requests the app-owned reader appearance controls.',
+      payloadFields: EMPTY_EVENT_FIELDS,
+    },
+    toggleHighlight: {
+      label: 'Toggle highlight',
+      eventType: 'reader.toggleHighlight',
+      description: 'Requests the app-owned highlight action.',
+      payloadFields: EMPTY_EVENT_FIELDS,
+    },
+    openExternalLink: {
+      label: 'Open external link',
+      eventType: 'reader.openExternalLink',
+      description: 'Emitted when publication content requests an external URL.',
+      payloadFields: [{ path: 'url', type: 'string', label: 'URL' }],
+    },
+    readerError: {
+      label: 'Reader error',
+      eventType: 'reader.error',
+      description: 'Emitted when the adapter rejects or cannot load a document.',
+      payloadFields: [
+        { path: 'code', type: 'string', label: 'Error code' },
+        { path: 'format', type: 'string', label: 'Format' },
+        { path: 'message', type: 'string', label: 'Message' },
+      ],
+    },
+  },
+  slots: {
+    viewport: {
+      label: 'Reader viewport adapter',
+      allowedChildren: [],
+    },
+    headerActions: {
+      label: 'Header actions',
+      allowedChildren: [...CONTAINER_ALLOWED_CHILDREN],
+    },
+    footerActions: {
+      label: 'Footer actions',
+      allowedChildren: [...CONTAINER_ALLOWED_CHILDREN],
+    },
+  },
+  props: {
+    source: {
+      type: 'media',
+      category: 'Document',
+      label: 'Source',
+      mediaKinds: ['file'],
+    },
+    format: {
+      type: 'enum',
+      category: 'Document',
+      label: 'Format',
+      enum: ['epub', 'pdf'],
+      default: 'epub',
+    },
+    location: {
+      type: 'string',
+      category: 'State',
+      label: 'Location',
+    },
+    status: {
+      type: 'enum',
+      category: 'State',
+      label: 'Status',
+      enum: ['idle', 'loading', 'ready', 'error'],
+      default: 'idle',
+    },
+    page: {
+      type: 'number',
+      category: 'State',
+      label: 'Page',
+    },
+    pageCount: {
+      type: 'number',
+      category: 'State',
+      label: 'Page count',
+    },
+    progress: {
+      type: 'number',
+      category: 'State',
+      label: 'Progress',
+    },
+    canGoPrevious: {
+      type: 'boolean',
+      category: 'State',
+      label: 'Can go previous',
+    },
+    canGoNext: {
+      type: 'boolean',
+      category: 'State',
+      label: 'Can go next',
+    },
+    title: {
+      type: 'string',
+      category: 'Content',
+      label: 'Title',
+    },
+    subtitle: {
+      type: 'string',
+      category: 'Content',
+      label: 'Subtitle',
+    },
+    chapterLabel: {
+      type: 'string',
+      category: 'Content',
+      label: 'Chapter label',
+    },
+    pageLabel: {
+      type: 'string',
+      category: 'Content',
+      label: 'Page label',
+    },
+    previousPageLabel: {
+      type: 'string',
+      category: 'Content',
+      label: 'Previous page label',
+      default: 'Previous page',
+    },
+    nextPageLabel: {
+      type: 'string',
+      category: 'Content',
+      label: 'Next page label',
+      default: 'Next page',
+    },
+    contentsLabel: {
+      type: 'string',
+      category: 'Content',
+      label: 'Contents label',
+      default: 'Table of contents',
+    },
+    appearanceLabel: {
+      type: 'string',
+      category: 'Content',
+      label: 'Appearance label',
+      default: 'Reading appearance',
+    },
+    highlightLabel: {
+      type: 'string',
+      category: 'Content',
+      label: 'Highlight label',
+      default: 'Toggle highlight',
+    },
+    loadingLabel: {
+      type: 'string',
+      category: 'Content',
+      label: 'Loading label',
+      default: 'Loading document…',
+    },
+    errorTitle: {
+      type: 'string',
+      category: 'Content',
+      label: 'Error title',
+      default: 'Unable to open this document.',
+    },
+    unavailableTitle: {
+      type: 'string',
+      category: 'Content',
+      label: 'Unavailable title',
+      default: 'Reader preview unavailable.',
+    },
+    showChrome: {
+      type: 'boolean',
+      category: 'Chrome',
+      label: 'Show chrome',
+      default: true,
+    },
+    readerColorScheme: {
+      type: 'enum',
+      category: 'Appearance',
+      label: 'Color scheme',
+      enum: ['system', 'light', 'dark', 'sepia'],
+      default: 'system',
+    },
+    fontScale: {
+      type: 'number',
+      category: 'Appearance',
+      label: 'Font scale',
+      default: 1,
+    },
+    lineHeight: {
+      type: 'enum',
+      category: 'Appearance',
+      label: 'Line height',
+      enum: ['compact', 'normal', 'relaxed'],
+      default: 'normal',
+    },
+    highlighted: {
+      type: 'boolean',
+      category: 'State',
+      label: 'Highlighted',
+      default: false,
+    },
+    onPreviousPage: {
+      type: 'action',
+      category: 'Events',
+      label: 'Previous page action',
+    },
+    onNextPage: {
+      type: 'action',
+      category: 'Events',
+      label: 'Next page action',
+    },
+    onLocationChange: {
+      type: 'action',
+      category: 'Events',
+      label: 'Location change action',
+    },
+    onOpenContents: {
+      type: 'action',
+      category: 'Events',
+      label: 'Open contents action',
+    },
+    onOpenAppearance: {
+      type: 'action',
+      category: 'Events',
+      label: 'Open appearance action',
+    },
+    onToggleHighlight: {
+      type: 'action',
+      category: 'Events',
+      label: 'Toggle highlight action',
+    },
+    onOpenExternalLink: {
+      type: 'action',
+      category: 'Events',
+      label: 'Open external link action',
+    },
+    onReaderError: {
+      type: 'action',
+      category: 'Events',
+      label: 'Reader error action',
+    },
+  },
+} as const satisfies ZoraComponentMeta;

package/src/features/reader/public.ts

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

package/src/features/registry/ZORA_COMPONENT_REGISTRY.ts

@@ -0,0 +1,186 @@
+import type { InteractionPolicyProps } from '@ankhorage/surface';
+import type React from 'react';
+
+import type { ZoraComponentRegistry } from '../../types/registry';
+import { Accordion, AccordionItem } from '../accordion/public';
+import { ActivityIndicator } from '../activity-indicator/public';
+import { AppBar } from '../app-bar/public';
+import {
+  ForgotPasswordForm,
+  OAuthProviderButton,
+  OAuthProviderList,
+  OtpForm,
+  SignInForm,
+  SignUpForm,
+} from '../auth/public';
+import { Avatar, AvatarGroup } from '../avatar/public';
+import { Badge } from '../badge/public';
+import { BottomSheet } from '../bottom-sheet/public';
+import { Breadcrumbs } from '../breadcrumbs/public';
+import { Button, ButtonGroup, IconButton } from '../button/public';
+import { Card, MediaCard, MetricCard, PostCard, ProductCard } from '../card/public';
+import { ChatListItem, MessageBubble } from '../chat/public';
+import { Chip, ChipGroup } from '../chip/public';
+import { CollectionEditor } from '../collection-editor/public';
+import { ContentRail } from '../content-rail/public';
+import { DataTable } from '../data-table/public';
+import { DatePicker } from '../date-picker/public';
+import { Dialog } from '../dialog/public';
+import { EmptyState } from '../empty-state/public';
+import { Checkbox, CheckboxGroup } from '../form/checkbox/public';
+import { Field, Form, FormActions, FormError } from '../form/public';
+import { Radio, RadioGroup } from '../form/radio/public';
+import { SearchInput } from '../form/search-input/public';
+import { Select } from '../form/select/public';
+import { Switch } from '../form/switch/public';
+import { TextInput } from '../form/text-input/public';
+import { Gradient } from '../gradient/public';
+import { Hero } from '../hero/public';
+import { Icon } from '../icon/public';
+import { Image } from '../image/public';
+import { KeyboardAvoidingView } from '../keyboard-avoiding-view/public';
+import { AppShell, Divider, Grid, Screen, ScrollView, View } from '../layout/public';
+import { FlatList, List, ListItem, ListSection, SectionList } from '../list/public';
+import { MissingElement } from '../missing-element/public';
+import { Pagination } from '../pagination/public';
+import { PaletteItem } from '../palette-item/public';
+import { PopoverMenu } from '../popover-menu/public';
+import { Progress, ProgressRing } from '../progress/public';
+import { Rating } from '../rating/public';
+import { ReaderSurface } from '../reader/public';
+import { BarcodeScannerView, CameraPermissionView, ScanOverlay } from '../scanner/public';
+import { ScreenSection, SectionHeader } from '../section/public';
+import { SelectableItem } from '../selection/public';
+import { Skeleton, SkeletonCard, SkeletonList, SkeletonText } from '../skeleton/public';
+import { Surface } from '../surface/public';
+import { Tab, TabList, TabPanel, Tabs } from '../tabs/public';
+import { ThemeModeToggle } from '../theme/adapters/inbound/ThemeModeToggle';
+import { TimePicker } from '../time-picker/public';
+import { Timeline } from '../timeline/public';
+import { Toast } from '../toast/public';
+import { Toolbar } from '../toolbar/public';
+import { TreeItem, TreeView } from '../tree-view/public';
+import { Heading, Text } from '../typography/public';
+import { Uploader } from '../uploader/public';
+
+type ComponentPropsFor<K extends keyof typeof _ZORA_COMPONENT_REGISTRY> = React.ComponentProps<
+  (typeof _ZORA_COMPONENT_REGISTRY)[K]
+>;
+
+type AcceptsSurfaceInteractionPolicyProps<P> = 'interactionPolicy' extends keyof P
+  ? InteractionPolicyProps extends Pick<P, 'interactionPolicy'>
+    ? Pick<P, 'interactionPolicy'> extends InteractionPolicyProps
+      ? true
+      : false
+    : false
+  : false;
+
+type RegistryInteractionPolicyContract = {
+  [K in keyof typeof _ZORA_COMPONENT_REGISTRY]: AcceptsSurfaceInteractionPolicyProps<
+    ComponentPropsFor<K>
+  >;
+};
+
+type _AssertTrue<T extends true> = T;
+type _RegistryInteractionPolicyCheck = _AssertTrue<
+  RegistryInteractionPolicyContract[keyof typeof _ZORA_COMPONENT_REGISTRY]
+>;
+
+const _ZORA_COMPONENT_REGISTRY = {
+  Accordion,
+  AccordionItem,
+  ActivityIndicator,
+  AppBar,
+  Avatar,
+  AvatarGroup,
+  Badge,
+  Breadcrumbs,
+  Button,
+  ButtonGroup,
+  Card,
+  Checkbox,
+  CheckboxGroup,
+  Chip,
+  ChipGroup,
+  DataTable,
+  DatePicker,
+  Dialog,
+  Form,
+  FormActions,
+  FormError,
+  Field,
+  Gradient,
+  Heading,
+  Icon,
+  IconButton,
+  Image,
+  KeyboardAvoidingView,
+  TextInput,
+  MediaCard,
+  MetricCard,
+  Pagination,
+  PopoverMenu,
+  Progress,
+  ProgressRing,
+  Radio,
+  RadioGroup,
+  Rating,
+  SearchInput,
+  Select,
+  Switch,
+  Skeleton,
+  SkeletonCard,
+  SkeletonList,
+  SkeletonText,
+  Tab,
+  TabList,
+  TabPanel,
+  Tabs,
+  Text,
+  TimePicker,
+  Toast,
+  Toolbar,
+  Uploader,
+  BottomSheet,
+  FlatList,
+  SectionList,
+  ScrollView,
+  View,
+  ThemeModeToggle,
+  Divider,
+  Grid,
+  Surface,
+  AppShell,
+  Screen,
+  ScreenSection,
+  ForgotPasswordForm,
+  OAuthProviderButton,
+  OAuthProviderList,
+  OtpForm,
+  SignInForm,
+  SignUpForm,
+  ChatListItem,
+  CollectionEditor,
+  ContentRail,
+  EmptyState,
+  Hero,
+  List,
+  ListItem,
+  ListSection,
+  MessageBubble,
+  MissingElement,
+  PostCard,
+  ProductCard,
+  ReaderSurface,
+  BarcodeScannerView,
+  CameraPermissionView,
+  ScanOverlay,
+  SectionHeader,
+  SelectableItem,
+  PaletteItem,
+  Timeline,
+  TreeItem,
+  TreeView,
+} as const satisfies ZoraComponentRegistry;
+
+export const ZORA_COMPONENT_REGISTRY: ZoraComponentRegistry = _ZORA_COMPONENT_REGISTRY;

package/src/features/registry/public.ts

@@ -0,0 +1 @@
+export { ZORA_COMPONENT_REGISTRY } from './ZORA_COMPONENT_REGISTRY';

package/src/features/registry/registry.test.ts

@@ -0,0 +1,97 @@
+import { describe, expect, test } from 'bun:test';
+
+import type { ZoraComponentRegistry } from '../../types/registry';
+
+const NON_RUNTIME_COMPONENT_EXPORTS = new Set([
+  'GradientRendererProvider',
+  'SelectionProvider',
+  'ToastProvider',
+  'ZoraPluginCompositionError',
+]);
+const RUNTIME_THEME_COMPONENT_EXPORTS = ['ThemeModeToggle'] as const;
+const REGISTRY_SNAPSHOT_PREFIX = 'ZORA_REGISTRY_SNAPSHOT:';
+
+let registryEntriesPromise: Promise<readonly string[]> | undefined;
+
+async function listRuntimeRegistryEntries(): Promise<readonly string[]> {
+  registryEntriesPromise ??= (async () => {
+    const subprocess = Bun.spawn({
+      cmd: [process.execPath, 'test', 'test-fixtures/registrySnapshot.test.ts'],
+      stdout: 'pipe',
+      stderr: 'pipe',
+    });
+    const [stdout, stderr, exitCode] = await Promise.all([
+      new Response(subprocess.stdout).text(),
+      new Response(subprocess.stderr).text(),
+      subprocess.exited,
+    ]);
+
+    if (exitCode !== 0) {
+      throw new Error(`Failed to inspect ZORA_COMPONENT_REGISTRY:\n${stdout}\n${stderr}`);
+    }
+
+    const output = `${stdout}\n${stderr}`;
+    const escapedPrefix = REGISTRY_SNAPSHOT_PREFIX.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+    const snapshotJson = new RegExp(`${escapedPrefix}(\\[[^\\r\\n]*\\])`).exec(output)?.[1];
+
+    if (!snapshotJson) {
+      throw new Error('Registry snapshot subprocess did not emit a registry snapshot.');
+    }
+
+    const parsed: unknown = JSON.parse(snapshotJson);
+    if (
+      !Array.isArray(parsed) ||
+      !parsed.every((entry): entry is string => typeof entry === 'string')
+    ) {
+      throw new Error('Registry snapshot must be a JSON array of component names.');
+    }
+
+    return parsed;
+  })();
+
+  return registryEntriesPromise;
+}
+
+async function listPublicConcreteComponentExports(): Promise<readonly string[]> {
+  const source = await Bun.file('src/index.ts').text();
+  const componentExports = Array.from(
+    source.matchAll(
+      /export\s+\{([^}]+)\}\s+from '\.\/(components\/[^']+|features\/[^']+|foundation|layout\/[^']+|patterns\/[^']+)';/g,
+    ),
+  )
+    .flatMap((match) => match[1].split(',').map((item) => item.trim()))
+    .map((item) => item.split(' as ')[0].trim())
+    .filter((name) => /^[A-Z][A-Za-z0-9]+$/.test(name))
+    .filter((name) => !NON_RUNTIME_COMPONENT_EXPORTS.has(name));
+
+  return [...componentExports, ...RUNTIME_THEME_COMPONENT_EXPORTS].sort();
+}
+
+describe('ZORA_COMPONENT_REGISTRY', () => {
+  test('is exported from the public root API', async () => {
+    const source = await Bun.file('src/index.ts').text();
+    const registry: ZoraComponentRegistry = {};
+    const registryEntries = await listRuntimeRegistryEntries();
+
+    expect(registry).toEqual({});
+    expect(registryEntries).toContain('Screen');
+    expect(registryEntries).toContain('View');
+    expect(source).toContain("export type { ZoraComponentRegistry } from './types/registry';");
+    expect(source).toContain(
+      "export { ZORA_COMPONENT_REGISTRY } from './features/registry/public';",
+    );
+  });
+
+  test('covers every public concrete ZORA component export supported for runtime rendering', async () => {
+    const publicComponentExports = await listPublicConcreteComponentExports();
+
+    expect(await listRuntimeRegistryEntries()).toEqual(publicComponentExports);
+  });
+
+  test('does not register provider-only exports', async () => {
+    const registryEntries = await listRuntimeRegistryEntries();
+
+    expect(registryEntries).not.toContain('ToastProvider');
+    expect(registryEntries).not.toContain('SelectionProvider');
+  });
+});