@zeix/le-truc 0.15.0

package/server/SERVER.md

@@ -0,0 +1,286 @@
+# Development Server
+
+The unified server system provides a flexible, layout-driven development server that can handle both documentation and component testing with automatic layout selection based on routes.
+
+## Features
+
+- **Flexible Layout System**: Automatic layout selection based on URL patterns
+- **Multiple Server Modes**: Documentation, examples, or unified (both)
+- **Hot Module Reloading**: Live updates during development
+- **Template Variables**: Full template variable substitution
+- **Include Support**: Template includes for shared content
+- **Compression**: Automatic response compression
+- **Asset Handling**: Smart asset serving with caching
+
+## Quick Start
+
+```bash
+# Start unified server (documentation + examples)
+bun run serve
+
+# Documentation only
+bun run serve:docs
+
+# Examples only
+bun run serve:examples
+
+# Custom configuration
+bun server/serve-unified.ts --mode unified --port 8000
+```
+
+## Layout System
+
+### Automatic Layout Selection
+
+The server automatically selects layouts based on URL patterns:
+
+| URL Pattern | Layout | Description |
+|-------------|--------|-------------|
+| `/test/{component}.html` | `test` | Component testing pages |
+| `/api/classes/{id}.html` | `api` | API documentation (classes) |
+| `/api/functions/{id}.html` | `api` | API documentation (functions) |
+| `/api/type-aliases/{id}.html` | `api` | API documentation (types) |
+| `/api/variables/{id}.html` | `api` | API documentation (variables) |
+| `/examples/{example}.html` | `example` | Example showcase pages |
+| `/blog/{article}.html` | `blog` | Blog articles |
+| `/api/`, `/examples/`, `/blog/` | `overview` | Index/listing pages |
+| All other pages | `page` | Default documentation layout |
+
+### Available Layouts
+
+#### 1. **page** - Default Documentation Layout
+- Full navigation and header
+- Template variable support
+- Include processing
+- Used for: Regular documentation pages
+
+#### 2. **test** - Component Testing Layout
+- Minimal chrome for testing
+- Error display component
+- Asset loading for components
+- Used for: `/test/{component}.html` routes
+
+#### 3. **api** - API Documentation Layout
+- Breadcrumb navigation
+- Sidebar table of contents
+- API-specific styling and metadata
+- Used for: API reference pages
+
+#### 4. **example** - Example Showcase Layout
+- Hero header with example metadata
+- Live demo and source code links
+- Navigation between examples
+- Used for: Example documentation pages
+
+#### 5. **blog** - Blog Article Layout
+- Article-focused design
+- Author information
+- Reading time and metadata
+- Navigation between posts
+- Used for: Blog articles
+
+#### 6. **overview** - Listing/Index Layout
+- Grid-based content display
+- Search and filter functionality
+- Pagination support
+- Statistics display
+- Used for: Index pages and overviews
+
+## Template Variables
+
+All layouts support template variable substitution using `{{ variable-name }}` syntax:
+
+### Common Variables
+- `{{ content }}` - Main content area
+- `{{ title }}` - Page title
+- `{{ description }}` - Page description
+- `{{ section }}` - Current section (docs, api, examples, etc.)
+- `{{ base-path }}` - Base URL path
+- `{{ css-hash }}` - CSS asset hash for cache busting
+- `{{ js-hash }}` - JS asset hash for cache busting
+
+### Layout-Specific Variables
+
+#### Test Layout
+- `{{ component-name }}` - Name of the component being tested
+
+#### API Layout
+- `{{ api-category }}` - API category (classes, functions, etc.)
+- `{{ api-name }}` - API item name
+- `{{ api-kind }}` - API item kind
+- `{{ toc }}` - Table of contents
+
+#### Example Layout
+- `{{ example-name }}` - Example name
+- `{{ example-description }}` - Example description
+- `{{ example-difficulty }}` - Difficulty level
+- `{{ example-slug }}` - URL-safe example identifier
+- `{{ example-tags }}` - Example tags
+- `{{ example-source }}` - Source code URL
+
+#### Blog Layout
+- `{{ author }}` - Article author
+- `{{ published-date }}` - Publication date
+- `{{ reading-time }}` - Estimated reading time
+- `{{ blog-tags }}` - Article tags
+- `{{ prev-post }}` - Previous post URL
+- `{{ next-post }}` - Next post URL
+
+#### Overview Layout
+- `{{ overview-title }}` - Overview page title
+- `{{ overview-description }}` - Overview description
+- `{{ overview-stats }}` - Statistics display
+- `{{ search-placeholder }}` - Search input placeholder
+- `{{ filter-options }}` - Filter dropdown options
+
+## Server Modes
+
+### `docs` Mode
+- Serves built documentation from `./docs`
+- Enables HMR and compression
+- Builds documentation on startup
+- Default port: 3000
+
+### `examples` Mode
+- Serves component test pages from `./examples`
+- Handles `/test/{component}.html` routes
+- Serves example assets from `/assets/`
+- Default port: 3000
+
+### `unified` Mode (Default)
+- Combines both docs and examples functionality
+- Supports all route types and layouts
+- Full feature set enabled
+- Default port: 5000
+
+## Configuration
+
+### Environment Variables
+- `PORT` - Server port (overrides defaults)
+- `HOST` - Server hostname (default: localhost)
+
+### Command Line Options
+```bash
+bun server/serve.ts [options]
+
+Options:
+  --mode <mode>           Server mode: docs, examples, unified
+  --port <port>           Port number
+  --host <host>           Host address
+  --no-hmr                Disable Hot Module Reloading
+  --no-compression        Disable response compression
+  --build-first           Build documentation before starting
+  --help                  Show help message
+```
+
+### Programmatic Usage
+
+```typescript
+import { UnifiedDevServer } from './server/serve'
+
+const server = new UnifiedDevServer({
+  mode: 'unified',
+  port: 8000,
+  enableHMR: true,
+  buildFirst: true,
+})
+
+await server.start()
+```
+
+## Adding New Layouts
+
+1. Create the layout file in `server/layouts/`:
+```html
+<!doctype html>
+<html lang="en">
+  <head>
+    <title>{{ title }}</title>
+    <!-- ... -->
+  </head>
+  <body>
+    {{ content }}
+  </body>
+</html>
+```
+
+2. Add the layout path to `server/config.ts`:
+```typescript
+export const LAYOUT_PATHS = {
+  // existing layouts...
+  'my-layout': `${LAYOUTS_DIR}/my-layout.html`,
+} as const
+```
+
+3. Add route mapping:
+```typescript
+export const ROUTE_LAYOUT_MAP = {
+  // existing routes...
+  '/my-section/': 'my-layout',
+} as const
+```
+
+4. Add to default layouts in `server/layout-engine.ts`:
+```typescript
+export const DEFAULT_LAYOUTS: LayoutConfig[] = [
+  // existing layouts...
+  {
+    name: 'my-layout',
+    path: LAYOUT_PATHS['my-layout'],
+    type: 'template',
+    contentMarker: CONTENT_MARKER,
+    defaultContext: {
+      section: 'my-section',
+    }
+  }
+]
+```
+
+## Architecture
+
+The unified server is built on top of the existing build system and integrates with:
+
+- **Build System**: Uses existing `server/build.ts` for documentation building
+- **Template Engine**: Leverages `server/templates/` utilities
+- **File Watching**: Inherits from existing file watching system
+- **Layout Engine**: New flexible layout processing system
+- **Asset Handling**: Smart asset resolution across multiple directories
+
+## Migration from Old Servers
+
+### From `server/serve.ts` (Documentation)
+- Replace `bun server/serve.ts` with `bun run serve:docs`
+- All existing functionality preserved
+- Additional layout flexibility added
+
+### From `examples/server.ts` (Component Testing)
+- Replace `bun examples/server.ts` with `bun run serve:examples`
+- Test pages now use proper layout system
+- Enhanced styling and error handling
+
+### Combined Usage
+- Use `bun run serve` for unified development
+- Single server handles both use cases
+- Consistent development experience
+
+## Troubleshooting
+
+### Layout Not Found
+- Check that layout file exists in `server/layouts/`
+- Verify layout is added to `LAYOUT_PATHS` in config
+- Ensure route mapping exists in `ROUTE_LAYOUT_MAP`
+
+### Template Variables Not Working
+- Verify variable names match exactly (case-sensitive)
+- Check that layout type is set to `'template'` not `'simple'`
+- Ensure context is being passed correctly
+
+### Assets Not Loading
+- Check asset paths in layout files
+- Verify assets exist in expected directories (`docs/assets/`, `examples/assets/`)
+- Check browser network tab for 404 errors
+
+### HMR Not Working
+- Ensure WebSocket connection is established
+- Check browser console for connection errors
+- Verify `enableHMR` option is true

