@heyramzi/ui 1.54.2 → 2.0.1

package/src/onboarding/types.ts

@@ -0,0 +1,34 @@
+export type Side = "top" | "bottom" | "left" | "right";
+export type Placement = Side | `${Side}-${"start" | "end"}`;
+
+/** One stop on a page. `target` is a CSS selector, usually `[data-tour="name"]`. */
+export type Step = { target: string; title: string; body: string; placement?: Placement };
+
+/**
+ * `route` is a SvelteKit route id such as `/(app)/projects/[id]`, so params never matter.
+ * `version` starts at 1. Raise it and everyone who saw the old one sees the tour again.
+ */
+export type Tour =
+	| { id: string; version?: number; route: string; kind: "steps"; steps: Step[] }
+	| { id: string; version?: number; route: string; kind: "intro"; title: string; body: string; image?: string };
+
+export type Outcome = "completed" | "dismissed";
+
+/** Where seen-state lives. `load` runs once per session. */
+export interface SeenStore {
+	/** Tour id to the version seen. */
+	load(): Promise<Record<string, number>>;
+	markSeen(tourId: string, version: number, outcome: Outcome): Promise<void>;
+	/** One tour, or all of them when no id is given. */
+	reset(tourId?: string): Promise<void>;
+}
+
+export type Strings = {
+	next: string;
+	back: string;
+	done: string;
+	skip: string;
+	progress: (n: number, total: number) => string;
+};
+
+export const MAX_STEPS = 6;

package/src/onboarding/wait.ts

@@ -0,0 +1,29 @@
+const find = (selector: string) => document.querySelector(selector);
+
+/** Resolves with the element once the selector matches, or null after `timeoutMs` or an abort. */
+export function waitForElement(
+	selector: string,
+	timeoutMs: number,
+	signal?: AbortSignal,
+): Promise<Element | null> {
+	return new Promise((resolve) => {
+		const now = find(selector);
+		if (now) return resolve(now);
+		if (signal?.aborted) return resolve(null);
+
+		const finish = (el: Element | null) => {
+			observer.disconnect();
+			clearTimeout(timer);
+			signal?.removeEventListener("abort", onAbort);
+			resolve(el);
+		};
+		const onAbort = () => finish(null);
+		const observer = new MutationObserver(() => {
+			const el = find(selector);
+			if (el) finish(el);
+		});
+		const timer = setTimeout(() => finish(find(selector)), timeoutMs);
+		observer.observe(document.documentElement, { childList: true, subtree: true });
+		signal?.addEventListener("abort", onAbort);
+	});
+}

package/src/shadcn/command/command-input.svelte

@@ -46,7 +46,7 @@
 
 			// The caret carries focus instead, which is why it is brand indigo two lines down.
 			"focus-visible:shadow-none",
-			"caret-brand-indigo placeholder:text-muted-foreground/70 w-full bg-transparent outline-hidden disabled:cursor-not-allowed disabled:opacity-50",
+			"caret-brand placeholder:text-muted-foreground/70 w-full bg-transparent outline-hidden disabled:cursor-not-allowed disabled:opacity-50",
 			// A combobox popover's search line is 36px, measured; `lg` is the
 			// standalone palette header and keeps its own larger rhythm.
 			size === "lg" ? "py-3.5 text-[15px]" : "py-2 text-[13px]",

package/src/slides/Controls.svelte

