@heyramzi/ui 0.0.0-stage → 6.1.0

package/src/design/index.css

@@ -0,0 +1,270 @@
+/* The craft layer, the opinionated half of a design system.
+ *
+ * A palette says which colours a product uses. This file says how a surface
+ * lifts off the page, how round a control is against a card, and how long an
+ * overlay takes to arrive. Those three answers are what separate a kit that
+ * looks assembled from one that looks made, and they were the part every app
+ * here was re-deciding per component.
+ *
+ * WHY it ships beside the palette rather than inside it: the palette is the
+ * brand and differs per app; elevation, radius and motion are craft and should
+ * not. An app imports this, then tints it with `--elev-tint` and nothing else.
+ *
+ * Studied from beautifului.dev and rareui.com, which both build the same three
+ * ladders: a hairline that is a shadow rather than a border, a radius that
+ * steps by the role of the box, and a close that is faster than its open.
+ *
+ * Import once, after Tailwind:
+ *   @import "@heyramzi/ui/design";
+ */
+
+@import "./polish.css";
+
+/* ── Radius, by role not by size ─────────────────────────────
+   A chip inside a control inside a card has to read as nested, which needs
+   three radii that step, not one radius reused. The Tailwind names are the
+   home so `rounded-lg` on a button already resolves to the control radius and
+   no component has to learn a new class. */
+@theme {
+  --radius-xs: 4px; /* tag, dot, inline code */
+  --radius-sm: 6px; /* chip, badge, small pill */
+  --radius-md: 7px; /* between a chip and a control */
+  --radius-lg: 8px; /* control: button, input, select, menu item */
+  --radius-xl: 10px; /* card, panel, stage */
+  --radius-2xl: 14px; /* overlay: dialog, sheet, command palette */
+  --radius-3xl: 20px; /* hero surface, full-bleed panel */
+}
+
+/* ── Elevation ───────────────────────────────────────────────
+   Four steps of lift, plus the two edges that are not lift.
+
+   WHY the steps are shadow-only and the hairline is its own token: most boxes
+   in a kit already draw a border, and an elevation that bakes a `0 0 0 1px`
+   ring into every step gives those boxes two edges a pixel apart. Compose them
+   where a component drops its border:
+
+     box-shadow: var(--elev-hairline), var(--elev-card);
+
+   WHY each step is stacked rather than one blurred drop: a single shadow reads
+   as a sticker. Depth is several offsets falling off together, which is what
+   the eye reads as distance. They cost nothing extra because every stop is the
+   same colour at a different alpha.
+
+   WHY the blur radii are large and the alphas small: a 4px blur at 20% draws a
+   visible grey edge, which the eye reads as a second border. A 28px blur at 7%
+   is barely a colour anywhere and reads as height. Reach for more blur before
+   more alpha, every time.
+
+   `--elev-tint` is the one knob an app turns. Pure black greys a warm palette
+   out; the hue of the app's own darkest surface keeps the shadow in the
+   family. */
+:root {
+  --elev-tint: oklch(0 0 0);
+
+  /* Resting on the page. A button, a chip, a row. */
+  --elev-btn:
+    0 1px 1px -0.5px color-mix(in oklab, var(--elev-tint) 7%, transparent),
+    0 2px 5px -2px color-mix(in oklab, var(--elev-tint) 6%, transparent);
+
+  /* Sitting on the page. A card, a stage, a panel. */
+  --elev-card:
+    0 1px 2px -1px color-mix(in oklab, var(--elev-tint) 7%, transparent),
+    0 4px 9px -3px color-mix(in oklab, var(--elev-tint) 6%, transparent),
+    0 14px 28px -10px color-mix(in oklab, var(--elev-tint) 7%, transparent);
+
+  /* Lifted off the page. A hovered card, a popover, a menu. */
+  --elev-raised:
+    0 1px 2px -1px color-mix(in oklab, var(--elev-tint) 8%, transparent),
+    0 6px 13px -4px color-mix(in oklab, var(--elev-tint) 9%, transparent),
+    0 20px 40px -12px color-mix(in oklab, var(--elev-tint) 12%, transparent);
+
+  /* Floating over a dimmed page. A dialog, a sheet, a command palette. */
+  --elev-overlay:
+    0 2px 4px -1px color-mix(in oklab, var(--elev-tint) 8%, transparent),
+    0 12px 26px -8px color-mix(in oklab, var(--elev-tint) 12%, transparent),
+    0 40px 72px -20px color-mix(in oklab, var(--elev-tint) 20%, transparent);
+
+  /* The two edges. A hairline separates a surface from what is behind it; a rim
+     is the light catching its top edge, which is what makes a filled control
+     read as a physical key rather than a coloured rectangle. */
+  --elev-hairline: 0 0 0 1px var(--color-border, var(--border));
+  --elev-rim: inset 0 1px 0 color-mix(in oklab, white 16%, transparent);
+
+  /* A field is the one box that goes in rather than up. */
+  --elev-field: inset 0 1px 2px color-mix(in oklab, var(--elev-tint) 7%, transparent);
+}
+
+/* A dark surface cannot cast a darker shadow than the page it sits on, so the
+   hairline does the separating and the shadow only sinks what is behind it. On
+   dark the hairline is white at a low alpha, which is what reads as a lit edge
+   rather than as a drawn border. */
+.dark {
+  --elev-btn: 0 1px 2px color-mix(in oklab, black 30%, transparent);
+  --elev-card:
+    0 1px 2px color-mix(in oklab, black 24%, transparent),
+    0 4px 12px -4px color-mix(in oklab, black 30%, transparent);
+  --elev-raised:
+    0 2px 6px color-mix(in oklab, black 30%, transparent),
+    0 10px 24px -6px color-mix(in oklab, black 38%, transparent);
+  --elev-overlay:
+    0 4px 10px color-mix(in oklab, black 34%, transparent),
+    0 24px 56px -12px color-mix(in oklab, black 50%, transparent);
+
+  --elev-hairline: 0 0 0 1px color-mix(in oklab, white 10%, transparent);
+  --elev-rim: inset 0 1px 0 color-mix(in oklab, white 10%, transparent);
+  --elev-field: inset 0 1px 2px color-mix(in oklab, black 40%, transparent);
+}
+
+/* ── Focus ───────────────────────────────────────────────────
+   One ring, two parts: a solid edge that redraws the control's own outline in
+   the accent, and a soft halo that carries it off the surface. Written as a
+   variable so a component spends one line on it and every control focuses the
+   same way. */
+:root {
+  --ring-color: var(--color-ring, var(--ring));
+  --ring-halo: color-mix(in oklab, var(--ring-color) 16%, transparent);
+  /* A solid pixel redrawing the control's own edge, then a wide soft band. At a
+     higher alpha the band reads as a second border rather than as a glow, which
+     is why it is 16% over 4px and not 30% over 2px. */
+  --ring-focus: 0 0 0 1px var(--ring-color), 0 0 0 5px var(--ring-halo);
+}
+
+/* ── Motion ──────────────────────────────────────────────────
+   The transitions-dev scale, verbatim, so a snippet pasted from that skill and
+   a component written here read from the same names.
+
+   The doctrine in one line: an open is an invitation and a close should get out
+   of the way, so every close is shorter than its open and no close bounces. */
+:root {
+  --duration-stagger: 40ms;
+  --duration-micro: 80ms;
+  --duration-quick: 150ms; /* every close, text swap, tooltip in */
+  --duration-fast: 250ms; /* every open, tabs, icon swap, page slide */
+  --duration-medium: 350ms; /* panel close, toast close */
+  --duration-slow: 400ms; /* panel open, skeleton reveal */
+  --duration-very-slow: 500ms; /* emphasis: badge, text reveal, success check */
+
+  --ease-smooth-out: cubic-bezier(0.22, 1, 0.36, 1); /* all surface motion */
+  --ease-in-out: ease-in-out; /* swaps and cross-fades */
+  --ease-out: ease-out; /* tooltips */
+  --ease-linear: linear; /* shimmer, pulse, spinner */
+
+  --distance-micro: 4px;
+  --distance-small: 6px;
+  --distance-base: 8px;
+  --distance-medium: 12px;
+  --distance-large: 30px;
+
+  --scale-large: 0.96; /* modal */
+  --scale-medium: 0.97; /* dropdown, popover open */
+  --scale-small: 0.98; /* tooltip */
+  --scale-tiny: 0.99; /* dropdown close */
+
+  --blur-small: 2px;
+  --blur-medium: 3px;
+  --blur-large: 8px;
+}
+
+/* Tailwind utility aliases, so `shadow-card`, `duration-fast` and
+   `ease-smooth-out` exist as classes and a component can stay in utilities
+   instead of dropping into a style block for one shadow. */
+@theme inline {
+  --shadow-hairline: var(--elev-hairline);
+  --shadow-btn: var(--elev-btn);
+  --shadow-card: var(--elev-card);
+  --shadow-raised: var(--elev-raised);
+  --shadow-overlay: var(--elev-overlay);
+  --shadow-field: var(--elev-field);
+  --shadow-rim: var(--elev-rim);
+  /* A filled control: the lit top edge and the resting lift, in one class,
+     because the two never appear apart and utilities cannot be stacked. */
+  --shadow-key: var(--elev-rim), var(--elev-btn);
+  /* The composed pair, for a surface that draws no border of its own. */
+  --shadow-edge-card: var(--elev-hairline), var(--elev-card);
+  --shadow-edge-raised: var(--elev-hairline), var(--elev-raised);
+  --shadow-edge-overlay: var(--elev-hairline), var(--elev-overlay);
+
+  --ease-smooth-out: var(--ease-smooth-out);
+
+  /* WHY the durations are re-declared under a second name: Tailwind's
+     `duration-*` utility reads `--transition-duration-*`, not `--duration-*`, so
+     the six names above generated no class at all. `duration-fast` therefore
+     compiled to nothing and the element ended up at `transition-duration: 0s`:
+     no error, no warning, and a component that simply does not animate. The
+     comment at the top of this block had claimed `duration-fast` was a class
+     since the block was written. Found 31 Aug 2026 by probing a live page. */
+  --transition-duration-micro: var(--duration-micro);
+  --transition-duration-quick: var(--duration-quick);
+  --transition-duration-fast: var(--duration-fast);
+  --transition-duration-medium: var(--duration-medium);
+  --transition-duration-slow: var(--duration-slow);
+  --transition-duration-very-slow: var(--duration-very-slow);
+}
+
+/* The bits-ui state variants every primitive in `./shadcn` is written against.
+ *
+ * bits-ui v2 writes `data-checked` / `data-open` and v1 wrote
+ * `data-state="checked"`, so each variant matches both and a component does not
+ * have to know which it is talking to. They live here rather than in a
+ * consumer's stylesheet because the classes that need them ship in this
+ * package: an app that defines only the palette rendered a switch that never
+ * moved. Moved out of upsys `tokens.css` on 14 Sep 2026, with the kit. */
+@custom-variant data-open {
+  &:where([data-state="open"]),
+  &:where([data-open]:not([data-open="false"])) {
+    @slot;
+  }
+}
+
+@custom-variant data-closed {
+  &:where([data-state="closed"]),
+  &:where([data-closed]:not([data-closed="false"])) {
+    @slot;
+  }
+}
+
+@custom-variant data-checked {
+  &:where([data-state="checked"]),
+  &:where([data-checked]:not([data-checked="false"])) {
+    @slot;
+  }
+}
+
+@custom-variant data-unchecked {
+  &:where([data-state="unchecked"]),
+  &:where([data-unchecked]:not([data-unchecked="false"])) {
+    @slot;
+  }
+}
+
+@custom-variant data-selected {
+  &:where([data-selected]) {
+    @slot;
+  }
+}
+
+@custom-variant data-disabled {
+  &:where([data-disabled="true"]),
+  &:where([data-disabled]:not([data-disabled="false"])) {
+    @slot;
+  }
+}
+
+@custom-variant data-active {
+  &:where([data-state="active"]),
+  &:where([data-active]:not([data-active="false"])) {
+    @slot;
+  }
+}
+
+@custom-variant data-horizontal {
+  &:where([data-orientation="horizontal"]) {
+    @slot;
+  }
+}
+
+@custom-variant data-vertical {
+  &:where([data-orientation="vertical"]) {
+    @slot;
+  }
+}

