specra 0.1.13 → 0.2.0

package/dist/components/docs/SidebarMenuItems.svelte

@@ -0,0 +1,344 @@
+<script lang="ts">
+  import { page } from '$app/stores';
+  import { ChevronRight, ChevronDown, FolderOpen, Lock } from 'lucide-svelte';
+  import type { SpecraConfig } from '../../config.types.js';
+  import Icon from './Icon.svelte';
+  import { sortSidebarItems, sortSidebarGroups } from '../../sidebar-utils.js';
+
+  interface DocItem {
+    title: string;
+    slug: string;
+    filePath: string;
+    section?: string;
+    group?: string;
+    sidebar?: string;
+    sidebar_position?: number;
+    categoryLabel?: string;
+    categoryPosition?: number;
+    categoryCollapsible?: boolean;
+    categoryCollapsed?: boolean;
+    categoryIcon?: string;
+    categoryTabGroup?: string;
+    meta?: {
+      icon?: string;
+      tab_group?: string;
+      sidebar_position?: number;
+      order?: number;
+      [key: string]: any;
+    };
+  }
+
+  interface SidebarGroup {
+    label: string;
+    path: string;
+    icon?: string;
+    items: DocItem[];
+    position: number;
+    collapsible: boolean;
+    defaultCollapsed: boolean;
+    children: Record<string, SidebarGroup>;
+  }
+
+  interface Props {
+    docs: DocItem[];
+    version: string;
+    onLinkClick?: () => void;
+    config: SpecraConfig;
+    activeTabGroup?: string;
+  }
+
+  let { docs, version, onLinkClick, config, activeTabGroup }: Props = $props();
+
+  let collapsed: Record<string, boolean> = $state({});
+  let pathname = $derived($page.url.pathname);
+
+  // Filter docs by active tab group if tab groups are configured
+  let hasTabGroups = $derived(
+    config.navigation?.tabGroups && config.navigation.tabGroups.length > 0
+  );
+
+  let filteredDocs = $derived.by(() => {
+    if (hasTabGroups && activeTabGroup) {
+      return docs.filter((doc) => {
+        const docTabGroup = doc.meta?.tab_group || doc.categoryTabGroup;
+        if (!docTabGroup) {
+          return activeTabGroup === config.navigation?.tabGroups?.[0]?.id;
+        }
+        return docTabGroup === activeTabGroup;
+      });
+    }
+    return docs;
+  });
+
+  // Build hierarchical tree structure
+  interface SidebarStructure {
+    rootGroups: Record<string, SidebarGroup>;
+    standalone: DocItem[];
+  }
+
+  let structure = $derived.by((): SidebarStructure => {
+    const rootGroups: Record<string, SidebarGroup> = {};
+    const standalone: DocItem[] = [];
+
+    filteredDocs.forEach((doc) => {
+      const pathParts = doc.filePath.split('/');
+      const isIndexFile =
+        doc.filePath.endsWith('/index') ||
+        doc.filePath === 'index' ||
+        (pathParts.length > 1 && doc.slug === pathParts.slice(0, -1).join('/'));
+
+      const customGroup = doc.sidebar || doc.group;
+
+      if (customGroup) {
+        const groupName = customGroup.charAt(0).toUpperCase() + customGroup.slice(1);
+        if (!rootGroups[groupName]) {
+          rootGroups[groupName] = {
+            label: groupName,
+            path: customGroup,
+            items: [],
+            position: 999,
+            collapsible: doc.categoryCollapsible ?? true,
+            defaultCollapsed: doc.categoryCollapsed ?? false,
+            children: {}
+          };
+        }
+        if (isIndexFile) {
+          rootGroups[groupName].position = doc.sidebar_position ?? 999;
+          rootGroups[groupName].icon = doc.categoryIcon;
+        } else {
+          rootGroups[groupName].items.push(doc);
+        }
+        return;
+      }
+
+      if (pathParts.length > 1) {
+        const folderParts = pathParts.slice(0, -1);
+        let currentLevel = rootGroups;
+        let currentPath = '';
+
+        for (let i = 0; i < folderParts.length; i++) {
+          const folder = folderParts[i];
+          currentPath = currentPath ? `${currentPath}/${folder}` : folder;
+          const folderLabel = folder
+            .split('-')
+            .map((w) => w.charAt(0).toUpperCase() + w.slice(1))
+            .join(' ');
+
+          if (!currentLevel[folder]) {
+            currentLevel[folder] = {
+              label:
+                doc.categoryLabel && i === folderParts.length - 1
+                  ? doc.categoryLabel
+                  : folderLabel,
+              path: currentPath,
+              icon: doc.categoryIcon,
+              items: [],
+              position: doc.categoryPosition ?? 999,
+              collapsible: doc.categoryCollapsible ?? true,
+              defaultCollapsed: doc.categoryCollapsed ?? false,
+              children: {}
+            };
+          }
+
+          if (i === folderParts.length - 1) {
+            if (isIndexFile) {
+              currentLevel[folder].position =
+                doc.categoryPosition ?? doc.sidebar_position ?? 999;
+              if (doc.categoryLabel) {
+                currentLevel[folder].label = doc.categoryLabel;
+              }
+              if (doc.categoryIcon) {
+                currentLevel[folder].icon = doc.categoryIcon;
+              }
+            } else {
+              currentLevel[folder].items.push(doc);
+            }
+          }
+
+          currentLevel = currentLevel[folder].children;
+        }
+      } else {
+        if (!isIndexFile) {
+          standalone.push(doc);
+        }
+      }
+    });
+
+    return { rootGroups, standalone };
+  });
+
+  let sortedRootGroups = $derived(sortSidebarGroups(structure.rootGroups));
+  let sortedStandalone = $derived(sortSidebarItems(structure.standalone));
+
+  function toggleSection(section: string) {
+    collapsed = { ...collapsed, [section]: !collapsed[section] };
+  }
+
+  function isActiveInGroup(group: SidebarGroup): boolean {
+    const hasActiveItem = group.items.some(
+      (doc) => pathname === `/docs/${version}/${doc.slug}`
+    );
+    if (hasActiveItem) return true;
+    return Object.values(group.children).some((child) => isActiveInGroup(child));
+  }
+
+  function getGroupHref(group: SidebarGroup): string {
+    let groupHref = `/docs/${version}/${group.path}`;
+
+    if (config.features?.i18n) {
+      const i18n = config.features.i18n;
+      const locales = typeof i18n === 'object' ? i18n.locales : ['en'];
+      const pathParts = pathname?.split('/') || [];
+      const potentialLocale = pathParts[3];
+
+      if (potentialLocale && locales.includes(potentialLocale)) {
+        groupHref = `/docs/${version}/${potentialLocale}/${group.path}`;
+      }
+    }
+
+    return groupHref;
+  }
+
+  function isGroupCollapsed(groupKey: string, group: SidebarGroup): boolean {
+    const hasActive = isActiveInGroup(group);
+    const isGroupActive = pathname === `/docs/${version}/${group.path}`;
+    if (hasActive || isGroupActive) return false;
+    return collapsed[groupKey] ?? group.defaultCollapsed;
+  }
+
+  type MergedItem =
+    | { type: 'group'; key: string; group: SidebarGroup; position: number }
+    | { type: 'item'; doc: DocItem; position: number };
+
+  function getMergedItems(group: SidebarGroup): MergedItem[] {
+    const sortedItems = sortSidebarItems(group.items);
+    const sortedChildren = sortSidebarGroups(group.children);
+
+    const merged: MergedItem[] = [
+      ...sortedChildren.map(([childKey, childGroup]) => ({
+        type: 'group' as const,
+        key: childKey,
+        group: childGroup,
+        position: childGroup.position
+      })),
+      ...sortedItems.map((doc) => ({
+        type: 'item' as const,
+        doc,
+        position: doc.sidebar_position ?? doc.meta?.sidebar_position ?? doc.meta?.order ?? 999
+      }))
+    ];
+
+    merged.sort((a, b) => a.position - b.position);
+    return merged;
+  }
+</script>
+
+<!-- Recursive group renderer component -->
+{#snippet renderGroup(groupKey: string, group: SidebarGroup, depth: number)}
+  {@const sortedItems = sortSidebarItems(group.items)}
+  {@const sortedChildren = sortSidebarGroups(group.children)}
+  {@const hasChildren = sortedChildren.length > 0}
+  {@const hasItems = sortedItems.length > 0}
+  {@const hasContent = hasChildren || hasItems}
+  {@const isGroupActive = pathname === `/docs/${version}/${group.path}`}
+  {@const isCollapsed = isGroupCollapsed(groupKey, group)}
+  {@const marginLeft = depth > 0 ? 'ml-4' : ''}
+  {@const groupHref = getGroupHref(group)}
+  {@const mergedItems = getMergedItems(group)}
+
+  <div class="space-y-1 {marginLeft}">
+    <div class="flex items-center group">
+      <a
+        href={groupHref}
+        onclick={(e) => {
+          e.preventDefault();
+          toggleSection(groupKey);
+        }}
+        class="flex items-center gap-2 flex-1 px-3 py-2 text-sm font-semibold rounded-l-xl transition-all {isGroupActive
+          ? 'bg-primary/10 text-primary'
+          : 'text-foreground hover:bg-accent/50'}"
+      >
+        {#if group.icon}
+          <Icon icon={group.icon} size={16} className="shrink-0" />
+        {:else}
+          <FolderOpen size={16} class="shrink-0" />
+        {/if}
+        {group.label}
+      </a>
+
+      {#if hasContent && group.collapsible && config.navigation?.collapsibleSidebar}
+        <button
+          onclick={(e) => {
+            e.preventDefault();
+            e.stopPropagation();
+            toggleSection(groupKey);
+          }}
+          class="p-2 rounded-r-xl transition-all {isGroupActive ? 'hover:bg-primary/20' : 'hover:bg-accent/50'}"
+          aria-label={isCollapsed ? 'Expand section' : 'Collapse section'}
+        >
+          {#if isCollapsed}
+            <ChevronRight class="h-4 w-4 {isGroupActive ? 'text-primary' : 'text-muted-foreground'}" />
+          {:else}
+            <ChevronDown class="h-4 w-4 {isGroupActive ? 'text-primary' : 'text-muted-foreground'}" />
+          {/if}
+        </button>
+      {/if}
+    </div>
+
+    {#if !isCollapsed && hasContent}
+      <div class="ml-4 space-y-1">
+        {#each mergedItems as item}
+          {#if item.type === 'group'}
+            {@render renderGroup(`${groupKey}/${item.key}`, item.group, depth + 1)}
+          {:else}
+            {@const href = `/docs/${version}/${item.doc.slug}`}
+            {@const isActive = pathname === href}
+            <a
+              {href}
+              onclick={onLinkClick}
+              class="flex items-center gap-2 px-3 py-2 text-sm rounded-xl transition-all {isActive
+                ? 'bg-primary/10 text-primary font-medium'
+                : 'text-foreground hover:text-foreground hover:bg-accent/50'}"
+            >
+              {#if item.doc.meta?.icon}
+                <Icon icon={item.doc.meta.icon} size={16} className="shrink-0" />
+              {/if}
+              {item.doc.title}
+              {#if item.doc.meta?.isProtected}
+                <Lock size={14} class="shrink-0 text-muted-foreground ml-auto" />
+              {/if}
+            </a>
+          {/if}
+        {/each}
+      </div>
+    {/if}
+  </div>
+{/snippet}
+
+<nav class="space-y-1">
+  {#if sortedStandalone.length > 0}
+    {#each sortedStandalone as doc (doc.slug)}
+      {@const href = `/docs/${version}/${doc.slug}`}
+      {@const isActive = pathname === href}
+      <a
+        {href}
+        onclick={onLinkClick}
+        class="flex items-center gap-2 px-3 py-2 text-sm rounded-xl transition-all {isActive
+          ? 'bg-primary/10 text-primary font-medium'
+          : 'text-foreground hover:text-foreground hover:bg-accent/50'}"
+      >
+        {#if doc.meta?.icon}
+          <Icon icon={doc.meta.icon} size={16} className="shrink-0" />
+        {/if}
+        {doc.title}
+        {#if doc.meta?.isProtected}
+          <Lock size={14} class="shrink-0 text-muted-foreground ml-auto" />
+        {/if}
+      </a>
+    {/each}
+  {/if}
+
+  {#each sortedRootGroups as [groupKey, group] (groupKey)}
+    {@render renderGroup(groupKey, group, 0)}
+  {/each}
+</nav>

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

@@ -0,0 +1,33 @@
+import type { SpecraConfig } from '../../config.types.js';
+interface DocItem {
+    title: string;
+    slug: string;
+    filePath: string;
+    section?: string;
+    group?: string;
+    sidebar?: string;
+    sidebar_position?: number;
+    categoryLabel?: string;
+    categoryPosition?: number;
+    categoryCollapsible?: boolean;
+    categoryCollapsed?: boolean;
+    categoryIcon?: string;
+    categoryTabGroup?: string;
+    meta?: {
+        icon?: string;
+        tab_group?: string;
+        sidebar_position?: number;
+        order?: number;
+        [key: string]: any;
+    };
+}
+interface Props {
+    docs: DocItem[];
+    version: string;
+    onLinkClick?: () => void;
+    config: SpecraConfig;
+    activeTabGroup?: string;
+}
+declare const SidebarMenuItems: import("svelte").Component<Props, {}, "">;
+type SidebarMenuItems = ReturnType<typeof SidebarMenuItems>;
+export default SidebarMenuItems;

package/dist/components/docs/SidebarSkeleton.svelte

@@ -0,0 +1,50 @@
+<script lang="ts">
+  // SidebarSkeleton: Loading skeleton for the sidebar navigation
+</script>
+
+<div class="animate-pulse space-y-4 px-4 py-6">
+  <!-- Search skeleton -->
+  <div class="h-9 bg-muted rounded-md w-full"></div>
+
+  <!-- Group 1 -->
+  <div class="space-y-2">
+    <div class="h-4 bg-muted rounded-md w-24"></div>
+    <div class="space-y-1.5 pl-2">
+      <div class="h-4 bg-muted rounded-md w-36"></div>
+      <div class="h-4 bg-muted rounded-md w-28"></div>
+      <div class="h-4 bg-muted rounded-md w-32"></div>
+      <div class="h-4 bg-muted rounded-md w-24"></div>
+    </div>
+  </div>
+
+  <!-- Group 2 -->
+  <div class="space-y-2">
+    <div class="h-4 bg-muted rounded-md w-20"></div>
+    <div class="space-y-1.5 pl-2">
+      <div class="h-4 bg-muted rounded-md w-32"></div>
+      <div class="h-4 bg-muted rounded-md w-36"></div>
+      <div class="h-4 bg-muted rounded-md w-24"></div>
+    </div>
+  </div>
+
+  <!-- Group 3 -->
+  <div class="space-y-2">
+    <div class="h-4 bg-muted rounded-md w-28"></div>
+    <div class="space-y-1.5 pl-2">
+      <div class="h-4 bg-muted rounded-md w-28"></div>
+      <div class="h-4 bg-muted rounded-md w-36"></div>
+      <div class="h-4 bg-muted rounded-md w-32"></div>
+      <div class="h-4 bg-muted rounded-md w-20"></div>
+      <div class="h-4 bg-muted rounded-md w-28"></div>
+    </div>
+  </div>
+
+  <!-- Group 4 -->
+  <div class="space-y-2">
+    <div class="h-4 bg-muted rounded-md w-24"></div>
+    <div class="space-y-1.5 pl-2">
+      <div class="h-4 bg-muted rounded-md w-32"></div>
+      <div class="h-4 bg-muted rounded-md w-28"></div>
+    </div>
+  </div>
+</div>

package/dist/components/docs/SidebarSkeleton.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 SidebarSkeleton: $$__sveltets_2_IsomorphicComponent<Record<string, never>, {
+    [evt: string]: CustomEvent<any>;
+}, {}, {}, string>;
+type SidebarSkeleton = InstanceType<typeof SidebarSkeleton>;
+export default SidebarSkeleton;

package/dist/components/docs/SiteBanner.svelte

@@ -0,0 +1,92 @@
+<script lang="ts">
+  import { Info, AlertTriangle, CheckCircle, XCircle, X } from 'lucide-svelte';
+  import { browser } from '$app/environment';
+  import type { SpecraConfig } from '../../config.types.js';
+
+  interface Props {
+    config: SpecraConfig;
+  }
+
+  let { config }: Props = $props();
+
+  const banner = $derived(config.banner);
+  const isEnabled = $derived(banner?.enabled && banner?.message);
+  const bannerType = $derived(banner?.type || 'info');
+  const isDismissible = $derived(banner?.dismissible !== false);
+
+  let isDismissed = $state(false);
+
+  // Safe hash for storage key (handles non-Latin1 chars like emojis)
+  function safeHash(str: string): string {
+    let hash = 0;
+    for (let i = 0; i < str.length; i++) {
+      const char = str.charCodeAt(i);
+      hash = ((hash << 5) - hash) + char;
+      hash |= 0;
+    }
+    return Math.abs(hash).toString(36);
+  }
+
+  // Check localStorage for dismissal state
+  $effect(() => {
+    if (!browser || !banner?.message) return;
+    const storageKey = `specra-banner-dismissed-${safeHash(banner.message)}`;
+    const dismissed = localStorage.getItem(storageKey);
+    if (dismissed === 'true') {
+      isDismissed = true;
+    }
+  });
+
+  function dismiss() {
+    isDismissed = true;
+    if (browser && banner?.message) {
+      const storageKey = `specra-banner-dismissed-${safeHash(banner.message)}`;
+      localStorage.setItem(storageKey, 'true');
+    }
+  }
+
+  const typeStyles: Record<string, string> = {
+    info: 'bg-blue-500/10 border-blue-500/20 text-blue-700 dark:text-blue-300',
+    warning: 'bg-yellow-500/10 border-yellow-500/20 text-yellow-700 dark:text-yellow-300',
+    success: 'bg-green-500/10 border-green-500/20 text-green-700 dark:text-green-300',
+    error: 'bg-red-500/10 border-red-500/20 text-red-700 dark:text-red-300'
+  };
+
+  const iconColor: Record<string, string> = {
+    info: 'text-blue-500',
+    warning: 'text-yellow-500',
+    success: 'text-green-500',
+    error: 'text-red-500'
+  };
+</script>
+
+{#if isEnabled && !isDismissed}
+  <div
+    class="relative flex items-center justify-center gap-2 px-4 py-2.5 text-sm border-b {typeStyles[bannerType] || typeStyles.info}"
+    role="banner"
+  >
+    <span class="shrink-0 {iconColor[bannerType] || iconColor.info}">
+      {#if bannerType === 'info'}
+        <Info class="h-4 w-4" />
+      {:else if bannerType === 'warning'}
+        <AlertTriangle class="h-4 w-4" />
+      {:else if bannerType === 'success'}
+        <CheckCircle class="h-4 w-4" />
+      {:else if bannerType === 'error'}
+        <XCircle class="h-4 w-4" />
+      {/if}
+    </span>
+
+    <span class="text-center font-medium">{banner?.message}</span>
+
+    {#if isDismissible}
+      <button
+        onclick={dismiss}
+        class="absolute right-3 top-1/2 -translate-y-1/2 p-1 rounded-md hover:bg-black/10 dark:hover:bg-white/10 transition-colors"
+        aria-label="Dismiss banner"
+      >
+        <X class="h-3.5 w-3.5" />
+      </button>
+    {/if}
+  </div>
+{/if}

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

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

package/dist/components/docs/Step.svelte

@@ -0,0 +1,44 @@
+<script lang="ts">
+  import type { Snippet } from 'svelte';
+
+  interface Props {
+    title: string;
+    children?: Snippet;
+  }
+
+  let { title, children }: Props = $props();
+</script>
+
+<div class="step-item relative pl-8 pb-6 border-l-2 border-border last:border-l-0 last:pb-0">
+  <div class="mb-2">
+    <h3 class="text-lg font-semibold text-foreground">{title}</h3>
+  </div>
+  <div class="prose prose-sm dark:prose-invert max-w-none [&>*:last-child]:mb-0">
+    {#if children}
+      {@render children()}
+    {/if}
+  </div>
+</div>
+
+<style>
+  .step-item {
+    counter-increment: step;
+  }
+  .step-item::before {
+    content: counter(step);
+    position: absolute;
+    left: 0;
+    transform: translateX(-50%);
+    width: 2rem;
+    height: 2rem;
+    border-radius: 9999px;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    font-size: 0.875rem;
+    font-weight: 600;
+    z-index: 10;
+    background: hsl(var(--primary));
+    color: hsl(var(--primary-foreground));
+  }
+</style>

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

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

package/dist/components/docs/Steps.svelte

@@ -0,0 +1,15 @@
+<script lang="ts">
+  import type { Snippet } from 'svelte';
+
+  interface Props {
+    children?: Snippet;
+  }
+
+  let { children }: Props = $props();
+</script>
+
+<div class="my-6 ml-4 space-y-6" style="counter-reset: step;">
+  {#if children}
+    {@render children()}
+  {/if}
+</div>

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

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

package/dist/components/docs/Tab.svelte

@@ -0,0 +1,40 @@
+<script lang="ts">
+  import { getContext, onMount } from 'svelte';
+  import type { Writable } from 'svelte/store';
+  import type { Snippet } from 'svelte';
+
+  interface Props {
+    label: string;
+    children?: Snippet;
+  }
+
+  let { label, children }: Props = $props();
+
+  const ctx = getContext<{
+    registerTab: (label: string) => void;
+    activeTab: Writable<string>;
+    setActiveTab: (label: string) => void;
+  }>('specra-tabs');
+
+  let isActive = $state(false);
+
+  onMount(() => {
+    ctx.registerTab(label);
+  });
+
+  // Subscribe to active tab changes
+  $effect(() => {
+    const unsub = ctx.activeTab.subscribe((value) => {
+      isActive = value === label;
+    });
+    return unsub;
+  });
+</script>
+
+{#if isActive}
+  <div class="prose prose-slate dark:prose-invert max-w-none [&>*:first-child]:mt-0">
+    {#if children}
+      {@render children()}
+    {/if}
+  </div>
+{/if}

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

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