@@ -0,0 +1,138 @@
+<script lang="ts">
+  import type { DeckController } from './deck-controller.svelte.js';
+
+  interface Props {
+    deck: DeckController;
+    /** Shown only when the deck has somewhere to open the presenter view. */
+    onpresenter?: () => void;
+    onfullscreen: () => void;
+  };
+
+  let { deck, onpresenter, onfullscreen }: Props = $props();
+
+  const icons = {
+    prev: 'M15 5 8 12l7 7',
+    next: 'm9 5 7 7-7 7',
+    overview: 'M4 5h6v6H4zM14 5h6v6h-6zM4 15h6v4H4zM14 15h6v4h-6z',
+    presenter: 'M4 5h16v10H4zM8 19h8M12 15v4',
+    fullscreen: 'M4 9V4h5M20 9V4h-5M4 15v5h5M20 15v5h-5',
+  };
+</script>
+
+{#snippet button(icon: keyof typeof icons, label: string, onclick: () => void, disabled = false, pressed?: boolean)}
+  <button type="button" class="deck__button" {onclick} {disabled} aria-label={label} aria-pressed={pressed}>
+    <svg viewBox="0 0 24 24" width="18" height="18" aria-hidden="true">
+      <path d={icons[icon]} fill="none" stroke="currentColor" stroke-width="1.75" stroke-linecap="round" stroke-linejoin="round" />
+    </svg>
+  </button>
+{/snippet}
+
+<div class="deck__controls deck__chrome">
+  {@render button('prev', deck.labels.previous, () => deck.prev(), deck.atStart)}
+  <span class="deck__counter" aria-hidden="true">{deck.ordinal.n} / {deck.ordinal.of}</span>
+  {@render button('next', deck.labels.next, () => deck.next(), deck.atEnd)}
+  <span class="deck__divider" aria-hidden="true"></span>
+  {@render button('overview', deck.labels.overview, () => deck.toggleOverview(), false, deck.overview)}
+  {#if onpresenter}
+    {@render button('presenter', deck.labels.presenter, onpresenter)}
+  {/if}
+  {@render button('fullscreen', deck.labels.fullscreen, onfullscreen)}
+</div>
+
+<style>
+  .deck__controls {
+    position: absolute;
+    right: 12px;
+    bottom: 14px;
+    z-index: 5;
+    display: flex;
+    align-items: center;
+    gap: 2px;
+    padding: 4px;
+    color: var(--deck-fg);
+    background: color-mix(in srgb, var(--deck-bg) 72%, transparent);
+    border: 1px solid var(--deck-line);
+    border-radius: 12px;
+    backdrop-filter: blur(var(--blur-large, 8px));
+    opacity: 0.55;
+    transition: opacity var(--deck-t-quick) var(--deck-ease);
+  }
+  .deck__controls:focus-within {
+    opacity: 1;
+  }
+  @media (hover: hover) and (pointer: fine) {
+    .deck__controls:hover {
+      opacity: 1;
+    }
+  }
+  .deck__button {
+    display: grid;
+    place-items: center;
+    width: 32px;
+    height: 32px;
+    padding: 0;
+    color: inherit;
+    background: transparent;
+    border: 0;
+    border-radius: 8px;
+    cursor: pointer;
+    transition:
+      background-color var(--deck-t-quick) var(--deck-ease),
+      transform var(--deck-t-quick) var(--deck-ease);
+  }
+  @media (hover: hover) and (pointer: fine) {
+    .deck__button:hover:not(:disabled) {
+      background: var(--deck-line);
+    }
+  }
+  .deck__button:active:not(:disabled) {
+    transform: scale(var(--scale-medium, 0.97));
+  }
+  .deck__button[aria-pressed='true'] {
+    color: var(--deck-on-accent);
+    background: var(--deck-accent);
+  }
+  .deck__button:disabled {
+    opacity: 0.3;
+    cursor: default;
+  }
+  .deck__button:focus-visible {
+    outline: 2px solid var(--deck-accent);
+    outline-offset: 1px;
+  }
+  .deck__counter {
+    min-width: 52px;
+    font: 500 12px/1 var(--deck-font);
+    font-variant-numeric: tabular-nums;
+    text-align: center;
+    color: var(--deck-muted);
+  }
+  .deck__divider {
+    width: 1px;
+    height: 16px;
+    margin: 0 4px;
+    background: var(--deck-line);
+  }
+
+  @media (hover: none) {
+    .deck__controls {
+      opacity: 0.9;
+    }
+  }
+  /* On a small deck the controls shrink and drop the extras, so they don't cover the slide. */
+  @container (max-width: 520px) {
+    .deck__controls {
+      right: 6px;
+      bottom: 10px;
+      padding: 2px;
+    }
+    .deck__button {
+      width: 28px;
+      height: 28px;
+    }
+    .deck__counter,
+    .deck__divider {
+      display: none;
+    }
+  }
+</style>

package/src/slides/Deck.svelte

@@ -0,0 +1,271 @@
+<script lang="ts">
+  import './theme.css';
+  import { flushSync, onMount, setContext, untrack } from 'svelte';
+  import { attachBridge, attachChannel, attachUrlSync } from './bridges.js';
+  import Controls from './Controls.svelte';
+  import { DeckController } from './deck-controller.svelte.js';
+  import Overview from './Overview.svelte';
+  import SlideList from './SlideList.svelte';
+  import { DECK_KEY, DEFAULT_CANVAS, type DeckProps } from './types.js';
+
+  let {
+    index = $bindable(0),
+    step = $bindable(0),
+    controller = $bindable(),
+    id,
+    title,
+    locale,
+    canvas = DEFAULT_CANVAS,
+    theme = 'ink',
+    transition = 'fade',
+    slides,
+    registry,
+    progress = true,
+    controls = true,
+    loop = false,
+    keyboard = true,
+    fragments = true,
+    urlSync = false,
+    bridge = false,
+    sync,
+    presenter,
+    labels,
+    class: className,
+    style,
+    onchange,
+    children,
+  }: DeckProps = $props();
+
+  /* The accessors read and write the bindable props, so the controller keeps no copy of them. */
+  const deck = new DeckController({
+    get index() {
+      return index;
+    },
+    set index(value) {
+      index = value;
+    },
+    get step() {
+      return step;
+    },
+    set step(value) {
+      step = value;
+    },
+    get loop() {
+      return loop;
+    },
+    get fragments() {
+      return fragments;
+    },
+    get keyboard() {
+      return keyboard;
+    },
+    get presenter() {
+      return !!presenter;
+    },
+    get controls() {
+      return controls;
+    },
+    get canvas() {
+      return canvas;
+    },
+    get labels() {
+      return labels;
+    },
+    transition: viewTransition,
+  });
+  controller = deck;
+  setContext(DECK_KEY, deck);
+
+  let root = $state<HTMLElement>();
+  let stage = $state<HTMLElement>();
+
+  /* Morph hands the swap to the browser, which animates elements sharing a `data-morph` name. */
+  function viewTransition(update: () => void) {
+    const reduced = matchMedia('(prefers-reduced-motion: reduce)').matches;
+    if (transition !== 'morph' || reduced || !document.startViewTransition) return update();
+    document.documentElement.dataset.deckVt = '';
+    const run = document.startViewTransition(() => flushSync(update));
+    run.finished.finally(() => delete document.documentElement.dataset.deckVt);
+  }
+
+  onMount(() => deck.mount());
+
+  $effect(() => deck.listen((position) => onchange?.(position.index, position.step)));
+  $effect(() => {
+    const options = urlSync;
+    if (options) return untrack(() => attachUrlSync(deck, options === true ? {} : options));
+  });
+  $effect(() => {
+    const options = bridge;
+    if (options) return untrack(() => attachBridge(deck, options === true ? {} : options));
+  });
+  $effect(() => {
+    const name = sync;
+    if (name) return untrack(() => attachChannel(deck, name));
+  });
+
+  $effect(() => {
+    const el = stage;
+    if (!el) return;
+    const measure = () => (deck.size = { w: el.offsetWidth, h: el.offsetHeight });
+    measure();
+    const observer = new ResizeObserver(measure);
+    observer.observe(el);
+    return () => observer.disconnect();
+  });
+
+  async function toggleFullscreen() {
+    try {
+      if (document.fullscreenElement) await document.exitFullscreen();
+      else await root?.requestFullscreen();
+    } catch {
+      /* A browser without the API, or a denied request. */
+    }
+  }
+
+  const openPresenter = $derived(
+    presenter ? () => void window.open(presenter, `heyramzi-slides-${id ?? ''}`, 'popup,width=1280,height=800') : undefined,
+  );
+
+  function onkeydown(event: KeyboardEvent) {
+    const action = deck.handleKey(event);
+    if (action === 'fullscreen') void toggleFullscreen();
+    else if (action === 'presenter') openPresenter?.();
+  }
+
+  let swipe: { x: number; y: number } | null = null;
+  function onpointerdown(event: PointerEvent) {
+    deck.activate();
+    swipe = event.pointerType === 'mouse' ? null : { x: event.clientX, y: event.clientY };
+  }
+  function onpointerup(event: PointerEvent) {
+    if (!swipe || deck.overview) return;
+    const dx = event.clientX - swipe.x;
+    const dy = event.clientY - swipe.y;
+    swipe = null;
+    if (Math.abs(dx) < 48 || Math.abs(dx) < Math.abs(dy)) return;
+    if (dx < 0) deck.next();
+    else deck.prev();
+  }
+</script>
+
+<svelte:head>
+  {@html `<style>@page{size:${canvas.w}px ${canvas.h}px;margin:0}</style>`}
+</svelte:head>
+<svelte:window {onkeydown} />
+
+<!-- svelte-ignore a11y_no_noninteractive_tabindex -->
+<!-- svelte-ignore a11y_no_noninteractive_element_interactions -->
+<div
+  bind:this={root}
+  class={['deck', `deck--${theme}`, className]}
+  style:aspect-ratio="{canvas.w} / {canvas.h}"
+  style:--deck-dir={deck.direction}
+  {style}
+  lang={locale}
+  role="region"
+  aria-roledescription={deck.labels.deckRole}
+  aria-label={title ?? deck.labels.deck}
+  tabindex="0"
+  data-deck={id}
+  data-view={deck.view}
+  data-transition={transition}
+  data-morphing={deck.morphing || undefined}
+  onfocusin={() => deck.activate()}
+  onpointerenter={() => deck.activate()}
+  {onpointerdown}
+  {onpointerup}
+>
+  <div bind:this={stage} class="deck__stage">
+    {#if slides && registry}
+      <SlideList {slides} {registry} unknownLabel={deck.labels.unknownType} />
+    {:else}
+      {@render children?.()}
+    {/if}
+    {#if deck.overview}
+      <Overview {deck} returnFocus={root} />
+    {/if}
+  </div>
+
+  <div class="deck__sr" aria-live="polite" aria-atomic="true">{deck.labels.slide(deck.ordinal.n, deck.ordinal.of)}</div>
+
+  {#if progress}
+    <div
+      class="deck__progress deck__chrome"
+      role="progressbar"
+      aria-label={deck.labels.progress}
+      aria-valuemin="1"
+      aria-valuemax={deck.ordinal.of}
+      aria-valuenow={deck.ordinal.n}
+      aria-valuetext={deck.labels.slide(deck.ordinal.n, deck.ordinal.of)}
+    >
+      <div class="deck__progress-fill" style:transform="scaleX({deck.progress})"></div>
+    </div>
+  {/if}
+
+  {#if controls}
+    <Controls {deck} onpresenter={openPresenter} onfullscreen={toggleFullscreen} />
+  {/if}
+</div>
+
+<style>
+  .deck {
+    position: relative;
+    display: block;
+    width: 100%;
+    height: 100%;
+    min-height: 0;
+    overflow: hidden;
+    container-type: inline-size;
+    background: var(--deck-letterbox);
+    color: var(--deck-fg);
+    font-family: var(--deck-font);
+    outline: none;
+    touch-action: pan-y;
+    -webkit-tap-highlight-color: transparent;
+  }
+  .deck:focus-visible {
+    outline: 2px solid var(--deck-accent);
+    outline-offset: -2px;
+  }
+  .deck:fullscreen {
+    background: var(--deck-bg);
+  }
+
+  .deck__stage {
+    position: absolute;
+    inset: 0;
+    overflow: hidden;
+  }
+
+  .deck__progress {
+    position: absolute;
+    right: 0;
+    bottom: 0;
+    left: 0;
+    z-index: 5;
+    height: 3px;
+    background: var(--deck-line);
+  }
+  .deck__progress-fill {
+    height: 100%;
+    background: var(--deck-accent);
+    transform-origin: 0 50%;
+    transition: transform var(--deck-t-morph) var(--deck-ease);
+  }
+
+  .deck__sr {
+    position: absolute;
+    width: 1px;
+    height: 1px;
+    overflow: hidden;
+    clip-path: inset(50%);
+    white-space: nowrap;
+  }
+
+  @media (prefers-reduced-motion: reduce) {
+    .deck__progress-fill {
+      transition: none;
+    }
+  }
+</style>

package/src/slides/Fragment.svelte

@@ -0,0 +1,71 @@
+<script lang="ts">
+  import { getContext, type Snippet } from 'svelte';
+  import { SLIDE_KEY, type SlideContext } from './types.js';
+
+  interface Props {
+    /** Reveal at this step. `1` is the first press of the arrow key. */
+    step?: number;
+    /** How it arrives: `rise` (default), `fade` or `scale`. */
+    reveal?: 'rise' | 'fade' | 'scale';
+    /** The element to render, so a fragment can be an `li` inside a `ul`. */
+    as?: string;
+    class?: string;
+    style?: string;
+    children?: Snippet;
+  };
+
+  let { step = 1, reveal = 'rise', as: tag = 'div', class: className, style, children }: Props = $props();
+
+  const slide = getContext<SlideContext | undefined>(SLIDE_KEY);
+  const visible = $derived(slide ? slide.shown(step) : true);
+
+  /* Fragments that share a step arrive one after another, in the order they mounted. */
+  let order = $state(0);
+  $effect(() => {
+    if (!slide) return;
+    const joined = slide.join(step);
+    order = joined.order;
+    return joined.leave;
+  });
+</script>
+
+<svelte:element
+  this={tag}
+  class={['deck-fragment', className]}
+  {style}
+  style:--frag-i={order}
+  data-reveal={reveal}
+  data-visible={visible}
+  aria-hidden={!visible}
+  inert={!visible}
+>
+  {@render children?.()}
+</svelte:element>
+
+<style>
+  .deck-fragment {
+    opacity: 0;
+    transition:
+      opacity var(--deck-t-slide) var(--deck-ease),
+      transform var(--deck-t-slide) var(--deck-ease);
+  }
+  .deck-fragment[data-reveal='rise'] {
+    transform: translateY(var(--deck-shift));
+  }
+  .deck-fragment[data-reveal='scale'] {
+    transform: scale(var(--scale-large, 0.96));
+  }
+  .deck-fragment[data-visible='true'] {
+    opacity: 1;
+    transform: none;
+    transition-delay: calc(var(--frag-i) * var(--deck-stagger));
+  }
+
+  @media (prefers-reduced-motion: reduce) {
+    .deck-fragment {
+      transform: none !important;
+      transition: opacity var(--deck-t-quick) linear;
+      transition-delay: 0s !important;
+    }
+  }
+</style>

package/src/slides/Overview.svelte

@@ -0,0 +1,113 @@
+<script lang="ts">
+  import type { DeckController } from './deck-controller.svelte.js';
+
+  interface Props { deck: DeckController; returnFocus?: HTMLElement };
+
+  let { deck, returnFocus }: Props = $props();
+
+  let tiles = $state<HTMLButtonElement[]>([]);
+
+  /* Focus follows the cursor, so arrow keys and Tab agree on where you are. */
+  $effect(() => {
+    tiles[deck.cursor]?.focus({ preventScroll: true });
+  });
+  $effect(() => () => returnFocus?.focus({ preventScroll: true }));
+</script>
+
+<ol class="deck__tiles deck__chrome">
+  {#each deck.visible as slideIndex, n (slideIndex)}
+    {@const box = deck.grid.boxes[n]}
+    {@const label = deck.entries[slideIndex]?.label}
+    {#if box}
+      <li
+        class="deck__tile-cell"
+        style:left="{box.x}px"
+        style:top="{box.y}px"
+        style:width="{deck.canvas.w * box.scale}px"
+        style:height="{deck.canvas.h * box.scale}px"
+      >
+        <button
+          bind:this={tiles[n]}
+          type="button"
+          class="deck__tile"
+          tabindex={n === deck.cursor ? 0 : -1}
+          aria-current={slideIndex === deck.position.index ? 'step' : undefined}
+          aria-label={label ? `${deck.labels.slide(n + 1, deck.visible.length)}: ${label}` : deck.labels.slide(n + 1, deck.visible.length)}
+          onclick={() => deck.select(slideIndex)}
+          onfocus={() => (deck.cursor = n)}
+        >
+          <span class="deck__tile-n">{n + 1}</span>
+        </button>
+      </li>
+    {/if}
+  {/each}
+</ol>
+
+<style>
+  .deck__tiles {
+    position: absolute;
+    inset: 0;
+    z-index: 4;
+    margin: 0;
+    padding: 0;
+    list-style: none;
+    /* The ring and number appear once the thumbnails have landed. */
+    animation: tiles-in var(--deck-t-quick) linear var(--deck-t-morph) backwards;
+  }
+  @keyframes tiles-in {
+    from {
+      opacity: 0;
+    }
+  }
+  @media (prefers-reduced-motion: reduce) {
+    .deck__tiles {
+      animation: none;
+    }
+  }
+  .deck__tile-cell {
+    position: absolute;
+  }
+  .deck__tile {
+    position: absolute;
+    inset: 0;
+    padding: 0;
+    color: var(--deck-fg);
+    background: transparent;
+    border: 0;
+    border-radius: 10px;
+    cursor: pointer;
+    outline: 2px solid transparent;
+    outline-offset: 3px;
+    transition: outline-color var(--deck-t-quick) var(--deck-ease);
+  }
+  @media (hover: hover) and (pointer: fine) {
+    .deck__tile:hover {
+      outline-color: color-mix(in srgb, var(--deck-accent) 55%, transparent);
+    }
+  }
+  .deck__tile[aria-current='step'] {
+    outline-color: var(--deck-accent);
+  }
+  .deck__tile:focus-visible {
+    outline-color: var(--deck-fg);
+  }
+  .deck__tile-n {
+    position: absolute;
+    bottom: -12px;
+    left: 50%;
+    min-width: 22px;
+    transform: translateX(-50%);
+    padding: 3px 6px;
+    font: 600 11px/1 var(--deck-font);
+    font-variant-numeric: tabular-nums;
+    text-align: center;
+    color: var(--deck-fg);
+    background: var(--deck-bg);
+    box-shadow: 0 0 0 1px var(--deck-line);
+    border-radius: 6px;
+  }
+  .deck__tile[aria-current='step'] .deck__tile-n {
+    color: var(--deck-on-accent);
+    background: var(--deck-accent);
+  }
+</style>