package/src/design/polish.css

@@ -0,0 +1,159 @@
+/* The rules the craft layer applies for itself.
+ *
+ * Two layers, on purpose. `base` holds the element defaults (focus, selection,
+ * scrollbars) so any component class or utility beats them. `components` holds
+ * the three motion primitives, so a utility still beats those too.
+ *
+ * WHY the layers are not optional: an `@import` at the top of an app stylesheet
+ * lands OUTSIDE Tailwind's layers, and unlayered CSS beats every layered rule
+ * whatever its specificity. Written bare, a `:where()` selector here would
+ * silently outrank `focus-visible:ring-3` on every control in the app.
+ *
+ * Imported by ./index.css. Do not import it on its own, because it reads the tokens
+ * that file declares. */
+
+@layer base {
+  /* One ring for the whole kit. `:where` keeps it at specificity zero on top of
+     the layer, so a control that needs a different ring writes one and wins. */
+  :where(a, button, input, select, textarea, summary, [tabindex]):focus-visible {
+    outline: none;
+    box-shadow: var(--ring-focus);
+  }
+
+  /* The accent at a low alpha, not the browser blue, because a selected word is
+     the one moment the palette shows up inside running text. */
+  ::selection {
+    background: color-mix(in oklab, var(--ring-color) 24%, transparent);
+  }
+
+  /* A default macOS overlay scrollbar paints a black bar on a dark panel. Track
+     transparent, thumb on the line token, so it belongs to whatever surface it
+     is over. The border is what insets the thumb without a second element. */
+  :where(html) {
+    scrollbar-color: var(--color-border, var(--border)) transparent;
+  }
+
+  ::-webkit-scrollbar {
+    width: 10px;
+    height: 10px;
+  }
+
+  ::-webkit-scrollbar-track {
+    background: transparent;
+  }
+
+  ::-webkit-scrollbar-thumb {
+    border: 3px solid transparent;
+    background-clip: padding-box;
+    border-radius: 999px;
+    background-color: var(--color-border, var(--border));
+  }
+
+  ::-webkit-scrollbar-thumb:hover {
+    background-color: var(--color-muted-foreground, var(--muted-foreground));
+  }
+}
+
+@layer components {
+  /* Three moves the kit repeats. They are classes rather than tokens because a
+     component wants one name, not four declarations, and because the reduced
+     motion guard then lives in one place instead of in every component.
+
+     Namespaced `t-` to match the transitions-dev snippets, which these sit
+     beside rather than duplicate. */
+
+  /* A control that reads as a key: it travels down a pixel under the finger.
+     The travel is what sells it, because a colour change alone reads as a hover
+     state, not as a press. */
+  .t-press {
+    transition:
+      background-color var(--duration-quick) var(--ease-smooth-out),
+      border-color var(--duration-quick) var(--ease-smooth-out),
+      color var(--duration-quick) var(--ease-smooth-out),
+      box-shadow var(--duration-quick) var(--ease-smooth-out),
+      transform var(--duration-micro) var(--ease-smooth-out);
+  }
+
+  .t-press:active:not(:disabled, [aria-disabled="true"]) {
+    transform: translateY(1px);
+  }
+
+  /* A card that answers the pointer. It rises by a pixel and gains the next
+     step of elevation, so the hover reads as the card coming forward rather
+     than as its border changing colour. */
+  .t-lift {
+    transition:
+      box-shadow var(--duration-fast) var(--ease-smooth-out),
+      transform var(--duration-fast) var(--ease-smooth-out);
+  }
+
+  .t-lift:hover {
+    transform: translateY(-1px);
+    box-shadow: var(--elev-raised);
+  }
+
+  /* A surface arriving. The open carries the distance, the scale and the blur;
+     the close drops all three and takes less time, per the open/close
+     asymmetry rule in transitions-dev. */
+  .t-enter {
+    animation: t-enter var(--duration-fast) var(--ease-smooth-out) both;
+  }
+
+  .t-exit {
+    animation: t-exit var(--duration-quick) var(--ease-smooth-out) both;
+  }
+
+  @media (prefers-reduced-motion: reduce) {
+    .t-press,
+    .t-lift {
+      transition: none;
+    }
+
+    .t-press:active,
+    .t-lift:hover {
+      transform: none;
+    }
+
+    .t-enter,
+    .t-exit {
+      animation-duration: 1ms;
+    }
+  }
+}
+
+@keyframes t-enter {
+  from {
+    opacity: 0;
+    transform: translateY(var(--distance-micro)) scale(var(--scale-medium));
+    filter: blur(var(--blur-small));
+  }
+  to {
+    opacity: 1;
+    transform: none;
+    filter: none;
+  }
+}
+
+/* A mark confirming a state that has already changed: it arrives after the box
+   it sits in, so it overshoots slightly instead of fading. */
+@keyframes t-check {
+  from {
+    opacity: 0;
+    transform: scale(0.4);
+  }
+  to {
+    opacity: 1;
+    transform: scale(1);
+  }
+}
+
+@keyframes t-exit {
+  from {
+    opacity: 1;
+    transform: none;
+  }
+  to {
+    opacity: 0;
+    transform: scale(var(--scale-tiny));
+  }
+}

