specra 0.1.13 → 0.2.0

package/dist/components/docs/TabGroups.svelte

@@ -0,0 +1,183 @@
+<script lang="ts">
+  import { ChevronDown } from 'lucide-svelte';
+  import { goto } from '$app/navigation';
+  import type { TabGroup, SpecraConfig } from '../../config.types.js';
+  import Icon from './Icon.svelte';
+
+  interface DocItem {
+    slug: string;
+    version?: string;
+    meta?: {
+      tab_group?: string;
+      title?: string;
+      [key: string]: unknown;
+    };
+    tabGroup?: string;
+    categoryTabGroup?: string;
+    [key: string]: unknown;
+  }
+
+  interface Props {
+    tabGroups: TabGroup[];
+    activeTabId?: string;
+    onTabChange?: (tabId: string) => void;
+    mobileOnly?: boolean;
+    docs?: DocItem[];
+    version?: string;
+    flush?: boolean;
+  }
+
+  let { tabGroups, activeTabId, onTabChange, mobileOnly = false, docs, version, flush = false }: Props = $props();
+
+  let dropdownOpen = $state(false);
+
+  // Filter out tabs that have no associated docs
+  let filteredTabGroups = $derived.by(() => {
+    if (!docs) return tabGroups;
+    return tabGroups.filter((tab) => {
+      const hasDocsInTab = docs.some((doc) => {
+        const docTabGroup = doc.meta?.tab_group || doc.categoryTabGroup;
+        return docTabGroup === tab.id || (!docTabGroup && tab.id === tabGroups[0]?.id);
+      });
+      return hasDocsInTab;
+    });
+  });
+
+  let activeTab = $derived(activeTabId || filteredTabGroups[0]?.id || '');
+  let activeTabData = $derived(filteredTabGroups.find((tab) => tab.id === activeTab));
+
+  function handleTabChange(tabId: string) {
+    onTabChange?.(tabId);
+    dropdownOpen = false;
+
+    // Navigate to the first item in the new tab group if docs are provided
+    if (docs && version) {
+      const firstDocInTab = docs.find((doc) => {
+        const docTabGroup = doc.meta?.tab_group || doc.categoryTabGroup;
+        return docTabGroup === tabId || (!docTabGroup && tabId === filteredTabGroups[0]?.id);
+      });
+
+      if (firstDocInTab) {
+        goto(`/docs/${version}/${firstDocInTab.slug}`);
+      }
+    }
+  }
+</script>
+
+{#if filteredTabGroups.length > 0}
+  {#if mobileOnly}
+    <!-- Mobile only version (for sidebar) -->
+    <div class="relative">
+      <button
+        onclick={() => (dropdownOpen = !dropdownOpen)}
+        class="flex items-center justify-between w-full px-3 py-2 text-sm font-medium text-foreground bg-muted/50 rounded-lg hover:bg-muted transition-colors"
+        aria-label="Select tab group"
+        aria-expanded={dropdownOpen}
+      >
+        <div class="flex items-center gap-2">
+          {#if activeTabData?.icon}
+            <Icon icon={activeTabData.icon} size={16} class="shrink-0" />
+          {/if}
+          <span>{activeTabData?.label}</span>
+        </div>
+        <ChevronDown
+          class="h-4 w-4 transition-transform {dropdownOpen ? 'rotate-180' : ''}"
+        />
+      </button>
+
+      {#if dropdownOpen}
+        <!-- svelte-ignore a11y_no_static_element_interactions -->
+        <div
+          class="fixed inset-0 z-40"
+          onclick={() => (dropdownOpen = false)}
+          onkeydown={(e) => { if (e.key === 'Escape') dropdownOpen = false; }}
+        ></div>
+        <div class="absolute top-full left-0 right-0 mt-2 bg-background border border-border rounded-lg shadow-lg z-50 max-h-[60vh] overflow-y-auto">
+          {#each filteredTabGroups as tab}
+            {@const isActive = tab.id === activeTab}
+            <button
+              onclick={() => handleTabChange(tab.id)}
+              class="flex items-center gap-2 w-full px-3 py-2 text-sm font-medium text-left transition-colors first:rounded-t-lg last:rounded-b-lg {isActive
+                ? 'bg-primary/10 text-primary'
+                : 'text-muted-foreground hover:bg-accent hover:text-foreground'}"
+            >
+              {#if tab.icon}
+                <Icon icon={tab.icon} size={16} class="shrink-0" />
+              {/if}
+              {tab.label}
+            </button>
+          {/each}
+        </div>
+      {/if}
+    </div>
+  {:else}
+    <!-- Full version with sticky header -->
+    <div class="sticky top-16 z-30 border-b border-border bg-background/95 backdrop-blur supports-[backdrop-filter]:bg-background/60">
+      <div class="{flush ? '' : 'container mx-auto'} px-4 md:px-6">
+        <!-- Mobile Dropdown -->
+        <div class="md:hidden relative">
+          <button
+            onclick={() => (dropdownOpen = !dropdownOpen)}
+            class="flex items-center justify-between w-full px-4 py-3 text-sm font-medium text-foreground"
+            aria-label="Select tab"
+            aria-expanded={dropdownOpen}
+          >
+            <div class="flex items-center gap-2">
+              {#if activeTabData?.icon}
+                <Icon icon={activeTabData.icon} size={16} class="shrink-0" />
+              {/if}
+              {activeTabData?.label}
+            </div>
+            <ChevronDown
+              class="h-4 w-4 transition-transform {dropdownOpen ? 'rotate-180' : ''}"
+            />
+          </button>
+
+          {#if dropdownOpen}
+            <!-- svelte-ignore a11y_no_static_element_interactions -->
+            <div
+              class="fixed inset-0 z-40"
+              onclick={() => (dropdownOpen = false)}
+              onkeydown={(e) => { if (e.key === 'Escape') dropdownOpen = false; }}
+            ></div>
+            <div class="absolute top-full left-0 right-0 bg-background border border-border shadow-lg z-50 max-h-[60vh] overflow-y-auto">
+              {#each filteredTabGroups as tab}
+                {@const isActive = tab.id === activeTab}
+                <button
+                  onclick={() => handleTabChange(tab.id)}
+                  class="flex items-center gap-2 w-full px-4 py-3 text-sm font-medium text-left transition-colors {isActive
+                    ? 'bg-primary/10 text-primary'
+                    : 'text-muted-foreground hover:bg-accent hover:text-foreground'}"
+                >
+                  {#if tab.icon}
+                    <Icon icon={tab.icon} size={16} class="shrink-0" />
+                  {/if}
+                  {tab.label}
+                </button>
+              {/each}
+            </div>
+          {/if}
+        </div>
+
+        <!-- Desktop Tabs -->
+        <nav class="hidden md:flex gap-1" aria-label="Documentation tabs">
+          {#each filteredTabGroups as tab}
+            {@const isActive = tab.id === activeTab}
+            <button
+              onclick={() => handleTabChange(tab.id)}
+              class="flex items-center gap-2 px-4 py-3 text-sm font-medium whitespace-nowrap transition-all border-b-2 {isActive
+                ? 'border-primary text-primary'
+                : 'border-transparent text-muted-foreground hover:text-foreground hover:border-border'}"
+              aria-current={isActive ? 'page' : undefined}
+            >
+              {#if tab.icon}
+                <Icon icon={tab.icon} size={16} class="shrink-0" />
+              {/if}
+              {tab.label}
+            </button>
+          {/each}
+        </nav>
+      </div>
+    </div>
+  {/if}
+{/if}

package/dist/components/docs/TabGroups.svelte.d.ts

@@ -0,0 +1,25 @@
+import type { TabGroup } from '../../config.types.js';
+interface DocItem {
+    slug: string;
+    version?: string;
+    meta?: {
+        tab_group?: string;
+        title?: string;
+        [key: string]: unknown;
+    };
+    tabGroup?: string;
+    categoryTabGroup?: string;
+    [key: string]: unknown;
+}
+interface Props {
+    tabGroups: TabGroup[];
+    activeTabId?: string;
+    onTabChange?: (tabId: string) => void;
+    mobileOnly?: boolean;
+    docs?: DocItem[];
+    version?: string;
+    flush?: boolean;
+}
+declare const TabGroups: import("svelte").Component<Props, {}, "">;
+type TabGroups = ReturnType<typeof TabGroups>;
+export default TabGroups;

package/dist/components/docs/TableOfContents.svelte

@@ -0,0 +1,100 @@
+<script lang="ts">
+  import { browser } from '$app/environment';
+  import type { SpecraConfig } from '../../config.types.js';
+  import type { TOCItem } from '../../toc.js';
+
+  interface Props {
+    items: TOCItem[];
+    config: SpecraConfig;
+  }
+
+  let { items, config }: Props = $props();
+
+  let activeId = $state('');
+
+  const showToc = $derived(config.navigation?.showTableOfContents !== false);
+  const maxDepth = $derived(config.navigation?.tocMaxDepth ?? 3);
+  const filteredItems = $derived(items.filter((item) => item.level <= maxDepth));
+
+  // Check if tab groups are configured
+  const hasTabGroups = $derived(
+    config.navigation?.tabGroups != null && config.navigation.tabGroups.length > 0
+  );
+
+  // Adjust top position based on whether tabs are present
+  const stickyTop = $derived(hasTabGroups ? 'top-[7.5rem]' : 'top-24');
+  const maxHeight = $derived(hasTabGroups ? 'max-h-[calc(100vh-10rem)]' : 'max-h-[calc(100vh-7rem)]');
+
+  $effect(() => {
+    if (!browser || !showToc || filteredItems.length === 0) return;
+
+    const observer = new IntersectionObserver(
+      (entries) => {
+        for (const entry of entries) {
+          if (entry.isIntersecting) {
+            activeId = entry.target.id;
+            break;
+          }
+        }
+      },
+      {
+        rootMargin: '-80px 0px -80% 0px',
+        threshold: 0,
+      }
+    );
+
+    // Observe all heading elements
+    const headingElements = filteredItems
+      .map((item) => document.getElementById(item.id))
+      .filter(Boolean) as HTMLElement[];
+
+    headingElements.forEach((el) => observer.observe(el));
+
+    return () => {
+      headingElements.forEach((el) => observer.unobserve(el));
+      observer.disconnect();
+    };
+  });
+
+  function handleClick(e: MouseEvent, id: string) {
+    e.preventDefault();
+    const element = document.getElementById(id);
+    if (element) {
+      const offset = 100;
+      const elementPosition = element.getBoundingClientRect().top;
+      const offsetPosition = elementPosition + window.scrollY - offset;
+
+      window.scrollTo({
+        top: offsetPosition,
+        behavior: 'smooth',
+      });
+
+      // Update URL without jumping
+      window.history.replaceState(null, '', `#${id}`);
+
+      // Manually set active ID after scroll
+      activeId = id;
+    }
+  }
+</script>
+
+{#if showToc && filteredItems.length > 0}
+  <aside class="w-64 hidden xl:block shrink-0 sticky {stickyTop} self-start">
+    <div class="{maxHeight} overflow-y-auto bg-muted/30 dark:bg-muted/10 rounded-2xl p-4 border border-border/50">
+      <h3 class="text-xs font-semibold text-muted-foreground uppercase tracking-wider mb-4 px-2">On this page</h3>
+      <nav class="space-y-1">
+        {#each filteredItems as item, index}
+          <a
+            href="#{item.id}"
+            onclick={(e) => handleClick(e, item.id)}
+            class="block text-sm transition-all cursor-pointer rounded-xl px-3 py-2 {item.level === 3 ? 'ml-3' : ''} {activeId === item.id
+              ? 'text-primary font-medium'
+              : 'text-foreground hover:bg-accent/50'}"
+          >
+            {item.title}
+          </a>
+        {/each}
+      </nav>
+    </div>
+  </aside>
+{/if}

package/dist/components/docs/TableOfContents.svelte.d.ts

@@ -0,0 +1,9 @@
+import type { SpecraConfig } from '../../config.types.js';
+import type { TOCItem } from '../../toc.js';
+interface Props {
+    items: TOCItem[];
+    config: SpecraConfig;
+}
+declare const TableOfContents: import("svelte").Component<Props, {}, "">;
+type TableOfContents = ReturnType<typeof TableOfContents>;
+export default TableOfContents;

package/dist/components/docs/Tabs.svelte

@@ -0,0 +1,69 @@
+<script lang="ts">
+  import { setContext } from 'svelte';
+  import { writable } from 'svelte/store';
+  import type { Snippet } from 'svelte';
+
+  interface Props {
+    children?: Snippet;
+    defaultValue?: string;
+  }
+
+  let { children, defaultValue }: Props = $props();
+
+  // Registration system: Tab children register themselves
+  let tabs = $state<Array<{ label: string }>>([]);
+  let activeTab = $state(defaultValue || '');
+
+  function registerTab(label: string) {
+    // Avoid duplicate registrations
+    if (!tabs.find((t) => t.label === label)) {
+      tabs = [...tabs, { label }];
+    }
+    // If no active tab yet, set first
+    if (!activeTab) {
+      activeTab = label;
+    }
+  }
+
+  function setActiveTab(label: string) {
+    activeTab = label;
+  }
+
+  // Store for reactive access from children
+  const activeTabStore = writable(activeTab || '');
+  $effect(() => {
+    activeTabStore.set(activeTab);
+  });
+
+  setContext('specra-tabs', {
+    registerTab,
+    activeTab: activeTabStore,
+    setActiveTab,
+  });
+</script>
+
+<div class="my-6">
+  <!-- Tab buttons -->
+  <div class="flex items-center gap-1 border-b border-border mb-4">
+    {#each tabs as tab}
+      {@const isActive = activeTab === tab.label}
+      <button
+        onclick={() => setActiveTab(tab.label)}
+        class="px-4 py-2 text-sm font-medium transition-colors border-b-2 -mb-px
+          {isActive
+            ? 'border-primary text-primary'
+            : 'border-transparent text-muted-foreground hover:text-foreground hover:border-border'
+          }"
+      >
+        {tab.label}
+      </button>
+    {/each}
+  </div>
+
+  <!-- Tab content -->
+  <div>
+    {#if children}
+      {@render children()}
+    {/if}
+  </div>
+</div>

package/dist/components/docs/Tabs.svelte.d.ts

@@ -0,0 +1,8 @@
+import type { Snippet } from 'svelte';
+interface Props {
+    children?: Snippet;
+    defaultValue?: string;
+}
+declare const Tabs: import("svelte").Component<Props, {}, "">;
+type Tabs = ReturnType<typeof Tabs>;
+export default Tabs;

package/dist/components/docs/ThemeToggle.svelte

@@ -0,0 +1,16 @@
+<script lang="ts">
+  import { Moon, Sun } from 'lucide-svelte';
+  import { themeStore } from '../../stores/theme.js';
+</script>
+
+<button
+  onclick={() => themeStore.toggle()}
+  class="flex items-center justify-center w-9 h-9 rounded-md border border-border bg-background hover:bg-accent transition-colors"
+  aria-label="Toggle theme"
+>
+  {#if $themeStore === 'dark'}
+    <Sun class="h-4 w-4 text-foreground" />
+  {:else}
+    <Moon class="h-4 w-4 text-foreground" />
+  {/if}
+</button>

package/dist/components/docs/ThemeToggle.svelte.d.ts

@@ -0,0 +1,18 @@
+interface $$__sveltets_2_IsomorphicComponent<Props extends Record<string, any> = any, Events extends Record<string, any> = any, Slots extends Record<string, any> = any, Exports = {}, Bindings = string> {
+    new (options: import('svelte').ComponentConstructorOptions<Props>): import('svelte').SvelteComponent<Props, Events, Slots> & {
+        $$bindings?: Bindings;
+    } & Exports;
+    (internal: unknown, props: {
+        $$events?: Events;
+        $$slots?: Slots;
+    }): Exports & {
+        $set?: any;
+        $on?: any;
+    };
+    z_$$bindings?: Bindings;
+}
+declare const ThemeToggle: $$__sveltets_2_IsomorphicComponent<Record<string, never>, {
+    [evt: string]: CustomEvent<any>;
+}, {}, {}, string>;
+type ThemeToggle = InstanceType<typeof ThemeToggle>;
+export default ThemeToggle;

package/dist/components/docs/Tooltip.svelte

@@ -0,0 +1,44 @@
+<script lang="ts">
+  import type { Snippet } from 'svelte';
+
+  type TooltipPosition = 'top' | 'bottom' | 'left' | 'right';
+
+  interface Props {
+    content: string;
+    position?: TooltipPosition;
+    children?: Snippet;
+  }
+
+  let { content, position = 'top', children }: Props = $props();
+
+  let isVisible = $state(false);
+
+  const positions: Record<TooltipPosition, string> = {
+    top: 'bottom-full left-1/2 -translate-x-1/2 mb-2',
+    bottom: 'top-full left-1/2 -translate-x-1/2 mt-2',
+    left: 'right-full top-1/2 -translate-y-1/2 mr-2',
+    right: 'left-full top-1/2 -translate-y-1/2 ml-2',
+  };
+</script>
+
+<span
+  class="relative inline-flex underline decoration-dotted cursor-help"
+  onmouseenter={() => (isVisible = true)}
+  onmouseleave={() => (isVisible = false)}
+  onfocusin={() => (isVisible = true)}
+  onfocusout={() => (isVisible = false)}
+  role="button"
+  tabindex="0"
+>
+  {#if children}
+    {@render children()}
+  {/if}
+  {#if isVisible}
+    <span
+      class="absolute {positions[position]} z-50 px-2 py-1 text-xs text-white bg-gray-900 dark:bg-gray-700 rounded whitespace-nowrap pointer-events-none"
+      role="tooltip"
+    >
+      {content}
+    </span>
+  {/if}
+</span>

package/dist/components/docs/Tooltip.svelte.d.ts

@@ -0,0 +1,10 @@
+import type { Snippet } from 'svelte';
+type TooltipPosition = 'top' | 'bottom' | 'left' | 'right';
+interface Props {
+    content: string;
+    position?: TooltipPosition;
+    children?: Snippet;
+}
+declare const Tooltip: import("svelte").Component<Props, {}, "">;
+type Tooltip = ReturnType<typeof Tooltip>;
+export default Tooltip;

package/dist/components/docs/VersionSwitcher.svelte

@@ -0,0 +1,95 @@
+<script lang="ts">
+  import { ChevronDown, Check } from 'lucide-svelte';
+  import { goto } from '$app/navigation';
+  import { page } from '$app/stores';
+  import { browser } from '$app/environment';
+
+  interface Props {
+    currentVersion: string;
+    versions: string[];
+  }
+
+  let { currentVersion, versions }: Props = $props();
+
+  let isOpen = $state(false);
+  let dropdownEl = $state<HTMLDivElement | null>(null);
+
+  $effect(() => {
+    if (!browser || !isOpen) return;
+
+    function handleClickOutside(e: MouseEvent) {
+      if (dropdownEl && !dropdownEl.contains(e.target as Node)) {
+        isOpen = false;
+      }
+    }
+
+    function handleEscape(e: KeyboardEvent) {
+      if (e.key === 'Escape') {
+        isOpen = false;
+      }
+    }
+
+    document.addEventListener('click', handleClickOutside);
+    document.addEventListener('keydown', handleEscape);
+
+    return () => {
+      document.removeEventListener('click', handleClickOutside);
+      document.removeEventListener('keydown', handleEscape);
+    };
+  });
+
+  function switchVersion(version: string) {
+    if (version === currentVersion) {
+      isOpen = false;
+      return;
+    }
+
+    const currentPath = $page.url.pathname;
+    const newPath = currentPath.replace(
+      new RegExp(`/${currentVersion}(/|$)`),
+      `/${version}$1`
+    );
+
+    isOpen = false;
+    goto(newPath);
+  }
+</script>
+
+{#if versions.length > 1}
+  <div class="relative" bind:this={dropdownEl}>
+    <button
+      onclick={() => (isOpen = !isOpen)}
+      class="flex items-center gap-1.5 h-8 px-3 text-sm font-medium rounded-md border border-border bg-background hover:bg-accent transition-colors text-foreground"
+      aria-expanded={isOpen}
+      aria-haspopup="listbox"
+      aria-label="Switch version"
+    >
+      <span>{currentVersion}</span>
+      <ChevronDown class="h-3.5 w-3.5 text-muted-foreground transition-transform {isOpen ? 'rotate-180' : ''}" />
+    </button>
+
+    {#if isOpen}
+      <div
+        class="absolute top-full right-0 mt-1 w-40 py-1 bg-popover border border-border rounded-md shadow-lg z-50"
+        role="listbox"
+        aria-label="Available versions"
+      >
+        {#each versions as version}
+          <button
+            role="option"
+            aria-selected={version === currentVersion}
+            onclick={() => switchVersion(version)}
+            class="w-full flex items-center justify-between px-3 py-1.5 text-sm transition-colors {version === currentVersion
+              ? 'text-primary bg-accent/50 font-medium'
+              : 'text-foreground hover:bg-accent'}"
+          >
+            <span>{version}</span>
+            {#if version === currentVersion}
+              <Check class="h-3.5 w-3.5 text-primary" />
+            {/if}
+          </button>
+        {/each}
+      </div>
+    {/if}
+  </div>
+{/if}

package/dist/components/docs/VersionSwitcher.svelte.d.ts

@@ -0,0 +1,7 @@
+interface Props {
+    currentVersion: string;
+    versions: string[];
+}
+declare const VersionSwitcher: import("svelte").Component<Props, {}, "">;
+type VersionSwitcher = ReturnType<typeof VersionSwitcher>;
+export default VersionSwitcher;

package/dist/components/docs/Video.svelte

@@ -0,0 +1,84 @@
+<script lang="ts">
+  interface Props {
+    src: string;
+    caption?: string;
+    autoplay?: boolean;
+    loop?: boolean;
+    muted?: boolean;
+    controls?: boolean;
+    poster?: string;
+  }
+
+  let {
+    src,
+    caption,
+    autoplay = false,
+    loop = false,
+    muted = false,
+    controls = true,
+    poster,
+  }: Props = $props();
+
+  // YouTube URL detection
+  function getYouTubeId(url: string): string | null {
+    const match = url.match(
+      /(?:youtube\.com\/(?:[^/]+\/.+\/|(?:v|e(?:mbed)?)\/|.*[?&]v=)|youtu\.be\/)([^"&?/\s]{11})/
+    );
+    return match ? match[1] : null;
+  }
+
+  // Vimeo URL detection
+  function getVimeoId(url: string): string | null {
+    const match = url.match(/vimeo\.com\/(\d+)/);
+    return match ? match[1] : null;
+  }
+
+  let isYouTube = $derived(src.includes('youtube.com') || src.includes('youtu.be'));
+  let isVimeo = $derived(src.includes('vimeo.com'));
+  let youtubeId = $derived(getYouTubeId(src));
+  let vimeoId = $derived(getVimeoId(src));
+</script>
+
+<figure class="my-6">
+  <div class="relative rounded-xl border border-border overflow-hidden bg-muted/30">
+    {#if isYouTube && youtubeId}
+      <div class="relative w-full" style="padding-bottom: 56.25%;">
+        <iframe
+          class="absolute top-0 left-0 w-full h-full"
+          src="https://www.youtube.com/embed/{youtubeId}{autoplay ? '?autoplay=1' : ''}"
+          title="YouTube video"
+          allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture"
+          allowfullscreen
+        ></iframe>
+      </div>
+    {:else if isVimeo && vimeoId}
+      <div class="relative w-full" style="padding-bottom: 56.25%;">
+        <iframe
+          class="absolute top-0 left-0 w-full h-full"
+          src="https://player.vimeo.com/video/{vimeoId}{autoplay ? '?autoplay=1' : ''}"
+          title="Vimeo video"
+          allow="autoplay; fullscreen; picture-in-picture"
+          allowfullscreen
+        ></iframe>
+      </div>
+    {:else}
+      <video
+        {src}
+        {controls}
+        autoplay={autoplay}
+        {loop}
+        {muted}
+        {poster}
+        class="w-full h-auto"
+      >
+        Your browser does not support the video tag.
+        <track kind="captions" />
+      </video>
+    {/if}
+  </div>
+  {#if caption}
+    <figcaption class="mt-2 text-center text-sm text-muted-foreground italic">
+      {caption}
+    </figcaption>
+  {/if}
+</figure>