create-omg 0.4.30

package/dist/template/src/components/ui/sound.ts

@@ -0,0 +1,182 @@
+// useSound / playSound — the AUDIO half of the delight kit (its haptic-ish
+// sibling to the visual `transitions` / `AnimatedNumber` primitives).
+//
+// Every sound is SYNTHESIZED at runtime with the Web Audio API — there are no
+// `.mp3`/`.wav` files to ship, fetch, or decode. The whole thing is a few
+// oscillators and a gain envelope, so it adds ~0kb of assets and a couple kb of
+// code, and it themes to nothing (pure tones) so it drops into any app.
+//
+// Design rules baked in, so a button that opts into sound never feels cheap:
+//   - One shared, lazily-created AudioContext, resumed on the first gesture.
+//     Browsers block audio until a user interaction, and a button press IS one,
+//     so the first click both unlocks and plays.
+//   - Silently no-ops when Web Audio is unavailable (SSR, old browsers) or when
+//     sound is disabled — exactly like the haptics singleton. It never throws.
+//   - Respects `prefers-reduced-motion`: a user who asked for a calmer, quieter
+//     experience gets silence unless the app explicitly forces sound on.
+//   - Short, quiet, rounded envelopes (soft attack + exponential release) so
+//     presses read as a tactile "tick", never a harsh beep.
+//
+// Self-contained: no CSS, no Tailwind, no runtime dependency beyond React.
+// Edit the PRESETS table freely — it's vendored into your project.
+
+import { useCallback, useMemo } from "react"
+
+/** Built-in synthesized sounds. Pass one of these names to `play`. */
+export type SoundName =
+  | "tap" // soft, short press tick — the default for buttons
+  | "click" // crisper, slightly louder press
+  | "toggleOn" // rising two-tone — switch/checkbox turning on
+  | "toggleOff" // falling two-tone — switch/checkbox turning off
+  | "success" // pleasant rising major third — save/confirm
+  | "error" // low, buzzy descending — invalid/destructive
+  | "notify" // gentle two-note chime — a new item/notification
+
+type Tone = {
+  /** Oscillator frequency in Hz (or the START of a glide, with `to`). */
+  freq: number
+  /** Optional glide target — the pitch ramps from `freq` to `to`. */
+  to?: number
+  /** How long the tone rings, in seconds. */
+  duration: number
+  /** Peak gain (0–1). Kept low so sounds stay tactile, not startling. */
+  gain?: number
+  /** Oscillator shape. `sine`/`triangle` are soft; `square`/`sawtooth` bite. */
+  type?: OscillatorType
+  /** Delay before this tone starts, in seconds (for two-note sequences). */
+  delay?: number
+}
+
+// Each preset is one or more tones layered/sequenced. Frequencies are chosen
+// to sit in a musical relationship (unison, thirds, fifths) so multi-tone
+// sounds read as "nice" rather than random.
+const PRESETS: Record<SoundName, Tone[]> = {
+  tap: [{ freq: 660, duration: 0.05, gain: 0.05, type: "sine" }],
+  click: [{ freq: 880, duration: 0.045, gain: 0.07, type: "triangle" }],
+  toggleOn: [
+    { freq: 587.33, duration: 0.06, gain: 0.05, type: "sine" },
+    { freq: 880, duration: 0.07, gain: 0.05, type: "sine", delay: 0.045 },
+  ],
+  toggleOff: [
+    { freq: 880, duration: 0.06, gain: 0.05, type: "sine" },
+    { freq: 587.33, duration: 0.07, gain: 0.05, type: "sine", delay: 0.045 },
+  ],
+  success: [
+    { freq: 523.25, duration: 0.08, gain: 0.05, type: "sine" },
+    { freq: 659.25, duration: 0.12, gain: 0.05, type: "sine", delay: 0.07 },
+  ],
+  error: [{ freq: 200, to: 120, duration: 0.16, gain: 0.06, type: "sawtooth" }],
+  notify: [
+    { freq: 784, duration: 0.08, gain: 0.045, type: "triangle" },
+    { freq: 1046.5, duration: 0.12, gain: 0.045, type: "triangle", delay: 0.06 },
+  ],
+}
+
+let ctx: AudioContext | null = null
+let enabled = true
+
+function prefersReducedMotion(): boolean {
+  return (
+    typeof window !== "undefined" &&
+    typeof window.matchMedia === "function" &&
+    window.matchMedia("(prefers-reduced-motion: reduce)").matches
+  )
+}
+
+function getContext(): AudioContext | null {
+  if (typeof window === "undefined") return null
+  const Ctor: typeof AudioContext | undefined =
+    window.AudioContext ??
+    (window as unknown as { webkitAudioContext?: typeof AudioContext })
+      .webkitAudioContext
+  if (!Ctor) return null
+  if (!ctx) {
+    try {
+      ctx = new Ctor()
+    } catch {
+      return null
+    }
+  }
+  // A context created before a gesture starts `suspended`; a gesture-driven
+  // call resumes it. Fire-and-forget — if it's blocked, playback just no-ops.
+  if (ctx.state === "suspended") void ctx.resume().catch(() => {})
+  return ctx
+}
+
+function ring(context: AudioContext, tone: Tone, startAt: number) {
+  const osc = context.createOscillator()
+  const amp = context.createGain()
+  const peak = tone.gain ?? 0.05
+  const t0 = startAt + (tone.delay ?? 0)
+  const t1 = t0 + tone.duration
+
+  osc.type = tone.type ?? "sine"
+  osc.frequency.setValueAtTime(tone.freq, t0)
+  if (tone.to != null) osc.frequency.exponentialRampToValueAtTime(tone.to, t1)
+
+  // Soft attack, exponential release — a rounded "tick", not a click artifact.
+  amp.gain.setValueAtTime(0.0001, t0)
+  amp.gain.exponentialRampToValueAtTime(peak, t0 + 0.008)
+  amp.gain.exponentialRampToValueAtTime(0.0001, t1)
+
+  osc.connect(amp).connect(context.destination)
+  osc.start(t0)
+  osc.stop(t1 + 0.02)
+}
+
+/**
+ * Play a synthesized sound. Safe to call anywhere: silently no-ops on unsupported
+ * platforms, when sound is disabled, or under `prefers-reduced-motion`. Best
+ * called from within a user gesture (a click/press handler) so the browser lets
+ * audio through.
+ *
+ * You can also pass an ad-hoc tone (or array of tones) instead of a preset name
+ * to synthesize a one-off sound.
+ */
+export function playSound(sound: SoundName | Tone | Tone[]): void {
+  if (!enabled || prefersReducedMotion()) return
+  const context = getContext()
+  if (!context) return
+  const tones =
+    typeof sound === "string" ? PRESETS[sound] : Array.isArray(sound) ? sound : [sound]
+  if (!tones || tones.length === 0) return
+  const now = context.currentTime
+  try {
+    for (const tone of tones) ring(context, tone, now)
+  } catch {
+    // AudioContext can throw if it was closed out from under us — ignore.
+  }
+}
+
+/**
+ * Globally enable or disable all synthesized sound (e.g. a settings toggle).
+ * Defaults to enabled. Disabling makes every `playSound`/`useSound().play` a
+ * no-op without changing any call sites.
+ */
+export function setSoundEnabled(next: boolean): void {
+  enabled = next
+}
+
+/** Whether synthesized sound is currently enabled (ignores reduced-motion). */
+export function isSoundEnabled(): boolean {
+  return enabled
+}
+
+/**
+ * Hook wrapper. Returns a stable `play` you can drop into event handlers, plus
+ * the enable/disable controls. `play` defaults to the `"tap"` press tick.
+ *
+ * ```tsx
+ * const { play } = useSound()
+ * <Button onClick={() => { play("success"); save() }}>Save</Button>
+ * ```
+ */
+export function useSound() {
+  const play = useCallback((sound: SoundName | Tone | Tone[] = "tap") => {
+    playSound(sound)
+  }, [])
+  return useMemo(
+    () => ({ play, setEnabled: setSoundEnabled, isEnabled: isSoundEnabled }),
+    [play],
+  )
+}

