@alliance-droid/svelte-docs-system 0.0.1

package/docs/en/components/index.md

@@ -0,0 +1,622 @@
+---
+title: Components Reference
+description: Complete reference for all documentation system components
+author: Andrew
+date: 2026-02-05
+---
+
+# Components Reference
+
+Complete reference for the 6 core components that make up the SvelteKit Documentation System.
+
+## Overview
+
+The documentation system provides these ready-to-use components:
+
+1. **DocLayout** - Main wrapper that orchestrates all theme components
+2. **Navbar** - Fixed header with navigation and controls
+3. **Sidebar** - Responsive navigation sidebar
+4. **Footer** - Multi-column footer with links
+5. **Callout** - Alert boxes with info/warning/success/error variants
+6. **Breadcrumbs** - Path navigation for current page
+
+Additional utility components:
+- **CodeBlock** - Code highlighting with copy button
+- **Tabs** - Tabbed content switcher
+- **Image** - Responsive image with captions
+- **APITable** - API reference table component
+- **Search** - Full-text search interface
+
+## Component Import
+
+Import components from `$lib/components`:
+
+```typescript
+import DocLayout from '$lib/components/DocLayout.svelte';
+import Navbar from '$lib/components/Navbar.svelte';
+import Sidebar from '$lib/components/Sidebar.svelte';
+import Footer from '$lib/components/Footer.svelte';
+import Callout from '$lib/components/Callout.svelte';
+import Breadcrumbs from '$lib/components/Breadcrumbs.svelte';
+```
+
+Or use the barrel export:
+
+```typescript
+import {
+  DocLayout,
+  Navbar,
+  Sidebar,
+  Footer,
+  Callout,
+  Breadcrumbs,
+} from '$lib/components';
+```
+
+## 1. DocLayout
+
+**Purpose:** Main wrapper component that orchestrates theme, navbar, sidebar, and footer.
+
+### Props
+
+```typescript
+interface DocLayoutProps {
+  title?: string;              // Documentation title/site name
+  logo?: string | null;        // Logo image URL
+  sections?: NavSection[];     // Navigation sections for sidebar
+  copyright?: string;          // Footer copyright text
+  footerLinks?: FooterLink[];  // Additional footer links
+  children?: Snippet;          // Page content
+}
+
+interface NavSection {
+  title: string;
+  items: NavItem[];
+}
+
+interface NavItem {
+  label: string;
+  href?: string;
+  icon?: string;
+  children?: NavItem[];
+}
+
+interface FooterLink {
+  label: string;
+  href: string;
+}
+```
+
+### Example Usage
+
+```svelte
+<script lang="ts">
+  import DocLayout from '$lib/components/DocLayout.svelte';
+  import type { NavSection } from '$lib/stores/nav';
+
+  const sections: NavSection[] = [
+    {
+      title: 'Documentation',
+      items: [
+        { label: 'Home', href: '/docs' },
+        { label: 'Setup', href: '/docs/setup' },
+      ],
+    },
+  ];
+</script>
+
+<DocLayout
+  title="My Documentation"
+  logo="/logo.svg"
+  {sections}
+  copyright="© 2026 My Project"
+  footerLinks={[
+    { label: 'GitHub', href: 'https://github.com/myproject' },
+    { label: 'Support', href: 'https://support.myproject.com' },
+  ]}
+>
+  <slot />
+</DocLayout>
+```
+
+### Features
+
+- ✅ Responsive grid layout (sidebar + main content)
+- ✅ Mobile sidebar overlay with backdrop
+- ✅ Dark mode support
+- ✅ Sticky navbar
+- ✅ Automatic active page highlighting
+- ✅ Accessible navigation
+
+---
+
+## 2. Navbar
+
+**Purpose:** Fixed header with logo, navigation toggle, theme selector, and controls.
+
+### Props
+
+```typescript
+interface NavbarProps {
+  title?: string;           // Brand/site name
+  logo?: string | null;     // Logo image URL
+  onLogoClick?: () => void; // Logo click handler
+}
+```
+
+### Example Usage
+
+```svelte
+<script lang="ts">
+  import Navbar from '$lib/components/Navbar.svelte';
+
+  function handleLogoClick() {
+    window.location.href = '/';
+  }
+</script>
+
+<Navbar
+  title="My Docs"
+  logo="/logo.svg"
+  onLogoClick={handleLogoClick}
+/>
+```
+
+### Features
+
+- ✅ Sticky positioning at viewport top
+- ✅ Logo/brand click handler
+- ✅ Mobile hamburger menu button
+- ✅ Dark mode toggle (sun/moon icons)
+- ✅ Language selector dropdown
+- ✅ Version selector dropdown
+- ✅ Responsive: hamburger on mobile, controls on desktop
+- ✅ FontAwesome icon support
+
+### Customizing Navbar
+
+Edit `src/lib/components/Navbar.svelte` to add custom buttons or controls:
+
+```svelte
+<nav class="navbar">
+  <div class="navbar-brand">
+    <button on:click={onLogoClick}>
+      {#if logo}
+        <img src={logo} alt={title} />
+      {/if}
+      {title}
+    </button>
+  </div>
+
+  <div class="navbar-center">
+    <!-- Add custom buttons here -->
+    <button class="btn btn-sm">Custom Action</button>
+  </div>
+
+  <div class="navbar-end">
+    <!-- Hamburger, theme toggle, etc -->
+  </div>
+</nav>
+```
+
+---
+
+## 3. Sidebar
+
+**Purpose:** Responsive navigation sidebar with nested items, active highlighting, and mobile overlay.
+
+### Props
+
+```typescript
+interface SidebarProps {
+  sections?: NavSection[];              // Navigation sections
+  currentPath?: string;                 // Current route for active state
+  onNavigate?: (path: string) => void; // Called when item clicked
+}
+```
+
+### Example Usage
+
+```svelte
+<script lang="ts">
+  import Sidebar from '$lib/components/Sidebar.svelte';
+  import { page } from '$app/stores';
+
+  let currentPath = $derived($page.url.pathname);
+
+  const sections = [
+    {
+      title: 'Getting Started',
+      items: [
+        { label: 'Installation', href: '/docs/install' },
+        { label: 'Quick Start', href: '/docs/quick-start' },
+      ],
+    },
+  ];
+
+  function handleNavigate(path: string) {
+    window.location.href = path;
+  }
+</script>
+
+<Sidebar {sections} {currentPath} onNavigate={handleNavigate} />
+```
+
+### Features
+
+- ✅ Collapsible sections
+- ✅ Nested navigation items
+- ✅ Active page highlighting with blue accent
+- ✅ Mobile overlay with backdrop
+- ✅ Auto-close on navigation (mobile)
+- ✅ FontAwesome icon support
+- ✅ Smooth slide-in animation
+- ✅ Scrollable on overflow
+
+### Sidebar Variants
+
+**Compact mode** (less padding):
+
+```svelte
+<style>
+  :global(.sidebar-item) {
+    @apply py-1 px-2; /* Less padding */
+  }
+</style>
+```
+
+**Collapsible sections** (by default):
+
+```svelte
+<script lang="ts">
+  let expandedSections = new Set();
+
+  function toggleSection(title: string) {
+    if (expandedSections.has(title)) {
+      expandedSections.delete(title);
+    } else {
+      expandedSections.add(title);
+    }
+    expandedSections = expandedSections;
+  }
+</script>
+```
+
+---
+
+## 4. Footer
+
+**Purpose:** Multi-column footer with project info, links, and social media.
+
+### Props
+
+```typescript
+interface FooterProps {
+  copyright?: string;                        // Copyright text
+  links?: { label: string; href: string }[]; // Footer links
+}
+```
+
+### Example Usage
+
+```svelte
+<script lang="ts">
+  import Footer from '$lib/components/Footer.svelte';
+</script>
+
+<Footer
+  copyright="© 2026 My Project. All rights reserved."
+  links={[
+    { label: 'GitHub', href: 'https://github.com' },
+    { label: 'Twitter', href: 'https://twitter.com' },
+    { label: 'Support', href: 'https://support.example.com' },
+  ]}
+/>
+```
+
+### Features
+
+- ✅ Three-column layout (About, Resources, Connect)
+- ✅ Responsive grid (stacks on mobile)
+- ✅ Social media buttons
+- ✅ Copyright notice
+- ✅ Dark mode styling
+- ✅ Customizable links
+- ✅ FontAwesome icon support
+
+### Footer Structure
+
+```
+┌─────────────────────────────────────────┐
+│ About          Resources      Connect   │
+│ Description    - Link 1       GitHub   │
+│ of project     - Link 2       Twitter  │
+│                - Link 3       Email    │
+│ © 2026         - Link 4       RSS      │
+└─────────────────────────────────────────┘
+```
+
+---
+
+## 5. Callout
+
+**Purpose:** Alert boxes with different variants (info, warning, success, error).
+
+### Props
+
+```typescript
+interface CalloutProps {
+  variant?: 'info' | 'warning' | 'success' | 'error'; // Box type
+  title?: string;                                       // Optional title
+  icon?: string;                                        // FontAwesome icon
+  children?: Snippet;                                   // Content
+}
+```
+
+### Example Usage
+
+```svelte
+<script lang="ts">
+  import Callout from '$lib/components/Callout.svelte';
+</script>
+
+<!-- Info callout -->
+<Callout variant="info" title="Pro Tip">
+  You can customize colors in tailwind.config.ts
+</Callout>
+
+<!-- Warning callout -->
+<Callout variant="warning" title="Breaking Change">
+  Version 2.0 requires Node.js 18+
+</Callout>
+
+<!-- Success callout -->
+<Callout variant="success" title="Installation Complete">
+  Your documentation system is ready to use!
+</Callout>
+
+<!-- Error callout -->
+<Callout variant="error" title="Configuration Error">
+  Please check your theme configuration
+</Callout>
+```
+
+### Callout Variants
+
+| Variant | Color | Icon | Use Case |
+|---------|-------|------|----------|
+| `info` | Blue | ℹ️ | Tips, notes, FYI |
+| `warning` | Amber | ⚠️ | Important warnings |
+| `success` | Green | ✓ | Confirmations, completed tasks |
+| `error` | Red | ✕ | Errors, failures |
+
+### Styling
+
+```svelte
+<style>
+  :global(.callout-info) {
+    @apply bg-blue-50 border-l-4 border-blue-500;
+  }
+
+  :global(.callout-info.dark) {
+    @apply bg-blue-900/20 border-blue-400;
+  }
+</style>
+```
+
+---
+
+## 6. Breadcrumbs
+
+**Purpose:** Display current page path as navigable breadcrumbs.
+
+### Props
+
+```typescript
+interface BreadcrumbsProps {
+  items?: BreadcrumbItem[];
+}
+
+interface BreadcrumbItem {
+  label: string;
+  href?: string;    // Optional - no href = current page
+}
+```
+
+### Example Usage
+
+```svelte
+<script lang="ts">
+  import Breadcrumbs from '$lib/components/Breadcrumbs.svelte';
+</script>
+
+<Breadcrumbs
+  items={[
+    { label: 'Docs', href: '/docs' },
+    { label: 'Getting Started', href: '/docs/getting-started' },
+    { label: 'Installation' }, <!-- Current page -->
+  ]}
+/>
+```
+
+### Rendering
+
+```
+Home > Documentation > Getting Started > Installation
+```
+
+### Auto-Generate from Path
+
+```typescript
+import { page } from '$app/stores';
+
+let breadcrumbs = $derived.by(() => {
+  const segments = $page.url.pathname
+    .split('/')
+    .filter(s => s && s !== 'docs');
+
+  return [
+    { label: 'Docs', href: '/docs' },
+    ...segments.map((segment, i) => ({
+      label: segment
+        .split('-')
+        .map(w => w.charAt(0).toUpperCase() + w.slice(1))
+        .join(' '),
+      href: i < segments.length - 1
+        ? '/docs/' + segments.slice(0, i + 1).join('/')
+        : undefined,
+    })),
+  ];
+});
+```
+
+---
+
+## Additional Components
+
+### CodeBlock
+
+Syntax-highlighted code blocks with copy button:
+
+```svelte
+<script lang="ts">
+  import CodeBlock from '$lib/components/CodeBlock.svelte';
+</script>
+
+<CodeBlock
+  language="typescript"
+  code={`export interface Props {
+  title: string;
+  variant: 'info' | 'warning';
+}`}
+/>
+```
+
+### Tabs
+
+Tabbed content interface:
+
+```svelte
+<script lang="ts">
+  import Tabs from '$lib/components/Tabs.svelte';
+</script>
+
+<Tabs
+  tabs={[
+    { label: 'TypeScript', content: '// TS code' },
+    { label: 'JavaScript', content: '// JS code' },
+  ]}
+/>
+```
+
+### Image
+
+Responsive images with captions:
+
+```svelte
+<script lang="ts">
+  import Image from '$lib/components/Image.svelte';
+</script>
+
+<Image
+  src="/screenshots/dashboard.png"
+  alt="Dashboard overview"
+  caption="The main dashboard interface"
+  width={800}
+  height={600}
+/>
+```
+
+### APITable
+
+API reference table component:
+
+```svelte
+<script lang="ts">
+  import APITable from '$lib/components/APITable.svelte';
+</script>
+
+<APITable
+  rows={[
+    {
+      method: 'GET',
+      endpoint: '/api/users',
+      description: 'Get all users',
+      returns: 'User[]',
+    },
+    {
+      method: 'POST',
+      endpoint: '/api/users',
+      description: 'Create new user',
+      returns: 'User',
+    },
+  ]}
+/>
+```
+
+---
+
+## Component Composition
+
+Build custom components by composing these primitives:
+
+```svelte
+<script lang="ts">
+  import Callout from '$lib/components/Callout.svelte';
+  import CodeBlock from '$lib/components/CodeBlock.svelte';
+</script>
+
+<Callout variant="warning" title="Before You Start">
+  This example requires Node.js 18+
+</Callout>
+
+<CodeBlock
+  language="bash"
+  code="npm install my-package"
+/>
+```
+
+---
+
+## Accessibility
+
+All components follow Web Content Accessibility Guidelines (WCAG):
+
+- ✅ Semantic HTML
+- ✅ ARIA labels where needed
+- ✅ Keyboard navigation support
+- ✅ Sufficient color contrast
+- ✅ Focus management
+- ✅ Screen reader tested
+
+---
+
+## Dark Mode
+
+All components fully support dark mode via Tailwind's `dark:` prefix:
+
+```svelte
+<div class="bg-claude-bg dark:bg-claude-dark-bg text-claude-text dark:text-claude-dark-text">
+  Content adapts to theme automatically
+</div>
+```
+
+---
+
+## Responsive Design
+
+Components are fully responsive:
+
+- **Mobile** (< 768px) - Single column, stacked layout
+- **Tablet** (768px - 1024px) - Two column layout
+- **Desktop** (> 1024px) - Full multi-column layout
+
+Test using browser dev tools to verify responsive behavior.
+
+---
+
+## Next Steps
+
+- [Explore Component Examples](/docs/components/examples)
+- [Customize Component Styling](/docs/config/theme)
+- [Build Custom Components](/docs/guides/custom-components)