@alliance-droid/svelte-docs-system 0.0.2 → 0.1.1

package/docs/THEME_INHERITANCE.md

@@ -1,192 +0,0 @@
-# Theme Inheritance from Parent App
-
-## Overview
-
-The svelte-docs-system automatically inherits the theme (light/dark mode) from its parent application when embedded, eliminating the need for separate theme management. When used standalone, it maintains its own theme preference via localStorage.
-
-## Architecture
-
-### Parent Theme Detection
-
-The theme store implements a multi-level fallback system to determine the active theme:
-
-1. **Parent App Theme (when embedded)** - Checks if the docs are running inside a parent application
-2. **Stored Preference** - Falls back to localStorage in standalone mode
-3. **System Preference** - Uses OS-level dark mode preference if available
-4. **Default** - Falls back to 'light' theme
-
-### Detection Mechanism
-
-#### Embedded Detection
-```typescript
-function isEmbedded(): boolean {
-  try {
-    return window.parent !== window && window.parent !== null;
-  } catch {
-    return false;
-  }
-}
-```
-
-Checks if `window.parent` is different from the current window, indicating the app is embedded in an iframe or similar container.
-
-#### Parent Theme Detection
-```typescript
-function getParentTheme(): Theme | null {
-  if (!isEmbedded()) return null;
-  
-  try {
-    if (window.parent?.document?.documentElement) {
-      const hasDarkClass =
-        window.parent.document.documentElement.classList.contains('dark');
-      return hasDarkClass ? 'dark' : 'light';
-    }
-  } catch (e) {
-    // Cross-origin errors are silently handled
-  }
-  
-  return null;
-}
-```
-
-The parent app must apply the `dark` class to its `document.documentElement` when dark mode is active. This is the standard pattern used by Tailwind CSS and similar frameworks.
-
-### Reactive Synchronization
-
-When embedded, the store sets up a MutationObserver to watch the parent's `document.documentElement` for class changes:
-
-```typescript
-const observer = new MutationObserver((mutations) => {
-  mutations.forEach((mutation) => {
-    if (
-      mutation.type === 'attributes' &&
-      mutation.attributeName === 'class' &&
-      mutation.target === window.parent?.document?.documentElement
-    ) {
-      // Parent's dark class changed, update our theme
-      const parentTheme = getParentTheme();
-      if (parentTheme) {
-        applyTheme(parentTheme);
-        set(parentTheme);
-      }
-    }
-  });
-});
-```
-
-This ensures that when the parent app changes themes, the embedded docs automatically update.
-
-## Implementation Details
-
-### Parent App Requirements
-
-For the docs to detect and inherit the parent's theme, the parent application must:
-
-1. **Add/remove the `dark` class** on `document.documentElement`
-   ```javascript
-   // When switching to dark mode:
-   document.documentElement.classList.add('dark');
-   
-   // When switching to light mode:
-   document.documentElement.classList.remove('dark');
-   ```
-
-2. **Be on the same origin** (or use postMessage for cross-origin scenarios)
-
-### Standalone Mode
-
-When the docs are not embedded in a parent application:
-
-- Theme preference is saved to `localStorage` with key `'theme'`
-- User can toggle theme with the theme button in the navbar
-- Theme persists across page reloads
-- Falls back to system preference if no localStorage preference exists
-
-### Embedded Mode
-
-When the docs are embedded in a parent application:
-
-- **Theme is read-only** from the parent's perspective
-- The theme toggle button will still work but updates only the local document
-- localStorage is NOT used (avoids conflicts with parent app)
-- Automatically syncs with parent app theme changes
-- Gracefully handles cross-origin access restrictions
-
-## Error Handling
-
-The implementation is defensive and handles various edge cases:
-
-- **Cross-origin iframes** - Silently falls back to system preference when parent document is inaccessible
-- **Missing localStorage** - Uses optional chaining and try-catch blocks
-- **SSR environments** - Returns 'light' theme as default when window is undefined
-- **Null/undefined checks** - Uses optional chaining throughout
-
-## Testing
-
-The theme store includes comprehensive unit tests:
-
-- Theme initialization with various scenarios
-- Theme set/toggle operations
-- Dark class application to document
-- localStorage persistence in standalone mode
-- Reactive updates based on store changes
-
-Run tests with:
-```bash
-npm test -- src/lib/stores/theme.test.ts
-```
-
-## Example Integration
-
-### Parent App (system-db-dashboard)
-
-```typescript
-// In the parent app's theme store
-const { subscribe, set } = writable<Theme>(getInitialTheme());
-
-const setTheme = (theme: Theme) => {
-  if (theme === 'dark') {
-    document.documentElement.classList.add('dark');
-  } else {
-    document.documentElement.classList.remove('dark');
-  }
-  set(theme);
-};
-```
-
-### Embedded Docs
-
-The docs automatically detect and use the parent's theme without any additional configuration.
-
-## CSS Classes
-
-The theme uses the standard Tailwind CSS dark mode convention:
-
-- Light mode: No `dark` class
-- Dark mode: `dark` class on `html` element (document.documentElement)
-
-All styles use the `dark:` variant for dark mode:
-```css
-.text-light-color {
-  @apply text-black dark:text-white;
-}
-```
-
-## Future Enhancements
-
-Potential improvements for cross-origin scenarios:
-
-1. **PostMessage API** - Use window.parent.postMessage for cross-origin theme sync
-2. **Custom Events** - Emit/listen for custom theme change events
-3. **CSS Custom Properties** - Share theme colors via CSS variables instead of class names
-
-## Migration Guide
-
-If updating from the old theme system:
-
-1. The theme store API remains the same (`theme.set()`, `theme.toggle()`, `theme.subscribe()`)
-2. localStorage key is still `'theme'`
-3. Dark mode still uses the `dark` class on `document.documentElement`
-4. No changes needed in components using the theme store
-
-The new parent detection is completely transparent to existing code.

