feat(angular): initial Angular integration — drop-in viewer, docs, and marketing landing

.changeset/angular-pdf-viewer-initial.md

@@ -0,0 +1,13 @@
+---
+'@embedpdf/angular-pdf-viewer': minor
+---
+
+Initial release of `@embedpdf/angular-pdf-viewer`. Provides an Angular 21+ standalone `PDFViewer` component (selector `<embedpdf-viewer>`) that wraps `@embedpdf/snippet`, mirroring the contract of the existing Vue/React/Svelte wrapper viewers:
+
+- Signal-based `config` input
+- Signal-based outputs: `(init)`, `(ready)`, `(themeChange)` (forwards the snippet's `themechange` custom event)
+- Reactive state signals: `container: Signal<EmbedPdfContainer | null>`, `registry: Signal<PluginRegistry | null>`
+- `OnPush` change detection, SSR-safe `afterNextRender` mounting, `DestroyRef` cleanup
+- `provideEmbedPdfViewerConfig({ ... })` + `EMBEDPDF_VIEWER_DEFAULT_CONFIG` token for app/route/component-scoped default config that merges with per-instance `[config]` (via `mergeViewerConfigs` deep-merge rules)
+
+Built via `@analogjs/vite-plugin-angular` for AOT-compiled FESM2022 output following Analog's library-build guidance.

.changeset/config.json

@@ -55,6 +55,8 @@
     "@embedpdf/example-vue-tailwind",
     "@embedpdf/example-vue-vuetify",
     "@embedpdf/example-svelte-tailwind",
+    "@embedpdf/example-angular-pdf-viewer",
+    "@embedpdf/example-angular-tailwind",
     "@embedpdf/example-engines-node",
     "@embedpdf/example-pdfium-node",
     "@embedpdf/ai",

.github/workflows/test.yml

@@ -0,0 +1,66 @@
+name: Test
+
+on:
+  pull_request:
+    branches: [main, feature/angular]
+  push:
+    branches: [main, feature/angular]
+
+concurrency:
+  group: test-${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+jobs:
+  test-node:
+    name: Node-mode tests
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: pnpm/action-setup@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: pnpm
+      - run: pnpm install --frozen-lockfile
+      - name: Run Node-mode + jsdom tests
+        run: pnpm test
+
+  detect-angular-changes:
+    name: Detect Angular touchpoints
+    runs-on: ubuntu-latest
+    outputs:
+      changed: ${{ steps.filter.outputs.angular }}
+    steps:
+      - uses: actions/checkout@v4
+      - uses: dorny/paths-filter@v3
+        id: filter
+        with:
+          filters: |
+            angular:
+              - 'packages/*/src/angular/**'
+              - 'viewers/angular/**'
+              - 'examples/angular-custom/**'
+              - 'packages/build/src/vite/**'
+
+  test-browser:
+    name: Browser-mode tests (Angular)
+    runs-on: ubuntu-latest
+    needs: detect-angular-changes
+    if: needs.detect-angular-changes.outputs.changed == 'true'
+    steps:
+      - uses: actions/checkout@v4
+      - uses: pnpm/action-setup@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: pnpm
+      - run: pnpm install --frozen-lockfile
+      - name: Cache Playwright browsers
+        uses: actions/cache@v4
+        with:
+          path: ~/.cache/ms-playwright
+          key: playwright-${{ runner.os }}-${{ hashFiles('pnpm-lock.yaml') }}
+      - name: Install Playwright Chromium
+        run: pnpm --filter @embedpdf/angular-pdf-viewer exec playwright install --with-deps chromium
+      - name: Run browser-mode tests
+        run: pnpm test:browser

.gitignore

@@ -3,15 +3,31 @@ node_modules
 **/node_modules/
 **/dist
 **/.turbo
+**/coverage
+**/.vercel
+**/playwright-report
+**/test-results
+**/blob-report
+**/vitest-results
+**/storybook-static
+**/public/_pagefind/
+.env
+.env*.local
 config/tsup.config.bundled*
 config/tsup.frameworks.config.bundled*
 .next
 .cursor
 .DS_Store
+.env
 .gcs_entries
 .gclient*
 .cipd
 .idea
 publish-summary.json
 **/.svelte-kit
 **/*/*.tgz
+.env
+.env.*
+**/playwright-report
+**/test-results
+CLAUDE.md

examples/angular-pdf-viewer/.gitignore

@@ -0,0 +1,2 @@
+playwright-report/
+test-results/

examples/angular-pdf-viewer/README.md

@@ -0,0 +1,44 @@
+# Angular PDF Viewer Demo
+
+This example is a **modern Angular 21.2 zoneless** demo app for `@embedpdf/angular-pdf-viewer`.
+
+It serves two purposes:
+
+- Manual verification of the drop-in viewer UX with config-driven customization
+- End-to-end validation that Angular config and runtime registry hooks reach the snippet correctly
+- Reference usage of the lightweight capability-signal helpers exported by `@embedpdf/angular-pdf-viewer`
+
+## What this example demonstrates
+
+- `disabledCategories: ['annotation']` to remove annotation tools from the UI
+- `theme.preference: 'light'` for deterministic color mode
+- A custom Angular-red accent via `theme.light.accent`
+- A runtime toolbar customization via `(ready)`, `createPluginCapabilitySignal(...)`, `commands.registerCommand()`, and `ui.mergeSchema()`
+- An Angular-owned config panel, toggled by a runtime-injected `Config` button, that can animate open/closed, live-toggle theme mode, and expose up to four checkbox-based view options for annotations, search, sidebar, and zoom controls
+
+## Related Angular example workspace
+
+If you are looking for the **live examples embedded in the website docs**, see [`examples/angular-tailwind`](../angular-tailwind/).
+
+That workspace has a different job:
+
+- **`angular-pdf-viewer`** — the consumer-style demo app for validating the drop-in package in a realistic Angular app
+- **`angular-tailwind`** — the docs-example workspace that exports multiple focused Angular demos for `website/`
+
+Start here when you want the clearest reference for integrating `@embedpdf/angular-pdf-viewer` into an application. Jump to `angular-tailwind` when you want to work on the docs demos themselves.
+
+## Scripts
+
+- `pnpm dev` — run the demo app locally on `http://127.0.0.1:4300`
+- `pnpm build` — production build
+- `pnpm e2e` — run Playwright end-to-end tests
+
+## Turbo usage
+
+Run this suite through Turbo:
+
+- `pnpm e2e:angular-pdf-viewer`
+
+Or run all e2e tasks in the monorepo:
+
+- `pnpm e2e`

examples/angular-pdf-viewer/e2e/viewer.spec.ts

@@ -0,0 +1,109 @@
+import { expect, test } from '@playwright/test';
+
+const stableScreenshotOptions = {
+  animations: 'disabled',
+  caret: 'hide',
+  scale: 'css',
+} as const;
+
+test('applies Angular config-driven theme and category customization', async ({ page }) => {
+  await page.goto('/');
+
+  await expect(page.getByRole('heading', { name: 'EmbedPDF Angular Viewer Demo' })).toBeVisible();
+  await expect(
+    page.getByText(
+      'Light theme, Angular red accent, annotation tools disabled, custom config panel added at runtime',
+    ),
+  ).toBeVisible();
+  await expect(page.locator('embedpdf-viewer')).toBeVisible();
+
+  await expect(page.getByTestId('viewer-status')).toHaveText('ready', {
+    timeout: 30_000,
+  });
+
+  const container = page.locator('embedpdf-viewer embedpdf-container');
+  await expect(container).toHaveCount(1);
+  await expect(container).toHaveAttribute('data-color-scheme', 'light');
+
+  const themeState = await container.evaluate((node) => {
+    const viewer = node as HTMLElement & {
+      themePreference?: string;
+    };
+
+    return {
+      themePreference: viewer.themePreference ?? null,
+      accentPrimary: getComputedStyle(viewer).getPropertyValue('--ep-accent-primary').trim(),
+    };
+  });
+
+  expect(themeState).toEqual({
+    themePreference: 'light',
+    accentPrimary: '#dd0031',
+  });
+
+  await expect(page.getByRole('button', { name: 'View' })).toBeVisible();
+  await expect(page.getByRole('button', { name: 'Config', exact: true })).toBeVisible();
+  await expect(page.getByRole('button', { name: 'Annotate' })).toHaveCount(0);
+  await expect(page.getByRole('button', { name: 'Highlight' })).toHaveCount(0);
+
+  await page.getByRole('button', { name: 'Config', exact: true }).click();
+  const configPanel = page.getByTestId('angular-config-panel');
+  const configPanelShell = page.getByTestId('angular-config-panel-shell');
+  await expect(configPanel).toBeVisible();
+
+  const viewerBounds = await page.locator('embedpdf-viewer').boundingBox();
+  expect(viewerBounds).not.toBeNull();
+  expect(viewerBounds!.width).toBeGreaterThanOrEqual(320);
+  expect(viewerBounds!.height).toBeGreaterThanOrEqual(320);
+
+  await expect(page.getByTestId('theme-mode')).toHaveText('light');
+  await expect(page.getByTestId('disabled-categories')).toHaveText('Annotations');
+  await expect(page.getByTestId('view-option-sidebar')).toBeChecked();
+  await expect(page.getByTestId('view-option-search')).toBeChecked();
+  await expect(page.getByTestId('view-option-zoom')).toBeChecked();
+  await expect(page.getByTestId('view-option-annotations')).not.toBeChecked();
+
+  await expect(configPanelShell).toHaveScreenshot(
+    'angular-config-panel-default.png',
+    stableScreenshotOptions,
+  );
+
+  await page.getByTestId('toggle-theme').click();
+
+  const darkThemeState = await container.evaluate((node) => ({
+    colorScheme: node.getAttribute('data-color-scheme'),
+    accentPrimary: getComputedStyle(node).getPropertyValue('--ep-accent-primary').trim(),
+  }));
+
+  expect(darkThemeState).toEqual({
+    colorScheme: 'dark',
+    accentPrimary: '#ff5c7c',
+  });
+  await expect(page.getByTestId('theme-mode')).toHaveText('dark');
+
+  await page.getByTestId('view-option-annotations').check();
+  await page.getByTestId('view-option-search').uncheck();
+  await expect(page.getByTestId('disabled-categories')).toHaveText('Search');
+  await expect(page.getByRole('button', { name: 'Annotate' })).toBeVisible();
+  await expect(page.getByRole('button', { name: 'Search' })).toHaveCount(0);
+
+  await expect(configPanelShell).toHaveScreenshot(
+    'angular-config-panel-toggled.png',
+    stableScreenshotOptions,
+  );
+
+  await page.getByTestId('header-config-toggle').click();
+  await expect(configPanel).not.toBeVisible();
+  await expect(page.getByRole('button', { name: 'Config', exact: true })).toBeVisible();
+  await expect(page.getByTestId('header-config-toggle')).toHaveText('Show config');
+
+  await page.getByTestId('header-config-toggle').click();
+  await expect(configPanel).toBeVisible();
+  await expect(page.getByTestId('header-config-toggle')).toHaveText('Collapse config');
+
+  await page.getByTestId('reset-demo').click();
+  await expect(page.getByTestId('theme-mode')).toHaveText('light');
+  await expect(page.getByTestId('disabled-categories')).toHaveText('Annotations');
+  await expect(page.getByRole('button', { name: 'Annotate' })).toHaveCount(0);
+  await expect(page.getByRole('button', { name: 'Search' })).toBeVisible();
+});

examples/angular-pdf-viewer/index.html

@@ -0,0 +1,12 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>EmbedPDF Angular Viewer Demo</title>
+  </head>
+  <body>
+    <app-root></app-root>
+    <script type="module" src="/src/main.ts"></script>
+  </body>
+</html>

examples/angular-pdf-viewer/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@embedpdf/example-angular-pdf-viewer",
+  "private": true,
+  "version": "0.0.0",
+  "type": "module",
+  "license": "MIT",
+  "scripts": {
+    "dev": "vite --host 127.0.0.1 --port 4300",
+    "build": "vite build",
+    "preview": "vite preview --host 127.0.0.1 --port 4300",
+    "e2e": "playwright test"
+  },
+  "dependencies": {
+    "@embedpdf/angular-pdf-viewer": "workspace:*",
+    "@angular/compiler": "^21.2.12",
+    "@angular/core": "^21.2.12",
+    "@angular/platform-browser": "^21.2.12",
+    "rxjs": "^7.8.2",
+    "tslib": "^2.8.1"
+  },
+  "devDependencies": {
+    "@analogjs/vite-plugin-angular": "^2.5.0",
+    "@angular/build": "^21.2.10",
+    "@angular/compiler-cli": "^21.2.12",
+    "@playwright/test": "^1.54.2",
+    "typescript": "^5.9.3",
+    "vite": "^6.4.1"
+  }
+}

examples/angular-pdf-viewer/playwright.config.ts

@@ -0,0 +1,38 @@
+import { defineConfig, devices } from '@playwright/test';
+
+const stableViewport = {
+  width: 1440,
+  height: 1200,
+} as const;
+
+export default defineConfig({
+  testDir: './e2e',
+  fullyParallel: true,
+  forbidOnly: !!process.env.CI,
+  retries: process.env.CI ? 2 : 0,
+  reporter: process.env.CI
+    ? [['github'], ['html', { open: 'never' }]]
+    : [['list'], ['html', { open: 'never' }]],
+  use: {
+    baseURL: 'http://127.0.0.1:4300',
+    trace: 'on-first-retry',
+  },
+  webServer: {
+    command: 'pnpm dev',
+    url: 'http://127.0.0.1:4300',
+    reuseExistingServer: !process.env.CI,
+    timeout: 120_000,
+  },
+  projects: [
+    {
+      name: 'chromium',
+      use: {
+        ...devices['Desktop Chrome'],
+        viewport: stableViewport,
+        deviceScaleFactor: 1,
+        colorScheme: 'light',
+        locale: 'en-US',
+      },
+    },
+  ],
+});