Actions & scripts

import { useEffect, useRef, useState } from 'react';
import { Viewer, DocumentGate } from '@embedpdf/react/runtime';
import type { OpenInput } from '@embedpdf/react/runtime';
import {
  actionsPlugin,
  useActions,
  useActionsEvent,
  useActionsUiAdapter,
  type ActionContext,
  type PdfActionTree,
} from '@embedpdf/react/actions';
import { localEngine } from '@embedpdf/engine';

import './javascript.css';

const engine = localEngine();
// JavaScript on, and two fields scripts often ask for about the user.
const plugins = [
  actionsPlugin({
    javascript: { enabled: true, identity: { name: 'Dana Smith', corporation: 'Acme' } },
  }),
];

const ebook = async (): Promise<OpenInput> => {
  const response = await fetch('https://snippet.embedpdf.com/ebook.pdf');
  return { kind: 'bytes', id: 'ebook', bytes: new Uint8Array(await response.arrayBuffer()) };
};

// A JavaScript action, as a PDF carries it behind a button or a link.
const script = (code: string): PdfActionTree => ({
  root: { type: 'javascript', subtype: 'JavaScript', script: code, next: [] },
  incomplete: false,
  warningFlags: 0,
  warnings: [],
});
const click: ActionContext = {
  origin: 'user',
  source: { kind: 'api' },
  event: { scope: 'activate' },
};

const GREETING = "app.alert('Hello, ' + identity.name + ' from ' + identity.corporation + '!');";

// Edit the script and run it. Its alerts and its errors show below it.
function ScriptConsole() {
  const actions = useActions();
  const [code, setCode] = useState(GREETING);
  const [output, setOutput] = useState<Array<{ kind: 'alert' | 'error'; text: string }>>([]);
  const show = (kind: 'alert' | 'error', text: string) =>
    setOutput((lines) => [{ kind, text }, ...lines].slice(0, 5));

  // A script's alert goes to your UI adapter: here, a line below the script.
  useActionsUiAdapter({ alert: (message) => show('alert', message) });
  useActionsEvent(
    (capability) => capability.onScriptFailed,
    ({ error }) => show('error', error.message),
  );

  // The greeting runs once on load.
  const greeted = useRef(false);
  useEffect(() => {
    if (greeted.current) return;
    greeted.current = true;
    void actions.execute(script(GREETING), click);
  });

  return (
    <section className="panel">
      <label className="name" htmlFor="script">
        Script {actions.isScriptingEnabled() ? '' : '(JavaScript is off)'}
      </label>
      <textarea
        id="script"
        className="code"
        spellCheck={false}
        rows={3}
        value={code}
        onChange={(event) => setCode(event.target.value)}
      />
      <div className="actions">
        <button
          type="button"
          className="button primary"
          onClick={() => actions.execute(script(code), click)}
        >
          Run
        </button>
        <button type="button" className="button" onClick={() => setCode('app.alrt("typo");')}>
          A script with a mistake
        </button>
      </div>
      <ol className="output" aria-live="polite">
        {output.map((line, index) => (
          <li key={output.length - index} className={line.kind}>
            {line.text}
          </li>
        ))}
      </ol>
    </section>
  );
}

export default function App() {
  return (
    <Viewer engine={engine} plugins={plugins} initialDocuments={[{ source: ebook }]}>
      <DocumentGate fallback={<p className="loading">Loading…</p>}>
        <ScriptConsole />
      </DocumentGate>
    </Viewer>
  );
}

import { useEffect, useRef, useState } from 'react';
import { Viewer, DocumentGate } from '@embedpdf/react/runtime';
import type { OpenInput } from '@embedpdf/react/runtime';
import {
  actionsPlugin,
  useActions,
  useActionsUiAdapter,
  type ActionContext,
  type PdfActionTree,
} from '@embedpdf/react/actions';
import { localEngine } from '@embedpdf/engine';

import './website-links.css';

const engine = localEngine();
const plugins = [actionsPlugin()];

const ebook = async (): Promise<OpenInput> => {
  const response = await fetch('https://snippet.embedpdf.com/ebook.pdf');
  return { kind: 'bytes', id: 'ebook', bytes: new Uint8Array(await response.arrayBuffer()) };
};

// A link to a website, as a PDF carries it: what getActionTree() reads from a link.
const websiteLink: PdfActionTree = {
  root: { type: 'uri', subtype: 'URI', uri: 'https://www.embedpdf.com', isMap: false, next: [] },
  incomplete: false,
  warningFlags: 0,
  warnings: [],
};
const click: ActionContext = {
  origin: 'user',
  source: { kind: 'api' },
  event: { scope: 'activate' },
};

