@heyramzi/ui 1.54.2 → 2.0.0

package/src/slides/demo.svelte

@@ -0,0 +1,176 @@
+<script lang="ts">
+  import Deck from './Deck.svelte';
+  import type { DeckController } from './deck-controller.svelte.js';
+  import DemoSlides, { demoStyle } from './demo-slides.svelte';
+  import type { DeckTheme, DeckTransition } from './types.js';
+
+  interface Props {
+    /** Where the presenter view is mounted. Leave out to hide the button. */
+    presenter?: string;
+  };
+
+  let { presenter }: Props = $props();
+
+  const themes: DeckTheme[] = ['ink', 'paper', 'auto'];
+  const transitions: DeckTransition[] = ['fade', 'slide', 'zoom', 'morph'];
+
+  let theme = $state<DeckTheme>('ink');
+  let transition = $state<DeckTransition>('fade');
+  let deck = $state<DeckController>();
+</script>
+
+<div class="demo">
+  <div class="demo__bar">
+    <div class="demo__group" role="radiogroup" aria-label="Theme">
+      {#each themes as option (option)}
+        <button
+          type="button"
+          role="radio"
+          aria-checked={theme === option}
+          class="demo__option"
+          onclick={() => (theme = option)}>{option}</button
+        >
+      {/each}
+    </div>
+    <label class="demo__field">
+      <span>Transition</span>
+      <select bind:value={transition}>
+        {#each transitions as option (option)}
+          <option value={option}>{option}</option>
+        {/each}
+      </select>
+    </label>
+    <div class="demo__actions">
+      <button type="button" class="demo__action" onclick={() => deck?.toggleOverview()}>Overview</button>
+      {#if presenter}
+        <a class="demo__action" href={presenter} target="heyramzi-slides-demo-presenter">Presenter</a>
+      {/if}
+      <button type="button" class="demo__action" onclick={() => window.print()}>Print</button>
+    </div>
+  </div>
+
+  <div class="demo__stage">
+    <Deck
+      bind:controller={deck}
+      id="slides-demo"
+      title="Slides demo"
+      sync="slides-demo"
+      urlSync={false}
+      {theme}
+      {transition}
+      {presenter}
+      style={demoStyle}
+    >
+      <DemoSlides />
+    </Deck>
+  </div>
+</div>
+
+<style>
+  .demo {
+    display: grid;
+    gap: 14px;
+    width: 100%;
+  }
+
+  .demo__bar {
+    display: flex;
+    flex-wrap: wrap;
+    align-items: center;
+    gap: 10px 16px;
+    font-size: 13px;
+  }
+  .demo__group {
+    display: inline-flex;
+    padding: 3px;
+    background: color-mix(in srgb, currentColor 7%, transparent);
+    border-radius: 10px;
+  }
+  .demo__option {
+    padding: 5px 12px;
+    font: inherit;
+    font-weight: 500;
+    color: inherit;
+    text-transform: capitalize;
+    background: transparent;
+    border: 0;
+    border-radius: 7px;
+    opacity: 0.65;
+    cursor: pointer;
+    transition:
+      background-color var(--duration-quick, 150ms) var(--ease-smooth-out, ease-out),
+      opacity var(--duration-quick, 150ms) var(--ease-smooth-out, ease-out);
+  }
+  @media (hover: hover) and (pointer: fine) {
+    .demo__option:hover {
+      opacity: 1;
+    }
+  }
+  .demo__option[aria-checked='true'] {
+    background: color-mix(in srgb, currentColor 14%, transparent);
+    opacity: 1;
+  }
+  .demo__field {
+    display: inline-flex;
+    align-items: center;
+    gap: 8px;
+    opacity: 0.85;
+  }
+  .demo__field select {
+    padding: 5px 8px;
+    font: inherit;
+    color: inherit;
+    text-transform: capitalize;
+    background: color-mix(in srgb, currentColor 7%, transparent);
+    border: 0;
+    border-radius: 8px;
+  }
+  .demo__actions {
+    display: inline-flex;
+    gap: 6px;
+    margin-left: auto;
+  }
+  .demo__action {
+    padding: 6px 12px;
+    font: inherit;
+    font-weight: 500;
+    color: inherit;
+    text-decoration: none;
+    background: transparent;
+    border: 1px solid color-mix(in srgb, currentColor 22%, transparent);
+    border-radius: 8px;
+    cursor: pointer;
+    transition: background-color var(--duration-quick, 150ms) var(--ease-smooth-out, ease-out);
+  }
+  @media (hover: hover) and (pointer: fine) {
+    .demo__action:hover {
+      background: color-mix(in srgb, currentColor 8%, transparent);
+    }
+  }
+  .demo__option:focus-visible,
+  .demo__action:focus-visible,
+  .demo__field select:focus-visible {
+    outline: 2px solid currentColor;
+    outline-offset: 2px;
+  }
+
+  .demo__stage {
+    overflow: hidden;
+    border-radius: 16px;
+    box-shadow: 0 0 0 1px color-mix(in srgb, currentColor 14%, transparent);
+  }
+
+  @media print {
+    .demo {
+      display: block;
+    }
+    .demo__bar {
+      display: none;
+    }
+    .demo__stage {
+      overflow: visible;
+      border-radius: 0;
+      box-shadow: none;
+    }
+  }
+</style>

package/src/slides/export/capture.ts

@@ -0,0 +1,113 @@
+// Capture a page, or one element of it, to PNG at a canvas size and device scale.
+
+import { mkdir, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import type { BrowserLike, LocatorLike, PageLike, Size, WaitUntil } from './types.js';
+
+/**
+ * `networkidle` makes a screenshot land on a finished page and never fires on a
+ * page that keeps polling: an analytics beacon, a chat widget, a buffering hero
+ * video. So the first attempt asks for idle and a retry falls back to `load`,
+ * which always fires; the caller's `wait` settles whatever is left.
+ */
+export const DEFAULT_WAITS: readonly WaitUntil[] = ['networkidle', 'load'];
+
+export interface GotoOptions {
+  /** Tried in order; the first that resolves wins and the last failure is thrown. */
+  waits?: readonly WaitUntil[];
+  timeout?: number;
+}
+
+/** Navigates, retrying with the next wait condition when one times out. */
+export async function gotoSettled(page: PageLike, url: string, options: GotoOptions = {}) {
+  const waits = options.waits ?? DEFAULT_WAITS;
+  const timeout = options.timeout ?? 45_000;
+  let failure: unknown;
+  for (const waitUntil of waits) {
+    try {
+      return await page.goto(url, { waitUntil, timeout });
+    } catch (error) {
+      failure = error;
+    }
+  }
+  throw failure ?? new Error('gotoSettled needs at least one wait condition.');
+}
+
+export type CaptureSource = { url: string } | { html: string };
+
+export interface CaptureOptions {
+  /** The viewport the page lays out in. */
+  size: Size;
+  /** Device scale factor; 2 doubles the pixels. Default 1. */
+  scale?: number;
+  /** Capture just the first element matching this selector, once it is visible. */
+  selector?: string;
+  /** Capture the whole scrollable page. Ignored when a selector is given. */
+  fullPage?: boolean;
+  /** CSS added after load, for hiding overlays. */
+  style?: string;
+  /** Settle time in ms after load, for animations and virtualised lists. */
+  wait?: number;
+  goto?: GotoOptions;
+  /** Also write the PNG here. */
+  path?: string;
+}
+
+/** Opens a page at the canvas size, captures it to PNG and closes the page. */
+export async function capturePage(
+  browser: BrowserLike,
+  source: CaptureSource,
+  options: CaptureOptions,
+): Promise<Uint8Array> {
+  const page = await browser.newPage({
+    viewport: options.size,
+    deviceScaleFactor: options.scale ?? 1,
+  });
+  try {
+    if ('url' in source) await gotoSettled(page, source.url, options.goto);
+    else await page.setContent(source.html, { waitUntil: 'load' });
+    if (options.style) await page.addStyleTag({ content: options.style });
+    if (options.wait) await page.waitForTimeout(options.wait);
+    const { selector } = options;
+    let bytes: Uint8Array;
+    if (selector) {
+      const target = page.locator(selector).first();
+      await target.waitFor({ state: 'visible' });
+      bytes = await target.screenshot({ type: 'png' });
+    } else {
+      bytes = await page.screenshot({ type: 'png', fullPage: options.fullPage });
+    }
+    if (options.path) {
+      await mkdir(path.dirname(options.path), { recursive: true });
+      await writeFile(options.path, bytes);
+    }
+    return bytes;
+  } finally {
+    await page.close();
+  }
+}
+
+/** `01.png`, `02.png` ...: the file name for the nth capture, one-based, zero-padded. */
+export function frameName(index: number, digits = 2, extension = 'png'): string {
+  return `${String(index + 1).padStart(digits, '0')}.${extension}`;
+}
+
+/**
+ * Screenshots every element a locator matches into `dir`, one PNG each, and
+ * returns the paths in order. The elements are the pages of a deck.
+ */
+export async function captureEach(
+  elements: LocatorLike,
+  dir: string,
+  options: { digits?: number } = {},
+): Promise<string[]> {
+  await mkdir(dir, { recursive: true });
+  const count = await elements.count();
+  const files: string[] = [];
+  for (let index = 0; index < count; index++) {
+    const file = path.join(dir, frameName(index, options.digits));
+    await elements.nth(index).screenshot({ path: file });
+    files.push(file);
+  }
+  return files;
+}

package/src/slides/export/ffmpeg.ts

@@ -0,0 +1,120 @@
+// Encode frames to an mp4 with the ffmpeg on the machine. The package ships no
+// binary; pass `ffmpeg` to name one that is not on PATH.
+
+import { spawn } from 'node:child_process';
+import { mkdir, rm } from 'node:fs/promises';
+import path from 'node:path';
+
+/** Runs ffmpeg and resolves when it exits 0; the error carries the tail of its stderr. */
+export function runFfmpeg(args: string[], ffmpeg = 'ffmpeg'): Promise<void> {
+  return new Promise((resolve, reject) => {
+    const child = spawn(ffmpeg, args, { stdio: ['ignore', 'ignore', 'pipe'] });
+    let stderr = '';
+    child.stderr.on('data', (chunk) => {
+      stderr += chunk;
+    });
+    child.on('error', (error) =>
+      reject(new Error(`${ffmpeg} could not be started (${error.message}). Video export needs ffmpeg on PATH, or pass its path.`)),
+    );
+    child.on('close', (code) =>
+      code === 0 ? resolve() : reject(new Error(`${ffmpeg} exited ${code}:\n${stderr.slice(-1500)}`)),
+    );
+  });
+}
+
+export interface EncodeOptions {
+  fps: number;
+  /** x264 constant rate factor; lower is bigger and cleaner. Default 23. */
+  crf?: number;
+  /** x264 speed preset. Default `slow`. */
+  preset?: string;
+  /** The printf pattern the frames are numbered with. Default `%04d.png`. */
+  pattern?: string;
+  ffmpeg?: string;
+}
+
+/** The ffmpeg arguments for a silent yuv420p H.264 mp4 from a numbered image sequence. */
+export function encodeArgs(dir: string, outFile: string, options: EncodeOptions): string[] {
+  return [
+    '-y',
+    '-hide_banner',
+    '-loglevel',
+    'error',
+    '-framerate',
+    String(options.fps),
+    '-i',
+    path.join(dir, options.pattern ?? '%04d.png'),
+    '-an',
+    '-vf',
+    'format=yuv420p',
+    '-c:v',
+    'libx264',
+    '-preset',
+    options.preset ?? 'slow',
+    '-crf',
+    String(options.crf ?? 23),
+    '-movflags',
+    '+faststart',
+    outFile,
+  ];
+}
+
+/** Encodes a folder of numbered frames. There is no audio stream at all. */
+export async function encodeFrames(dir: string, outFile: string, options: EncodeOptions): Promise<void> {
+  await mkdir(path.dirname(outFile), { recursive: true });
+  await runFfmpeg(encodeArgs(dir, outFile, options), options.ffmpeg);
+}
+
+export interface LoopFrame {
+  /** Zero-based frame number. */
+  index: number;
+  /** Position in the cycle, in [0, 1). */
+  t: number;
+  /** Where this frame must be written, as a PNG. */
+  file: string;
+}
+
+export interface LoopOptions extends Omit<EncodeOptions, 'fps' | 'pattern'> {
+  fps?: number;
+  seconds?: number;
+  /** Photograph the frame at `t`; called once per frame, in order. */
+  drawFrame(frame: LoopFrame): Promise<void>;
+}
+
+/** Frames for a loop of this length: whole frames only, never fewer than one. */
+export function loopFrameCount(seconds: number, fps: number): number {
+  return Math.max(1, Math.round(seconds * fps));
+}
+
+/**
+ * Renders a seamless loop: asks `drawFrame` for t = 0, 1/n, ... (n-1)/n and
+ * encodes the result.
+ *
+ * `t` never reaches 1, so the last frame is one step short of the first and
+ * the cut back to frame zero is the same step as every other. Driving all
+ * motion off one t is what makes the seam exact by construction. A captured
+ * CSS animation loops only when its last frame happens to land on its first.
+ */
+export async function renderLoop(
+  outFile: string,
+  options: LoopOptions,
+): Promise<{ file: string; frames: number; seconds: number }> {
+  const fps = options.fps ?? 30;
+  const seconds = options.seconds ?? 2.5;
+  const frames = loopFrameCount(seconds, fps);
+  const work = `${outFile}.frames`;
+  await mkdir(work, { recursive: true });
+  try {
+    for (let index = 0; index < frames; index++) {
+      await options.drawFrame({
+        index,
+        t: index / frames,
+        file: path.join(work, `${String(index).padStart(4, '0')}.png`),
+      });
+    }
+    await encodeFrames(work, outFile, { ...options, fps });
+  } finally {
+    await rm(work, { recursive: true, force: true });
+  }
+  return { file: outFile, frames, seconds };
+}

package/src/slides/export/index.ts

@@ -0,0 +1,9 @@
+// @heyramzi/ui/slides/export: Node-only. Capture, print and encode slides without
+// depending on Playwright or bundling ffmpeg. Hand it the Playwright pages and
+// browsers you already have.
+
+export * from './capture.js';
+export * from './ffmpeg.js';
+export * from './launch.js';
+export * from './pdf.js';
+export type * from './types.js';

package/src/slides/export/launch.ts

@@ -0,0 +1,10 @@
+/**
+ * Launches Chromium, falling back to the installed Chrome. The bundled
+ * Chromium goes missing after a Playwright bump, and Chrome prints the same.
+ * Pass `chromium` from Playwright.
+ */
+export async function launchChromium<B>(chromium: {
+  launch(options?: { headless?: boolean; channel?: string }): Promise<B>;
+}): Promise<B> {
+  return chromium.launch({ headless: true }).catch(() => chromium.launch({ headless: true, channel: 'chrome' }));
+}

package/src/slides/export/pdf.ts

@@ -0,0 +1,152 @@
+// Print a URL or HTML to PDF at a page size, and assemble captured PNGs into one.
+
+import { readFile } from 'node:fs/promises';
+import type { PageLike, ResponseLike, Size, WaitUntil } from './types.js';
+
+/** Chromium drops backgrounds in its print pipeline without the color-adjust line. */
+export const RESET_CSS = `*{margin:0;padding:0;box-sizing:border-box;}
+html{-webkit-print-color-adjust:exact;print-color-adjust:exact;}`;
+
+/** The `@page` rule for a page of this size in CSS pixels, with no margin. */
+export function pageRule(size: Size): string {
+  return `@page{size:${size.width}px ${size.height}px;margin:0;}`;
+}
+
+/** The reset, the page size and one full-bleed `.page` box per image. */
+export function imagePagesCss(size: Size, background?: string): string {
+  return `${RESET_CSS}
+${background ? `body{background:${background};}\n` : ''}${pageRule(size)}
+.page{display:block;width:${size.width}px;height:${size.height}px;break-after:page;}
+.page:last-child{break-after:auto;}`;
+}
+
+/** One `<img class="page">` per data URL, laid out so each prints on its own page. */
+export function imagePagesHtml(dataUrls: string[], size: Size, background?: string): string {
+  const pages = dataUrls.map((dataUrl) => `<img class="page" src="${dataUrl}" alt="">`).join('');
+  return `<!doctype html><html><head><meta charset="utf-8"><style>
+${imagePagesCss(size, background)}
+</style></head><body>${pages}</body></html>`;
+}
+
+/** The page count of a PDF, read off its page objects. */
+export function countPdfPages(pdf: Uint8Array): number {
+  return (Buffer.from(pdf).toString('latin1').match(/\/Type\s*\/Page[^s]/g) ?? []).length;
+}
+
+export interface PrintOptions {
+  /**
+   * The page size in CSS pixels. Leave it out to print at the size the
+   * document's own `@page` declares, which a fixed-size deck writes.
+   */
+  size?: Size;
+  /** A selector to wait for, or a function that resolves when the page is ready to print. */
+  ready?: string | ((page: PageLike) => Promise<void>);
+  /** How long `ready` may take, in ms. Default 60000. */
+  readyTimeout?: number;
+  /** A final pause in ms once ready, for paint that has no signal. */
+  settle?: number;
+  /** For example `1-12`. */
+  pageRanges?: string;
+  /** Write the PDF here as well as returning it. */
+  path?: string;
+}
+
+export interface PrintResult {
+  pdf: Uint8Array;
+  pages: number;
+  /** The `src` of every image that had not loaded when the page was printed. */
+  brokenImages: string[];
+}
+
+/**
+ * Waits until fonts and images have settled and the caller's own signal has
+ * fired, then prints the page as it stands. Returns the PDF with its page count
+ * and the images that never loaded, so a caller can refuse a half-painted sheet.
+ */
+export async function printPage(page: PageLike, options: PrintOptions = {}): Promise<PrintResult> {
+  const { ready } = options;
+  if (typeof ready === 'string') {
+    await page.waitForSelector(ready, { timeout: options.readyTimeout ?? 60_000 });
+  } else if (ready) {
+    await ready(page);
+  }
+  await page.evaluate(() => document.fonts.ready.then(() => undefined));
+  if (options.settle) await page.waitForTimeout(options.settle);
+  const brokenImages = await page.evaluate(() =>
+    [...document.images].filter((img) => !img.complete || img.naturalWidth === 0).map((img) => img.src),
+  );
+  const { size } = options;
+  const pdf = await page.pdf({
+    path: options.path,
+    printBackground: true,
+    ...(size
+      ? { width: `${size.width}px`, height: `${size.height}px` }
+      : { preferCSSPageSize: true }),
+    pageRanges: options.pageRanges,
+  });
+  return { pdf, pages: countPdfPages(pdf), brokenImages };
+}
+
+export interface PrintNavigation extends PrintOptions {
+  /** The load condition for the navigation. Default `load`. */
+  waitUntil?: WaitUntil;
+  /** Called with the navigation response; throw to refuse to print an error page. */
+  check?: (response: ResponseLike | null, page: PageLike) => void;
+}
+
+/** Opens a URL in the page and prints it. The caller owns the page and any routing on it. */
+export async function printUrl(
+  page: PageLike,
+  url: string,
+  options: PrintNavigation = {},
+): Promise<PrintResult> {
+  const response = await page.goto(url, { waitUntil: options.waitUntil ?? 'load' });
+  options.check?.(response, page);
+  return printPage(page, options);
+}
+
+/** Loads HTML into the page and prints it. */
+export async function printHtml(
+  page: PageLike,
+  html: string,
+  options: PrintNavigation = {},
+): Promise<PrintResult> {
+  await page.setContent(html, { waitUntil: options.waitUntil ?? 'load' });
+  return printPage(page, options);
+}
+
+export interface ImagesToPdfOptions {
+  /** The size of every page, in CSS pixels. Each image is drawn at exactly this size. */
+  size: Size;
+  /** The ground behind the images. */
+  background?: string;
+}
+
+/**
+ * Lays PNGs out one per page and prints that, nothing else.
+ *
+ * Printing the original document would run it through Chromium's print
+ * pipeline, which re-rasterises effects instead of compositing them: a blurred
+ * backdrop lost 47% of its chroma that way. Handing the pipeline flat bitmaps
+ * removes the whole class of drift, so the PDF shows what the PNG shows.
+ *
+ * Each image is a file path or the bytes themselves.
+ */
+export async function imagesToPdf(
+  page: PageLike,
+  images: Array<string | Uint8Array>,
+  options: ImagesToPdfOptions,
+): Promise<Uint8Array> {
+  if (images.length === 0) throw new Error('imagesToPdf needs at least one image.');
+  const dataUrls = await Promise.all(
+    images.map(async (image) => {
+      const bytes = typeof image === 'string' ? await readFile(image) : image;
+      return `data:image/png;base64,${Buffer.from(bytes).toString('base64')}`;
+    }),
+  );
+  const { pdf } = await printHtml(page, imagePagesHtml(dataUrls, options.size, options.background), {
+    size: options.size,
+    pageRanges: `1-${images.length}`,
+  });
+  return pdf;
+}

package/src/slides/export/types.ts

@@ -0,0 +1,48 @@
+// The slice of a Playwright page the export helpers touch, declared here so the
+// package takes no dependency on Playwright. Playwright's own Page, Locator and
+// Browser satisfy these as they are, whichever version the caller has installed.
+
+export interface Size {
+  width: number;
+  height: number;
+}
+
+export type WaitUntil = 'load' | 'domcontentloaded' | 'networkidle';
+
+export interface ResponseLike {
+  ok(): boolean;
+  status(): number;
+}
+
+export interface LocatorLike {
+  first(): LocatorLike;
+  nth(index: number): LocatorLike;
+  count(): Promise<number>;
+  waitFor(options?: { state?: 'visible'; timeout?: number }): Promise<void>;
+  screenshot(options?: { path?: string; type?: 'png' }): Promise<Uint8Array>;
+}
+
+export interface PageLike {
+  goto(url: string, options?: { waitUntil?: WaitUntil; timeout?: number }): Promise<ResponseLike | null>;
+  setContent(html: string, options?: { waitUntil?: WaitUntil; timeout?: number }): Promise<void>;
+  addStyleTag(options: { content: string }): Promise<unknown>;
+  evaluate<R>(pageFunction: () => R | Promise<R>): Promise<R>;
+  waitForTimeout(ms: number): Promise<void>;
+  waitForSelector(selector: string, options?: { timeout?: number }): Promise<unknown>;
+  locator(selector: string): LocatorLike;
+  screenshot(options?: { type?: 'png'; fullPage?: boolean }): Promise<Uint8Array>;
+  pdf(options: {
+    path?: string;
+    width?: string;
+    height?: string;
+    printBackground?: boolean;
+    preferCSSPageSize?: boolean;
+    pageRanges?: string;
+  }): Promise<Uint8Array>;
+  url(): string;
+  close(): Promise<void>;
+}
+
+export interface BrowserLike {
+  newPage(options?: { viewport?: Size; deviceScaleFactor?: number }): Promise<PageLike>;
+}

package/src/slides/index.ts

@@ -0,0 +1,19 @@
+export { default as Deck } from './Deck.svelte';
+export { default as Slide } from './Slide.svelte';
+export { default as Fragment } from './Fragment.svelte';
+export { default as Presenter } from './Presenter.svelte';
+export { DeckController } from './deck-controller.svelte.js';
+export type { SlideEntry, Source } from './deck-controller.svelte.js';
+export { defaultLabels } from './labels.js';
+export type { DeckLabels } from './labels.js';
+export type { Position } from './navigation.js';
+export type {
+  BridgeOptions,
+  Canvas,
+  DeckTheme,
+  DeckTransition,
+  SlideAlign,
+  SlideNotes,
+  UrlSync,
+} from './types.js';
+export { DEFAULT_CANVAS } from './types.js';