@heyramzi/ui 1.54.1 → 2.0.0

package/src/slides/labels.ts

@@ -0,0 +1,48 @@
+/** Every string the package renders. Pass a partial `labels` prop to translate. */
+export type DeckLabels = {
+  deck: string;
+  deckRole: string;
+  slideRole: string;
+  previous: string;
+  next: string;
+  fullscreen: string;
+  overview: string;
+  presenter: string;
+  progress: string;
+  slide: (n: number, of: number) => string;
+  upcoming: string;
+  current: string;
+  notes: string;
+  noNotes: string;
+  endOfDeck: string;
+  timer: string;
+  startTimer: string;
+  pauseTimer: string;
+  resetTimer: string;
+  unknownType: (type: string) => string;
+};
+
+export const defaultLabels: DeckLabels = {
+  deck: 'Slide deck',
+  deckRole: 'presentation',
+  slideRole: 'slide',
+  previous: 'Previous slide',
+  next: 'Next slide',
+  fullscreen: 'Toggle fullscreen',
+  overview: 'Slide overview',
+  presenter: 'Open presenter view',
+  progress: 'Deck progress',
+  slide: (n, of) => `Slide ${n} of ${of}`,
+  upcoming: 'Next',
+  current: 'Now',
+  notes: 'Notes',
+  noNotes: 'No notes for this slide.',
+  endOfDeck: 'End of deck.',
+  timer: 'Elapsed time',
+  startTimer: 'Start timer',
+  pauseTimer: 'Pause timer',
+  resetTimer: 'Reset timer',
+  unknownType: (type) => `Unknown slide type: ${type}`,
+};
+
+export const resolveLabels = (labels?: Partial<DeckLabels>): DeckLabels => ({ ...defaultLabels, ...labels });

package/src/slides/layout.ts

@@ -0,0 +1,51 @@
+/* Where a slide sits inside the stage: centred to fit, or in the overview grid. */
+
+import type { Canvas } from './types.js';
+
+export type Size = { w: number; h: number };
+
+/** A slide's place: its top-left corner in stage px and its scale. */
+export type Box = { x: number; y: number; scale: number };
+
+export type Grid = { cols: number; boxes: Box[] };
+
+export function fitBox(view: Size, canvas: Canvas): Box {
+  const scale = Math.max(0, Math.min(view.w / canvas.w, view.h / canvas.h));
+  return { x: (view.w - canvas.w * scale) / 2, y: (view.h - canvas.h * scale) / 2, scale };
+}
+
+/** The scale at which `cols` columns of `count` canvases fit the view. */
+function scaleFor(cols: number, count: number, view: Size, canvas: Canvas, pad: number, gap: number): number {
+  const rows = Math.ceil(count / cols);
+  const byWidth = (view.w - 2 * pad - (cols - 1) * gap) / cols / canvas.w;
+  const byHeight = (view.h - 2 * pad - (rows - 1) * gap) / rows / canvas.h;
+  return Math.min(byWidth, byHeight);
+}
+
+/** Lays `count` canvases in the roomiest grid that shows them all, centred. */
+export function gridBoxes(view: Size, canvas: Canvas, count: number): Grid {
+  if (count === 0 || view.w <= 0 || view.h <= 0) return { cols: 1, boxes: [] };
+  const pad = Math.min(56, Math.max(16, view.w * 0.04));
+  /* The gap holds the slide number that hangs below each cell. */
+  const gap = Math.max(26, pad * 0.6);
+
+  let cols = 1;
+  let scale = scaleFor(1, count, view, canvas, pad, gap);
+  for (let c = 2; c <= count; c++) {
+    const candidate = scaleFor(c, count, view, canvas, pad, gap);
+    if (candidate > scale) [cols, scale] = [c, candidate];
+  }
+
+  const cellW = canvas.w * scale;
+  const cellH = canvas.h * scale;
+  const rows = Math.ceil(count / cols);
+  const left = (view.w - (cols * cellW + (cols - 1) * gap)) / 2;
+  const top = (view.h - (rows * cellH + (rows - 1) * gap)) / 2;
+
+  const boxes = Array.from({ length: count }, (_, i) => ({
+    x: left + (i % cols) * (cellW + gap),
+    y: top + Math.floor(i / cols) * (cellH + gap),
+    scale,
+  }));
+  return { cols, boxes };
+}

