@heyramzi/ui 0.0.0-stage → 1.53.0

package/src/ai/typing-dots/TypingDots.css

@@ -0,0 +1,39 @@
+.typing-dots {
+  display: inline-flex;
+  align-items: center;
+  gap: 0.25rem;
+}
+
+.typing-dots .typing-dot {
+  width: var(--typing-dot-size, 4px);
+  height: var(--typing-dot-size, 4px);
+  border-radius: 999px;
+  background: currentColor;
+  animation: typing-dot 900ms cubic-bezier(0.25, 1, 0.5, 1) infinite;
+}
+
+.typing-dots .typing-dot:nth-child(2) {
+  animation-delay: 120ms;
+}
+
+.typing-dots .typing-dot:nth-child(3) {
+  animation-delay: 240ms;
+}
+
+@keyframes typing-dot {
+  0%,
+  100% {
+    opacity: 0.35;
+    transform: translateY(0);
+  }
+  45% {
+    opacity: 1;
+    transform: translateY(-2px);
+  }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .typing-dots .typing-dot {
+    animation: none;
+  }
+}

package/src/ai/typing-dots/TypingDots.svelte

@@ -0,0 +1,27 @@
+<script lang="ts" module>
+	import type { HTMLAttributes } from "svelte/elements";
+
+	export interface TypingDotsProps extends HTMLAttributes<HTMLSpanElement> {
+		/** Dot diameter in px. */
+		size?: number;
+		class?: string;
+	}
+</script>
+
+<script lang="ts">
+	import "./TypingDots.css";
+	import { cn } from "@heyramzi/utils";
+
+	let { size = 4, class: className, ...rest }: TypingDotsProps = $props();
+</script>
+
+<span
+	class={cn("typing-dots", className)}
+	style:--typing-dot-size="{size}px"
+	aria-hidden="true"
+	{...rest}
+>
+	<span class="typing-dot"></span>
+	<span class="typing-dot"></span>
+	<span class="typing-dot"></span>
+</span>

package/src/ai/typing-dots/index.ts

@@ -0,0 +1,10 @@
+import TypingDots from "./TypingDots.svelte";
+
+import type { TypingDotsProps } from "./TypingDots.svelte";
+
+export {
+  TypingDots,
+  type TypingDotsProps,
+  //
+  TypingDots as Root,
+};

package/src/ai/voice-waveform/VoiceWaveform.css

@@ -0,0 +1,40 @@
+.waveform {
+  display: inline-flex;
+  align-items: center;
+  gap: 2px;
+  height: 28px;
+}
+
+.waveform span {
+  width: 3px;
+  height: 8px;
+  border-radius: 999px;
+  background: currentColor;
+  opacity: 0.45;
+  transition:
+    height 180ms cubic-bezier(0.25, 1, 0.5, 1),
+    opacity 180ms cubic-bezier(0.25, 1, 0.5, 1);
+}
+
+.waveform.active span {
+  height: var(--bar-height);
+  opacity: 0.9;
+  animation: voice-bar 760ms cubic-bezier(0.25, 1, 0.5, 1) infinite;
+  animation-delay: var(--delay);
+}
+
+@keyframes voice-bar {
+  0%,
+  100% {
+    transform: scaleY(0.7);
+  }
+  50% {
+    transform: scaleY(1);
+  }
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .waveform.active span {
+    animation: none;
+  }
+}

package/src/ai/voice-waveform/VoiceWaveform.svelte