package/server/build.ts

@@ -0,0 +1,91 @@
+#!/usr/bin/env bun
+
+import { apiEffect } from './effects/api'
+import { cssEffect } from './effects/css'
+import { examplesEffect } from './effects/examples'
+import { jsEffect } from './effects/js'
+import { menuEffect } from './effects/menu'
+import { pagesEffect } from './effects/pages'
+import { serviceWorkerEffect } from './effects/service-worker'
+import { sitemapEffect } from './effects/sitemap'
+import { getFilePath } from './io'
+
+/**
+ * Simple reactive build system orchestration
+ *
+ * This file initializes the file signals and starts the effects
+ * in the correct order for both initial builds and incremental updates.
+ */
+
+export async function build() {
+	const startTime = performance.now()
+	console.log('🚀 Starting build...')
+
+	try {
+		// Change to project root directory since config paths are relative to it
+		const projectRoot = getFilePath(import.meta.dir, '..')
+		process.chdir(projectRoot)
+		console.log(`📁 Working directory: ${process.cwd()}`)
+
+		// Wait a moment for file watchers to initialize
+		await new Promise(resolve => setTimeout(resolve, 1000))
+
+		// Initialize effects in order
+		// API docs should be generated first, then CSS/JS, then pages processing
+		console.log('🚀 Initializing effects...')
+		const apiCleanup = apiEffect()
+		const cssCleanup = cssEffect()
+		const jsCleanup = jsEffect()
+		const serviceWorkerCleanup = serviceWorkerEffect()
+		const examplesCleanup = examplesEffect()
+		const pagesCleanup = pagesEffect()
+		const menuCleanup = menuEffect()
+		const sitemapCleanup = sitemapEffect()
+
+		// Wait a moment for initial processing to complete
+		await new Promise(resolve => setTimeout(resolve, 500))
+
+		const duration = performance.now() - startTime
+		console.log(`✅ Build completed in ${duration.toFixed(2)}ms`)
+
+		// Return cleanup function for graceful shutdown
+		return () => {
+			apiCleanup?.()
+			cssCleanup?.()
+			jsCleanup?.()
+			serviceWorkerCleanup?.()
+			examplesCleanup?.()
+			pagesCleanup?.()
+			menuCleanup?.()
+			sitemapCleanup?.()
+		}
+	} catch (error) {
+		console.error('❌ Build failed:', error)
+		throw error
+	}
+}
+
+async function main() {
+	try {
+		const cleanup = await build()
+
+		// Handle graceful shutdown
+		process.on('SIGINT', () => {
+			console.log('\n🛑 Shutting down...')
+			cleanup?.()
+			process.exit(0)
+		})
+
+		// Keep process alive in watch mode
+		console.log('👀 Watching for changes... (Press Ctrl+C to stop)')
+		await new Promise(() => {}) // Keep alive indefinitely
+	} catch (error) {
+		console.error('💥 Fatal error:', error)
+		process.exit(1)
+	}
+}
+
+// Run if this file is executed directly
+if (import.meta.main) {
+	main()
+}