package/dist/template/src/components/ui/transitions.tsx

@@ -0,0 +1,419 @@
+// Transitions — dependency-free, CSS-only micro-interactions.
+//
+// Vendored from transitions.dev (Jakub Antalík), editable source. The motion
+// lives in the injected `.vui-t-*` stylesheet (see vibes-ui-styles.ts); these
+// React wrappers just own the awkward bits — flipping `.is-open` AFTER first
+// paint so the open transition actually runs, keeping a closing element mounted
+// until its exit finishes, and the three-phase reflow dance for swapping text.
+// Self-contained: no Tailwind utility classes, no motion library, no runtime
+// dependency beyond React. Only transform/opacity/filter animate, and every
+// family honors prefers-reduced-motion.
+//
+// Reach for these when the DELIGHT rule "motion should REDUCE perceived travel"
+// applies: a dialog, a menu, a drawer, a wizard step, or any element/label that
+// swaps. Don't pull in Framer Motion for these — and don't wrap them in
+// <AnimatePresence>; the two systems fight over the same element.
+
+import {
+  useEffect,
+  useRef,
+  useState,
+  type CSSProperties,
+  type ReactNode,
+} from "react"
+import { flushSync } from "react-dom"
+import { ensureStyles } from "@/components/ui/vibes-ui-styles"
+
+function cx(...parts: Array<string | false | null | undefined>): string {
+  return parts.filter(Boolean).join(" ")
+}
+
+/**
+ * Mount/show lifecycle for an open/close element. Returns `mounted` (keep it in
+ * the DOM through the exit transition) and `show` (drives `.is-open`). On open
+ * it waits two animation frames before flipping `show`, so the element first
+ * paints in its closed state and the open transition has somewhere to travel
+ * from; on close it holds the element mounted for `closeMs` while `.is-closing`
+ * plays, then unmounts it.
+ */
+function usePresence(open: boolean, closeMs: number) {
+  const [mounted, setMounted] = useState(open)
+  const [show, setShow] = useState(open)
+
+  useEffect(() => {
+    if (open) {
+      setMounted(true)
+      let raf2 = 0
+      const raf1 = requestAnimationFrame(() => {
+        raf2 = requestAnimationFrame(() => setShow(true))
+      })
+      return () => {
+        cancelAnimationFrame(raf1)
+        cancelAnimationFrame(raf2)
+      }
+    }
+    setShow(false)
+    const timer = setTimeout(() => setMounted(false), closeMs)
+    return () => clearTimeout(timer)
+  }, [open, closeMs])
+
+  return { mounted, show }
+}
+
+// ── Modal ──────────────────────────────────────────────────────────────────
+
+export type ModalProps = {
+  /** Whether the dialog is open. */
+  open: boolean
+  /** Called when the backdrop is clicked (wire it to your close handler). */
+  onClose?: () => void
+  children: ReactNode
+  /** Render a fading scrim behind the dialog. Default `true`. */
+  backdrop?: boolean
+  className?: string
+  style?: CSSProperties
+}
+
+/**
+ * Centered dialog that scales + fades in, and (faster) back out. Stays mounted
+ * through the close transition, then unmounts itself. Renders an optional
+ * click-to-close backdrop. Style the dialog surface via `className` — bring your
+ * own `Card` or padding/background.
+ */
+export function Modal({
+  open,
+  onClose,
+  children,
+  backdrop = true,
+  className = "",
+  style,
+}: ModalProps) {
+  useEffect(ensureStyles, [])
+  const { mounted, show } = usePresence(open, 150)
+  if (!mounted) return null
+  const state = show ? "is-open" : "is-closing"
+
+  return (
+    <>
+      {backdrop ? (
+        <div
+          className={cx("vui", "vui-t-backdrop", state)}
+          onClick={onClose}
+          aria-hidden="true"
+        />
+      ) : null}
+      <div
+        className={cx("vui", "vui-t-modal", state, className)}
+        style={style}
+        role="dialog"
+        aria-modal="true"
+      >
+        {children}
+      </div>
+    </>
+  )
+}
+
+// ── Menu ─────────────────────────────────────────────────────────────────────
+
+export type MenuOrigin =
+  | "top-left"
+  | "top-center"
+  | "top-right"
+  | "bottom-left"
+  | "bottom-center"
+  | "bottom-right"
+
+export type MenuProps = {
+  /** Whether the menu is open. */
+  open: boolean
+  children: ReactNode
+  /** Corner the menu scales out from — match it to the trigger. Default `top-left`. */
+  origin?: MenuOrigin
+  className?: string
+  style?: CSSProperties
+}
+
+/**
+ * Popover/dropdown that scales from its anchor corner. Position the element
+ * yourself (the caller owns layout — e.g. an absolutely-positioned wrapper under
+ * the trigger); this only animates open/close and unmounts when closed.
+ */
+export function Menu({
+  open,
+  children,
+  origin = "top-left",
+  className = "",
+  style,
+}: MenuProps) {
+  useEffect(ensureStyles, [])
+  const { mounted, show } = usePresence(open, 150)
+  if (!mounted) return null
+
+  return (
+    <div
+      className={cx("vui", "vui-t-menu", show ? "is-open" : "is-closing", className)}
+      data-origin={origin}
+      style={style}
+      role="menu"
+    >
+      {children}
+    </div>
+  )
+}
+
+// ── Panel ────────────────────────────────────────────────────────────────────
+
+export type PanelProps = {
+  /** Whether the panel is revealed. */
+  open: boolean
+  children: ReactNode
+  className?: string
+  style?: CSSProperties
+}
+
+/**
+ * Inline reveal — a drawer, sheet, or expander that slides up, fades, and
+ * un-blurs into place. Stays mounted in both states (so it can clip inside an
+ * `overflow: hidden` container); set `--vui-t-panel-y` to ~half the panel
+ * height via `style` for a fuller travel.
+ */
+export function Panel({ open, children, className = "", style }: PanelProps) {
+  useEffect(ensureStyles, [])
+  return (
+    <div
+      className={cx("vui", "vui-t-panel", className)}
+      data-open={open ? "true" : "false"}
+      style={style}
+    >
+      {children}
+    </div>
+  )
+}
+
+// ── Expand ───────────────────────────────────────────────────────────────────
+
+export type ExpandProps = {
+  /** Whether the region is expanded. */
+  open: boolean
+  children: ReactNode
+  className?: string
+  style?: CSSProperties
+}
+
+/**
+ * Height-auto reveal that animates smoothly WITHOUT measuring the DOM — an
+ * accordion row, a disclosure, a "show more" section, a collapsible filter
+ * panel. Built on the `grid-template-rows: 0fr → 1fr` trick, so it interpolates
+ * to the content's natural height (no fixed `max-height` guesswork, no JS
+ * measurement, no clipping when the content grows). Stays mounted in both
+ * states and clips its overflow while collapsed. Reach for this instead of
+ * toggling `hidden`/`display:none` (which snaps) or hand-rolling a `max-height`
+ * hack. For an overlay drawer/sheet that floats above content use `Panel`; this
+ * one pushes surrounding layout as it opens.
+ */
+export function Expand({ open, children, className = "", style }: ExpandProps) {
+  useEffect(ensureStyles, [])
+  return (
+    <div
+      className={cx("vui", "vui-t-expand", className)}
+      data-open={open ? "true" : "false"}
+      style={style}
+    >
+      <div className="vui-t-expand-inner">{children}</div>
+    </div>
+  )
+}
+
+// ── animateView (View Transitions) ─────────────────────────────────────────────
+
+/**
+ * Run a state update inside a native View Transition so the browser cross-fades
+ * / morphs between the before and after DOM — list reorders, a filter that adds
+ * or removes rows, a route/tab swap, an item moving between two lists. Give the
+ * elements that should morph a stable `viewTransitionName` (via `style`) and the
+ * browser tweens their position/size for you.
+ *
+ * Uses `document.startViewTransition` with `flushSync` so React commits the
+ * update synchronously inside the transition callback. Degrades gracefully: if
+ * the API is unsupported OR the user prefers reduced motion, the update is
+ * applied immediately with no animation. Safe to call from any event handler.
+ *
+ *   animateView(() => setItems(reorder(items)))
+ */
+export function animateView(update: () => void): void {
+  const doc = document as Document & {
+    startViewTransition?: (cb: () => void | Promise<void>) => unknown
+  }
+  const reducedMotion =
+    typeof window !== "undefined" &&
+    typeof window.matchMedia === "function" &&
+    window.matchMedia("(prefers-reduced-motion: reduce)").matches
+
+  if (typeof doc.startViewTransition !== "function" || reducedMotion) {
+    update()
+    return
+  }
+  doc.startViewTransition(() => flushSync(update))
+}
+
+// ── PageSlide ────────────────────────────────────────────────────────────────
+
+export type PageSlideProps = {
+  /** Active page index (0-based). */
+  page: number
+  /** One node per page, in order. Pages before `page` exit left, after exit right. */
+  pages: ReactNode[]
+  className?: string
+  style?: CSSProperties
+}
+
+/**
+ * Side-by-side wizard / tab steps. Only the active page is interactive; the
+ * others sit stacked, blurred, and shifted toward the side they came from, so
+ * forward/back reads as horizontal travel. Keeps every page mounted.
+ */
+export function PageSlide({ page, pages, className = "", style }: PageSlideProps) {
+  useEffect(ensureStyles, [])
+  return (
+    <div className={cx("vui", "vui-t-pages", className)} style={style}>
+      {pages.map((node, i) => (
+        <div
+          key={i}
+          className={cx("vui-t-page", i === page && "is-active")}
+          style={
+            {
+              "--vui-t-page-x":
+                i < page
+                  ? "calc(var(--vui-t-page-dist, 8px) * -1)"
+                  : "var(--vui-t-page-dist, 8px)",
+            } as CSSProperties
+          }
+          aria-hidden={i === page ? undefined : true}
+        >
+          {node}
+        </div>
+      ))}
+    </div>
+  )
+}
+
+// ── IconSwap ─────────────────────────────────────────────────────────────────
+
+export type IconSwapProps = {
+  /** Which icon is showing. */
+  active: "a" | "b"
+  /** First icon (shown when `active === "a"`). */
+  a: ReactNode
+  /** Second icon (shown when `active === "b"`). */
+  b: ReactNode
+  className?: string
+  style?: CSSProperties
+}
+
+/**
+ * Cross-fade + scale between two stacked icons (play/pause, moon/sun,
+ * copy/check). Both icons render at once, sharing a grid cell; the inactive one
+ * fades, blurs, and shrinks away.
+ */
+export function IconSwap({ active, a, b, className = "", style }: IconSwapProps) {
+  useEffect(ensureStyles, [])
+  return (
+    <span
+      className={cx("vui", "vui-t-icon-swap", className)}
+      data-state={active}
+      style={style}
+    >
+      <span className="vui-t-icon" data-icon="a" aria-hidden={active !== "a"}>
+        {a}
+      </span>
+      <span className="vui-t-icon" data-icon="b" aria-hidden={active !== "b"}>
+        {b}
+      </span>
+    </span>
+  )
+}
+
+// ── TextSwap ─────────────────────────────────────────────────────────────────
+
+export type TextSwapProps = {
+  /** The current text. Changing it animates the old out (up) and the new in (from below). */
+  children: string
+  className?: string
+  style?: CSSProperties
+}
+
+/**
+ * Swap a short label/status string in place: the old text lifts up + blurs +
+ * fades, then the new text rises from below. Handy for state words ("Saving…" →
+ * "Saved", "Copy" → "Copied"). For runtime numbers reach for `AnimatedNumber`,
+ * and for rolling slot-text reach for `AnimatedText`; this is for arbitrary
+ * label replacement.
+ */
+export function TextSwap({ children, className = "", style }: TextSwapProps) {
+  useEffect(ensureStyles, [])
+  const ref = useRef<HTMLSpanElement | null>(null)
+  const [text, setText] = useState(children)
+  const prev = useRef(children)
+
+  useEffect(() => {
+    const el = ref.current
+    if (!el || children === prev.current) return
+    const next = children
+    prev.current = next
+
+    el.classList.add("is-exit")
+    const dur =
+      parseFloat(getComputedStyle(el).getPropertyValue("--vui-t-text-dur")) || 200
+    const timer = setTimeout(() => {
+      setText(next)
+      el.classList.remove("is-exit")
+      el.classList.add("is-enter-start")
+      // Force reflow so the jump-below state paints before we release it.
+      void el.offsetWidth
+      el.classList.remove("is-enter-start")
+    }, dur)
+    return () => clearTimeout(timer)
+  }, [children])
+
+  return (
+    <span ref={ref} className={cx("vui", "vui-t-text", className)} style={style}>
+      {text}
+    </span>
+  )
+}
+
+// ── NotificationBadge ────────────────────────────────────────────────────────
+
+export type NotificationBadgeProps = {
+  /** Whether the badge is shown. Toggling pops it in / out. */
+  show: boolean
+  /** Badge contents (a count, a dot). */
+  children?: ReactNode
+  className?: string
+  style?: CSSProperties
+}
+
+/**
+ * A count/dot that pops in with a slight overshoot and shrinks-blurs out. Place
+ * it inside a `position: relative` trigger (e.g. a bell button); it pins to the
+ * top-right corner and never intercepts pointer events.
+ */
+export function NotificationBadge({
+  show,
+  children,
+  className = "",
+  style,
+}: NotificationBadgeProps) {
+  useEffect(ensureStyles, [])
+  return (
+    <span
+      className={cx("vui", "vui-t-badge", className)}
+      data-open={show ? "true" : "false"}
+      style={style}
+      aria-hidden={!show}
+    >
+      <span className="vui-t-badge-dot">{children}</span>
+    </span>
+  )
+}