package/src/effects/animated-beam/AnimatedBeam.svelte

@@ -0,0 +1,132 @@
+<script lang="ts" module>
+	import type { AnimatedBeamProps } from "./types.js";
+</script>
+
+<script lang="ts">
+	// =========================
+	// IMPORTS
+	// =========================
+	import { cn } from "@heyramzi/utils";
+	import BeamSvg from "./diagrams/BeamSvg.svelte";
+	import { usePathCalculator } from "./path-calculator.svelte.js";
+
+	// =========================
+	// PROPS
+	// =========================
+	let {
+		class: className,
+		containerRef,
+		fromRef,
+		toRef,
+		curvature = 0,
+		reverse = false,
+		duration = 4,
+		delay = 0,
+		pathColor = "gray",
+		pathWidth = 2,
+		pathOpacity = 0.2,
+		gradientStartColor = "#ffaa40",
+		gradientStopColor = "#414fd2",
+		startXOffset = 0,
+		startYOffset = 0,
+		endXOffset = 0,
+		endYOffset = 0,
+		fromAnchor = "center",
+		toAnchor = "center",
+	}: AnimatedBeamProps = $props();
+
+	// =========================
+	// STATE
+	// =========================
+	const id = `beam-${Math.random().toString(36).slice(2, 10)}`;
+	const path = usePathCalculator();
+	let motionOK = $state(true);
+
+	// ========================= DERIVED ========================= WHY: a short bright band (the stops) is swept along the path by animating the
+
+	// gradient vector. forward runs the comet from start to end, reverse the other way.
+
+	// Same coordinate pairs the motion-sv version used, as SMIL value lists, so no animation runtime is pulled into the dependency-free package.
+	const coords = $derived(
+		reverse ? { x1: "90%;-10%", x2: "100%;0%" } : { x1: "10%;110%", x2: "0%;100%" },
+	);
+
+	// =========================
+	// FUNCTIONS
+	// =========================
+	function updatePath() {
+		path.calculatePath(
+			containerRef,
+			fromRef,
+			toRef,
+			curvature,
+			startXOffset,
+			startYOffset,
+			endXOffset,
+			endYOffset,
+			fromAnchor,
+			toAnchor,
+		);
+	}
+
+	// =========================
+	// EFFECTS
+	// =========================
+	$effect(() => {
+		// WHY: touch every geometry input so the path recomputes when a ref,
+		// anchor, or offset changes, not just on container resize.
+		void [
+			containerRef,
+			fromRef,
+			toRef,
+			curvature,
+			startXOffset,
+			startYOffset,
+			endXOffset,
+			endYOffset,
+			fromAnchor,
+			toAnchor,
+		];
+		updatePath();
+		if (!containerRef) return;
+		let raf = 0;
+		const ro = new ResizeObserver(() => {
+			cancelAnimationFrame(raf);
+			raf = requestAnimationFrame(updatePath);
+		});
+		ro.observe(containerRef);
+		return () => {
+			cancelAnimationFrame(raf);
+			ro.disconnect();
+		};
+	});
+
+	$effect(() => {
+		if (typeof window === "undefined") return;
+		const mq = window.matchMedia("(prefers-reduced-motion: reduce)");
+		motionOK = !mq.matches;
+		const onChange = () => (motionOK = !mq.matches);
+		mq.addEventListener("change", onChange);
+		return () => mq.removeEventListener("change", onChange);
+	});
+</script>
+
+<!-- =========================== -->
+<!-- MARKUP -->
+<!-- =========================== -->
+<BeamSvg
+	{id}
+	class={cn("pointer-events-none absolute left-0 top-0 transform-gpu stroke-2", className)}
+	width={path.svgDimensions.width}
+	height={path.svgDimensions.height}
+	pathD={path.pathD}
+	{pathColor}
+	{pathWidth}
+	{pathOpacity}
+	{motionOK}
+	{coords}
+	{duration}
+	{delay}
+	{gradientStartColor}
+	{gradientStopColor}
+/>