// Your UI decides how a website opens: here, it asks first.
function AskBeforeOpening() {
  const actions = useActions();
  const [asking, setAsking] = useState<string | null>(null);

  useActionsUiAdapter({ openUri: (uri) => setAsking(uri) });

  // The link is clicked once on load, so the question is there to see.
  const clicked = useRef(false);
  useEffect(() => {
    if (clicked.current) return;
    clicked.current = true;
    void actions.execute(websiteLink, click);
  });

  return (
    <section className="panel">
      <p className="lead">
        The document links to <code>https://www.embedpdf.com</code>.
      </p>
      <button type="button" className="button" onClick={() => actions.execute(websiteLink, click)}>
        Click the link
      </button>
      {asking && (
        <div className="prompt" role="alertdialog" aria-label="Open a website">
          <p className="prompt-text">
            This document wants to open <strong>{asking}</strong>.
          </p>
          <div className="prompt-actions">
            <button type="button" className="button" onClick={() => setAsking(null)}>
              Stay here
            </button>
            <button
              type="button"
              className="button primary"
              onClick={() => {
                window.open(asking, '_blank', 'noopener');
                setAsking(null);
              }}
            >
              Open in a new tab
            </button>
          </div>
        </div>
      )}
    </section>
  );
}

export default function App() {
  return (
    <Viewer engine={engine} plugins={plugins} initialDocuments={[{ source: ebook }]}>
      <DocumentGate fallback={<p className="loading">Loading…</p>}>
        <AskBeforeOpening />
      </DocumentGate>
    </Viewer>
  );
}

import { useEffect, useRef, useState } from 'react';
import { Viewer, DocumentGate } from '@embedpdf/react/runtime';
import type { OpenInput } from '@embedpdf/react/runtime';
import {
  actionsPlugin,
  useActions,
  useActionsEvent,
  useActionsSettings,
  useActionsUiAdapter,
  type ActionContext,
  type ActionOrigin,
  type ActionPolicyDecision,
  type PdfActionTree,
} from '@embedpdf/react/actions';
import { localEngine } from '@embedpdf/engine';

import './rules.css';

const engine = localEngine();
// Websites open only on a click, as the page's example registers it.
const plugins = [
  actionsPlugin({
    policy: { uri: { user: 'adapter', hover: 'block', lifecycle: 'block' } },
  }),
];

const ebook = async (): Promise<OpenInput> => {
  const response = await fetch('https://snippet.embedpdf.com/ebook.pdf');
  return { kind: 'bytes', id: 'ebook', bytes: new Uint8Array(await response.arrayBuffer()) };
};

// A link to a website, as a PDF carries it: what getActionTree() reads from a link.
const websiteLink: PdfActionTree = {
  root: { type: 'uri', subtype: 'URI', uri: 'https://www.embedpdf.com', isMap: false, next: [] },
  incomplete: false,
  warningFlags: 0,
  warnings: [],
};

// The three ways an action can start, each as the context it runs with.
const STARTS: ReadonlyArray<{ label: string; context: ActionContext }> = [
  {
    label: 'A click',
    context: { origin: 'user', source: { kind: 'api' }, event: { scope: 'activate' } },
  },
  {
    label: 'The pointer over it',
    context: {
      origin: 'hover',
      source: { kind: 'api' },
      event: { scope: 'annotation', name: 'cursorEnter' },
    },
  },
  {
    label: 'The document opening',
    context: {
      origin: 'lifecycle',
      source: { kind: 'api' },
      event: { scope: 'document', name: 'open' },
    },
  },
];
const RULES: readonly ActionPolicyDecision[] = ['allow', 'adapter', 'report', 'block'];

