@heyramzi/ui 0.0.0-stage → 1.53.0

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";

package/src/effects/animated-beam/path-calculator.svelte.ts

@@ -0,0 +1,70 @@
+import type { AnchorPosition } from "./types.js";
+
+function anchorX(
+  rect: DOMRect,
+  containerLeft: number,
+  anchor: AnchorPosition,
+  offset: number,
+): number {
+  const left = rect.left - containerLeft;
+  if (anchor === "left") return left + offset;
+  if (anchor === "right") return left + rect.width + offset;
+  return left + rect.width / 2 + offset;
+}
+
+export function usePathCalculator() {
+  let pathD = $state("");
+  let svgDimensions = $state({ width: 0, height: 0 });
+
+  function calculatePath(
+    containerRef: HTMLElement | null,
+    fromRef: HTMLElement | null,
+    toRef: HTMLElement | null,
+    curvature: number,
+    startXOffset: number,
+    startYOffset: number,
+    endXOffset: number,
+    endYOffset: number,
+    fromAnchor: AnchorPosition = "center",
+    toAnchor: AnchorPosition = "center",
+  ) {
+    if (!containerRef || !fromRef || !toRef) return;
+
+    const containerRect = containerRef.getBoundingClientRect();
+    const rectA = fromRef.getBoundingClientRect();
+    const rectB = toRef.getBoundingClientRect();
+
+    svgDimensions = { width: containerRect.width, height: containerRect.height };
+
+    const startX = anchorX(rectA, containerRect.left, fromAnchor, startXOffset);
+    const startY = rectA.top - containerRect.top + rectA.height / 2 + startYOffset;
+    const endX = anchorX(rectB, containerRect.left, toAnchor, endXOffset);
+    const endY = rectB.top - containerRect.top + rectB.height / 2 + endYOffset;
+
+    // A cubic with horizontal handles, not a quadratic through a raised midpoint.
+
+    // The quadratic put its single control point at `midY - curvature`, which for a fan into one node lands past the far end:
+
+    // the top beam dove below the hub and crossed the middle beam before arriving, and three beams bundled into a lens for the last stretch.
+
+    // Handles along the axis of travel make each beam leave and arrive perpendicular to its anchor, so a fan converges at the anchor and nowhere else.
+
+    // `curvature` still bows the middle, and zero still draws a straight line between two anchors at the same height.
+    const span = Math.abs(endX - startX);
+    const handle = Math.max(span * 0.5, 24);
+    const direction = endX >= startX ? 1 : -1;
+    const c1x = startX + handle * direction;
+    const c2x = endX - handle * direction;
+    pathD = `M ${startX},${startY} C ${c1x},${startY - curvature} ${c2x},${endY - curvature} ${endX},${endY}`;
+  }
+
+  return {
+    get pathD() {
+      return pathD;
+    },
+    get svgDimensions() {
+      return svgDimensions;
+    },
+    calculatePath,
+  };
+}

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

@@ -0,0 +1,23 @@
+export type AnchorPosition = "center" | "left" | "right";
+
+export interface AnimatedBeamProps {
+  class?: string;
+  containerRef: HTMLElement | null;
+  fromRef: HTMLElement | null;
+  toRef: HTMLElement | null;
+  curvature?: number;
+  reverse?: boolean;
+  pathColor?: string;
+  pathWidth?: number;
+  pathOpacity?: number;
+  gradientStartColor?: string;
+  gradientStopColor?: string;
+  delay?: number;
+  duration?: number;
+  startXOffset?: number;
+  startYOffset?: number;
+  endXOffset?: number;
+  endYOffset?: number;
+  fromAnchor?: AnchorPosition;
+  toAnchor?: AnchorPosition;
+}

package/src/effects/border-beam/BorderBeam.svelte