@@ -0,0 +1,46 @@
+<script lang="ts">
+	// =========================
+	// IMPORTS
+	// =========================
+
+	import "./VoiceWaveform.css";
+	import { cn } from "@heyramzi/utils";
+	import type { HTMLAttributes } from "svelte/elements";
+
+	// =========================
+	// TYPES
+	// =========================
+
+	export interface VoiceWaveformProps extends HTMLAttributes<HTMLDivElement> {
+		active?: boolean;
+		class?: string;
+		bars?: readonly number[];
+	}
+
+	// =========================
+	// CONSTANTS
+	// =========================
+
+	const DEFAULT_BARS = [10, 18, 26, 16, 22, 12] as const;
+
+	// =========================
+	// PROPS
+	// =========================
+
+	let {
+		active = false,
+		class: className,
+		bars = DEFAULT_BARS,
+		...rest
+	}: VoiceWaveformProps = $props();
+</script>
+
+<!-- =========================== -->
+<!-- MARKUP -->
+<!-- =========================== -->
+
+<div class={cn("waveform", className)} class:active aria-hidden="true" {...rest}>
+	{#each bars as height, index (index)}
+		<span style={`--bar-height: ${height}px; --delay: ${index * 70}ms`}></span>
+	{/each}
+</div>

package/src/ai/voice-waveform/index.ts

@@ -0,0 +1,5 @@
+import VoiceWaveform from "./VoiceWaveform.svelte";
+import type { VoiceWaveformProps } from "./VoiceWaveform.svelte";
+
+export { VoiceWaveform, type VoiceWaveformProps };
+export default VoiceWaveform;

package/src/ambient.d.ts

@@ -0,0 +1,4 @@
+/**
+ * A stylesheet imported for its side effect, bundled by the consumer's Vite.
+ */
+declare module "*.css";

package/src/animations/README.md

@@ -0,0 +1,84 @@
+# @heyramzi/ui — animations
+
+Production-ready CSS transitions adapted from **[transitions.dev](https://transitions.dev)** by [Jakub Antalík](https://github.com/Jakubantalik) ([source](https://github.com/Jakubantalik/transitions.dev)).
+
+The whole free catalogue is here. The paid ones are not, and are never vendored — Ramzi, 14 Sep 2026: "the pro effects we don't need them".
+
+## Staying in sync
+
+```bash
+pnpm sync:transitions          # fetch upstream, vendor it, report what moved
+pnpm sync:transitions --check  # fail if upstream moved (CI / pre-release)
+```
+
+The script writes pristine upstream copies to `.upstream/transitions/` and hashes them in `.upstream/transitions.lock.json`. It never touches these files: `git diff .upstream/` is the upstream changelog, and porting a change is a decision. `PORTED` in `scripts/sync-transitions.mjs` maps each upstream slug to its home here, and the script reports any slug that has none.
+
+## What's here
+
+| File | Selector | Used by |
+| --- | --- | --- |
+| `avatar-group-hover.css` | `.t-avatar-group`, `.t-avatar` | standalone |
+| `card-tilt.css` | `.t-tilt`, `.t-tilt-card`, `.t-tilt-glare` | standalone |
+| `digit-pop-in.css` | `.t-digit` | standalone |
+| `dropdown.css` | `.t-dropdown` | `shadcn/tooltip`, `dropdown-menu`, `popover`, `context-menu` and `select` content |
+| `input-clear-dissolve.css` | `.t-clear`, `.t-clear-mirror`, `.t-clear-glow` | standalone |
+| `input-shake.css` | `.t-input-wrap`, `.t-input`, `.t-error-msg` | (none, form layer moved to upsys) |
+| `learn-more-hover.css` | `.t-learn`, `.t-learn-chevron` | standalone |
+| `like-button.css` | `.t-like`, `.t-like-particles` | standalone |
+| `modal.css` | `.t-modal`, `.t-modal-backdrop` | `shadcn/dialog`, `shadcn/alert-dialog` |
+| `page-side-by-side.css` | `.t-page` | standalone |
+| `plus-menu-morph.css` | `.t-morph`, `.t-morph-plus`, `.t-morph-menu` | standalone |
+| `resize.css` | `.t-resize` | standalone |
+| `shimmer-text.css` | `.t-shimmer` | `thinking-states.css` |
+| `spinning-counter.css` | `.t-reel`, `.t-reel-col` | standalone |
+| `success-check.css` | `.t-success-check` | standalone |
+| `text-swap.css` + `text-swap.ts` | `.t-text-swap` | standalone |
+| `thinking-states.css` | `.t-think`, `.t-think-text` | standalone |
+
+`index.css` is the barrel — imports all of the above.
+
+## Fifteen upstream transitions that are not files here
+
+One behaviour, one implementation. Where a component already did the job, the upstream recipe was merged into it or dropped, rather than shipped as a second way to do the same thing.
+
+| Upstream | Where it lives instead |
+| --- | --- |
+| `toggle` | `shadcn/switch/switch.svelte` — the thumb slide, on our switch. |
+| `checkbox-check` | `shadcn/checkbox/checkbox.svelte` — the fill and border, on our checkbox. |
+| `toast-open-close` | `shadcn/sonner` — svelte-sonner owns toast motion. |
+| `banner-stacking` | `shadcn/sonner` — stacking and hover spread are what it does. |
+| `matrix-dot-loader` | `ai/loading-state` — `PixelLoader` is the dot-grid loader. |
+| `tabs-sliding` | `shadcn/tabs/tabs-list.svelte` with `lib/sliding-pill.ts` — the pill slides under the active tab. |
+| `tooltip-open-close` | `shadcn/tooltip/tooltip-content.svelte` — wired through `.t-dropdown`. |
+| `accordion` | `shadcn/accordion/accordion-content.svelte` — the expand and collapse keyframes. |
+| `skeleton-loader-and-reveal` | `shadcn/skeleton/skeleton.svelte` — the pulse. |
+| `notification-badge` | `shadcn/badge/badge.svelte` — the badge. |
+| `reasoning-stream` | `ai/reasoning/ReasoningContent.svelte` — the reasoning body. |
+| `streaming-text` | `effects/reveal/TextEffect.svelte` — word by word with a blur. |
+| `texts-reveal` | `effects/reveal/TextEffect.svelte` — the staggered rise. |
+| `panel-reveal` | `shadcn/sheet/sheet.css` — the sheet slide, imported by the sheet itself. |
+| `icon-swap` | `effects/theme-toggle/ThemeToggle.svelte` — the sun, moon and monitor icons cross-fade. |
+
+One more pair looks like a duplicate and is not: `spinning-counter` rolls a number between values, `digit-pop-in` updates one in place.
+
+## How to consume
+
+These styles are **not** auto-loaded with the components. Consumers import them once:
+
+```css
+@import "@heyramzi/ui/animations";
+```
+
+The two merged into components are the exception — `switch.svelte` and `checkbox.svelte` import their own CSS, so they animate with no consumer action.
+
+## Tunable tokens
+
+Every transition reads semantic CSS variables (`--modal-open-dur`, `--tilt-follow`, `--think-swap`). Where the shared motion scale in `@heyramzi/ui/design` has a token at that exact value, the variable defaults to it and keeps the literal as the fallback:
+
+```css
+--toast-open: var(--duration-medium, 350ms);
+```
+
+So the scale is single-sourced when the design layer is imported, and the transition still runs at the shipped value when it is not. A value the scale has no token for — a 1000ms tilt return, a 90ms reel stagger — stays a literal rather than being rounded onto the nearest rung. Override any of them at `:root` or per-scope to retune without forking the CSS.
+
+See the `transitions-dev` skill in vibe-kit (`ai-doc/skills/design/motion/transitions-dev/SKILL.md`) for the full token list and the per-transition variables.

package/src/animations/avatar-group-hover.css

@@ -0,0 +1,47 @@
+/* Transitions.dev — Avatar group hover */
+/* Source: https://github.com/Jakubantalik/transitions.dev */
+
+/*
+  Usage:
+    Apply .t-avatar to each item in your group (avatar, chip,
+    badge, button). Bring your own size, shape, and stacking;
+    this stylesheet only owns the hover transform + transition.
+
+      <div class="t-avatar-group">
+        <div class="t-avatar">…</div>
+        <div class="t-avatar">…</div>
+      </div>
+
+  Wire-up (JS):
+    On mouseenter of any .t-avatar, walk every sibling and set
+    inline --shift and --scale-active with a distance falloff.
+    Set transition-timing-function inline BEFORE the variable
+    writes — --avatar-ease-in on hover-in, --avatar-ease-out on
+    the root's mouseleave.
+*/
+
+:root {
+  --avatar-lift: -4px;
+  --avatar-dur: 320ms;
+  --avatar-scale: 1.05;
+  --avatar-falloff: 0.45;
+  --avatar-ease-in: var(--ease-smooth-out, cubic-bezier(0.22, 1, 0.36, 1));
+  --avatar-ease-out: var(--ease-smooth-out);
+}
+
+/* Hover-spring transition only — bring your own avatar/chip
+   styling (size, shape, border, stacking, background). */
+.t-avatar {
+  transform-origin: center;
+  /* translateY before scale so scale doesn't amplify the lift offset. */
+  transform: translateY(var(--shift, 0px)) scale(var(--scale-active, 1));
+  transition: transform var(--avatar-dur) var(--avatar-ease-in);
+  will-change: transform;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .t-avatar {
+    transition: none !important;
+    transform: none !important;
+  }
+}

package/src/animations/card-tilt.css

@@ -0,0 +1,74 @@
+/* Card hover tilt — transitions.dev `3d-tilt`.
+   Bind pointermove to the flat outer `.t-tilt`, never the card: the rotating
+   edges slip under the cursor and the hover flickers. JS writes --tilt-rx/ry
+   and --tilt-gx/gy, adds `.is-tilting` while moving and `.is-hover` for the
+   glare. Return and glare clocks have no token at their length, by design:
+   the settle is meant to read slower than any surface. */
+:root {
+  --tilt-perspective: 1000px;
+  --tilt-return: 1000ms;
+  --tilt-return-ease: var(--ease-smooth-out, cubic-bezier(0.22, 1, 0.36, 1));
+  --tilt-follow: var(--duration-slow, 400ms);
+  --tilt-follow-ease: var(--ease-smooth-out, cubic-bezier(0.22, 1, 0.36, 1));
+  --tilt-glare-opacity: 0.32;
+  --tilt-glare-fade: 300ms;
+  --tilt-glare-ease: var(--ease-smooth-out, cubic-bezier(0.22, 1, 0.36, 1));
+}
+
+/* touch-action lets a finger drag the tilt instead of scrolling the page. */
+.t-tilt {
+  touch-action: none;
+}
+
+.t-tilt-card {
+  position: relative;
+  border-radius: var(--radius-xl, 10px);
+  overflow: hidden;
+  transform: perspective(var(--tilt-perspective)) rotateX(var(--tilt-rx, 0deg))
+    rotateY(var(--tilt-ry, 0deg));
+  transform-style: preserve-3d;
+  transition: transform var(--tilt-return) var(--tilt-return-ease);
+  will-change: transform;
+}
+/* A short follow clock while the pointer moves, so the tilt tracks it 1:1. */
+.t-tilt-card.is-tilting {
+  transition: transform var(--tilt-follow) var(--tilt-follow-ease);
+}
+
+/* Layered soft circles that add like light at the pointer position. */
+.t-tilt-glare {
+  position: absolute;
+  inset: 0;
+  pointer-events: none;
+  opacity: 0;
+  mix-blend-mode: screen;
+  background:
+    radial-gradient(
+      circle 95px at var(--tilt-gx, 50%) var(--tilt-gy, 50%),
+      rgb(255 255 255 / 0.48),
+      rgb(255 255 255 / 0.06) 52%,
+      rgb(255 255 255 / 0) 84%
+    ),
+    radial-gradient(
+      circle 200px at var(--tilt-gx, 50%) var(--tilt-gy, 50%),
+      rgb(255 255 255 / 0.22),
+      rgb(255 255 255 / 0.04) 58%,
+      rgb(255 255 255 / 0) 78%
+    ),
+    radial-gradient(
+      circle 360px at var(--tilt-gx, 50%) var(--tilt-gy, 50%),
+      rgb(255 255 255 / 0.1),
+      rgb(255 255 255 / 0) 88%
+    );
+  transition: opacity var(--tilt-glare-fade) var(--tilt-glare-ease);
+}
+.t-tilt.is-hover .t-tilt-glare {
+  opacity: var(--tilt-glare-opacity);
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .t-tilt-card {
+    transform: none !important;
+    transition: none !important;
+  }
+}

package/src/animations/digit-pop-in.css

@@ -0,0 +1,78 @@
+/* Transitions.dev — Number pop-in */
+/* Source: https://github.com/Jakubantalik/transitions.dev */
+
+/*
+  Usage:
+    <span class="t-digit-group is-animating">
+      <span class="t-digit">1</span>
+      <span class="t-digit">2</span>
+      <span class="t-digit" data-stagger="1">.</span>
+      <span class="t-digit" data-stagger="2">3</span>
+    </span>
+
+  Replay:
+    Remove `.is-animating`, re-render digits (or swap text),
+    force a reflow, then re-add `.is-animating`.
+
+  Direction:
+    --digit-dir-x / --digit-dir-y are unit-less multipliers
+    (e.g. 1, -1, 0) applied to --digit-distance.
+*/
+
+:root {
+  --digit-dur: var(--duration-very-slow, 500ms);
+  --digit-distance: var(--distance-base, 8px);
+  --digit-stagger: 70ms;
+  --digit-blur: var(--blur-small, 2px);
+  --digit-ease: var(--ease-smooth-out, cubic-bezier(0.22, 1, 0.36, 1));
+  --digit-dir-x: 0;
+  --digit-dir-y: 1;
+}
+
+@keyframes t-digit-pop-in {
+  0% {
+    transform: translate(
+      calc(var(--digit-distance) * var(--digit-dir-x)),
+      calc(var(--digit-distance) * var(--digit-dir-y))
+    );
+    opacity: 0;
+    filter: blur(var(--digit-blur));
+  }
+  100% {
+    transform: translate(0, 0);
+    opacity: 1;
+    filter: blur(0);
+  }
+}
+
+.t-digit-group {
+  display: inline-flex;
+  align-items: baseline;
+}
+.t-digit {
+  display: inline-block;
+  will-change: transform, opacity, filter;
+}
+.t-digit-group.is-animating .t-digit {
+  animation: t-digit-pop-in var(--digit-dur) var(--digit-ease) both;
+}
+.t-digit-group.is-animating .t-digit[data-stagger="1"] {
+  animation-delay: var(--digit-stagger);
+}
+.t-digit-group.is-animating .t-digit[data-stagger="2"] {
+  animation-delay: calc(var(--digit-stagger) * 2);
+}
+
+/* === Extension: support more than 2 stagger steps for longer numbers === */
+.t-digit-group.is-animating .t-digit[data-stagger="3"] {
+  animation-delay: calc(var(--digit-stagger) * 3);
+}
+.t-digit-group.is-animating .t-digit[data-stagger="4"] {
+  animation-delay: calc(var(--digit-stagger) * 4);
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .t-digit-group .t-digit {
+    animation: none !important;
+  }
+}

package/src/animations/dropdown.css

@@ -0,0 +1,121 @@
+/* Transitions.dev — Menu dropdown */
+/* Source: https://github.com/Jakubantalik/transitions.dev */
+
+:root {
+  --dropdown-open-dur: var(--duration-fast, 250ms);
+  --dropdown-close-dur: var(--duration-quick, 150ms);
+  --dropdown-pre-scale: var(--scale-medium, 0.97);
+  --dropdown-closing-scale: var(--scale-tiny, 0.99);
+  --dropdown-ease: var(--ease-smooth-out, cubic-bezier(0.22, 1, 0.36, 1));
+}
+
+/* === Upstream: class-based toggle === */
+.t-dropdown {
+  transform-origin: top left;
+  transform: scale(var(--dropdown-pre-scale));
+  opacity: 0;
+  pointer-events: none;
+  transition:
+    transform var(--dropdown-open-dur) var(--dropdown-ease),
+    opacity var(--dropdown-open-dur) var(--dropdown-ease);
+  will-change: transform, opacity;
+}
+.t-dropdown[data-origin="top-right"] {
+  transform-origin: top right;
+}
+.t-dropdown[data-origin="top-center"] {
+  transform-origin: top center;
+}
+.t-dropdown[data-origin="bottom-left"] {
+  transform-origin: bottom left;
+}
+.t-dropdown[data-origin="bottom-center"] {
+  transform-origin: bottom center;
+}
+.t-dropdown[data-origin="bottom-right"] {
+  transform-origin: bottom right;
+}
+
+.t-dropdown.is-open {
+  transform: scale(1);
+  opacity: 1;
+  pointer-events: auto;
+}
+.t-dropdown.is-closing {
+  transform: scale(var(--dropdown-closing-scale));
+  opacity: 0;
+  pointer-events: none;
+  transition:
+    transform var(--dropdown-close-dur) var(--dropdown-ease),
+    opacity var(--dropdown-close-dur) var(--dropdown-ease);
+}
+
+/* === Extension: bits-ui data-state integration === */
+/* WHY: bits-ui mounts content with [data-state] and [data-side]/[data-align]
+   attributes. These selectors mirror the upstream states so consumers can drop
+   .t-dropdown on a Popover/Menu/Tooltip Content.
+
+   WHY "instant-open" is in the list: a tooltip reports three open states, not
+   two. It says "delayed-open" when it waited out the hover delay and
+   "instant-open" when it skipped that delay, which is every open while
+   delayDuration is 0 and every neighbour opened inside the skip window. That
+   third name was missing here, so those tooltips mounted, took no open rule,
+   and stayed at opacity 0: present in the DOM, never on screen. Found
+   11 Sep 2026 in upsys, where the kit's provider defaulted delayDuration to 0
+   and so produced nothing but "instant-open". */
+.t-dropdown[data-state="open"],
+.t-dropdown[data-state="delayed-open"],
+.t-dropdown[data-state="instant-open"] {
+  transform: scale(1);
+  opacity: 1;
+  pointer-events: auto;
+}
+.t-dropdown[data-state="closed"] {
+  transform: scale(var(--dropdown-closing-scale));
+  opacity: 0;
+  pointer-events: none;
+  transition:
+    transform var(--dropdown-close-dur) var(--dropdown-ease),
+    opacity var(--dropdown-close-dur) var(--dropdown-ease);
+}
+.t-dropdown[data-side="bottom"][data-align="start"] {
+  transform-origin: top left;
+}
+.t-dropdown[data-side="bottom"][data-align="center"] {
+  transform-origin: top center;
+}
+.t-dropdown[data-side="bottom"][data-align="end"] {
+  transform-origin: top right;
+}
+.t-dropdown[data-side="top"][data-align="start"] {
+  transform-origin: bottom left;
+}
+.t-dropdown[data-side="top"][data-align="center"] {
+  transform-origin: bottom center;
+}
+.t-dropdown[data-side="top"][data-align="end"] {
+  transform-origin: bottom right;
+}
+.t-dropdown[data-side="left"],
+.t-dropdown[data-side="inline-end"] {
+  transform-origin: right center;
+}
+.t-dropdown[data-side="right"],
+.t-dropdown[data-side="inline-start"] {
+  transform-origin: left center;
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .t-dropdown {
+    transition: none !important;
+  }
+}
+
+/* A tooltip that skipped its delay skips its entrance too. The first one in a
+   group waits and animates in; the neighbours the pointer travels to inside the
+   skip window are already open by the time the eye arrives, so animating them
+   only adds a wait the delay was there to hide. Scoped to the tooltip slot
+   because a menu or popover never reports this state. */
+[data-slot="tooltip-content"].t-dropdown[data-state="instant-open"] {
+  transition: none;
+}

package/src/animations/index.css

@@ -0,0 +1,23 @@
+/* Transitions.dev — bundle */
+/* Source: https://github.com/Jakubantalik/transitions.dev */
+/* Refresh the vendored upstream with `pnpm sync:transitions`. Fourteen free
+   transitions are not here because a component already owns them. See
+   README.md. */
+
+@import "./modal.css";
+@import "./dropdown.css";
+@import "./text-swap.css";
+@import "./resize.css";
+@import "./digit-pop-in.css";
+@import "./page-side-by-side.css";
+@import "./input-shake.css";
+@import "./success-check.css";
+@import "./avatar-group-hover.css";
+@import "./shimmer-text.css";
+@import "./input-clear-dissolve.css";
+@import "./learn-more-hover.css";
+@import "./card-tilt.css";
+@import "./plus-menu-morph.css";
+@import "./like-button.css";
+@import "./spinning-counter.css";
+@import "./thinking-states.css";