yaxa-svelte 2.8.1 → 2.9.0

package/README.md

@@ -15,6 +15,7 @@ _Nuxt UI v4 & Nuxt UI Pro Equivalent for SvelteKit 2 & 3 & Svelte 5 with Built-i
 [![License: MIT](https://img.shields.io/badge/License-MIT-emerald.svg)](LICENSE)
 [![Security Policy](https://img.shields.io/badge/Security-Policy-blue.svg)](SECURITY.md)
 [![Contributing](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](CONTRIBUTING.md)
+[![Sponsor](https://img.shields.io/badge/Sponsor-%E2%99%A5-ea4aaa?style=flat&logo=githubsponsors&logoColor=white)](https://github.com/sponsors/FuntionalFrost)
 
 <br />
 
@@ -553,39 +554,40 @@ A zero-overhead, runes-native query and mutation cache built specifically for Sv
 
 ## 📦 Subpath Exports Architecture
 
-| Subpath                 | Description                                                                                                                                                                                                                                                                            |
-| :---------------------- | :------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `yaxa-svelte`           | Core UI Primitives, SEO Components, `<Gate />`, Type-Safe Client RPC (`createApiClient`), Runes Query Engine (`createQuery`, `createMutation`, `QueryClient`), Theme System & Composables (`useGate`, `useUpload`, `useSSE`, `useToast`, `useClipboard`, etc.)                         |
-| `yaxa-svelte/seo`       | Standalone SEO & Agent Engine: Sitemaps, robots.txt, XSL stylesheets, OpenGraph SVG, Schema.org JSON-LD (FAQPage, Product), WebManifest, llms.txt, skill.md, `useSeo()` runes, and prerendering utilities (Zero DB/Auth dependencies; 100% compatible with `@sveltejs/adapter-static`) |
-| `yaxa-svelte/admin`     | Drizzle ORM Schema Introspection, `<AdminDashboard />`, `createYaxaAdminHook`, `createDrizzleAdmin`, `<DevSandbox />`, `<RecordDrawer />`                                                                                                                                              |
-| `yaxa-svelte/server`    | `yaxaEndpoint` Pipeline, Declarative Guards, OpenAPI 3.1 & Scalar Docs, RFC 7807, Real-Time SSE (`yaxaSSE`, `broadcast`), AI Streaming (`createAiStreamHandler`), Background Jobs (`enqueueJob`, `createJobRunner`), `eventBus`, Server Hooks, DB, Storage & Email                     |
-| `yaxa-svelte/auth`      | Better-Auth client & server integration (`useAuth`, `<SignInCard />`, `<SignUpCard />`, `<ResetPasswordCard />`, `<AuthCard />`, `<PasskeyUI />`, `<TwoFactorModal />`, `createYaxaAuth`)                                                                                              |
-| `yaxa-svelte/db`        | Multi-dialect Drizzle ORM clients & schemas for Neon (PostgreSQL) and Turso (SQLite/LibSQL)                                                                                                                                                                                            |
-| `yaxa-svelte/polar`     | Polar.sh billing, customer portal sessions, and webhook synchronization                                                                                                                                                                                                                |
-| `yaxa-svelte/email`     | Resend transactional email templates with automatic development console fallback                                                                                                                                                                                                       |
-| `yaxa-svelte/storage`   | AWS S3 and Cloudflare R2 presigned upload URL generators                                                                                                                                                                                                                               |
-| `yaxa-svelte/testing`   | Test mocks & utilities (`createMockSiteConfig`, `createMockUser`, `createTestWrapperProps`)                                                                                                                                                                                            |
-| `yaxa-svelte/vite`      | Turnkey Vite plugin (`yaxa()`)                                                                                                                                                                                                                                                         |
-| `yaxa-svelte/yaxa.css`  | Standalone turnkey Tailwind CSS v4 stylesheet with base styling, `@theme`, and scrollbars                                                                                                                                                                                              |
-| `yaxa-svelte/theme.css` | Pure Tailwind CSS v4 design tokens, `:root` variables, and harmonic radius scale without `@import 'tailwindcss'`                                                                                                                                                                       |
+| Subpath                 | Description                                                                                                                                                                                                                                                                                                                                                           |
+| :---------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `yaxa-svelte`           | Core UI Primitives, SEO Components, `<Gate />`, Type-Safe Client RPC (`createApiClient`), Runes Query Engine (`createQuery`, `createMutation`, `QueryClient`), Theme System & Composables (`useGate`, `useUpload`, `useSSE`, `useToast`, `useClipboard`, etc.)                                                                                                        |
+| `yaxa-svelte/seo`       | Standalone SEO & Agent Engine: Sitemaps, robots.txt, XSL stylesheets, OpenGraph SVG, Schema.org JSON-LD (FAQPage, Product), WebManifest, llms.txt, skill.md, `useSeo()` runes, and prerendering utilities (Zero DB/Auth dependencies; 100% compatible with `@sveltejs/adapter-static`)                                                                                |
+| `yaxa-svelte/admin`     | Drizzle ORM Schema Introspection, `<AdminDashboard />`, `createYaxaAdminHook`, `createDrizzleAdmin`, `<DevSandbox />`, `<RecordDrawer />`                                                                                                                                                                                                                             |
+| `yaxa-svelte/server`    | `yaxaEndpoint` Pipeline, W3C Distributed Tracing (`traceparent`, `requestId`), Contextual Logger & `Server-Timing` Metrics, Declarative Guards, OpenAPI 3.1 & Scalar Docs, RFC 7807, Real-Time SSE (`yaxaSSE`, `broadcast`), AI Streaming (`createAiStreamHandler`), Background Jobs (`enqueueJob`, `createJobRunner`), `eventBus`, Server Hooks, DB, Storage & Email |
+| `yaxa-svelte/auth`      | Better-Auth client & server integration (`useAuth`, `<SignInCard />`, `<SignUpCard />`, `<ResetPasswordCard />`, `<AuthCard />`, `<PasskeyUI />`, `<TwoFactorModal />`, `createYaxaAuth`)                                                                                                                                                                             |
+| `yaxa-svelte/db`        | Multi-dialect Drizzle ORM clients & schemas for Neon (PostgreSQL) and Turso (SQLite/LibSQL)                                                                                                                                                                                                                                                                           |
+| `yaxa-svelte/polar`     | Polar.sh billing, customer portal sessions, and webhook synchronization                                                                                                                                                                                                                                                                                               |
+| `yaxa-svelte/email`     | Resend transactional email templates with automatic development console fallback                                                                                                                                                                                                                                                                                      |
+| `yaxa-svelte/storage`   | AWS S3 and Cloudflare R2 presigned upload URL generators                                                                                                                                                                                                                                                                                                              |
+| `yaxa-svelte/testing`   | Test mocks & utilities (`createMockSiteConfig`, `createMockUser`, `createTestWrapperProps`)                                                                                                                                                                                                                                                                           |
+| `yaxa-svelte/vite`      | Turnkey Vite plugin (`yaxa()`)                                                                                                                                                                                                                                                                                                                                        |
+| `yaxa-svelte/yaxa.css`  | Standalone turnkey Tailwind CSS v4 stylesheet with base styling, `@theme`, and scrollbars                                                                                                                                                                                                                                                                             |
+| `yaxa-svelte/theme.css` | Pure Tailwind CSS v4 design tokens, `:root` variables, and harmonic radius scale without `@import 'tailwindcss'`                                                                                                                                                                                                                                                      |
 
 ---
 
 ## 🧩 Component Library
 
-| Category               | Components                                                                                                                                                                                                                                                                                                               |
-| :--------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| **Theming & Studio**   | `<ThemeStudio>`, `theme`, `ACCENT_PALETTES`, `NEUTRAL_PALETTES`, `RADIUS_PRESETS`, Harmonic Radius Multiplier Scale, Chart Palette Series Tokens                                                                                                                                                                         |
-| **AI Primitives**      | `<AiChat>`, `<PromptBar>`, `<AiThought>`, `<AiToolCall>`, `useAiChat`                                                                                                                                                                                                                                                    |
-| **Charts (Pure SVG)**  | `<LineChart>`, `<BarChart>`, `<DonutChart>` (0 external charting dependencies, auto-responsive, dark/light theme aware)                                                                                                                                                                                                  |
-| **SaaS & Auth Suite**  | `<Gate>`, `<UserMenu>`, `<OrgSwitcher>`, `<PricingCard>`, `<PricingTable>`, `<SubscriptionCard>`, `useGate`, `useUpload` (Root); `<SignInCard>`, `<SignUpCard>`, `<ResetPasswordCard>`, `<AuthCard>`, `<PasskeyUI>`, `<TwoFactorModal>`, `useAuth` (`yaxa-svelte/auth`)                                                  |
-| **Admin Suite**        | `<AdminDashboard>`, `<RecordDrawer>`, `<DevSandbox>`, `<ImpersonationBanner>`, `createYaxaAdminHook`, `createDrizzleAdmin`                                                                                                                                                                                               |
-| **Elements & Code**    | `<CodeDiff>` (Interactive Diff & Changelog), `<CodeBlock>`, `<DataTable>` (Client & Server Modes), `Button`, `ButtonGroup`, `Badge`, `Avatar`, `AvatarGroup`, `Chip`, `Meter`, `MetricCard`, `Kbd`, `Icon`, `Spinner`, `Progress`, `Skeleton`, `Link`, `Logo`, `Tree`, `Timeline`, `Terminal`, `VirtualList`, `Carousel` |
-| **Forms (Auto-Wired)** | `<Form>`, `<FormField>`, `Input`, `InputOTP`, `Textarea`, `Checkbox`, `Switch`, `Select`, `Combobox`, `MultiSelect`, `NumberInput`, `PhoneInput`, `CreditCardInput`, `RadioGroup`, `Slider`, `ColorPicker`, `ToggleGroup`, `DatePicker`, `DateRangePicker`, `Dropzone`, `<RichTextEditor>`                               |
-| **Layout & Blocks**    | `Container`, `Header`, `Footer`, `Section`, `Card`, `Divider`, `YaxaApp`, `DashboardShell` (with independent sidebar tokens), `ResizablePanels`, Page Blocks (`Hero`, `SaaS Metrics`, `FAQ`, `Testimonials`, `FeatureGrid`)                                                                                              |
-| **Overlays & Nav**     | `Tabs`, `Breadcrumb`, `Pagination`, `CommandPalette` (`⌘K`), `DropdownMenu`, `ContextMenu`, `Modal`, `Drawer`, `Slideover`, `Popover`, `Tooltip` (with `arrow={false}` & `unstyled`), `Alert`, `Accordion`, `NotificationCenter`, `Stepper`                                                                              |
-| **Motion & Actions**   | `springTilt`, `smoothSlide`, `staggerFly`, `autosize`, `clickOutside`, `portal`, `sortableItem`, `infiniteScrollAction`                                                                                                                                                                                                  |
-| **Composables**        | `useGate`, `useUpload`, `useClipboard`, `useShortcuts`, `useColorMode`, `useToast`, `useMediaQuery`, `useDebounce`, `useIdle`, `useInfiniteScroll`, `useSortable`, `useDataTable`, `useLocale` (Root); `useAuth` (`yaxa-svelte/auth`)                                                                                    |
+| Category               | Components                                                                                                                                                                                                                                                                                 |
+| :--------------------- | :----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **Theming & Studio**   | `<ThemeStudio>`, `theme`, `ACCENT_PALETTES`, `NEUTRAL_PALETTES`, `RADIUS_PRESETS`, Harmonic Radius Multiplier Scale, Chart Palette Series Tokens                                                                                                                                           |
+| **AI Primitives**      | `<AiChat>`, `<PromptBar>`, `<AiThought>`, `<AiToolCall>`, `useAiChat`                                                                                                                                                                                                                      |
+| **Charts (Pure SVG)**  | `<LineChart>`, `<BarChart>`, `<DonutChart>` (0 external charting dependencies, auto-responsive, dark/light theme aware)                                                                                                                                                                    |
+| **SaaS & Auth Suite**  | `<Gate>`, `<UserMenu>`, `<OrgSwitcher>`, `<PricingCard>`, `<PricingTable>`, `<SubscriptionCard>`, `useGate`, `useUpload` (Root); `<SignInCard>`, `<SignUpCard>`, `<ResetPasswordCard>`, `<AuthCard>`, `<PasskeyUI>`, `<TwoFactorModal>`, `useAuth` (`yaxa-svelte/auth`)                    |
+| **Admin Suite**        | `<AdminDashboard>`, `<RecordDrawer>`, `<DevSandbox>`, `<ImpersonationBanner>`, `createYaxaAdminHook`, `createDrizzleAdmin`                                                                                                                                                                 |
+| **Docs & Content**     | `<Callout>` (`note`, `tip`, `important`, `warning`, `caution`, `danger`), `<CodeGroup>` (Synced multi-tab code blocks with `syncKey`), `<Steps>` (Numbered vertical step guides), `<CodeDiff>`, `<CodeBlock>`                                                                              |
+| **Elements & Data**    | `<DataTable>` (Client & Server Modes), `Button`, `ButtonGroup`, `Badge`, `Avatar`, `AvatarGroup`, `Chip`, `Meter`, `MetricCard`, `Kbd`, `Icon`, `Spinner`, `Progress`, `Skeleton`, `Link`, `Logo`, `Tree`, `Timeline`, `Terminal`, `VirtualList`, `Carousel`                               |
+| **Forms (Auto-Wired)** | `<Form>`, `<FormField>`, `Input`, `InputOTP`, `Textarea`, `Checkbox`, `Switch`, `Select`, `Combobox`, `MultiSelect`, `NumberInput`, `PhoneInput`, `CreditCardInput`, `RadioGroup`, `Slider`, `ColorPicker`, `ToggleGroup`, `DatePicker`, `DateRangePicker`, `Dropzone`, `<RichTextEditor>` |
+| **Layout & Blocks**    | `Container`, `Header`, `Footer`, `Section`, `Card`, `Divider`, `YaxaApp`, `DashboardShell` (with independent sidebar tokens), `ResizablePanels`, Page Blocks (`Hero`, `SaaS Metrics`, `FAQ`, `Testimonials`, `FeatureGrid`)                                                                |
+| **Overlays & Nav**     | `Tabs`, `Breadcrumb`, `Pagination`, `CommandPalette` (`⌘K`), `DropdownMenu`, `ContextMenu`, `Modal`, `Drawer`, `Slideover`, `Popover`, `Tooltip` (with `arrow={false}` & `unstyled`), `Alert`, `Accordion`, `NotificationCenter`, `Stepper`                                                |
+| **Motion & Actions**   | `springTilt`, `smoothSlide`, `staggerFly`, `autosize`, `clickOutside`, `portal`, `sortableItem`, `infiniteScrollAction`                                                                                                                                                                    |
+| **Composables**        | `useGate`, `useUpload`, `useClipboard`, `useShortcuts`, `useColorMode`, `useToast`, `useMediaQuery`, `useDebounce`, `useIdle`, `useInfiniteScroll`, `useSortable`, `useDataTable`, `useLocale` (Root); `useAuth` (`yaxa-svelte/auth`)                                                      |
 
 ---
 
@@ -615,6 +617,16 @@ Contributions are always welcome! Please read our [Contributing Guidelines](CONT
 
 ---
 
+## 💖 Sponsors & Backing
+
+If you find Yaxa helpful for your applications or business, consider supporting its continuous development and maintenance:
+
+[![Sponsor on GitHub](https://img.shields.io/badge/Sponsor_on_GitHub-ea4aaa?style=for-the-badge&logo=githubsponsors&logoColor=white)](https://github.com/sponsors/FuntionalFrost)
+
+- **[GitHub Sponsors](https://github.com/sponsors/FuntionalFrost)**: Fund ongoing feature additions, bug fixes, SvelteKit version tracking, and documentation improvements.
+
+---
+
 ## 📄 License
 
 [MIT License](LICENSE) © 2026 Yaxa Contributors.

package/dist/components/content/Callout.svelte

@@ -0,0 +1,182 @@
+<script module lang="ts">
+	import { tv, cn, type VariantProps } from '../../utils/cn.js';
+	import type { Snippet } from 'svelte';
+	import type { IconSource } from '../elements/Icon.svelte';
+
+	export const calloutVariants = tv({
+		base: 'not-prose group relative my-4 flex w-full gap-3.5 overflow-hidden rounded-xl border border-l-4 p-4 text-sm transition-all duration-150',
+		variants: {
+			type: {
+				note: 'border-sky-200/80 border-l-sky-500 bg-sky-50/50 text-sky-950 dark:border-sky-900/40 dark:border-l-sky-400 dark:bg-sky-950/25 dark:text-sky-100',
+				info: 'border-sky-200/80 border-l-sky-500 bg-sky-50/50 text-sky-950 dark:border-sky-900/40 dark:border-l-sky-400 dark:bg-sky-950/25 dark:text-sky-100',
+				tip: 'border-emerald-200/80 border-l-emerald-500 bg-emerald-50/50 text-emerald-950 dark:border-emerald-900/40 dark:border-l-emerald-400 dark:bg-emerald-950/25 dark:text-emerald-100',
+				success:
+					'border-emerald-200/80 border-l-emerald-500 bg-emerald-50/50 text-emerald-950 dark:border-emerald-900/40 dark:border-l-emerald-400 dark:bg-emerald-950/25 dark:text-emerald-100',
+				important:
+					'border-violet-200/80 border-l-violet-500 bg-violet-50/50 text-violet-950 dark:border-violet-900/40 dark:border-l-violet-400 dark:bg-violet-950/25 dark:text-violet-100',
+				warning:
+					'border-amber-200/80 border-l-amber-500 bg-amber-50/50 text-amber-950 dark:border-amber-900/40 dark:border-l-amber-400 dark:bg-amber-950/25 dark:text-amber-100',
+				caution:
+					'border-rose-200/80 border-l-rose-500 bg-rose-50/50 text-rose-950 dark:border-rose-900/40 dark:border-l-rose-400 dark:bg-rose-950/25 dark:text-rose-100',
+				danger:
+					'border-rose-200/80 border-l-rose-500 bg-rose-50/50 text-rose-950 dark:border-rose-900/40 dark:border-l-rose-400 dark:bg-rose-950/25 dark:text-rose-100'
+			}
+		},
+		defaultVariants: {
+			type: 'note'
+		}
+	});
+
+	export type CalloutType = NonNullable<VariantProps<typeof calloutVariants>['type']>;
+
+	export interface CalloutSlots {
+		root?: string;
+		icon?: string;
+		content?: string;
+		title?: string;
+		body?: string;
+		close?: string;
+	}
+
+	export type CalloutProps = VariantProps<typeof calloutVariants> & {
+		title?: string;
+		description?: string;
+		icon?: IconSource;
+		href?: string;
+		target?: string;
+		closable?: boolean;
+		onclose?: () => void;
+		class?: string;
+		ui?: CalloutSlots;
+		children?: Snippet;
+	};
+</script>
+
+<script lang="ts">
+	import Icon from '../elements/Icon.svelte';
+
+	let {
+		type = 'note',
+		title,
+		description,
+		icon,
+		href,
+		target,
+		closable = false,
+		onclose,
+		class: className = '',
+		ui,
+		children
+	}: CalloutProps = $props();
+
+	let visible = $state(true);
+
+	const iconColorMap: Record<CalloutType, string> = {
+		note: 'text-sky-600 dark:text-sky-400',
+		info: 'text-sky-600 dark:text-sky-400',
+		tip: 'text-emerald-600 dark:text-emerald-400',
+		success: 'text-emerald-600 dark:text-emerald-400',
+		important: 'text-violet-600 dark:text-violet-400',
+		warning: 'text-amber-600 dark:text-amber-400',
+		caution: 'text-rose-600 dark:text-rose-400',
+		danger: 'text-rose-600 dark:text-rose-400'
+	};
+
+	let resolvedIcon = $derived.by((): IconSource => {
+		if (icon) return icon;
+		switch (type) {
+			case 'tip':
+			case 'success':
+				return 'check';
+			case 'important':
+				return 'sparkles';
+			case 'warning':
+			case 'caution':
+			case 'danger':
+				return 'alert';
+			case 'note':
+			case 'info':
+			default:
+				return 'info';
+		}
+	});
+
+	function handleClose(e: MouseEvent) {
+		e.preventDefault();
+		e.stopPropagation();
+		visible = false;
+		onclose?.();
+	}
+</script>
+
+{#if visible}
+	<svelte:element
+		this={href ? 'a' : 'div'}
+		{href}
+		{target}
+		rel={target === '_blank' ? 'noopener noreferrer' : undefined}
+		data-slot="root"
+		data-callout-type={type}
+		role="note"
+		class={cn(
+			calloutVariants({ type, class: className }),
+			href && 'cursor-pointer hover:shadow-sm',
+			ui?.root
+		)}
+	>
+		<div data-slot="icon" class={cn('mt-0.5 shrink-0', iconColorMap[type ?? 'note'], ui?.icon)}>
+			<Icon name={resolvedIcon} size="sm" />
+		</div>
+
+		<div data-slot="content" class={cn('min-w-0 flex-1 space-y-1', ui?.content)}>
+			{#if title}
+				<div
+					data-slot="title"
+					class={cn('flex items-center gap-1.5 font-semibold tracking-tight', ui?.title)}
+				>
+					<span>{title}</span>
+					{#if href}
+						<Icon
+							name="arrow-right"
+							size="xs"
+							class="transition-transform duration-150 group-hover:translate-x-0.5"
+						/>
+					{/if}
+				</div>
+			{/if}
+
+			{#if description}
+				<div data-slot="body" class={cn('leading-relaxed opacity-90', ui?.body)}>
+					{description}
+				</div>
+			{/if}
+
+			{#if children}
+				<div
+					data-slot="body"
+					class={cn(
+						'leading-relaxed opacity-90 [&_code]:rounded [&_code]:bg-black/5 [&_code]:px-1.5 [&_code]:py-0.5 [&_code]:font-mono [&_code]:text-xs dark:[&_code]:bg-white/10',
+						ui?.body
+					)}
+				>
+					{@render children()}
+				</div>
+			{/if}
+		</div>
+
+		{#if closable}
+			<button
+				type="button"
+				data-slot="close"
+				onclick={handleClose}
+				class={cn(
+					'-mt-1 -mr-1 inline-flex h-7 w-7 shrink-0 items-center justify-center rounded-lg opacity-60 transition-opacity hover:bg-black/5 hover:opacity-100 focus:outline-none dark:hover:bg-white/10',
+					ui?.close
+				)}
+				aria-label="Dismiss callout"
+			>
+				<Icon name="close" size="xs" />
+			</button>
+		{/if}
+	</svelte:element>
+{/if}

package/dist/components/content/Callout.svelte.d.ts

@@ -0,0 +1,39 @@
+import { type VariantProps } from '../../utils/cn.js';
+import type { Snippet } from 'svelte';
+import type { IconSource } from '../elements/Icon.svelte';
+export declare const calloutVariants: import("tailwind-variants").TVReturnType<{
+    type: {
+        note: string;
+        info: string;
+        tip: string;
+        success: string;
+        important: string;
+        warning: string;
+        caution: string;
+        danger: string;
+    };
+}, undefined, "not-prose group relative my-4 flex w-full gap-3.5 overflow-hidden rounded-xl border border-l-4 p-4 text-sm transition-all duration-150", undefined, undefined, undefined>;
+export type CalloutType = NonNullable<VariantProps<typeof calloutVariants>['type']>;
+export interface CalloutSlots {
+    root?: string;
+    icon?: string;
+    content?: string;
+    title?: string;
+    body?: string;
+    close?: string;
+}
+export type CalloutProps = VariantProps<typeof calloutVariants> & {
+    title?: string;
+    description?: string;
+    icon?: IconSource;
+    href?: string;
+    target?: string;
+    closable?: boolean;
+    onclose?: () => void;
+    class?: string;
+    ui?: CalloutSlots;
+    children?: Snippet;
+};
+declare const Callout: import("svelte").Component<CalloutProps, {}, "">;
+type Callout = ReturnType<typeof Callout>;
+export default Callout;

package/dist/components/content/CodeGroup.svelte

@@ -0,0 +1,238 @@
+<script module lang="ts">
+	import { tv, cn, type VariantProps } from '../../utils/cn.js';
+	import { SvelteMap } from 'svelte/reactivity';
+	import type { Snippet } from 'svelte';
+	import type { IconSource } from '../elements/Icon.svelte';
+
+	// Reactive cross-instance tab synchronization registry
+	const syncedTabs = new SvelteMap<string, string>();
+
+	export const codeGroupVariants = tv({
+		base: 'not-prose my-4 overflow-hidden rounded-xl border border-neutral-800 bg-neutral-950 shadow-sm',
+		variants: {
+			themeMode: {
+				dark: 'border-neutral-800 bg-neutral-950 text-neutral-100',
+				adaptive:
+					'border-neutral-200 bg-neutral-50 text-neutral-900 dark:border-neutral-800 dark:bg-neutral-950 dark:text-neutral-100'
+			}
+		},
+		defaultVariants: {
+			themeMode: 'dark'
+		}
+	});
+
+	export interface CodeGroupItem {
+		label: string;
+		value?: string;
+		code: string;
+		language?: string;
+		filename?: string;
+		icon?: IconSource;
+		showLineNumbers?: boolean;
+		highlightLines?: number[];
+	}
+
+	export interface CodeGroupSlots {
+		root?: string;
+		header?: string;
+		tabList?: string;
+		tab?: string;
+		activeTab?: string;
+		copyButton?: string;
+		body?: string;
+	}
+
+	export type CodeGroupProps = VariantProps<typeof codeGroupVariants> & {
+		items?: CodeGroupItem[];
+		activeTab?: string;
+		syncKey?: string;
+		showLineNumbers?: boolean;
+		wrap?: boolean;
+		class?: string;
+		ui?: CodeGroupSlots;
+		children?: Snippet<[string]>;
+	};
+</script>
+
+<script lang="ts">
+	import CodeBlock from '../elements/CodeBlock.svelte';
+	import Icon from '../elements/Icon.svelte';
+
+	let {
+		items = [],
+		activeTab = $bindable(''),
+		syncKey,
+		showLineNumbers = false,
+		wrap = false,
+		themeMode = 'dark',
+		class: className = '',
+		ui,
+		children
+	}: CodeGroupProps = $props();
+
+	let copied = $state(false);
+	let copyTimeout: ReturnType<typeof setTimeout> | undefined;
+
+	function getItemValue(item: CodeGroupItem): string {
+		return item.value ?? item.label;
+	}
+
+	function inferLanguage(item: CodeGroupItem): string {
+		if (item.language) return item.language;
+		const lower = (item.filename || item.label).toLowerCase();
+		if (['pnpm', 'npm', 'bun', 'yarn', 'npx', 'bash', 'sh', 'terminal', 'shell'].includes(lower)) {
+			return 'bash';
+		}
+		if (lower.endsWith('.svelte')) return 'svelte';
+		if (lower.endsWith('.ts') || lower.endsWith('.mts')) return 'typescript';
+		if (lower.endsWith('.js') || lower.endsWith('.mjs')) return 'javascript';
+		if (lower.endsWith('.json')) return 'json';
+		if (lower.endsWith('.css')) return 'css';
+		if (lower.endsWith('.yml') || lower.endsWith('.yaml')) return 'yaml';
+		if (lower.endsWith('.md') || lower.endsWith('.svx')) return 'markdown';
+		if (lower.endsWith('.sql')) return 'sql';
+		return 'typescript';
+	}
+
+	let resolvedTab = $derived.by(() => {
+		if (syncKey) {
+			const memVal = syncedTabs.get(syncKey);
+			if (memVal && items.some((item) => getItemValue(item) === memVal)) {
+				return memVal;
+			}
+			if (typeof window !== 'undefined') {
+				try {
+					const stored = window.localStorage.getItem(`yaxa-cg:${syncKey}`);
+					if (stored && items.some((item) => getItemValue(item) === stored)) {
+						return stored;
+					}
+				} catch {
+					// Ignore storage access errors
+				}
+			}
+		}
+		if (activeTab && items.some((item) => getItemValue(item) === activeTab)) {
+			return activeTab;
+		}
+		return items.length > 0 ? getItemValue(items[0]) : '';
+	});
+
+	let currentItem = $derived(
+		items.find((item) => getItemValue(item) === resolvedTab) ?? items[0] ?? null
+	);
+
+	function selectTab(val: string) {
+		activeTab = val;
+		if (syncKey) {
+			syncedTabs.set(syncKey, val);
+			if (typeof window !== 'undefined') {
+				try {
+					window.localStorage.setItem(`yaxa-cg:${syncKey}`, val);
+				} catch {
+					// Ignore storage write errors
+				}
+			}
+		}
+	}
+
+	async function handleCopy() {
+		if (!currentItem?.code) return;
+		try {
+			await navigator.clipboard.writeText(currentItem.code);
+			copied = true;
+			if (copyTimeout) clearTimeout(copyTimeout);
+			copyTimeout = setTimeout(() => {
+				copied = false;
+			}, 2000);
+		} catch {
+			// Clipboard API unavailable
+		}
+	}
+</script>
+
+<div data-slot="root" class={cn(codeGroupVariants({ themeMode, class: className }), ui?.root)}>
+	<!-- Tab Bar Header -->
+	<div
+		data-slot="header"
+		class={cn(
+			'flex items-center justify-between border-b px-3 py-1.5',
+			themeMode === 'adaptive'
+				? 'border-neutral-200 bg-neutral-100/80 dark:border-neutral-800 dark:bg-neutral-900/80'
+				: 'border-neutral-800 bg-neutral-900/80',
+			ui?.header
+		)}
+	>
+		<div
+			data-slot="tabList"
+			role="tablist"
+			aria-label="Code group tabs"
+			class={cn('flex items-center gap-1 overflow-x-auto', ui?.tabList)}
+		>
+			{#each items as item (item.value ?? item.label)}
+				{@const val = getItemValue(item)}
+				{@const isActive = resolvedTab === val}
+				<button
+					type="button"
+					role="tab"
+					aria-selected={isActive}
+					data-slot="tab"
+					data-state={isActive ? 'active' : 'inactive'}
+					onclick={() => selectTab(val)}
+					class={cn(
+						'relative inline-flex cursor-pointer items-center gap-1.5 rounded-lg px-2.5 py-1 font-mono text-xs font-medium whitespace-nowrap transition-colors focus:outline-none',
+						themeMode === 'adaptive'
+							? isActive
+								? 'bg-white text-neutral-950 shadow-2xs dark:bg-neutral-800 dark:text-white'
+								: 'text-neutral-500 hover:text-neutral-800 dark:text-neutral-400 dark:hover:text-neutral-200'
+							: isActive
+								? 'bg-neutral-800 text-white shadow-2xs'
+								: 'text-neutral-400 hover:bg-neutral-800/50 hover:text-neutral-200',
+						ui?.tab,
+						isActive && ui?.activeTab
+					)}
+				>
+					{#if item.icon}
+						<Icon name={item.icon} size="xs" />
+					{/if}
+					<span>{item.label}</span>
+				</button>
+			{/each}
+		</div>
+
+		{#if currentItem}
+			<button
+				type="button"
+				data-slot="copyButton"
+				onclick={handleCopy}
+				class={cn(
+					'ml-2 inline-flex shrink-0 cursor-pointer items-center gap-1 rounded-md px-2 py-1 text-xs font-medium transition-colors',
+					themeMode === 'adaptive'
+						? 'text-neutral-500 hover:bg-neutral-200/70 hover:text-neutral-900 dark:text-neutral-400 dark:hover:bg-neutral-800 dark:hover:text-white'
+						: 'text-neutral-400 hover:bg-neutral-800 hover:text-white',
+					ui?.copyButton
+				)}
+				aria-label="Copy code"
+			>
+				<Icon name={copied ? 'check' : 'copy'} size="xs" />
+				<span>{copied ? 'Copied' : 'Copy'}</span>
+			</button>
+		{/if}
+	</div>
+
+	<!-- Active Code Body -->
+	<div data-slot="body" class={cn('[&>div]:my-0 [&>div]:rounded-none [&>div]:border-0', ui?.body)}>
+		{#if children}
+			{@render children(resolvedTab)}
+		{:else if currentItem}
+			<CodeBlock
+				code={currentItem.code}
+				language={inferLanguage(currentItem)}
+				showLineNumbers={currentItem.showLineNumbers ?? showLineNumbers}
+				highlightLines={currentItem.highlightLines}
+				{wrap}
+				{themeMode}
+				class="my-0 rounded-none border-0 shadow-none"
+			/>
+		{/if}
+	</div>
+</div>

package/dist/components/content/CodeGroup.svelte.d.ts

@@ -0,0 +1,41 @@
+import { type VariantProps } from '../../utils/cn.js';
+import type { Snippet } from 'svelte';
+import type { IconSource } from '../elements/Icon.svelte';
+export declare const codeGroupVariants: import("tailwind-variants").TVReturnType<{
+    themeMode: {
+        dark: string;
+        adaptive: string;
+    };
+}, undefined, "not-prose my-4 overflow-hidden rounded-xl border border-neutral-800 bg-neutral-950 shadow-sm", undefined, undefined, undefined>;
+export interface CodeGroupItem {
+    label: string;
+    value?: string;
+    code: string;
+    language?: string;
+    filename?: string;
+    icon?: IconSource;
+    showLineNumbers?: boolean;
+    highlightLines?: number[];
+}
+export interface CodeGroupSlots {
+    root?: string;
+    header?: string;
+    tabList?: string;
+    tab?: string;
+    activeTab?: string;
+    copyButton?: string;
+    body?: string;
+}
+export type CodeGroupProps = VariantProps<typeof codeGroupVariants> & {
+    items?: CodeGroupItem[];
+    activeTab?: string;
+    syncKey?: string;
+    showLineNumbers?: boolean;
+    wrap?: boolean;
+    class?: string;
+    ui?: CodeGroupSlots;
+    children?: Snippet<[string]>;
+};
+declare const CodeGroup: import("svelte").Component<CodeGroupProps, {}, "activeTab">;
+type CodeGroup = ReturnType<typeof CodeGroup>;
+export default CodeGroup;