package/src/effects/animated-beam/diagrams/BeamSvg.svelte

@@ -0,0 +1,91 @@
+<script lang="ts">
+	// =========================
+	// PROPS
+	// =========================
+	type Props = {
+		id: string;
+		class?: string;
+		width: number;
+		height: number;
+		pathD: string;
+		pathColor: string;
+		pathWidth: number;
+		pathOpacity: number;
+		motionOK: boolean;
+		coords: { x1: string; x2: string };
+		duration: number;
+		delay: number;
+		gradientStartColor: string;
+		gradientStopColor: string;
+	};
+	let {
+		id,
+		class: className,
+		width,
+		height,
+		pathD,
+		pathColor,
+		pathWidth,
+		pathOpacity,
+		motionOK,
+		coords,
+		duration,
+		delay,
+		gradientStartColor,
+		gradientStopColor,
+	}: Props = $props();
+</script>
+
+<svg
+	fill="none"
+	{width}
+	{height}
+	xmlns="http://www.w3.org/2000/svg"
+	class={className}
+	viewBox="0 0 {width} {height}"
+>
+	<path
+		d={pathD}
+		stroke={pathColor}
+		stroke-width={pathWidth}
+		stroke-opacity={pathOpacity}
+		stroke-linecap="round"
+	/>
+	{#if motionOK}
+		<path
+			d={pathD}
+			stroke-width={pathWidth}
+			stroke={`url(#${id})`}
+			stroke-opacity="1"
+			stroke-linecap="round"
+		/>
+		<defs>
+			<linearGradient {id} gradientUnits="userSpaceOnUse" x1="0%" x2="0%" y1="0%" y2="0%">
+				<animate
+					attributeName="x1"
+					values={coords.x1}
+					dur="{duration}s"
+					begin="{delay}s"
+					calcMode="spline"
+					keyTimes="0;1"
+					keySplines="0.16 1 0.3 1"
+					repeatCount="indefinite"
+				/>
+				<animate
+					attributeName="x2"
+					values={coords.x2}
+					dur="{duration}s"
+					begin="{delay}s"
+					calcMode="spline"
+					keyTimes="0;1"
+					keySplines="0.16 1 0.3 1"
+					repeatCount="indefinite"
+				/>
+				<stop stop-color={gradientStartColor} stop-opacity="0"></stop>
+				<stop stop-color={gradientStartColor}></stop>
+				<stop offset="32.5%" stop-color={gradientStopColor}></stop>
+				<stop offset="100%" stop-color={gradientStopColor} stop-opacity="0"></stop>
+			</linearGradient>
+		</defs>
+	{/if}
+</svg>

package/src/effects/animated-beam/index.ts

@@ -0,0 +1,2 @@
+export { default as AnimatedBeam } from "./AnimatedBeam.svelte";
+export type { AnimatedBeamProps, AnchorPosition } from "./types.js";