package/docs/de/index.md

@@ -1,41 +0,0 @@
----
-title: Dokumentationsstartseite
-description: Willkommen beim SvelteKit-Dokumentationssystem
-author: Andrew
-date: 2026-02-05
----
-
-# Willkommen beim Dokumentationssystem
-
-Dies ist die Startseite Ihrer Dokumentationswebsite. Sie demonstriert das Markdown-Routingsystem in Aktion.
-
-## Funktionen
-
-- **Automatisches Routing** von Markdown-Dateien
-- **Unterstützung verschachtelter Pfade** (Dokumente in Ordnern organisieren)
-- **Frontmatter-Metadaten** (Titel, Autor, Datum)
-- **Professionelle Formatierung** sofort einsatzbereit
-- **Einfach zu personalisieren** und zu erweitern
-
-## Erste Schritte
-
-Schauen Sie sich die [Installationsanleitung](/docs/de/setup) an, um zu beginnen.
-
-## Projektstruktur
-
-```
-docs/
-├── index.md                 (Diese Datei)
-├── setup.md                (Erste-Schritte-Anleitung)
-├── routing.md              (Funktionsweise des Routings)
-├── api/
-│   ├── overview.md         (API-Übersicht)
-│   └── examples.md         (API-Beispiele)
-└── guides/
-    └── advanced.md         (Fortgeschrittene Themen)
-```
-
-Jede Markdown-Datei wird automatisch zu einer Route:
-- `docs/setup.md` → `/docs/de/setup`
-- `docs/api/overview.md` → `/docs/de/api/overview`
-- `docs/guides/advanced.md` → `/docs/de/guides/advanced`

package/docs/en/COMPONENTS.md

