@hyvnt/hyvui 0.3.0 → 0.4.0

package/dist/components/ambient/SignalRing.svelte

@@ -1,6 +1,12 @@
 <script lang="ts">
 	import { cn } from '../../utils/cn.js';
 
+	/**
+	 * Decorative pulsing sonar rings. Renders `aria-hidden`.
+	 * @example
+	 * <SignalRing size={160} color="var(--signal)" />
+	 * <SignalRing active={isLive} size={200} />
+	 */
 	interface Props {
 		/** Enable the pulsing animation. */
 		active?: boolean;
@@ -56,7 +62,7 @@
 		border-radius: 50%;
 		border: 1px solid;
 		opacity: 0;
-		animation: signal-ring-expand 3.6s ease-out infinite;
+		animation: signal-ring-expand 3.6s var(--ease-smooth) infinite;
 	}
 
 	.hyvui-signal-ring-1 {

package/dist/components/ambient/SignalRing.svelte.d.ts

@@ -1,3 +1,9 @@
+/**
+ * Decorative pulsing sonar rings. Renders `aria-hidden`.
+ * @example
+ * <SignalRing size={160} color="var(--signal)" />
+ * <SignalRing active={isLive} size={200} />
+ */
 interface Props {
     /** Enable the pulsing animation. */
     active?: boolean;

package/dist/components/ambient/ThreadLine.svelte

@@ -1,6 +1,13 @@
 <script lang="ts">
 	import { cn } from '../../utils/cn.js';
 
+	/**
+	 * Decorative SVG line with an optional traveling dot. Parent must have `position: relative`. Renders `aria-hidden`.
+	 * @example
+	 * <div style="position: relative; height: 200px;">
+	 *   <ThreadLine x1="0%" y1="0%" x2="100%" y2="100%" animated />
+	 * </div>
+	 */
 	interface Props {
 		/** Start x position (CSS value). */
 		x1?: string;

package/dist/components/ambient/ThreadLine.svelte.d.ts

@@ -1,3 +1,10 @@
+/**
+ * Decorative SVG line with an optional traveling dot. Parent must have `position: relative`. Renders `aria-hidden`.
+ * @example
+ * <div style="position: relative; height: 200px;">
+ *   <ThreadLine x1="0%" y1="0%" x2="100%" y2="100%" animated />
+ * </div>
+ */
 interface Props {
     /** Start x position (CSS value). */
     x1?: string;

package/dist/components/ambient/Vignette.svelte

@@ -1,6 +1,12 @@
 <script lang="ts">
 	import { cn } from '../../utils/cn.js';
 
+	/**
+	 * Fixed-position dark vignette overlay. Place once in root layout. Renders `aria-hidden`.
+	 * @example
+	 * <!-- in +layout.svelte (or use AppShell which adds it automatically) -->
+	 * <Vignette />
+	 */
 	interface Props {
 		/** Additional CSS classes. */
 		class?: string;

package/dist/components/ambient/Vignette.svelte.d.ts

@@ -1,3 +1,9 @@
+/**
+ * Fixed-position dark vignette overlay. Place once in root layout. Renders `aria-hidden`.
+ * @example
+ * <!-- in +layout.svelte (or use AppShell which adds it automatically) -->
+ * <Vignette />
+ */
 interface Props {
     /** Additional CSS classes. */
     class?: string;

package/dist/components/depth/DepthLayer.svelte

@@ -3,6 +3,14 @@
 	import type { DepthLevel } from '../../system/depth/depth.js';
 	import type { Snippet } from 'svelte';
 
+	/**
+	 * Places children at a named z-level within a DepthStage.
+	 * @example
+	 * <DepthStage>
+	 *   <DepthLayer level="ground"><HorizonGrid /></DepthLayer>
+	 *   <DepthLayer level="foreground"><Text variant="heading">in front</Text></DepthLayer>
+	 * </DepthStage>
+	 */
 	interface Props {
 		/** Z-level within a parent DepthStage. */
 		level?: DepthLevel;

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

@@ -1,5 +1,13 @@
 import type { DepthLevel } from '../../system/depth/depth.js';
 import type { Snippet } from 'svelte';
+/**
+ * Places children at a named z-level within a DepthStage.
+ * @example
+ * <DepthStage>
+ *   <DepthLayer level="ground"><HorizonGrid /></DepthLayer>
+ *   <DepthLayer level="foreground"><Text variant="heading">in front</Text></DepthLayer>
+ * </DepthStage>
+ */
 interface Props {
     /** Z-level within a parent DepthStage. */
     level?: DepthLevel;

package/dist/components/depth/DepthStage.svelte

@@ -3,6 +3,14 @@
 	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;
@@ -50,10 +58,6 @@
 		position: relative;
 	}
 
-	.hyvui-depth-stage > :global(*) {
-		transform-style: preserve-3d;
-	}
-
 	@media (prefers-reduced-motion: reduce) {
 		.hyvui-depth-stage {
 			perspective: none !important;

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

@@ -5,6 +5,14 @@
 	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;
@@ -41,6 +49,7 @@
 		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(() => {
@@ -57,6 +66,13 @@
 		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>
 
@@ -85,7 +101,7 @@
 
 	.hyvui-float-card-inner {
 		transform-style: preserve-3d;
-		will-change: transform;
+		backface-visibility: hidden;
 	}
 
 	.hyvui-float-card-leaving {

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;

package/dist/components/depth/HorizonGrid.svelte

@@ -2,6 +2,15 @@
 	import { cn } from '../../utils/cn.js';
 	import { onMount } from 'svelte';
 
+	/**
+	 * Canvas-drawn perspective grid with gold-to-teal gradient. Typically placed at ground level in a DepthStage.
+	 * @example
+	 * <DepthStage>
+	 *   <DepthLayer level="ground">
+	 *     <HorizonGrid rows={16} cols={10} vanishY={0.4} animated />
+	 *   </DepthLayer>
+	 * </DepthStage>
+	 */
 	interface Props {
 		/** Number of horizontal lines receding toward the vanishing point. */
 		rows?: number;
@@ -105,6 +114,10 @@
 		}
 
 		const dt = lastT ? t - lastT : 16;
+		if (lastT && dt < 32) {
+			animFrame = requestAnimationFrame(tick);
+			return;
+		}
 		lastT = t;
 
 		// Drift speed tuned to roughly match the previous "0.003 per frame" feel.
@@ -168,10 +181,22 @@
 			else if (animated && !prefersReduced && isVisible) start();
 		}
 
+		let scrollTimer = 0;
+		function onScroll() {
+			stop();
+			clearTimeout(scrollTimer);
+			scrollTimer = window.setTimeout(() => {
+				if (animated && !prefersReduced && isVisible && !document.hidden) start();
+			}, 150);
+		}
+
 		document.addEventListener('visibilitychange', onVisibility);
+		window.addEventListener('scroll', onScroll, { passive: true });
 
 		return () => {
 			document.removeEventListener('visibilitychange', onVisibility);
+			window.removeEventListener('scroll', onScroll);
+			clearTimeout(scrollTimer);
 			io.disconnect();
 			ro.disconnect();
 			stop();

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

@@ -1,3 +1,12 @@
+/**
+ * Canvas-drawn perspective grid with gold-to-teal gradient. Typically placed at ground level in a DepthStage.
+ * @example
+ * <DepthStage>
+ *   <DepthLayer level="ground">
+ *     <HorizonGrid rows={16} cols={10} vanishY={0.4} animated />
+ *   </DepthLayer>
+ * </DepthStage>
+ */
 interface Props {
     /** Number of horizontal lines receding toward the vanishing point. */
     rows?: number;

package/dist/components/depth/Plinth.svelte

@@ -1,6 +1,16 @@
 <script lang="ts">
 	import { cn } from '../../utils/cn.js';
 
+	/**
+	 * Near-invisible receding surface for anchoring floating elements in a DepthStage.
+	 * @example
+	 * <DepthStage>
+	 *   <DepthLayer level="raised">
+	 *     <FloatCard>content</FloatCard>
+	 *     <Plinth width="80%" depth="30px" />
+	 *   </DepthLayer>
+	 * </DepthStage>
+	 */
 	interface Props {
 		/** Width of the plinth surface. */
 		width?: string;

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

@@ -1,3 +1,13 @@
+/**
+ * Near-invisible receding surface for anchoring floating elements in a DepthStage.
+ * @example
+ * <DepthStage>
+ *   <DepthLayer level="raised">
+ *     <FloatCard>content</FloatCard>
+ *     <Plinth width="80%" depth="30px" />
+ *   </DepthLayer>
+ * </DepthStage>
+ */
 interface Props {
     /** Width of the plinth surface. */
     width?: string;

package/dist/components/display/Avatar.svelte

@@ -1,6 +1,11 @@
 <script lang="ts">
 	import { cn } from '../../utils/cn.js';
 
+	/**
+	 * @example
+	 * <Avatar name="Jane Doe" size={40} />
+	 * <Avatar src="/avatars/user.jpg" name="Jane Doe" size={32} />
+	 */
 	interface Props {
 		/** Image source URL. */
 		src?: string;

package/dist/components/display/Avatar.svelte.d.ts

@@ -1,3 +1,8 @@
+/**
+ * @example
+ * <Avatar name="Jane Doe" size={40} />
+ * <Avatar src="/avatars/user.jpg" name="Jane Doe" size={32} />
+ */
 interface Props {
     /** Image source URL. */
     src?: string;

package/dist/components/display/Badge.svelte

@@ -2,6 +2,12 @@
 	import { cn } from '../../utils/cn.js';
 	import type { Snippet } from 'svelte';
 
+	/**
+	 * @example
+	 * <Badge variant="ok">online</Badge>
+	 * <Badge variant="warn">degraded</Badge>
+	 * <Badge variant="accent">new</Badge>
+	 */
 	interface Props {
 		/** Badge color variant. */
 		variant?: 'default' | 'accent' | 'signal' | 'ok' | 'warn' | 'fail';
@@ -56,4 +62,14 @@
 		border-color: currentColor;
 		opacity: 0.8;
 	}
+
+	/* ── hextech: clipped top-left corner (hex gem cut) ───────────────── */
+	:global([data-register='hextech']) .hyvui-badge {
+		clip-path: polygon(6px 0%, 100% 0%, 100% 100%, 0% 100%, 0% 6px);
+	}
+
+	/* ── arcane: diagonal parallelogram cut ───────────────────────────── */
+	:global([data-register='arcane']) .hyvui-badge {
+		clip-path: polygon(5px 0%, 100% 0%, calc(100% - 5px) 100%, 0% 100%);
+	}
 </style>

package/dist/components/display/Badge.svelte.d.ts

@@ -1,4 +1,10 @@
 import type { Snippet } from 'svelte';
+/**
+ * @example
+ * <Badge variant="ok">online</Badge>
+ * <Badge variant="warn">degraded</Badge>
+ * <Badge variant="accent">new</Badge>
+ */
 interface Props {
     /** Badge color variant. */
     variant?: 'default' | 'accent' | 'signal' | 'ok' | 'warn' | 'fail';

package/dist/components/display/Blockquote.svelte

@@ -2,6 +2,10 @@
 	import { cn } from '../../utils/cn.js';
 	import type { Snippet } from 'svelte';
 
+	/**
+	 * @example
+	 * <Blockquote>the signal arrives before the message.</Blockquote>
+	 */
 	interface Props {
 		/** Additional CSS classes. */
 		class?: string;

package/dist/components/display/Blockquote.svelte.d.ts

@@ -1,4 +1,8 @@
 import type { Snippet } from 'svelte';
+/**
+ * @example
+ * <Blockquote>the signal arrives before the message.</Blockquote>
+ */
 interface Props {
     /** Additional CSS classes. */
     class?: string;

package/dist/components/display/CodeBlock.svelte

@@ -2,6 +2,11 @@
 	import { cn } from '../../utils/cn.js';
 	import Button from '../inputs/Button.svelte';
 
+	/**
+	 * @example
+	 * <CodeBlock code="npm install @hyvnt/hyvui" language="bash" />
+	 * <CodeBlock code={snippetString} language="typescript" copyable={false} />
+	 */
 	interface Props {
 		/** Code string to display. */
 		code?: string;

package/dist/components/display/CodeBlock.svelte.d.ts

@@ -1,3 +1,8 @@
+/**
+ * @example
+ * <CodeBlock code="npm install @hyvnt/hyvui" language="bash" />
+ * <CodeBlock code={snippetString} language="typescript" copyable={false} />
+ */
 interface Props {
     /** Code string to display. */
     code?: string;

package/dist/components/display/MetricCard.svelte

@@ -2,6 +2,12 @@
 	import { cn } from '../../utils/cn.js';
 	import Surface from '../primitives/Surface.svelte';
 
+	/**
+	 * @see surface — add `use:surface` on MetricCard for an entrance animation on mount.
+	 * @example
+	 * <MetricCard label="active sessions" value="1,284" trend="up" trendValue="+8%" />
+	 * <MetricCard label="error rate" value="0.02%" trend="down" trendValue="-0.01%" />
+	 */
 	interface Props {
 		/** Metric label. */
 		label?: string;
@@ -46,6 +52,23 @@
 		display: flex;
 		flex-direction: column;
 		gap: var(--space-sm);
+		transition:
+			transform var(--transition-smooth),
+			border-color var(--transition-fast);
+	}
+
+	:global(.hyvui-metric:hover) {
+		transform: translateY(-1px);
+	}
+
+	@media (prefers-reduced-motion: reduce) {
+		:global(.hyvui-metric) {
+			transition: none;
+		}
+
+		:global(.hyvui-metric:hover) {
+			transform: none;
+		}
 	}
 
 	.hyvui-metric-label {

package/dist/components/display/MetricCard.svelte.d.ts

@@ -1,3 +1,9 @@
+/**
+ * @see surface — add `use:surface` on MetricCard for an entrance animation on mount.
+ * @example
+ * <MetricCard label="active sessions" value="1,284" trend="up" trendValue="+8%" />
+ * <MetricCard label="error rate" value="0.02%" trend="down" trendValue="-0.01%" />
+ */
 interface Props {
     /** Metric label. */
     label?: string;

package/dist/components/display/Table.svelte

@@ -9,6 +9,13 @@
 		align?: 'left' | 'center' | 'right';
 	}
 
+	/**
+	 * @example
+	 * <Table
+	 *   columns={[{ key: 'name', label: 'name' }, { key: 'status', label: 'status' }]}
+	 *   rows={[{ name: 'alpha', status: 'active' }, { name: 'beta', status: 'pending' }]}
+	 * />
+	 */
 	interface Props {
 		/** Column definitions. */
 		columns?: TableColumn[];

package/dist/components/display/Table.svelte.d.ts

@@ -4,6 +4,13 @@ interface TableColumn {
     label: string;
     align?: 'left' | 'center' | 'right';
 }
+/**
+ * @example
+ * <Table
+ *   columns={[{ key: 'name', label: 'name' }, { key: 'status', label: 'status' }]}
+ *   rows={[{ name: 'alpha', status: 'active' }, { name: 'beta', status: 'pending' }]}
+ * />
+ */
 interface Props {
     /** Column definitions. */
     columns?: TableColumn[];

package/dist/components/feedback/Alert.svelte

@@ -2,6 +2,12 @@
 	import { cn } from '../../utils/cn.js';
 	import type { Snippet } from 'svelte';
 
+	/**
+	 * @example
+	 * <Alert variant="warn" title="rate limited">requests paused for 60 seconds</Alert>
+	 * <Alert variant="error">connection refused</Alert>
+	 * <Alert variant="ok" title="deployment complete">all services nominal</Alert>
+	 */
 	interface Props {
 		/** Alert variant determining accent color. */
 		variant?: 'info' | 'warn' | 'error' | 'ok';
@@ -50,6 +56,24 @@
 	.hyvui-alert {
 		border-left: 2px solid;
 		padding: 0.75rem 1rem;
+		animation: alert-in 0.3s cubic-bezier(0.22, 1, 0.36, 1) both;
+	}
+
+	@keyframes alert-in {
+		from {
+			opacity: 0;
+			transform: translateX(-6px);
+		}
+		to {
+			opacity: 1;
+			transform: translateX(0);
+		}
+	}
+
+	@media (prefers-reduced-motion: reduce) {
+		.hyvui-alert {
+			animation: none;
+		}
 	}
 
 	.hyvui-alert-title {

package/dist/components/feedback/Alert.svelte.d.ts

@@ -1,4 +1,10 @@
 import type { Snippet } from 'svelte';
+/**
+ * @example
+ * <Alert variant="warn" title="rate limited">requests paused for 60 seconds</Alert>
+ * <Alert variant="error">connection refused</Alert>
+ * <Alert variant="ok" title="deployment complete">all services nominal</Alert>
+ */
 interface Props {
     /** Alert variant determining accent color. */
     variant?: 'info' | 'warn' | 'error' | 'ok';

package/dist/components/feedback/EmptyState.svelte

@@ -2,6 +2,13 @@
 	import { cn } from '../../utils/cn.js';
 	import type { Snippet } from 'svelte';
 
+	/**
+	 * @example
+	 * <EmptyState title="no records found" description="adjust your filters to see results" />
+	 * <EmptyState title="nothing here yet">
+	 *   <Button variant="primary" onclick={create}>create one</Button>
+	 * </EmptyState>
+	 */
 	interface Props {
 		/** Primary message. */
 		title?: string;

package/dist/components/feedback/EmptyState.svelte.d.ts

@@ -1,4 +1,11 @@
 import type { Snippet } from 'svelte';
+/**
+ * @example
+ * <EmptyState title="no records found" description="adjust your filters to see results" />
+ * <EmptyState title="nothing here yet">
+ *   <Button variant="primary" onclick={create}>create one</Button>
+ * </EmptyState>
+ */
 interface Props {
     /** Primary message. */
     title?: string;

package/dist/components/feedback/ErrorState.svelte

@@ -3,6 +3,11 @@
 	import StatusDot from './StatusDot.svelte';
 	import Button from '../inputs/Button.svelte';
 
+	/**
+	 * @example
+	 * <ErrorState title="signal lost" description="the connection dropped unexpectedly" retry onretry={reload} />
+	 * <ErrorState title="the signal needs rest" />
+	 */
 	interface Props {
 		/** Error condition title. Describes the condition, not the cause. */
 		title?: string;

package/dist/components/feedback/ErrorState.svelte.d.ts

@@ -1,3 +1,8 @@
+/**
+ * @example
+ * <ErrorState title="signal lost" description="the connection dropped unexpectedly" retry onretry={reload} />
+ * <ErrorState title="the signal needs rest" />
+ */
 interface Props {
     /** Error condition title. Describes the condition, not the cause. */
     title?: string;

package/dist/components/feedback/Skeleton.svelte

@@ -1,6 +1,12 @@
 <script lang="ts">
 	import { cn } from '../../utils/cn.js';
 
+	/**
+	 * @example
+	 * <Skeleton height="1.2rem" width="60%" />
+	 * <Skeleton variant="circle" width="32px" height="32px" />
+	 * <Skeleton variant="card" height="120px" />
+	 */
 	interface Props {
 		/** Width of the skeleton element. */
 		width?: string;

package/dist/components/feedback/Skeleton.svelte.d.ts

@@ -1,3 +1,9 @@
+/**
+ * @example
+ * <Skeleton height="1.2rem" width="60%" />
+ * <Skeleton variant="circle" width="32px" height="32px" />
+ * <Skeleton variant="card" height="120px" />
+ */
 interface Props {
     /** Width of the skeleton element. */
     width?: string;