package/src/slides/model.ts

@@ -0,0 +1,47 @@
+/* Data-driven decks: a deck is JSON, and a registry says how each slide type draws itself. */
+
+import type { Component } from 'svelte';
+import type { Canvas, DeckTheme } from './types.js';
+
+export type SlideInstance<Content = unknown> = {
+  id: string;
+  type: string;
+  content: Content;
+  notes?: string;
+  hidden?: boolean;
+};
+
+export type DeckData<Content = unknown> = {
+  id: string;
+  title: string;
+  locale?: string;
+  canvas: Canvas;
+  theme?: DeckTheme;
+  slides: SlideInstance<Content>[];
+};
+
+/** What a layout component receives. */
+export type SlideLayoutProps<Content> = { content: Content; slide: SlideInstance<Content> };
+
+export type SlideType<Content = any> = {
+  type: string;
+  /** Human name, used as the slide's accessible label and in editors. */
+  label: string;
+  layout: Component<SlideLayoutProps<Content>>;
+};
+
+export type SlideRegistry = Readonly<Record<string, SlideType>>;
+
+/** Identity function that fixes `Content` from the layout. */
+export const defineSlideType = <Content>(definition: SlideType<Content>): SlideType<Content> => definition;
+
+/** Keys the types by their `type`. Two with the same name is a mistake worth failing on. */
+export function defineRegistry(types: readonly SlideType[]): SlideRegistry {
+  const registry: Record<string, SlideType> = {};
+  for (const slide of types) {
+    if (slide.type in registry) throw new Error(`Slide type "${slide.type}" is registered twice.`);
+    registry[slide.type] = slide;
+  }
+  return registry;
+}
+

package/src/slides/navigation.ts

@@ -0,0 +1,100 @@
+/* Paging rules as pure functions, so the controller stays a thin reactive shell. */
+
+export type Position = { index: number; step: number };
+
+/** What paging needs to know about a slide. `steps` is its highest fragment step. */
+export type SlideState = { steps: number; hidden: boolean };
+
+export type KeyAction =
+  | 'next'
+  | 'prev'
+  | 'up'
+  | 'down'
+  | 'first'
+  | 'last'
+  | 'select'
+  | 'overview'
+  | 'close'
+  | 'fullscreen'
+  | 'presenter';
+
+export const visibleIndexes = (slides: readonly SlideState[]): number[] =>
+  slides.flatMap((slide, index) => (slide.hidden ? [] : [index]));
+
+const clamp = (value: number, min: number, max: number) => Math.min(max, Math.max(min, value));
+
+/** Snaps a position onto a visible slide and a real step. Empty decks stay at 0, 0. */
+export function settle(slides: readonly SlideState[], position: Position): Position {
+  const visible = visibleIndexes(slides);
+  if (visible.length === 0) return { index: 0, step: 0 };
+  const index = visible.find((i) => i >= position.index) ?? visible[visible.length - 1];
+  return { index, step: clamp(position.step, 0, slides[index].steps) };
+}
+
+/** The position after one forward press, or null at the end of a deck that doesn't loop. */
+export function nextPosition(slides: readonly SlideState[], from: Position, loop = false): Position | null {
+  const visible = visibleIndexes(slides);
+  if (visible.length === 0) return null;
+  if (from.step < slides[from.index].steps) return { index: from.index, step: from.step + 1 };
+  const next = visible.find((i) => i > from.index);
+  if (next !== undefined) return { index: next, step: 0 };
+  return loop ? { index: visible[0], step: 0 } : null;
+}
+
+/** The position after one back press. Landing on an earlier slide shows it fully revealed. */
+export function prevPosition(slides: readonly SlideState[], from: Position, loop = false): Position | null {
+  const visible = visibleIndexes(slides);
+  if (visible.length === 0) return null;
+  if (from.step > 0) return { index: from.index, step: from.step - 1 };
+  const before = visible.filter((i) => i < from.index);
+  const index = before.length ? before[before.length - 1] : loop ? visible[visible.length - 1] : undefined;
+  return index === undefined ? null : { index, step: slides[index].steps };
+}
+
+/** Where slide `index` sits among the visible ones, 1 based, for "3 of 12". */
+export function ordinalOf(slides: readonly SlideState[], index: number): { n: number; of: number } {
+  const visible = visibleIndexes(slides);
+  return { n: Math.max(0, visible.indexOf(index)) + 1, of: visible.length };
+}
+
+/** How far through the deck a position is, 0 to 1. A slide's fragments split its own share. */
+export function progressOf(slides: readonly SlideState[], position: Position): number {
+  const visible = visibleIndexes(slides);
+  if (visible.length === 0) return 0;
+  const at = Math.max(0, visible.indexOf(position.index));
+  const steps = slides[position.index]?.steps ?? 0;
+  const share = steps > 0 ? (position.step + 1) / (steps + 1) : 1;
+  return (at + share) / visible.length;
+}
+
+/** Reads `?s=` as a zero based index. Anything that isn't a whole number in range is null. */
+export function parseSlideParam(raw: string | null | undefined, total: number): number | null {
+  if (!raw || !/^\d+$/.test(raw)) return null;
+  const index = Number(raw) - 1;
+  return index >= 0 && index < total ? index : null;
+}
+
+const KEYS: Record<string, KeyAction> = {
+  ArrowRight: 'next',
+  PageDown: 'next',
+  ArrowLeft: 'prev',
+  PageUp: 'prev',
+  ArrowUp: 'up',
+  ArrowDown: 'down',
+  Home: 'first',
+  End: 'last',
+  Enter: 'select',
+  Escape: 'close',
+  o: 'overview',
+  O: 'overview',
+  f: 'fullscreen',
+  F: 'fullscreen',
+  p: 'presenter',
+  P: 'presenter',
+};
+
+/** Maps a key to what the deck does with it. Space moves forward, Shift+Space back. */
+export function keyAction(key: string, shift = false): KeyAction | null {
+  if (key === ' ') return shift ? 'prev' : 'next';
+  return KEYS[key] ?? null;
+}