@@ -1,443 +0,0 @@
-# Core Documentation Components
-
-A collection of reusable Svelte 5 components for building beautiful, accessible documentation sites.
-
----
-
-## Table of Contents
-
-1. [Callout](#callout) - Alert boxes with variants
-2. [Tabs](#tabs) - Switchable content panels
-3. [CodeBlock](#codeblock) - Code display with copy button
-4. [Image](#image) - Responsive images with captions
-5. [APITable](#apitable) - API reference tables
-6. [Breadcrumbs](#breadcrumbs) - Navigation breadcrumbs
-
----
-
-## Callout
-
-**Component:** `<Callout />`
-
-Alert/notification boxes for highlighting important information.
-
-### Props
-
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `variant` | `'info' \| 'warning' \| 'success' \| 'error'` | `'info'` | Visual style variant |
-| `title` | `string` | `undefined` | Optional callout title |
-| `children` | `Snippet` | required | Content to display |
-
-### Variants
-
-- **info** (blue) - General information and tips
-- **warning** (amber) - Caution messages
-- **success** (green) - Positive/successful messages
-- **error** (red) - Error or critical messages
-
-### Usage Examples
-
-```svelte
-<Callout variant="info" title="Note">
-  This is informational content.
-</Callout>
-
-<Callout variant="warning" title="Warning">
-  Be careful with this setting.
-</Callout>
-
-<Callout variant="success" title="Success">
-  Operation completed successfully!
-</Callout>
-
-<Callout variant="error" title="Error">
-  Something went wrong. Please try again.
-</Callout>
-```
-
-### Styling
-
-- Default background and border colors based on variant
-- Dark mode support with `dark:` classes
-- Font Awesome icons for visual indicators
-- Responsive padding and layout
-
----
-
-## Tabs
-
-**Component:** `<Tabs />`
-
-Display multiple content panels with tab navigation.
-
-### Props
-
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `items` | `TabItem[]` | required | Array of tab definitions |
-| `defaultIndex` | `number` | `0` | Initially active tab index |
-
-### TabItem Type
-
-```typescript
-interface TabItem {
-  label: string;        // Tab button label
-  content?: string;     // HTML content (optional)
-}
-```
-
-### Usage Examples
-
-```svelte
-<script>
-  const tabs = [
-    { label: 'JavaScript', content: '<code>const x = 42;</code>' },
-    { label: 'Python', content: '<code>x = 42</code>' },
-    { label: 'Rust', content: '<code>let x = 42;</code>' }
-  ];
-</script>
-
-<Tabs items={tabs} defaultIndex={0} />
-```
-
-### Features
-
-- Click to switch between tabs
-- Active tab highlighting
-- HTML content rendering
-- Smooth transitions
-- Keyboard accessible
-
----
-
-## CodeBlock
-
-**Component:** `<CodeBlock />`
-
-Display code with syntax highlighting and copy functionality.
-
-### Props
-
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `code` | `string` | required | The code content to display |
-| `language` | `string` | `'plaintext'` | Programming language identifier |
-| `filename` | `string` | `undefined` | Optional filename header |
-
-### Usage Examples
-
-```svelte
-<CodeBlock
-  code="console.log('Hello, World!');"
-  language="javascript"
-  filename="hello.js"
-/>
-
-<CodeBlock
-  code={`function greet(name) {
-  return \`Hello, \${name}!\`;
-}`}
-  language="javascript"
-  filename="greet.js"
-/>
-
-<CodeBlock
-  code="npm install @mypackage/docs"
-  language="bash"
-/>
-```
-
-### Features
-
-- Copy-to-clipboard button
-- Language label display
-- Optional filename header
-- Monospace font rendering
-- Dark mode support
-- Visual feedback on copy
-
----
-
-## Image
-
-**Component:** `<Image />`
-
-Responsive images with caption and zoom functionality.
-
-### Props
-
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `src` | `string` | required | Image source URL |
-| `alt` | `string` | required | Alt text for accessibility |
-| `caption` | `string` | `undefined` | Optional image caption |
-| `width` | `number` | `undefined` | Image width (optional) |
-| `height` | `number` | `undefined` | Image height (optional) |
-| `zoomable` | `boolean` | `true` | Enable zoom on click |
-
-### Usage Examples
-
-```svelte
-<Image
-  src="/path/to/image.jpg"
-  alt="A beautiful landscape"
-  caption="Sunset over the mountains"
-/>
-
-<Image
-  src="https://via.placeholder.com/600x400"
-  alt="Placeholder"
-  caption="This image can be zoomed"
-  width={600}
-  height={400}
-  zoomable={true}
-/>
-
-<Image
-  src="/screenshot.png"
-  alt="App screenshot"
-  zoomable={false}
-/>
-```
-
-### Features
-
-- Responsive layout
-- Click to zoom overlay
-- Figure caption support
-- Keyboard support (ESC to close)
-- Accessible markup
-- Image dimensions support
-
----
-
-## APITable
-
-**Component:** `<APITable />`
-
-Display API reference documentation in table format.
-
-### Props
-
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `columns` | `Column[]` | required | Column definitions |
-| `rows` | `Row[]` | required | Table data rows |
-| `title` | `string` | `undefined` | Optional table title |
-| `description` | `string` | `undefined` | Optional description |
-
-### Column Type
-
-```typescript
-interface Column {
-  key: string;        // Data key
-  label: string;      // Column header label
-  width?: string;     // Optional CSS width
-}
-```
-
-### Usage Examples
-
-```svelte
-<script>
-  const columns = [
-    { key: 'name', label: 'Parameter Name' },
-    { key: 'type', label: 'Type' },
-    { key: 'required', label: 'Required' },
-    { key: 'description', label: 'Description', width: '40%' }
-  ];
-
-  const rows = [
-    {
-      name: 'apiKey',
-      type: 'string',
-      required: true,
-      description: 'Your API authentication key'
-    },
-    {
-      name: 'timeout',
-      type: 'number',
-      required: false,
-      description: 'Request timeout in milliseconds'
-    }
-  ];
-</script>
-
-<APITable
-  title="API Configuration"
-  description="Configuration options for the API client"
-  columns={columns}
-  rows={rows}
-/>
-```
-
-### Features
-
-- Sortable column layout
-- Alternate row colors
-- Boolean/null value formatting
-- Custom column widths
-- Title and description support
-- Empty state handling
-- Dark mode styling
-
----
-
-## Breadcrumbs
-
-**Component:** `<Breadcrumbs />`
-
-Navigation breadcrumb trail showing current page location.
-
-### Props
-
-| Prop | Type | Default | Description |
-|------|------|---------|-------------|
-| `items` | `BreadcrumbItem[]` | required | Breadcrumb items |
-
-### BreadcrumbItem Type
-
-```typescript
-interface BreadcrumbItem {
-  label: string;       // Display text
-  href?: string;       // Optional link URL
-}
-```
-
-### Usage Examples
-
-```svelte
-<script>
-  const breadcrumbs = [
-    { label: 'Home', href: '/' },
-    { label: 'Docs', href: '/docs' },
-    { label: 'Components', href: '/docs/components' },
-    { label: 'Callout' }  // Current page (no href)
-  ];
-</script>
-
-<Breadcrumbs items={breadcrumbs} />
-```
-
-### Features
-
-- Clickable navigation links
-- Chevron separators
-- Current page indicator
-- Semantic HTML (`<nav>`, `<ol>`, `<li>`)
-- Keyboard accessible
-- Dark mode support
-- Responsive layout
-
----
-
-## Dark Mode Support
-
-All components include built-in dark mode support using Tailwind CSS `dark:` variants.
-
-To enable dark mode:
-
-```svelte
-<script>
-  import { theme } from '$lib/stores/theme';
-</script>
-
-<button onclick={() => theme.toggle()}>
-  Toggle Dark Mode
-</button>
-```
-
----
-
-## Accessibility
-
-All components are built with accessibility in mind:
-
-- Semantic HTML structure
-- ARIA labels and roles
-- Keyboard navigation
-- Focus management
-- Color contrast compliance
-- Alt text support
-
----
-
-## Installation & Export
-
-All components are exported from `$lib`:
-
-```svelte
-<script>
-  import { 
-    Callout, 
-    Tabs, 
-    CodeBlock, 
-    Image, 
-    APITable, 
-    Breadcrumbs 
-  } from '$lib';
-</script>
-```
-
----
-
-## Testing
-
-Component tests are provided in `src/lib/components/*.test.ts`:
-
-```bash
-npm test                 # Run all tests
-npm run test:coverage    # Generate coverage report
-```
-
----
-
-## Styling with Tailwind
-
-Components use Tailwind CSS for styling. Customize by editing `tailwind.config.js`:
-
-```javascript
-export default {
-  content: ['./src/**/*.{html,js,svelte,ts}'],
-  theme: {
-    extend: {
-      colors: {
-        'doc-info': '#0ea5e9',
-        'doc-warning': '#f59e0b',
-        'doc-success': '#10b981',
-        'doc-error': '#ef4444',
-      },
-    },
-  },
-};
-```
-
----
-
-## Performance Notes
-
-- Components are lightweight and performant
-- No external dependencies required
-- SSR compatible
-- Optimized bundle size
-- Lazy loading compatible
-
----
-
-## Browser Support
-
-- Modern browsers (Chrome, Firefox, Safari, Edge)
-- Requires Svelte 5+
-- JavaScript required (but graceful degradation)
-
----
-
-## License
-
-MIT - Free for personal and commercial use
-
----
-
-**Last Updated:** February 4, 2026
-**Version:** 1.0.0