package/server/config.ts

@@ -0,0 +1,130 @@
+/**
+ * Development server configuration
+ */
+export const BASE_URL = 'https://zeixcom.github.io/le-truc'
+
+// Path constants
+export const SRC_DIR = './src'
+
+export const COMPONENTS_DIR = './examples'
+export const CSS_FILE = './examples/main.css'
+export const TS_FILE = './examples/main.ts'
+
+export const TEMPLATES_DIR = './server/templates'
+
+export const INPUT_DIR = './docs-src'
+export const PAGES_DIR = './docs-src/pages'
+export const API_DIR = './docs-src/api'
+export const LAYOUT_FILE = './docs-src/layout.html'
+export const INCLUDES_DIR = './docs-src/includes'
+export const MENU_FILE = './docs-src/includes/menu.html'
+
+export const OUTPUT_DIR = './docs'
+export const ASSETS_DIR = './docs/assets'
+export const EXAMPLES_DIR = './docs/examples'
+export const SITEMAP_FILE = './docs/sitemap.xml'
+
+// Page ordering configuration
+export const PAGE_ORDER = [
+	'index',
+	'getting-started',
+	'components',
+	'styling',
+	'data-flow',
+	'examples',
+	'api',
+	'blog',
+	'about',
+]
+
+// Layout system configuration
+export const LAYOUTS_DIR = './server/layouts'
+export const CONTENT_MARKER = '{{ content }}'
+
+// Layout file paths
+export const LAYOUT_PATHS = {
+	page: `${LAYOUTS_DIR}/page.html`,
+	test: `${LAYOUTS_DIR}/test.html`,
+	api: `${LAYOUTS_DIR}/api.html`,
+	example: `${LAYOUTS_DIR}/example.html`,
+	blog: `${LAYOUTS_DIR}/blog.html`,
+	overview: `${LAYOUTS_DIR}/overview.html`,
+} as const
+
+// Route patterns for automatic layout selection
+export const ROUTE_LAYOUT_MAP = {
+	'/test/': 'test',
+	'/api/classes/': 'api',
+	'/api/functions/': 'api',
+	'/api/type-aliases/': 'api',
+	'/api/variables/': 'api',
+	'/examples/': 'example',
+	'/blog/': 'blog',
+	'/api/': 'overview', // API overview
+	'/examples': 'overview', // Examples overview
+	'/blog': 'overview', // Blog index
+	'/': 'page', // Default pages
+} as const
+
+// Server configuration
+export const SERVER_CONFIG = {
+	PORT: 3000,
+	HOST: 'localhost',
+	ENABLE_HMR: true,
+	ENABLE_COMPRESSION: true,
+	DEPENDENCY_TIMEOUT: 50,
+} as const
+
+// Layout configuration interface
+export interface LayoutConfig {
+	name: string
+	path: string
+	type: 'simple' | 'template'
+	contentMarker: string
+	defaultContext?: Record<string, string>
+}
+
+// MIME types for static file serving
+export const MIME_TYPES = {
+	html: 'text/html',
+	css: 'text/css',
+	js: 'application/javascript',
+	json: 'application/json',
+	xml: 'application/xml',
+	svg: 'image/svg+xml',
+	png: 'image/png',
+	jpg: 'image/jpeg',
+	jpeg: 'image/jpeg',
+	gif: 'image/gif',
+	webp: 'image/webp',
+	avif: 'image/avif',
+	ico: 'image/x-icon',
+	woff: 'font/woff',
+	woff2: 'font/woff2',
+	ttf: 'font/ttf',
+	otf: 'font/otf',
+	pdf: 'application/pdf',
+	txt: 'text/plain',
+	map: 'application/json', // Source maps
+} as const
+
+// Compressible file types
+export const COMPRESSIBLE_TYPES = [
+	'.html',
+	'.css',
+	'.js',
+	'.json',
+	'.xml',
+	'.svg',
+	'.txt',
+] as const
+
+// Helper function to get layout for route
+export function getLayoutForRoute(path: string): keyof typeof LAYOUT_PATHS {
+	for (const [routePrefix, layoutName] of Object.entries(ROUTE_LAYOUT_MAP)) {
+		if (path.startsWith(routePrefix)) {
+			return layoutName as keyof typeof LAYOUT_PATHS
+		}
+	}
+	return 'page' // Default fallback
+}

