@hyvnt/hyvui 0.2.0 → 0.4.0

package/dist/components/ambient/SignalRing.svelte

@@ -1,100 +1,106 @@
-<script lang="ts">
-  import { cn } from '../../utils/cn.js';
-
-  interface Props {
-    /** Enable the pulsing animation. */
-    active?: boolean;
-    /** Ring diameter in pixels. */
-    size?: number;
-    /** Ring color (CSS color value). */
-    color?: string;
-    /** Additional CSS classes. */
-    class?: string;
-  }
-
-  let {
-    active = true,
-    size = 200,
-    color = 'var(--accent)',
-    class: className = '',
-  }: Props = $props();
-</script>
-
-<div
-  class={cn('hyvui-signal-ring', className)}
-  style:width="{size}px"
-  style:height="{size}px"
-  aria-hidden="true"
->
-  {#if active}
-    <span class="hyvui-signal-ring-pulse hyvui-signal-ring-1" style:border-color={color}></span>
-    <span class="hyvui-signal-ring-pulse hyvui-signal-ring-2" style:border-color={color}></span>
-    <span class="hyvui-signal-ring-pulse hyvui-signal-ring-3" style:border-color={color}></span>
-  {/if}
-  <span class="hyvui-signal-ring-core" style:background-color={color}></span>
-</div>
-
-<style>
-  .hyvui-signal-ring {
-    position: relative;
-    display: flex;
-    align-items: center;
-    justify-content: center;
-    pointer-events: none;
-  }
-
-  .hyvui-signal-ring-core {
-    width: 4px;
-    height: 4px;
-    border-radius: 50%;
-    opacity: 0.6;
-  }
-
-  .hyvui-signal-ring-pulse {
-    position: absolute;
-    inset: 0;
-    border-radius: 50%;
-    border: 1px solid;
-    opacity: 0;
-    animation: signal-ring-expand 3.6s ease-out infinite;
-  }
-
-  .hyvui-signal-ring-1 {
-    animation-delay: 0s;
-  }
-
-  .hyvui-signal-ring-2 {
-    animation-delay: 1.2s;
-  }
-
-  .hyvui-signal-ring-3 {
-    animation-delay: 2.4s;
-  }
-
-  @keyframes signal-ring-expand {
-    0% {
-      transform: scale(0.1);
-      opacity: 0.4;
-    }
-    100% {
-      transform: scale(1);
-      opacity: 0;
-    }
-  }
-
-  @media (prefers-reduced-motion: reduce) {
-    .hyvui-signal-ring-pulse {
-      animation: none;
-      opacity: 0.08;
-      transform: scale(0.6);
-    }
-
-    .hyvui-signal-ring-2 {
-      transform: scale(0.8);
-    }
-
-    .hyvui-signal-ring-3 {
-      transform: scale(1);
-    }
-  }
-</style>
+<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;
+		/** Ring diameter in pixels. */
+		size?: number;
+		/** Ring color (CSS color value). */
+		color?: string;
+		/** Additional CSS classes. */
+		class?: string;
+	}
+
+	let {
+		active = true,
+		size = 200,
+		color = 'var(--accent)',
+		class: className = ''
+	}: Props = $props();
+</script>
+
+<div
+	class={cn('hyvui-signal-ring', className)}
+	style:width="{size}px"
+	style:height="{size}px"
+	aria-hidden="true"
+>
+	{#if active}
+		<span class="hyvui-signal-ring-pulse hyvui-signal-ring-1" style:border-color={color}></span>
+		<span class="hyvui-signal-ring-pulse hyvui-signal-ring-2" style:border-color={color}></span>
+		<span class="hyvui-signal-ring-pulse hyvui-signal-ring-3" style:border-color={color}></span>
+	{/if}
+	<span class="hyvui-signal-ring-core" style:background-color={color}></span>
+</div>
+
+<style>
+	.hyvui-signal-ring {
+		position: relative;
+		display: flex;
+		align-items: center;
+		justify-content: center;
+		pointer-events: none;
+	}
+
+	.hyvui-signal-ring-core {
+		width: 4px;
+		height: 4px;
+		border-radius: 50%;
+		opacity: 0.6;
+	}
+
+	.hyvui-signal-ring-pulse {
+		position: absolute;
+		inset: 0;
+		border-radius: 50%;
+		border: 1px solid;
+		opacity: 0;
+		animation: signal-ring-expand 3.6s var(--ease-smooth) infinite;
+	}
+
+	.hyvui-signal-ring-1 {
+		animation-delay: 0s;
+	}
+
+	.hyvui-signal-ring-2 {
+		animation-delay: 1.2s;
+	}
+
+	.hyvui-signal-ring-3 {
+		animation-delay: 2.4s;
+	}
+
+	@keyframes signal-ring-expand {
+		0% {
+			transform: scale(0.1);
+			opacity: 0.4;
+		}
+		100% {
+			transform: scale(1);
+			opacity: 0;
+		}
+	}
+
+	@media (prefers-reduced-motion: reduce) {
+		.hyvui-signal-ring-pulse {
+			animation: none;
+			opacity: 0.08;
+			transform: scale(0.6);
+		}
+
+		.hyvui-signal-ring-2 {
+			transform: scale(0.8);
+		}
+
+		.hyvui-signal-ring-3 {
+			transform: scale(1);
+		}
+	}
+</style>

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,78 +1,78 @@
-<script lang="ts">
-  import { cn } from '../../utils/cn.js';
-
-  interface Props {
-    /** Start x position (CSS value). */
-    x1?: string;
-    /** Start y position (CSS value). */
-    y1?: string;
-    /** End x position (CSS value). */
-    x2?: string;
-    /** End y position (CSS value). */
-    y2?: string;
-    /** Enable the traveling dot animation. */
-    animated?: boolean;
-    /** Additional CSS classes. */
-    class?: string;
-  }
-
-  let {
-    x1 = '0%',
-    y1 = '0%',
-    x2 = '100%',
-    y2 = '100%',
-    animated = true,
-    class: className = '',
-  }: Props = $props();
-</script>
-
-<svg
-  class={cn('hyvui-thread-line', className)}
-  aria-hidden="true"
->
-  <line
-    {x1} {y1} {x2} {y2}
-    stroke="var(--line)"
-    stroke-width="1"
-  />
-  {#if animated}
-    <circle r="2" fill="var(--accent)">
-      <animateMotion
-        dur="3s"
-        repeatCount="indefinite"
-        path="M 0,0 L 1,0"
-        keyPoints="0;1"
-        keyTimes="0;1"
-        calcMode="linear"
-      >
-        <mpath>
-          <line {x1} {y1} {x2} {y2} />
-        </mpath>
-      </animateMotion>
-      <animate
-        attributeName="opacity"
-        values="0;0.8;0.8;0"
-        keyTimes="0;0.1;0.85;1"
-        dur="3s"
-        repeatCount="indefinite"
-      />
-    </circle>
-  {/if}
-</svg>
-
-<style>
-  .hyvui-thread-line {
-    position: absolute;
-    inset: 0;
-    width: 100%;
-    height: 100%;
-    pointer-events: none;
-    overflow: visible;
-  }
-
-  @media (prefers-reduced-motion: reduce) {
-    .hyvui-thread-line circle {
-      display: none;
-    }
-  }
-</style>
+<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;
+		/** Start y position (CSS value). */
+		y1?: string;
+		/** End x position (CSS value). */
+		x2?: string;
+		/** End y position (CSS value). */
+		y2?: string;
+		/** Enable the traveling dot animation. */
+		animated?: boolean;
+		/** Additional CSS classes. */
+		class?: string;
+	}
+
+	let {
+		x1 = '0%',
+		y1 = '0%',
+		x2 = '100%',
+		y2 = '100%',
+		animated = true,
+		class: className = ''
+	}: Props = $props();
+</script>
+
+<svg class={cn('hyvui-thread-line', className)} aria-hidden="true">
+	<line {x1} {y1} {x2} {y2} stroke="var(--line)" stroke-width="1" />
+	{#if animated}
+		<circle r="2" fill="var(--accent)">
+			<animateMotion
+				dur="3s"
+				repeatCount="indefinite"
+				path="M 0,0 L 1,0"
+				keyPoints="0;1"
+				keyTimes="0;1"
+				calcMode="linear"
+			>
+				<mpath>
+					<line {x1} {y1} {x2} {y2} />
+				</mpath>
+			</animateMotion>
+			<animate
+				attributeName="opacity"
+				values="0;0.8;0.8;0"
+				keyTimes="0;0.1;0.85;1"
+				dur="3s"
+				repeatCount="indefinite"
+			/>
+		</circle>
+	{/if}
+</svg>
+
+<style>
+	.hyvui-thread-line {
+		position: absolute;
+		inset: 0;
+		width: 100%;
+		height: 100%;
+		pointer-events: none;
+		overflow: visible;
+	}
+
+	@media (prefers-reduced-motion: reduce) {
+		.hyvui-thread-line circle {
+			display: none;
+		}
+	}
+</style>

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,26 +1,30 @@
-<script lang="ts">
-  import { cn } from '../../utils/cn.js';
-
-  interface Props {
-    /** Additional CSS classes. */
-    class?: string;
-  }
-
-  let {
-    class: className = '',
-  }: Props = $props();
-</script>
-
-<div class={cn('hyvui-vignette', className)} aria-hidden="true"></div>
-
-<style>
-  .hyvui-vignette {
-    position: fixed;
-    inset: 0;
-    pointer-events: none;
-    z-index: var(--z-overlay);
-    background:
-      radial-gradient(ellipse at 50% 0%, transparent 60%, rgba(0, 0, 0, 0.4)),
-      radial-gradient(ellipse at 50% 100%, transparent 60%, rgba(0, 0, 0, 0.5));
-  }
-</style>
+<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;
+	}
+
+	let { class: className = '' }: Props = $props();
+</script>
+
+<div class={cn('hyvui-vignette', className)} aria-hidden="true"></div>
+
+<style>
+	.hyvui-vignette {
+		position: fixed;
+		inset: 0;
+		pointer-events: none;
+		z-index: var(--z-overlay);
+		background:
+			radial-gradient(ellipse at 50% 0%, transparent 60%, rgba(0, 0, 0, 0.4)),
+			radial-gradient(ellipse at 50% 100%, transparent 60%, rgba(0, 0, 0, 0.5));
+	}
+</style>

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

@@ -1,27 +1,30 @@
-<script lang="ts">
-  import { cn } from '../../utils/cn.js';
-  import type { DepthLevel } from '../../system/depth/depth.js';
-  import type { Snippet } from 'svelte';
-
-  interface Props {
-    /** Z-level within a parent DepthStage. */
-    level?: DepthLevel;
-    /** HTML tag to render. */
-    as?: string;
-    /** Additional CSS classes. */
-    class?: string;
-    /** Layer content. */
-    children?: Snippet;
-  }
-
-  let {
-    level = 'ground',
-    as = 'div',
-    class: className = '',
-    children,
-  }: Props = $props();
-</script>
-
-<svelte:element this={as} class={cn(`depth-${level}`, className)}>
-  {#if children}{@render children()}{/if}
-</svelte:element>
+<script lang="ts">
+	import { cn } from '../../utils/cn.js';
+	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;
+		/** HTML tag to render. */
+		as?: string;
+		/** Additional CSS classes. */
+		class?: string;
+		/** Layer content. */
+		children?: Snippet;
+	}
+
+	let { level = 'ground', as = 'div', class: className = '', children }: Props = $props();
+</script>
+
+<svelte:element this={as} class={cn(`depth-${level}`, className)}>
+	{#if children}{@render children()}{/if}
+</svelte:element>

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;