package/src/slides/theme.css

@@ -0,0 +1,205 @@
+/*
+ * Everything global to a deck: tokens, authored type, the enter keyframes and print.
+ * Components keep their own box mechanics in scoped styles. Sizes are design px,
+ * because the whole canvas scales, so a 28px heading is 28px on a 960px canvas at any zoom.
+ * Colours are flat hex: Chromium's PDF pipeline shifts oklch.
+ */
+
+.deck,
+.deck-surface {
+  color-scheme: dark;
+
+  --deck-bg: light-dark(#f2f1ec, #0e1014);
+  --deck-fg: light-dark(#15171b, #f3f1ea);
+  --deck-accent: light-dark(#3e6b00, #c8f15a);
+  --deck-on-accent: light-dark(#f6f6f0, #0e1014);
+  --deck-muted: color-mix(in srgb, var(--deck-fg) 66%, transparent);
+  --deck-line: color-mix(in srgb, var(--deck-fg) 14%, transparent);
+  --deck-surface: color-mix(in srgb, var(--deck-fg) 6%, transparent);
+  --deck-letterbox: color-mix(in srgb, var(--deck-bg) 86%, var(--deck-fg));
+
+  --deck-font: ui-sans-serif, system-ui, sans-serif;
+  --deck-font-display: var(--deck-font);
+
+  --deck-pad: 64px;
+  --deck-text-display: 76px;
+  --deck-text-title: 46px;
+  --deck-text-heading: 28px;
+  --deck-text-lead: 22px;
+  --deck-text-body: 17px;
+  --deck-text-caption: 13px;
+
+  --deck-t-slide: var(--duration-fast, 250ms);
+  --deck-t-morph: var(--duration-slow, 400ms);
+  --deck-t-quick: var(--duration-quick, 150ms);
+  --deck-stagger: var(--duration-stagger, 40ms);
+  --deck-ease: var(--ease-smooth-out, cubic-bezier(0.22, 1, 0.36, 1));
+  --deck-shift: var(--distance-medium, 12px);
+}
+.deck--paper {
+  color-scheme: light;
+}
+.deck--auto {
+  color-scheme: light dark;
+}
+
+/* Authored type. Slides use these classes. */
+.deck .deck-display,
+.deck .deck-title,
+.deck .deck-heading {
+  margin: 0;
+  font-family: var(--deck-font-display);
+  color: var(--deck-fg);
+  text-wrap: balance;
+}
+.deck .deck-display {
+  font-size: var(--deck-text-display);
+  font-weight: 800;
+  line-height: 1;
+  letter-spacing: -0.03em;
+}
+.deck .deck-title {
+  font-size: var(--deck-text-title);
+  font-weight: 700;
+  line-height: 1.04;
+  letter-spacing: -0.03em;
+}
+.deck .deck-heading {
+  font-size: var(--deck-text-heading);
+  font-weight: 650;
+  line-height: 1.15;
+  letter-spacing: -0.02em;
+}
+.deck .deck-lead,
+.deck .deck-body,
+.deck .deck-caption {
+  margin: 0;
+  color: var(--deck-muted);
+  text-wrap: pretty;
+}
+.deck .deck-lead {
+  font-size: var(--deck-text-lead);
+  line-height: 1.4;
+}
+.deck .deck-body {
+  font-size: var(--deck-text-body);
+  line-height: 1.5;
+}
+.deck .deck-caption {
+  font-size: var(--deck-text-caption);
+  line-height: 1.4;
+}
+.deck .deck-label {
+  margin: 0;
+  font-size: var(--deck-text-caption);
+  font-weight: 600;
+  letter-spacing: 0.01em;
+  color: var(--deck-accent);
+}
+.deck .deck-accent {
+  color: var(--deck-accent);
+}
+
+/* How a slide enters. The slide it replaces stays put underneath, so no frame shows the page behind. */
+@keyframes deck-fade {
+  from {
+    opacity: 0;
+    transform: translateY(var(--deck-shift));
+  }
+}
+@keyframes deck-slide {
+  from {
+    opacity: 0;
+    transform: translateX(calc(var(--deck-dir, 1) * 48px));
+  }
+}
+@keyframes deck-zoom {
+  from {
+    opacity: 0;
+    transform: scale(var(--scale-large, 0.96));
+  }
+}
+.deck[data-transition='fade'] .slide[data-active='true'] .slide__surface {
+  animation-name: deck-fade;
+}
+.deck[data-transition='slide'] .slide[data-active='true'] .slide__surface {
+  animation-name: deck-slide;
+}
+.deck[data-transition='zoom'] .slide[data-active='true'] .slide__surface {
+  animation-name: deck-zoom;
+}
+.deck[data-morphing] .slide__surface {
+  animation: none !important;
+}
+
+/* A morph runs on the whole page, so it gets the deck's timing while it plays. */
+html[data-deck-vt] ::view-transition-group(*) {
+  animation-duration: var(--duration-slow, 400ms);
+  animation-timing-function: var(--ease-smooth-out, cubic-bezier(0.22, 1, 0.36, 1));
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .deck .slide__surface {
+    animation: none !important;
+  }
+  .deck .slide {
+    transition-duration: 0s !important;
+    transition-delay: 0s !important;
+  }
+  html[data-deck-vt] ::view-transition-group(*) {
+    animation-duration: 0s;
+  }
+}
+
+/* Print: one canvas per page, every reveal shown, no chrome. The @page size comes from the Deck. */
+@media print {
+  .deck {
+    position: static !important;
+    display: block !important;
+    width: auto !important;
+    height: auto !important;
+    aspect-ratio: auto !important;
+    overflow: visible !important;
+    background: none !important;
+    -webkit-print-color-adjust: exact;
+    print-color-adjust: exact;
+  }
+  .deck .deck__stage {
+    position: static !important;
+    display: block !important;
+    height: auto !important;
+    overflow: visible !important;
+    background: none !important;
+  }
+  .deck .slide {
+    position: relative !important;
+    display: block !important;
+    visibility: visible !important;
+    width: var(--slide-w) !important;
+    height: var(--slide-h) !important;
+    overflow: hidden !important;
+    transform: none !important;
+    transition: none !important;
+    break-inside: avoid;
+    /* Chrome rounds the page a fraction of a px short of the canvas, which would add a blank last page. */
+    margin-bottom: -1px;
+  }
+  .deck .slide[hidden] {
+    display: none !important;
+  }
+  .deck .slide ~ .slide {
+    break-before: page;
+  }
+  .deck .slide__surface {
+    animation: none !important;
+    border-radius: 0 !important;
+  }
+  .deck .deck-fragment {
+    opacity: 1 !important;
+    transform: none !important;
+    transition: none !important;
+  }
+  .deck .deck__chrome {
+    display: none !important;
+  }
+}

package/src/slides/types.ts

@@ -0,0 +1,86 @@
+import type { Snippet } from 'svelte';
+import type { DeckController } from './deck-controller.svelte.js';
+import type { DeckLabels } from './labels.js';
+import type { SlideInstance, SlideRegistry } from './model.js';
+
+export const DECK_KEY = Symbol('heyramzi.deck');
+export const SLIDE_KEY = Symbol('heyramzi.slide');
+
+/** `ink` is the dark default, `paper` a light surface, `auto` follows the system. */
+export type DeckTheme = 'ink' | 'paper' | 'auto';
+
+/** How a slide enters. `morph` uses the View Transitions API and falls back to a cut. */
+export type DeckTransition = 'fade' | 'slide' | 'zoom' | 'morph' | 'none';
+
+/** The design size in px. Slides lay out inside it and the whole canvas scales to fit. */
+export type Canvas = { w: number; h: number };
+
+export const DEFAULT_CANVAS: Canvas = { w: 960, h: 540 };
+
+/** Speaker notes: plain text, or a snippet for rich markup. */
+export type SlideNotes = string | Snippet;
+
+/** How a Slide lays out its own content. `bare` leaves the whole canvas to the author. */
+export type SlideAlign = 'center' | 'start' | 'bare';
+
+/** Where a deck keeps `?s=`. `write` replaces the default `history.replaceState`, so SvelteKit apps can use its own. */
+export type UrlSync = { param?: string; write?: (url: URL) => void };
+
+/** `origin` guards incoming messages and defaults to this page's origin. `'*'` accepts any. */
+export type BridgeOptions = { origin?: string };
+
+/** What a Fragment sees of the slide around it. */
+export type SlideContext = {
+  shown: (step: number) => boolean;
+  join: (step: number) => { order: number; leave: () => void };
+};
+
+/** Everything a Deck takes. */
+export type DeckProps = {
+  /** Active slide, zero based, hidden slides counted. Bindable. */
+  index?: number;
+  /** Active fragment step on the active slide. Bindable. */
+  step?: number;
+  /** The controller, for apps that drive the deck from outside. Bindable, read only. */
+  controller?: DeckController;
+  /** Names the deck's channel and region. A `DeckData` spreads straight in. */
+  id?: string;
+  /** Accessible name for the deck region. */
+  title?: string;
+  /** Language of the deck, set as `lang`. */
+  locale?: string;
+  /** Design size in px. Slides lay out inside it and it scales to fit. */
+  canvas?: Canvas;
+  /** Colour surface. `ink` (default), `paper` or `auto`. */
+  theme?: DeckTheme;
+  /** How slides enter: `fade` (default), `slide`, `zoom`, `morph` or `none`. */
+  transition?: DeckTransition;
+  /** Data mode: render these instances through `registry` instead of `children`. */
+  slides?: SlideInstance[];
+  registry?: SlideRegistry;
+  /** Show the progress bar. */
+  progress?: boolean;
+  /** Show the previous, next, overview and fullscreen controls. */
+  controls?: boolean;
+  /** Wrap around at the ends. */
+  loop?: boolean;
+  /** Respond to keys. Turn off when a slide holds a form. */
+  keyboard?: boolean;
+  /** Stage fragments. Off shows everything at once, as a share view does. */
+  fragments?: boolean;
+  /** Keep `?s=` at the current slide. Pass an object to rename it or write the URL yourself. */
+  urlSync?: boolean | UrlSync;
+  /** Let a parent frame drive this deck over postMessage. */
+  bridge?: boolean | BridgeOptions;
+  /** Mirror this deck across windows of one origin under this name. */
+  sync?: string;
+  /** Where the presenter view lives. Adds a button and the `p` key. */
+  presenter?: string;
+  /** Translate or reword any string. */
+  labels?: Partial<DeckLabels>;
+  class?: string;
+  style?: string;
+  onchange?: (index: number, step: number) => void;
+  children?: Snippet;
+};
+