package/server/effects/api.ts

@@ -0,0 +1,28 @@
+import { createEffect, match, resolve } from '@zeix/cause-effect'
+import { execSync } from 'child_process'
+import { API_DIR } from '../config'
+import { libraryScripts } from '../file-signals'
+
+export const apiEffect = () =>
+	createEffect(() => {
+		match(resolve({ library: libraryScripts.sources }), {
+			ok: () => {
+				try {
+					console.log('📚 Rebuilding API documentation...')
+
+					// Generate API docs using TypeDoc
+					execSync(
+						`typedoc --plugin typedoc-plugin-markdown --out ${API_DIR}/ index.ts`,
+						{ stdio: 'inherit' },
+					)
+
+					console.log('📚 API documentation rebuilt successfully')
+				} catch (error) {
+					console.error('Failed to rebuild API documentation:', error)
+				}
+			},
+			err: errors => {
+				console.error('API reference failed to rebuild', String(errors[0]))
+			},
+		})
+	})

package/server/effects/css.ts

@@ -0,0 +1,31 @@
+import { createEffect, match, resolve } from '@zeix/cause-effect'
+import { execSync } from 'child_process'
+import { ASSETS_DIR, CSS_FILE } from '../config'
+import { componentStyles, docsStyles } from '../file-signals'
+
+export const cssEffect = () =>
+	createEffect(() => {
+		match(
+			resolve({
+				components: componentStyles.sources,
+				docs: docsStyles.sources,
+			}),
+			{
+				ok: () => {
+					try {
+						console.log('🎨 Rebuilding CSS assets...')
+						execSync(
+							`bunx lightningcss --minify --bundle --targets ">= 0.25%" ${CSS_FILE} -o ${ASSETS_DIR}/main.css`,
+							{ stdio: 'inherit' },
+						)
+						console.log('CSS successfully rebuilt')
+					} catch (error) {
+						console.error('CSS failed to rebuild:', String(error))
+					}
+				},
+				err: errors => {
+					console.error('Error in CSS effect:', errors[0].message)
+				},
+			},
+		)
+	})