// The rules for websites, changed while the app runs, and what happens when the link runs.
function WebsiteRules() {
  const actions = useActions();
  const rules = useActionsSettings((settings) => settings.policy.uri);
  const [log, setLog] = useState<string[]>([]);
  const note = (line: string) => setLog((lines) => [line, ...lines].slice(0, 6));

  // Instead of opening a tab, the adapter notes the website it was given.
  useActionsUiAdapter({ openUri: (uri) => note(`Your adapter got ${uri}`) });
  useActionsEvent(
    (capability) => capability.onDiagnosticReported,
    ({ code, action }) => note(`The ${action} action was not run: ${code}`),
  );

  const run = (context: ActionContext) => actions.execute(websiteLink, context);
  const setRule = (origin: ActionOrigin, rule: ActionPolicyDecision) =>
    actions.updateSettings({ policy: { uri: { [origin]: rule } } });

  // One click on load, so the log shows what a click does.
  const clicked = useRef(false);
  useEffect(() => {
    if (clicked.current) return;
    clicked.current = true;
    void run(STARTS[0].context);
  });

  return (
    <section className="panel">
      <ul className="starts">
        {STARTS.map(({ label, context }) => (
          <li className="start" key={context.origin}>
            <span className="start-label">
              {label} <code>{context.origin}</code>
            </span>
            <select
              className="field"
              aria-label={`The rule for ${context.origin}`}
              value={rules[context.origin]}
              onChange={(event) =>
                setRule(context.origin, event.target.value as ActionPolicyDecision)
              }
            >
              {RULES.map((rule) => (
                <option key={rule} value={rule}>
                  {rule}
                </option>
              ))}
            </select>
            <button type="button" className="button" onClick={() => run(context)}>
              Run the link
            </button>
          </li>
        ))}
      </ul>
      <div className="footer">
        <ol className="log" aria-live="polite">
          {log.map((line, index) => (
            <li key={log.length - index}>{line}</li>
          ))}
        </ol>
        <button type="button" className="button" onClick={() => actions.resetSettings()}>
          Back to the registered rules
        </button>
      </div>
    </section>
  );
}

export default function App() {
  return (
    <Viewer engine={engine} plugins={plugins} initialDocuments={[{ source: ebook }]}>
      <DocumentGate fallback={<p className="loading">Loading…</p>}>
        <WebsiteRules />
      </DocumentGate>
    </Viewer>
  );
}

import { useEffect, useState } from 'react';
import { Viewer, DocumentGate } from '@embedpdf/react/runtime';
import type { OpenInput } from '@embedpdf/react/runtime';
import { Stage, stagePlugin, useStageState } from '@embedpdf/react/stage';
import { RenderLayer, renderPlugin } from '@embedpdf/react/render';
import {
  actionsPlugin,
  useActions,
  useActionsUiAdapter,
  type PdfNamedAction,
} from '@embedpdf/react/actions';
import { localEngine } from '@embedpdf/engine';

import './run-from-code.css';

const engine = localEngine();
const plugins = [stagePlugin(), renderPlugin(), actionsPlugin()];

const ebook = async (): Promise<OpenInput> => {
  const response = await fetch('https://snippet.embedpdf.com/ebook.pdf');
  return { kind: 'bytes', id: 'ebook', bytes: new Uint8Array(await response.arrayBuffer()) };
};

const VERBS: ReadonlyArray<[PdfNamedAction, string]> = [
  ['FirstPage', '⇤ First'],
  ['PrevPage', '‹ Previous'],
  ['NextPage', 'Next ›'],
  ['LastPage', 'Last ⇥'],
  ['Print', 'Print'],
];

// The viewer actions a PDF's buttons name, run from your own buttons.
function NamedActions() {
  const actions = useActions();
  const { currentPageIndex, pageCount } = useStageState();
  const [ran, setRan] = useState<string | null>(null);

  // Print goes to your UI adapter. This one says so, instead of opening the browser's print dialog.
  useActionsUiAdapter({ print: () => setRan('Print: your print handler ran') });

  // On load, as if a "Last page" button in the PDF was clicked. Running it twice changes nothing.
  useEffect(() => {
    void actions.executeNamed('LastPage').then(({ status }) => setRan(`LastPage: ${status}`));
  }, [actions]);

  return (
    <div className="toolbar">
      {VERBS.map(([name, label]) => (
        <button
          type="button"
          className="button"
          key={name}
          disabled={!actions.canExecuteNamed(name)}
          onClick={async () => {
            const { status } = await actions.executeNamed(name);
            if (name !== 'Print') setRan(`${name}: ${status}`);
          }}
        >
          {label}
        </button>
      ))}
      <span className="spacer" />
      <output className="readout">
        Page {currentPageIndex + 1} of {pageCount}
        {ran && <span className="ran"> · {ran}</span>}
      </output>
    </div>
  );
}

export default function App() {
  return (
    <Viewer engine={engine} plugins={plugins} initialDocuments={[{ source: ebook }]}>
      <DocumentGate fallback={<p className="loading">Loading…</p>}>
        <NamedActions />
        <Stage className="stage">{() => <RenderLayer />}</Stage>
      </DocumentGate>
    </Viewer>
  );
}