@@ -0,0 +1,223 @@
+<script lang="ts" module>
+	import type { ResolvedTheme } from "./presets.js";
+	import type { BorderBeamProps } from "./types.js";
+</script>
+
+<script lang="ts">
+	// IMPORTS
+	import { onDestroy, onMount } from "svelte";
+	import { generateCss } from "./css.js";
+	import { sizePresets, sizeThemePresets } from "./presets.js";
+	import { registerBorderBeamProperties } from "./register-properties.js";
+
+	// PROPS
+	let {
+		children,
+		size = "md",
+		colorVariant = "colorful",
+		theme = "dark",
+		staticColors = false,
+		duration,
+		active = true,
+		borderRadius,
+		brightness = 1.3,
+		saturation,
+		hueRange = 30,
+		strength = 1,
+		colors,
+		bloom = true,
+		pauseWhenOffscreen = true,
+		class: className,
+		onActivate,
+		onDeactivate,
+		onanimationend: userAnimationEnd,
+		style: userStyle,
+		...rest
+	}: BorderBeamProps = $props();
+
+	// STATE
+	const uid = `bb-${Math.random().toString(36).slice(2, 10)}`;
+	let container = $state<HTMLElement | null>(null);
+	let systemTheme = $state<ResolvedTheme>("dark");
+	let isActive = $state(false);
+	let isFading = $state(false);
+	let detectedRadius = $state<number | null>(null);
+	let isOffscreen = $state(false);
+	let isDocHidden = $state(false);
+
+	// DERIVED
+	const resolvedTheme = $derived(theme === "auto" ? systemTheme : theme);
+	const sizeConfig = $derived(sizePresets[size]);
+	const themeColorsForSize = $derived(sizeThemePresets[size][resolvedTheme]);
+	const effectiveRadius = $derived(borderRadius ?? detectedRadius ?? sizeConfig.borderRadius);
+	const effectiveDuration = $derived(duration ?? (size === "line" ? 2.4 : 1.96));
+	const effectiveSaturation = $derived(saturation ?? themeColorsForSize.saturation);
+	const effectiveHueRange = $derived(size === "line" ? Math.min(hueRange, 13) : hueRange);
+	const resolvedStatic = $derived(colorVariant === "mono" ? true : staticColors);
+
+	const css = $derived(
+		generateCss({
+			id: uid,
+			borderRadius: effectiveRadius,
+			borderWidth: sizeConfig.borderWidth,
+			duration: effectiveDuration,
+			strokeOpacity: themeColorsForSize.strokeOpacity,
+			innerOpacity: themeColorsForSize.innerOpacity,
+			bloomOpacity: themeColorsForSize.bloomOpacity,
+			innerShadow: themeColorsForSize.innerShadow,
+			size,
+			colorVariant,
+			staticColors: resolvedStatic,
+			brightness,
+			saturation: effectiveSaturation,
+			hueRange: effectiveHueRange,
+			theme: resolvedTheme,
+			colors,
+			bloom,
+		}),
+	);
+
+	// WHY: paused state combines viewport visibility and document visibility.
+	// Either being false freezes the beam via `animation-play-state: paused`.
+	const paused = $derived(pauseWhenOffscreen && (isOffscreen || isDocHidden));
+
+	const clampedStrength = $derived(Math.max(0, Math.min(1, strength)));
+
+	// EFFECTS
+	let mediaQuery: MediaQueryList | null = null;
+	let radiusObserver: MutationObserver | null = null;
+	let visibilityObserver: IntersectionObserver | null = null;
+
+	onMount(() => {
+		// WHY: shadow-DOM consumers (chrome extensions, embedded widgets) hit a Chromium edge case where @property at-rules emitted in an injected stylesheet do not register reliably for the shadow scope.
+
+		// Without the registration, the angle property is treated as a string, the keyframe can't interpolate, and the beam appears frozen with one repaint per iteration.
+
+		// CSS.registerProperty is global and document-scoped so it always succeeds, and duplicate registrations are silently ignored.
+		registerBorderBeamProperties(uid, size);
+
+		if (typeof window !== "undefined") {
+			mediaQuery = window.matchMedia("(prefers-color-scheme: dark)");
+			systemTheme = mediaQuery.matches ? "dark" : "light";
+			const handler = (e: MediaQueryListEvent) => {
+				systemTheme = e.matches ? "dark" : "light";
+			};
+			mediaQuery.addEventListener("change", handler);
+			return () => mediaQuery?.removeEventListener("change", handler);
+		}
+	});
+
+	$effect(() => {
+		if (borderRadius != null || !container) return;
+		const detect = () => {
+			const first = container?.firstElementChild as HTMLElement | null;
+			if (!first) return;
+			const cs = getComputedStyle(first);
+			const r = parseFloat(cs.borderTopLeftRadius);
+			if (!isNaN(r) && r > 0) detectedRadius = r;
+		};
+		detect();
+		radiusObserver = new MutationObserver(detect);
+		radiusObserver.observe(container, { childList: true, subtree: false });
+		return () => radiusObserver?.disconnect();
+	});
+
+	$effect(() => {
+		if (active && !isActive && !isFading) {
+			isActive = true;
+		} else if (!active && isActive && !isFading) {
+			isFading = true;
+		}
+	});
+
+	// WHY: pause beam animation while the host is offscreen or the tab is hidden.
+
+	// CSS animations keep ticking on backgrounded tabs in some browsers, and an offscreen beam burns rasterization budget for nothing.
+	$effect(() => {
+		if (!pauseWhenOffscreen || !container || typeof window === "undefined") return;
+
+		visibilityObserver = new IntersectionObserver(
+			(entries) => {
+				const entry = entries[0];
+				if (entry) isOffscreen = !entry.isIntersecting;
+			},
+			{ rootMargin: "64px" },
+		);
+		visibilityObserver.observe(container);
+
+		const onVisChange = () => {
+			isDocHidden = document.hidden;
+		};
+		isDocHidden = document.hidden;
+		document.addEventListener("visibilitychange", onVisChange);
+
+		return () => {
+			visibilityObserver?.disconnect();
+			visibilityObserver = null;
+			document.removeEventListener("visibilitychange", onVisChange);
+		};
+	});
+
+	onDestroy(() => {
+		mediaQuery = null;
+		radiusObserver?.disconnect();
+		visibilityObserver?.disconnect();
+	});
+
+	// FUNCTIONS
+	function handleAnimationEnd(e: AnimationEvent) {
+		const name = e.animationName;
+		if (name.includes("fade-out")) {
+			isActive = false;
+			isFading = false;
+			onDeactivate?.();
+		} else if (name.includes("fade-in")) {
+			onActivate?.();
+		}
+		userAnimationEnd?.(e as AnimationEvent & { currentTarget: EventTarget & HTMLDivElement });
+	}
+
+	// WHY: imperative CSS injection via Svelte action. The rolldown-based
+
+	// vite-plugin-svelte preprocessor does naive substring matching for the stylesheet markup, so an inline @html template literal containing the markup tag would trip postcss on the interpolated text.
+
+	// The action route attaches a real stylesheet node next to the host, bypassing the HTML parser entirely.
+	function injectStyle(node: Element, value: string) {
+		const styleEl = node.ownerDocument.createElement("style");
+		styleEl.textContent = value;
+		node.parentNode?.insertBefore(styleEl, node);
+		// WHY: $derived recomputes on any prop change, but the CSS string is
+		// often identical across reruns. Skip the DOM write so the browser
+		// doesn't re-parse the stylesheet for no reason.
+		let last = value;
+		return {
+			update(next: string) {
+				if (next === last) return;
+				last = next;
+				styleEl.textContent = next;
+			},
+			destroy() {
+				styleEl.remove();
+			},
+		};
+	}
+</script>
+
+<!-- MARKUP -->
+<div
+	bind:this={container}
+	{...rest}
+	data-beam={uid}
+	data-active={isActive && !isFading ? "" : undefined}
+	data-fading={isFading ? "" : undefined}
+	data-paused={paused ? "" : undefined}
+	class={className}
+	style="--beam-strength: {clampedStrength};{userStyle ?? ''}"
+	onanimationend={handleAnimationEnd}
+	use:injectStyle={css}
+>
+	{@render children()}
+	{#if bloom}
+		<div data-beam-bloom></div>
+	{/if}
+</div>