package/server/effects/examples.ts

@@ -0,0 +1,109 @@
+import { createEffect, match, resolve } from '@zeix/cause-effect'
+import { codeToHtml } from 'shiki'
+import { EXAMPLES_DIR } from '../config'
+import {
+	componentMarkup,
+	componentScripts,
+	componentStyles,
+	type FileInfo,
+} from '../file-signals'
+import { writeFileSafe } from '../io'
+import { type PanelType, tabGroup } from '../templates/fragments'
+
+const highlightCode = async (content: string, type: string) =>
+	await codeToHtml(content, {
+		lang: type,
+		theme: 'monokai',
+	})
+
+const generatePanels = async (
+	html: FileInfo,
+	css?: FileInfo,
+	ts?: FileInfo,
+) => {
+	const panels = [
+		{
+			type: 'html',
+			label: 'HTML',
+			filePath: html.path,
+			content: await highlightCode(html.content, 'html'),
+			selected: false,
+		},
+		css && {
+			type: 'css',
+			label: 'CSS',
+			filePath: css.path,
+			content: await highlightCode(css.content, 'css'),
+			selected: false,
+		},
+		ts && {
+			type: 'ts',
+			label: 'TypeScript',
+			filePath: ts.path,
+			content: await highlightCode(ts.content, 'typescript'),
+			selected: false,
+		},
+	].filter(Boolean) as PanelType[]
+
+	// Select the last panel by default (typically TypeScript)
+	panels[panels.length - 1].selected = true
+
+	return panels
+}
+
+export const examplesEffect = () =>
+	createEffect(() => {
+		match(
+			resolve({
+				htmlFiles: componentMarkup.sources,
+				cssFiles: componentStyles.sources,
+				tsFiles: componentScripts.sources,
+			}),
+			{
+				ok: async ({ htmlFiles, cssFiles, tsFiles }) => {
+					try {
+						console.log('🔄 Rebuilding example fragments...')
+
+						for (const path in htmlFiles) {
+							const html = htmlFiles[path]
+
+							// Only process main component HTML files (examples/component-name/component-name.html)
+							// Skip test files and other auxiliary HTML files
+							const pathParts = html.path.split('/')
+
+							if (pathParts.length < 3) {
+								continue // Skip files not in component directories
+							}
+
+							const componentName = pathParts[pathParts.length - 2] // Get directory name
+							const fileName = pathParts[pathParts.length - 1].replace(
+								/\.html$/,
+								'',
+							) // Get file name without extension
+
+							// Skip if filename doesn't match component directory name
+							if (componentName !== fileName) {
+								continue
+							}
+
+							const name = html.path.replace(/\.html$/, '')
+							const css = cssFiles[name + '.css']
+							const ts = tsFiles[name + '.ts']
+
+							const panels = await generatePanels(html, css, ts)
+							const outputPath = `${EXAMPLES_DIR}/${componentName}.html`
+							await writeFileSafe(outputPath, tabGroup(componentName, panels))
+						}
+
+						console.log('Example fragments successfully rebuilt')
+						return
+					} catch (error) {
+						console.error('Example fragments failed to rebuild:', String(error))
+					}
+				},
+				err: errors => {
+					console.error('Error in examples effect:', errors[0].message)
+				},
+			},
+		)
+	})

package/server/effects/js.ts

@@ -0,0 +1,32 @@
+import { createEffect, match, resolve } from '@zeix/cause-effect'
+import { execSync } from 'child_process'
+import { ASSETS_DIR, TS_FILE } from '../config'
+import { componentScripts, docsScripts, libraryScripts } from '../file-signals'
+
+export const jsEffect = () =>
+	createEffect(() => {
+		match(
+			resolve({
+				docs: docsScripts.sources,
+				library: libraryScripts.sources,
+				components: componentScripts.sources,
+			}),
+			{
+				ok: () => {
+					try {
+						console.log('🔧 Rebuilding JS assets...')
+						execSync(
+							`bun build ${TS_FILE} --outdir ${ASSETS_DIR}/ --minify --define process.env.DEV_MODE=false --sourcemap=external`,
+							{ stdio: 'inherit' },
+						)
+						console.log('JS successfully rebuilt')
+					} catch (error) {
+						console.error('JS failed to rebuild:', String(error))
+					}
+				},
+				err: errors => {
+					console.error('Error in JS effect:', errors[0].message)
+				},
+			},
+		)
+	})