@heyramzi/ui 1.54.1 → 2.0.0

package/src/slides/Presenter.svelte

@@ -0,0 +1,292 @@
+<script lang="ts">
+  import { untrack } from 'svelte';
+  import Deck from './Deck.svelte';
+  import type { DeckController } from './deck-controller.svelte.js';
+  import { resolveLabels } from './labels.js';
+  import { DEFAULT_CANVAS, type DeckProps } from './types.js';
+
+  interface Props
+    extends Pick<
+      DeckProps,
+      'id' | 'title' | 'locale' | 'canvas' | 'theme' | 'transition' | 'slides' | 'registry' | 'labels' | 'style' | 'children'
+    > {
+    /** The channel name the audience deck uses as its `sync`. */
+    sync: string;
+  }
+
+  let { sync, id, title, locale, canvas = DEFAULT_CANVAS, theme = 'ink', transition, slides, registry, labels: overrides, style, children }: Props =
+    $props();
+
+  const labels = $derived(resolveLabels(overrides));
+
+  let index = $state(0);
+  let step = $state(0);
+  let now = $state<DeckController>();
+
+  const upcoming = $derived(now?.upcoming ?? null);
+  const notes = $derived(now?.current?.notes);
+  const steps = $derived(now?.current?.steps ?? 0);
+
+  let elapsed = $state(0);
+  let running = $state(true);
+  $effect(() => {
+    if (!running) return;
+    const base = untrack(() => elapsed);
+    const start = Date.now();
+    const tick = setInterval(() => (elapsed = base + Math.round((Date.now() - start) / 1000)), 250);
+    return () => clearInterval(tick);
+  });
+
+  const clock = $derived.by(() => {
+    const [h, m, s] = [Math.floor(elapsed / 3600), Math.floor(elapsed / 60) % 60, elapsed % 60];
+    const pad = (n: number) => String(n).padStart(2, '0');
+    return h ? `${h}:${pad(m)}:${pad(s)}` : `${pad(m)}:${pad(s)}`;
+  });
+
+  function onkeydown(event: KeyboardEvent) {
+    if (event.key === 't' && !event.metaKey && !event.ctrlKey && !event.altKey) running = !running;
+  }
+</script>
+
+<svelte:window {onkeydown} />
+<svelte:head>
+  <title>{title ?? labels.deck}</title>
+</svelte:head>
+
+<div class="presenter deck-surface deck--{theme}" lang={locale} style:--ratio={canvas.w / canvas.h} {style}>
+  <header class="presenter__bar">
+    <h1 class="presenter__title">{title ?? labels.deck}</h1>
+    {#if now}
+      <span class="presenter__where">
+        {labels.slide(now.ordinal.n, now.ordinal.of)}{#if steps > 0}<span class="presenter__steps">{now.position.step}/{steps}</span>{/if}
+      </span>
+    {/if}
+    <div class="presenter__timer" role="timer" aria-label={labels.timer}>
+      <span class="presenter__clock">{clock}</span>
+      <button type="button" class="presenter__button" onclick={() => (running = !running)}>
+        {running ? labels.pauseTimer : labels.startTimer}
+      </button>
+      <button type="button" class="presenter__button" onclick={() => (elapsed = 0)}>{labels.resetTimer}</button>
+    </div>
+  </header>
+
+  <main class="presenter__main">
+    <section class="presenter__now" aria-label={labels.current}>
+      <div class="presenter__frame" style:aspect-ratio="{canvas.w} / {canvas.h}">
+        <Deck
+          bind:index
+          bind:step
+          bind:controller={now}
+          {sync}
+          {id}
+          {title}
+          {locale}
+          {canvas}
+          {theme}
+          {transition}
+          {slides}
+          {registry}
+          {labels}
+          {style}
+          controls={false}
+        >
+          {@render children?.()}
+        </Deck>
+      </div>
+    </section>
+
+    <aside class="presenter__side">
+      <section aria-label={labels.upcoming}>
+        <h2 class="presenter__heading">{labels.upcoming}</h2>
+        {#if upcoming !== null}
+          <div class="presenter__frame presenter__frame--next" style:aspect-ratio="{canvas.w} / {canvas.h}" inert>
+            <Deck
+              index={upcoming}
+              step={Number.MAX_SAFE_INTEGER}
+              {id}
+              {canvas}
+              {theme}
+              {slides}
+              {registry}
+              {labels}
+              {style}
+              transition="none"
+              controls={false}
+              progress={false}
+              keyboard={false}
+            >
+              {@render children?.()}
+            </Deck>
+          </div>
+        {:else}
+          <p class="presenter__empty">{labels.endOfDeck}</p>
+        {/if}
+      </section>
+
+      <section class="presenter__notes" aria-label={labels.notes}>
+        <h2 class="presenter__heading">{labels.notes}</h2>
+        <div class="presenter__notes-body">
+          {#if typeof notes === 'string'}
+            <p>{notes}</p>
+          {:else if notes}
+            {@render notes()}
+          {:else}
+            <p class="presenter__empty">{labels.noNotes}</p>
+          {/if}
+        </div>
+      </section>
+    </aside>
+  </main>
+</div>
+
+<style>
+  .presenter {
+    display: grid;
+    grid-template-rows: auto minmax(0, 1fr);
+    height: 100dvh;
+    color: var(--deck-fg);
+    background: var(--deck-bg);
+    font-family: var(--deck-font);
+  }
+
+  .presenter__bar {
+    display: flex;
+    flex-wrap: wrap;
+    align-items: center;
+    gap: 8px 20px;
+    padding: 12px 20px;
+    border-bottom: 1px solid var(--deck-line);
+  }
+  .presenter__title {
+    flex: 1;
+    min-width: 0;
+    margin: 0;
+    overflow: hidden;
+    font: 600 15px/1.2 var(--deck-font);
+    text-overflow: ellipsis;
+    white-space: nowrap;
+  }
+  .presenter__where {
+    display: flex;
+    align-items: center;
+    gap: 10px;
+    font: 500 14px/1 var(--deck-font);
+    color: var(--deck-muted);
+  }
+  .presenter__steps {
+    padding: 3px 7px;
+    font-size: 12px;
+    font-variant-numeric: tabular-nums;
+    color: var(--deck-on-accent);
+    background: var(--deck-accent);
+    border-radius: 6px;
+  }
+  .presenter__timer {
+    display: flex;
+    align-items: center;
+    gap: 8px;
+  }
+  .presenter__clock {
+    min-width: 5ch;
+    margin-right: 4px;
+    font: 700 28px/1 var(--deck-font-display);
+    font-variant-numeric: tabular-nums;
+    letter-spacing: -0.02em;
+  }
+  .presenter__button {
+    min-height: 32px;
+    padding: 0 12px;
+    font: 500 13px/1 var(--deck-font);
+    color: var(--deck-fg);
+    background: var(--deck-surface);
+    border: 1px solid var(--deck-line);
+    border-radius: 8px;
+    cursor: pointer;
+    transition: background-color var(--deck-t-quick) var(--deck-ease);
+  }
+  @media (hover: hover) and (pointer: fine) {
+    .presenter__button:hover {
+      background: var(--deck-line);
+    }
+  }
+  .presenter__button:focus-visible {
+    outline: 2px solid var(--deck-accent);
+    outline-offset: 2px;
+  }
+
+  .presenter__main {
+    display: grid;
+    grid-template-columns: minmax(0, 1.7fr) minmax(0, 1fr);
+    gap: 20px;
+    min-height: 0;
+    padding: 20px;
+  }
+  .presenter__now {
+    display: grid;
+    place-items: center;
+    min-height: 0;
+    container-type: size;
+  }
+  .presenter__frame {
+    overflow: hidden;
+    border-radius: 12px;
+    box-shadow: 0 0 0 1px var(--deck-line);
+  }
+  .presenter__now .presenter__frame {
+    width: min(100cqw, calc(100cqh * var(--ratio)));
+  }
+  .presenter__frame--next {
+    width: 100%;
+  }
+
+  .presenter__side {
+    display: grid;
+    grid-template-rows: auto minmax(0, 1fr);
+    gap: 20px;
+    min-height: 0;
+  }
+  .presenter__heading {
+    margin: 0 0 8px;
+    font: 600 12px/1 var(--deck-font);
+    letter-spacing: 0.02em;
+    color: var(--deck-muted);
+  }
+  .presenter__notes {
+    display: flex;
+    flex-direction: column;
+    min-height: 0;
+  }
+  .presenter__notes-body {
+    flex: 1;
+    min-height: 0;
+    padding-right: 4px;
+    overflow-y: auto;
+    font-size: clamp(18px, 1.5vw, 26px);
+    line-height: 1.5;
+    white-space: pre-line;
+    text-wrap: pretty;
+  }
+  .presenter__notes-body p {
+    margin: 0;
+  }
+  .presenter__empty {
+    margin: 0;
+    color: var(--deck-muted);
+  }
+
+  @media (max-width: 860px) {
+    .presenter {
+      height: auto;
+      min-height: 100dvh;
+    }
+    .presenter__main {
+      grid-template-columns: minmax(0, 1fr);
+    }
+    .presenter__now {
+      container-type: inline-size;
+    }
+    .presenter__now .presenter__frame {
+      width: 100%;
+    }
+  }
+</style>

package/src/slides/README.md

@@ -0,0 +1,89 @@
+# @heyramzi/ui/slides
+
+Slide decks for Svelte 5. Slides lay out on a fixed canvas (960 by 540 px by default) and the whole canvas scales to fit its container. Reveals, an overview grid, a presenter view, print and data-driven slide types are in the box. Theming is CSS variables only, so the core has no brand.
+
+```svelte
+<script>
+  import { Deck, Slide, Fragment } from '@heyramzi/ui/slides';
+</script>
+
+<Deck title="Q3 review" urlSync presenter="/present">
+  <Slide notes="Open on the number.">
+    <h1 class="deck-display">Revenue is up</h1>
+  </Slide>
+  <Slide>
+    <Fragment step={1}>First point</Fragment>
+    <Fragment step={2}>Second point</Fragment>
+  </Slide>
+</Deck>
+```
+
+Keys: arrows, Space (Shift+Space back), PageUp/PageDown, Home/End, `O` overview, `F` fullscreen, `P` presenter. Swipe works on touch. With several decks on a page, only the sole, focused or hovered deck answers keys.
+
+## Deck props
+
+| Prop | Default | |
+| --- | --- | --- |
+| `index`, `step` | 0 | Bindable. `index` counts hidden slides. |
+| `canvas` | `{ w: 960, h: 540 }` | Design size in px. |
+| `theme` | `'ink'` | `ink`, `paper` or `auto`. |
+| `transition` | `'fade'` | `fade`, `slide`, `zoom`, `morph` (View Transitions, elements with a shared `data-morph` name) or `none`. |
+| `keyboard` | `true` | Turn off when a slide holds a form. |
+| `fragments` | `true` | Off shows every step at once. |
+| `loop`, `progress`, `controls` | `false`, `true`, `true` | |
+| `urlSync` | `false` | Keeps `?s=` (1 based). Pass `{ param, write }` to rename it or write the URL yourself, for example with SvelteKit's `replaceState`. |
+| `bridge` | `false` | postMessage for iframes. In: `{type:'deck:nav', delta}`, `{type:'deck:go', index, step?}`. Out: `{type:'deck:change', index, step, total}`. Same origin unless `{ origin }`. |
+| `sync` | | Name that mirrors the deck across windows over BroadcastChannel. |
+| `presenter` | | URL of the presenter view. Adds a button and the `p` key. |
+| `labels` | | Partial `DeckLabels` to translate every string. |
+| `controller` | | Bindable `DeckController`: `next()`, `prev()`, `go(i, step)`, `toggleOverview()`, `position`, `ordinal`. |
+| `id`, `title`, `locale`, `onchange`, `class`, `style` | | |
+
+`Slide`: `notes` (string or snippet), `hidden`, `label`, `align` (`center`, `start`, `bare`). `Fragment`: `step`, `reveal` (`rise`, `fade`, `scale`), `as`. Fragments that share a step stagger. Authored type classes: `deck-display`, `deck-title`, `deck-heading`, `deck-lead`, `deck-body`, `deck-caption`, `deck-label`, `deck-accent`.
+
+## Theming
+
+Set variables on `.deck`: `--deck-bg`, `--deck-fg`, `--deck-accent`, `--deck-on-accent`, `--deck-font`, `--deck-font-display`, `--deck-pad`, `--deck-text-*` (design px) and the timing tokens `--deck-t-slide`, `--deck-t-morph`, `--deck-stagger`, `--deck-ease`. They default to the `@heyramzi/ui` motion tokens when present. Motion is transform and opacity only and stops under `prefers-reduced-motion`.
+
+## Data-driven decks
+
+```ts
+import { defineRegistry, defineSlideType } from '@heyramzi/ui/slides/model';
+
+const cover = defineSlideType({ type: 'cover', label: 'Cover', layout: CoverLayout });
+const registry = defineRegistry([cover]);
+```
+
+```svelte
+<Deck {...deck} {registry} />
+```
+
+`deck` is a `DeckData` (`id`, `title`, `locale?`, `canvas`, `theme?`, `slides: SlideInstance[]`). A slide is `{ id, type, content, notes?, hidden? }`. Validate content where it comes in, with the schema you already use.
+
+## Presenter view
+
+Mount it on its own route and give the audience deck the same `sync` name:
+
+```svelte
+<Presenter sync="q3" title="Q3 review"><Slides /></Presenter>
+```
+
+It shows the current slide, the next one, notes and a timer, in step with the audience window. Pass the same children or `slides` and `registry` as the audience deck.
+
+## Print
+
+Print gives one canvas per page, sized by an injected `@page` rule (960 by 540 px is 10 by 5.625 in), with every fragment shown and the chrome hidden. Hidden slides are skipped.
+
+## Export
+
+`@heyramzi/ui/slides/export` is Node only. It drives the Playwright browser and pages you pass in, and the `ffmpeg` on your path, so the package depends on neither.
+
+- `launchChromium(chromium)`: headless Chromium, falling back to installed Chrome.
+- `capturePage` and `captureEach`: PNGs of a page or each slide at a canvas size and device scale.
+- `printUrl`, `printHtml` and `printPage`: a PDF at the page size, after fonts, images and an optional `ready` selector settle.
+- `imagesToPdf`: one page per PNG, for colour that has to match the PNGs exactly.
+- `renderLoop` and `encodeFrames`: an mp4 from captured frames.
+
+## Accessibility
+
+The deck is a labelled region, inactive slides are `inert`, the progress bar has `role="progressbar"`, and a live region announces "Slide 3 of 12".

package/src/slides/Slide.svelte

@@ -0,0 +1,179 @@
+<script lang="ts">
+  import { getContext, setContext, type Snippet } from 'svelte';
+  import type { DeckController, SlideEntry } from './deck-controller.svelte.js';
+  import { DECK_KEY, SLIDE_KEY, type SlideAlign, type SlideContext, type SlideNotes } from './types.js';
+
+  interface Props {
+    /** Accessible name, read after "Slide 3 of 12". */
+    label?: string;
+    /** Speaker notes for the presenter view. */
+    notes?: SlideNotes;
+    /** Skipped by paging and left out of the overview and print. */
+    hidden?: boolean;
+    /** `center` (default), `start`, or `bare` to lay the canvas out yourself. */
+    align?: SlideAlign;
+    class?: string;
+    style?: string;
+    children?: Snippet;
+  };
+
+  let { label, notes, hidden = false, align = 'center', class: className, style, children }: Props = $props();
+
+  const deck = getContext<DeckController | undefined>(DECK_KEY);
+  if (!deck) throw new Error('<Slide> must be rendered inside <Deck>.');
+
+  let el = $state<HTMLElement | null>(null);
+  let steps = $state(0);
+  /* Fragments per step, so one leaving doesn't drop a step another still asks for. */
+  const counts = new Map<number, number>();
+
+  const entry: SlideEntry = {
+    id: Symbol('slide'),
+    get steps() {
+      return steps;
+    },
+    get hidden() {
+      return hidden;
+    },
+    get label() {
+      return label;
+    },
+    get notes() {
+      return notes;
+    },
+    get el() {
+      return el;
+    },
+  };
+
+  $effect(() => deck.register(entry));
+
+  const index = $derived(deck.entries.indexOf(entry));
+  const active = $derived(index >= 0 && deck.position.index === index);
+  const box = $derived(deck.boxOf(index));
+  const order = $derived(Math.max(0, deck.visible.indexOf(index)));
+
+  /* A slide that is leaving keeps the step it left at, so its fragments don't vanish mid-fade. */
+  let held = $state(0);
+  $effect.pre(() => {
+    if (active) held = deck.position.step;
+  });
+
+  const recount = () => (steps = counts.size ? Math.max(...counts.keys()) : 0);
+
+  setContext<SlideContext>(SLIDE_KEY, {
+    shown: (step) => deck.revealAll || step <= (active ? deck.position.step : held),
+    join(step) {
+      const order = counts.get(step) ?? 0;
+      counts.set(step, order + 1);
+      recount();
+      return {
+        order,
+        leave() {
+          const left = (counts.get(step) ?? 1) - 1;
+          if (left <= 0) counts.delete(step);
+          else counts.set(step, left);
+          recount();
+        },
+      };
+    },
+  });
+
+  /* A View Transition needs one element per name, so only the active slide holds its morph names. */
+  $effect(() => {
+    const names = el?.querySelectorAll<HTMLElement>('[data-morph]') ?? [];
+    for (const node of names) node.style.viewTransitionName = active ? (node.dataset.morph ?? '') : '';
+  });
+
+  const where = $derived(deck.labels.slide(order + 1, deck.visible.length));
+  const name = $derived(label ? `${where}: ${label}` : where);
+</script>
+
+<section
+  bind:this={el}
+  class={['slide', className]}
+  style:--slide-w="{deck.canvas.w}px"
+  style:--slide-h="{deck.canvas.h}px"
+  style:--slide-scale={box?.scale}
+  style:--i={order}
+  style:transform={box ? `translate3d(${box.x}px, ${box.y}px, 0) scale(${box.scale})` : undefined}
+  {style}
+  {hidden}
+  data-active={active}
+  role="group"
+  aria-roledescription={deck.labels.slideRole}
+  aria-label={name}
+  aria-hidden={!active}
+  inert={!active || deck.overview}
+>
+  <div class="slide__surface" data-align={align}>
+    {@render children?.()}
+  </div>
+</section>
+
+<style>
+  /* The box is a full canvas, moved and scaled from its top-left. */
+  .slide {
+    position: absolute;
+    top: 0;
+    left: 0;
+    z-index: 1;
+    width: var(--slide-w);
+    height: var(--slide-h);
+    transform-origin: 0 0;
+    visibility: hidden;
+    /* The old slide stays drawn for the length of the enter animation. */
+    transition: visibility 0s linear var(--deck-t-slide);
+  }
+  .slide[hidden] {
+    display: none;
+  }
+  .slide[data-active='true'] {
+    z-index: 2;
+    visibility: visible;
+    transition-delay: 0s;
+  }
+
+  /* The overview shows every slide. They all leave the stack at once and settle in turn, later ones slower. */
+  :global(.deck[data-view='overview']) .slide {
+    visibility: visible;
+  }
+  :global(.deck[data-morphing]) .slide {
+    transition:
+      visibility 0s linear calc(var(--deck-t-morph) + 10 * var(--deck-stagger)),
+      transform calc(var(--deck-t-morph) + min(var(--i), 10) * var(--deck-stagger)) var(--deck-ease);
+  }
+  /* Opening shows the slides at once, so only closing waits before hiding them. */
+  :global(.deck[data-morphing][data-view='overview']) .slide {
+    transition-delay: 0s;
+  }
+
+  .slide__surface {
+    position: relative;
+    box-sizing: border-box;
+    width: 100%;
+    height: 100%;
+    overflow: hidden;
+    color: var(--deck-fg);
+    background: var(--deck-bg);
+    font-family: var(--deck-font);
+    animation: var(--deck-t-slide) var(--deck-ease) backwards;
+  }
+  :global(.deck[data-view='overview']) .slide__surface {
+    /* Design px, so divide by the scale to get the same corner on every thumbnail. */
+    border-radius: calc(10px / var(--slide-scale, 1));
+    box-shadow: 0 0 0 calc(1px / var(--slide-scale, 1)) var(--deck-line);
+  }
+
+  .slide__surface[data-align='center'],
+  .slide__surface[data-align='start'] {
+    display: flex;
+    flex-direction: column;
+    justify-content: center;
+    padding: var(--deck-pad);
+  }
+  .slide__surface[data-align='center'] {
+    align-items: center;
+    text-align: center;
+  }
+</style>

package/src/slides/SlideList.svelte

@@ -0,0 +1,19 @@
+<script lang="ts">
+  import Slide from './Slide.svelte';
+  import type { SlideInstance, SlideRegistry } from './model.js';
+
+  interface Props { slides: SlideInstance[]; registry: SlideRegistry; unknownLabel: (type: string) => string };
+
+  let { slides, registry, unknownLabel }: Props = $props();
+</script>
+
+{#each slides as slide (slide.id)}
+  {@const definition = registry[slide.type]}
+  <Slide label={definition?.label} notes={slide.notes} hidden={slide.hidden} align="bare">
+    {#if definition}
+      <definition.layout content={slide.content} {slide} />
+    {:else}
+      <p class="deck-body" style:padding="var(--deck-pad)">{unknownLabel(slide.type)}</p>
+    {/if}
+  </Slide>
+{/each}

package/src/slides/ambient.d.ts

@@ -0,0 +1 @@
+declare module '*.css';

package/src/slides/bridges.ts

@@ -0,0 +1,69 @@
+/* The ways a deck talks to the outside: its URL, a parent frame, another window. Each returns a cleanup. */
+
+import type { DeckController } from './deck-controller.svelte.js';
+import { parseSlideParam } from './navigation.js';
+import type { BridgeOptions, UrlSync } from './types.js';
+
+/** Reads `?s=` once, then keeps it at the current slide. The write is a replace, so Back skips it. */
+export function attachUrlSync(deck: DeckController, { param = 's', write }: UrlSync = {}): () => void {
+  const initial = parseSlideParam(new URL(location.href).searchParams.get(param), deck.entries.length);
+  if (initial !== null) deck.go(initial, 0, 'remote');
+  return deck.listen(({ index }) => {
+    const url = new URL(location.href);
+    url.searchParams.set(param, String(index + 1));
+    if (write) write(url);
+    else history.replaceState(history.state, '', url);
+  });
+}
+
+/**
+ * Lets a host page drive a deck in an iframe. In: `{type:'deck:nav', delta}` and
+ * `{type:'deck:go', index, step?}`. Out to the parent: `{type:'deck:change', index, step, total}`.
+ */
+export function attachBridge(deck: DeckController, { origin = location.origin }: BridgeOptions = {}): () => void {
+  const onMessage = (event: MessageEvent) => {
+    if (origin !== '*' && event.origin !== origin) return;
+    const data = event.data;
+    if (data?.type === 'deck:nav') {
+      if (data.delta === -1) deck.prev();
+      else if (data.delta === 1) deck.next();
+    } else if (data?.type === 'deck:go' && Number.isInteger(data.index)) {
+      deck.go(data.index, Number.isInteger(data.step) ? data.step : 0, 'remote');
+    }
+  };
+  window.addEventListener('message', onMessage);
+  const stop = deck.listen(({ index, step }, source) => {
+    if (source === 'local' && window.parent !== window) {
+      window.parent.postMessage({ type: 'deck:change', index, step, total: deck.visible.length }, origin);
+    }
+  });
+  return () => {
+    window.removeEventListener('message', onMessage);
+    stop();
+  };
+}
+
+type ChannelMessage = { type: 'state'; from: string; index: number; step: number } | { type: 'hello'; from: string };
+
+/** Mirrors the deck across windows of one origin: the audience screen and a presenter view. */
+export function attachChannel(deck: DeckController, name: string): () => void {
+  if (typeof BroadcastChannel === 'undefined') return () => {};
+  const channel = new BroadcastChannel(`heyramzi-slides:${name}`);
+  const self = crypto.randomUUID();
+  const send = (message: ChannelMessage) => channel.postMessage(message);
+  const state = ({ index, step } = deck.position): ChannelMessage => ({ type: 'state', from: self, index, step });
+
+  channel.onmessage = ({ data }: MessageEvent<ChannelMessage>) => {
+    if (data.from === self) return;
+    if (data.type === 'hello') send(state());
+    else deck.go(data.index, data.step, 'remote');
+  };
+  const stop = deck.listen((position, source) => {
+    if (source === 'local') send(state(position));
+  });
+  send({ type: 'hello', from: self });
+  return () => {
+    stop();
+    channel.close();
+  };
+}