@hyvnt/hyvui 0.2.0 → 0.4.0

package/dist/components/depth/DepthStage.svelte

@@ -1,62 +1,67 @@
-<script lang="ts">
-  import { cn } from '../../utils/cn.js';
-  import type { PerspectivePreset } from '../../system/depth/depth.js';
-  import type { Snippet } from 'svelte';
-
-  interface Props {
-    /** Perspective distance preset. */
-    perspective?: PerspectivePreset;
-    /** CSS percentage for horizontal perspective origin. */
-    originX?: string;
-    /** CSS percentage for vertical perspective origin. */
-    originY?: string;
-    /** HTML tag to render. */
-    as?: string;
-    /** Additional CSS classes. */
-    class?: string;
-    /** Stage content. */
-    children?: Snippet;
-  }
-
-  let {
-    perspective = 'mid',
-    originX = '50%',
-    originY = '40%',
-    as = 'div',
-    class: className = '',
-    children,
-  }: Props = $props();
-
-  const perspectiveMap: Record<PerspectivePreset, string> = {
-    near: 'var(--perspective-near)',
-    mid: 'var(--perspective-mid)',
-    far: 'var(--perspective-far)',
-  };
-</script>
-
-<svelte:element
-  this={as}
-  class={cn('hyvui-depth-stage', className)}
-  style:perspective={perspectiveMap[perspective]}
-  style:perspective-origin="{originX} {originY}"
->
-  {#if children}{@render children()}{/if}
-</svelte:element>
-
-<style>
-  .hyvui-depth-stage {
-    transform-style: preserve-3d;
-    position: relative;
-  }
-
-  .hyvui-depth-stage > :global(*) {
-    transform-style: preserve-3d;
-  }
-
-  @media (prefers-reduced-motion: reduce) {
-    .hyvui-depth-stage {
-      perspective: none !important;
-      transform-style: flat;
-    }
-  }
-</style>
+<script lang="ts">
+	import { cn } from '../../utils/cn.js';
+	import type { PerspectivePreset } from '../../system/depth/depth.js';
+	import type { Snippet } from 'svelte';
+
+	/**
+	 * Establishes CSS 3D perspective context. Wrap any 3D composition in this.
+	 * @example
+	 * <DepthStage perspective="mid">
+	 *   <DepthLayer level="ground"><HorizonGrid /></DepthLayer>
+	 *   <DepthLayer level="raised"><FloatCard>content</FloatCard></DepthLayer>
+	 * </DepthStage>
+	 */
+	interface Props {
+		/** Perspective distance preset. */
+		perspective?: PerspectivePreset;
+		/** CSS percentage for horizontal perspective origin. */
+		originX?: string;
+		/** CSS percentage for vertical perspective origin. */
+		originY?: string;
+		/** HTML tag to render. */
+		as?: string;
+		/** Additional CSS classes. */
+		class?: string;
+		/** Stage content. */
+		children?: Snippet;
+	}
+
+	let {
+		perspective = 'mid',
+		originX = '50%',
+		originY = '40%',
+		as = 'div',
+		class: className = '',
+		children
+	}: Props = $props();
+
+	const perspectiveMap: Record<PerspectivePreset, string> = {
+		near: 'var(--perspective-near)',
+		mid: 'var(--perspective-mid)',
+		far: 'var(--perspective-far)'
+	};
+</script>
+
+<svelte:element
+	this={as}
+	class={cn('hyvui-depth-stage', className)}
+	style:perspective={perspectiveMap[perspective]}
+	style:perspective-origin="{originX}
+	{originY}"
+>
+	{#if children}{@render children()}{/if}
+</svelte:element>
+
+<style>
+	.hyvui-depth-stage {
+		transform-style: preserve-3d;
+		position: relative;
+	}
+
+	@media (prefers-reduced-motion: reduce) {
+		.hyvui-depth-stage {
+			perspective: none !important;
+			transform-style: flat;
+		}
+	}
+</style>

package/dist/components/depth/DepthStage.svelte.d.ts

@@ -1,5 +1,13 @@
 import type { PerspectivePreset } from '../../system/depth/depth.js';
 import type { Snippet } from 'svelte';
+/**
+ * Establishes CSS 3D perspective context. Wrap any 3D composition in this.
+ * @example
+ * <DepthStage perspective="mid">
+ *   <DepthLayer level="ground"><HorizonGrid /></DepthLayer>
+ *   <DepthLayer level="raised"><FloatCard>content</FloatCard></DepthLayer>
+ * </DepthStage>
+ */
 interface Props {
     /** Perspective distance preset. */
     perspective?: PerspectivePreset;

package/dist/components/depth/FloatCard.svelte

@@ -1,104 +1,129 @@
-<script lang="ts">
-  import { cn } from '../../utils/cn.js';
-  import { tiltTransform } from '../../system/depth/depth.js';
-  import Surface from '../primitives/Surface.svelte';
-  import type { Snippet } from 'svelte';
-
-  interface Props {
-    /** Maximum tilt angle in degrees. */
-    tiltMax?: number;
-    /** Z-elevation on hover. */
-    elevation?: 'raised' | 'foreground';
-    /** Additional CSS classes. */
-    class?: string;
-    /** Card content. */
-    children?: Snippet;
-  }
-
-  let {
-    tiltMax = 8,
-    elevation = 'raised',
-    class: className = '',
-    children,
-  }: Props = $props();
-
-  let innerTransform = $state('rotateX(0deg) rotateY(0deg) translateZ(0px)');
-  let isHovering = $state(false);
-
-  const prefersReduced =
-    typeof window !== 'undefined'
-      ? window.matchMedia('(prefers-reduced-motion: reduce)').matches
-      : false;
-
-  const elevationMap: Record<string, string> = {
-    raised: 'var(--depth-raised)',
-    foreground: 'var(--depth-foreground)',
-  };
-
-  function handlePointerMove(e: PointerEvent) {
-    if (prefersReduced) return;
-    const rect = (e.currentTarget as HTMLElement).getBoundingClientRect();
-    const x = (e.clientX - rect.left) / rect.width;
-    const y = (e.clientY - rect.top) / rect.height;
-    const tilt = tiltTransform(x, y, tiltMax);
-    innerTransform = `${tilt} translateZ(${elevationMap[elevation]})`;
-    isHovering = true;
-  }
-
-  function handlePointerLeave() {
-    isHovering = false;
-    innerTransform = 'rotateX(0deg) rotateY(0deg) translateZ(0px)';
-  }
-</script>
-
-<div
-  class={cn('hyvui-float-card', className)}
-  role="presentation"
-  onpointermove={handlePointerMove}
-  onpointerleave={handlePointerLeave}
->
-  <div
-    class="hyvui-float-card-inner"
-    class:hyvui-float-card-leaving={!isHovering}
-    style:transform={innerTransform}
-  >
-    <Surface variant="card" class="hyvui-float-card-surface">
-      {#if children}{@render children()}{/if}
-    </Surface>
-  </div>
-</div>
-
-<style>
-  .hyvui-float-card {
-    perspective: var(--perspective-mid);
-    perspective-origin: 50% 50%;
-  }
-
-  .hyvui-float-card-inner {
-    transform-style: preserve-3d;
-    will-change: transform;
-  }
-
-  .hyvui-float-card-leaving {
-    transition: transform var(--depth-transition);
-  }
-
-  :global(.hyvui-float-card-surface) {
-    padding: var(--space-card);
-  }
-
-  @media (prefers-reduced-motion: reduce) {
-    .hyvui-float-card {
-      perspective: none;
-    }
-
-    .hyvui-float-card-inner {
-      transform: none !important;
-      transform-style: flat;
-    }
-
-    .hyvui-float-card-leaving {
-      transition: none;
-    }
-  }
-</style>
+<script lang="ts">
+	import { cn } from '../../utils/cn.js';
+	import { tiltTransform } from '../../system/depth/depth.js';
+	import Surface from '../primitives/Surface.svelte';
+	import type { Snippet } from 'svelte';
+	import { onMount } from 'svelte';
+
+	/**
+	 * Self-contained pointer-tilt card. Works standalone or inside a DepthStage.
+	 * @example
+	 * <FloatCard tiltMax={6}>
+	 *   <Text variant="heading">floating content</Text>
+	 *   <Text>card body</Text>
+	 * </FloatCard>
+	 */
+	interface Props {
+		/** Maximum tilt angle in degrees. */
+		tiltMax?: number;
+		/** Z-elevation on hover. */
+		elevation?: 'raised' | 'foreground';
+		/** Additional CSS classes. */
+		class?: string;
+		/** Card content. */
+		children?: Snippet;
+	}
+
+	let { tiltMax = 8, elevation = 'raised', class: className = '', children }: Props = $props();
+
+	let innerEl: HTMLDivElement | undefined = $state();
+	let tiltEnabled = $state(false);
+	let frame = 0;
+	let lastX = 0;
+	let lastY = 0;
+
+	const elevationMap: Record<string, string> = {
+		raised: 'var(--depth-raised)',
+		foreground: 'var(--depth-foreground)'
+	};
+
+	onMount(() => {
+		const reduced = window.matchMedia('(prefers-reduced-motion: reduce)').matches;
+		const finePointer = window.matchMedia('(hover: hover) and (pointer: fine)').matches;
+		tiltEnabled = !reduced && finePointer;
+	});
+
+	function handlePointerMove(e: PointerEvent) {
+		if (!tiltEnabled || !innerEl) return;
+		const rect = (e.currentTarget as HTMLElement).getBoundingClientRect();
+		lastX = (e.clientX - rect.left) / rect.width;
+		lastY = (e.clientY - rect.top) / rect.height;
+
+		if (!innerEl.style.willChange) innerEl.style.willChange = 'transform';
+		innerEl.classList.remove('hyvui-float-card-leaving');
+		if (frame) return;
+		frame = requestAnimationFrame(() => {
+			frame = 0;
+			if (!innerEl) return;
+			const tilt = tiltTransform(lastX, lastY, tiltMax);
+			innerEl.style.transform = `${tilt} translateZ(${elevationMap[elevation]})`;
+		});
+	}
+
+	function handlePointerLeave() {
+		if (!innerEl) return;
+		if (frame) cancelAnimationFrame(frame);
+		frame = 0;
+		innerEl.classList.add('hyvui-float-card-leaving');
+		innerEl.style.transform = 'rotateX(0deg) rotateY(0deg) translateZ(0px)';
+		innerEl.addEventListener(
+			'transitionend',
+			() => {
+				if (innerEl) innerEl.style.willChange = '';
+			},
+			{ once: true }
+		);
+	}
+</script>
+
+<div
+	class={cn('hyvui-float-card', className)}
+	role="presentation"
+	onpointermove={handlePointerMove}
+	onpointerleave={handlePointerLeave}
+>
+	<div
+		class="hyvui-float-card-inner hyvui-float-card-leaving"
+		bind:this={innerEl}
+		style:transform="rotateX(0deg) rotateY(0deg) translateZ(0px)"
+	>
+		<Surface variant="card" class="hyvui-float-card-surface">
+			{#if children}{@render children()}{/if}
+		</Surface>
+	</div>
+</div>
+
+<style>
+	.hyvui-float-card {
+		perspective: var(--perspective-mid);
+		perspective-origin: 50% 50%;
+	}
+
+	.hyvui-float-card-inner {
+		transform-style: preserve-3d;
+		backface-visibility: hidden;
+	}
+
+	.hyvui-float-card-leaving {
+		transition: transform var(--depth-transition);
+	}
+
+	:global(.hyvui-float-card-surface) {
+		padding: var(--space-card);
+	}
+
+	@media (prefers-reduced-motion: reduce) {
+		.hyvui-float-card {
+			perspective: none;
+		}
+
+		.hyvui-float-card-inner {
+			transform: none !important;
+			transform-style: flat;
+		}
+
+		.hyvui-float-card-leaving {
+			transition: none;
+		}
+	}
+</style>

package/dist/components/depth/FloatCard.svelte.d.ts

@@ -1,4 +1,12 @@
 import type { Snippet } from 'svelte';
+/**
+ * Self-contained pointer-tilt card. Works standalone or inside a DepthStage.
+ * @example
+ * <FloatCard tiltMax={6}>
+ *   <Text variant="heading">floating content</Text>
+ *   <Text>card body</Text>
+ * </FloatCard>
+ */
 interface Props {
     /** Maximum tilt angle in degrees. */
     tiltMax?: number;