moai-adk 0.25.4__py3-none-any.whl → 0.32.8__py3-none-any.whl

moai_adk/templates/.claude/skills/moai-library-nextra/advanced-patterns.md

@@ -0,0 +1,336 @@
+---
+name: moai-library-nextra/advanced-patterns
+description: Advanced Nextra architecture patterns, MDX integration, dynamic routing, and site optimization
+---
+
+# Advanced Nextra Architecture Patterns (v5.0.0)
+
+## Advanced MDX Integration
+
+### 1. Custom MDX Components System
+
+```typescript
+import { MDXProvider } from '@mdx-js/react';
+import { useMemo } from 'react';
+
+interface MDXComponentConfig {
+ name: string;
+ component: React.ComponentType<any>;
+ props?: Record<string, any>;
+ metadata?: ComponentMetadata;
+}
+
+interface ComponentMetadata {
+ version: string;
+ description: string;
+ deprecated?: boolean;
+ replacedBy?: string;
+}
+
+class MDXComponentRegistry {
+ private components: Map<string, MDXComponentConfig> = new Map();
+ private componentCache: Map<string, React.ComponentType> = new Map();
+
+ registerComponent(config: MDXComponentConfig) {
+ this.components.set(config.name, config);
+ // Clear cache when registering new component
+ this.componentCache.delete(config.name);
+ }
+
+ getComponentForMDX(name: string) {
+ if (this.componentCache.has(name)) {
+ return this.componentCache.get(name)!;
+ }
+
+ const config = this.components.get(name);
+ if (!config) {
+ throw new Error(`Component not registered: ${name}`);
+ }
+
+ // Wrap with metadata warning if deprecated
+ let component = config.component;
+
+ if (config.metadata?.deprecated) {
+ component = (props) => {
+ console.warn(
+ `Deprecated component: ${name}. Use ${config.metadata?.replacedBy} instead`
+ );
+ return <config.component {...props} />;
+ };
+ }
+
+ this.componentCache.set(name, component);
+ return component;
+ }
+
+ getMDXProviderValue() {
+ const components: Record<string, React.ComponentType<any>> = {
+ // Override HTML elements
+ h1: CustomHeading1,
+ h2: CustomHeading2,
+ h3: CustomHeading3,
+ p: CustomParagraph,
+ a: CustomLink,
+ code: CustomCode,
+ pre: CustomPre,
+
+ // Custom components
+ ...Object.fromEntries(this.components.entries())
+ };
+
+ return components;
+ }
+}
+
+// Usage in Nextra pages
+export function AdvancedMDXPage({ children }: { children: React.ReactNode }) {
+ const registry = useMemo(() => new MDXComponentRegistry(), []);
+
+ registry.registerComponent({
+ name: 'Alert',
+ component: AlertComponent,
+ metadata: { version: '1.0.0', description: 'Alert notification' }
+ });
+
+ const mdxComponents = registry.getMDXProviderValue();
+
+ return (
+ <MDXProvider components={mdxComponents}>
+ {children}
+ </MDXProvider>
+ );
+}
+```
+
+## Dynamic Routing and Nested Structure
+
+### 1. Hierarchical Site Structure
+
+```typescript
+interface SiteNode {
+ title: string;
+ path: string;
+ children?: SiteNode[];
+ frontmatter?: Record<string, any>;
+ meta?: {
+ display?: 'hidden' | 'normal';
+ sort?: number;
+ href?: string;
+ target?: string;
+ search?: boolean;
+ };
+}
+
+class NextraArchitecture {
+ private siteTree: SiteNode[] = [];
+
+ // Build site structure from file system
+ async buildSiteTree(pagesDir: string): Promise<SiteNode[]> {
+ const tree: SiteNode[] = [];
+
+ const files = await this.scanDirectory(pagesDir);
+
+ for (const file of files) {
+ const node = await this.createNode(file, pagesDir);
+ tree.push(node);
+ }
+
+ // Sort by metadata
+ return this.sortNodes(tree);
+ }
+
+ private async createNode(filePath: string, baseDir: string): Promise<SiteNode> {
+ const relativePath = path.relative(baseDir, filePath);
+ const urlPath = '/' + relativePath.replace(/\.[^/.]+$/, '').replace(/\\g, '/');
+
+ // Extract frontmatter
+ const content = await fs.readFile(filePath, 'utf-8');
+ const frontmatter = this.extractFrontmatter(content);
+ const title = frontmatter.title || this.inferTitle(relativePath);
+
+ return {
+ title,
+ path: urlPath,
+ frontmatter,
+ meta: {
+ display: frontmatter.display || 'normal',
+ sort: frontmatter.sort || 0,
+ search: frontmatter.search !== false
+ }
+ };
+ }
+
+ private sortNodes(nodes: SiteNode[]): SiteNode[] {
+ // Sort by display priority and custom sort
+ return nodes.sort((a, b) => {
+ // Hidden items last
+ if (a.meta?.display === 'hidden') return 1;
+ if (b.meta?.display === 'hidden') return -1;
+
+ // Custom sort
+ const aSort = a.meta?.sort || 0;
+ const bSort = b.meta?.sort || 0;
+
+ return bSort - aSort;
+ });
+ }
+
+ private extractFrontmatter(content: string): Record<string, any> {
+ const match = content.match(/^---\n([\s\S]*?)\n---/);
+ if (!match) return {};
+
+ // Parse YAML frontmatter
+ return this.parseYAML(match[1]);
+ }
+}
+```
+
+### 2. Dynamic Import and Code Splitting
+
+```typescript
+import dynamic from 'next/dynamic';
+
+// Split docs by section
+const DocumentationRoutes = {
+ getting_started: dynamic(() => import('./docs/getting-started.mdx')),
+ api_reference: dynamic(() => import('./docs/api-reference.mdx')),
+ examples: dynamic(() => import('./docs/examples.mdx')),
+ faq: dynamic(() => import('./docs/faq.mdx'))
+};
+
+export function DynamicDocumentationPage({ section }: { section: string }) {
+ const Component = DocumentationRoutes[section as keyof typeof DocumentationRoutes];
+
+ if (!Component) {
+ return <NotFound section={section} />;
+ }
+
+ return (
+ <Suspense fallback={<LoadingSpinner />}>
+ <Component />
+ </Suspense>
+ );
+}
+```
+
+## Search and Navigation
+
+### 1. Full-Text Search Integration
+
+```typescript
+import Fuse from 'fuse.js';
+
+interface SearchableContent {
+ id: string;
+ title: string;
+ content: string;
+ path: string;
+ section: string;
+ keywords: string[];
+}
+
+class DocumentationSearch {
+ private index: Fuse<SearchableContent>;
+ private documents: SearchableContent[] = [];
+
+ async indexDocumentation(pages: SiteNode[]): Promise<void> {
+ this.documents = await this.extractSearchableContent(pages);
+
+ // Create Fuse index for fast full-text search
+ this.index = new Fuse(this.documents, {
+ keys: ['title', 'content', 'keywords'],
+ includeScore: true,
+ threshold: 0.3, // Fuzzy matching
+ minMatchCharLength: 2
+ });
+ }
+
+ async search(query: string, limit: number = 10): Promise<SearchResult[]> {
+ const results = this.index.search(query).slice(0, limit);
+
+ return results.map(result => ({
+ ...result.item,
+ relevance: 1 - (result.score || 0)
+ }));
+ }
+
+ private async extractSearchableContent(
+ pages: SiteNode[]
+ ): Promise<SearchableContent[]> {
+ const content: SearchableContent[] = [];
+
+ for (const page of pages) {
+ const mdxContent = await this.readMDXContent(page.path);
+ const extracted = this.extractFromMDX(mdxContent);
+
+ content.push({
+ id: page.path,
+ title: page.title,
+ content: extracted.text,
+ path: page.path,
+ section: this.inferSection(page.path),
+ keywords: extracted.keywords
+ });
+ }
+
+ return content;
+ }
+
+ private extractFromMDX(content: string) {
+ // Remove code blocks and MDX components
+ const text = content
+ .replace(/```[\s\S]*?```/g, '')
+ .replace(/<[^>]+>/g, '');
+
+ // Extract keywords from headings
+ const headings = content.match(/^#+\s+.+$/gm) || [];
+ const keywords = headings.map(h => h.replace(/^#+\s+/, ''));
+
+ return { text, keywords };
+ }
+}
+
+// React search component
+export function SearchBar() {
+ const [query, setQuery] = useState('');
+ const [results, setResults] = useState<SearchResult[]>([]);
+ const search = useSearch(); // Hook to access search instance
+
+ const handleSearch = async (q: string) => {
+ setQuery(q);
+ const searchResults = await search(q);
+ setResults(searchResults);
+ };
+
+ return (
+ <div className="search-container">
+ <input
+ type="search"
+ placeholder="Search documentation..."
+ value={query}
+ onChange={(e) => handleSearch(e.target.value)}
+ className="search-input"
+ />
+ {results.length > 0 && (
+ <ul className="search-results">
+ {results.map(result => (
+ <li key={result.id} className="search-result">
+ <Link href={result.path}>
+ <h3>{result.title}</h3>
+ <p className="excerpt">{result.content.substring(0, 100)}...</p>
+ <span className="relevance">
+ {(result.relevance * 100).toFixed(0)}% match
+ </span>
+ </Link>
+ </li>
+ ))}
+ </ul>
+ )}
+ </div>
+ );
+}
+```
+
+---
+
+Version: 5.0.0 | Last Updated: 2025-11-22 | Enterprise Ready:

moai_adk/templates/.claude/skills/moai-library-nextra/modules/advanced-deployment-patterns.md

@@ -0,0 +1,182 @@
+---
+name: advanced-deployment-patterns
+parent: moai-library-nextra
+description: Mobile optimization, accessibility, and SEO
+---
+
+# Module 3: Advanced Deployment & Patterns
+
+## Mobile Optimization
+
+### Mobile-First Layout
+
+```tsx
+// components/ui/MobileLayout.tsx
+import { useState } from 'react'
+
+export function MobileLayout({ children }) {
+ const [sidebarOpen, setSidebarOpen] = useState(false)
+
+ return (
+ <div className="min-h-screen bg-background">
+ {/* Mobile Header */}
+ <header className="sticky top-0 z-50 border-b md:hidden">
+ <div className="flex h-14 items-center px-4">
+ <button
+ onClick={() => setSidebarOpen(true)}
+ className="mr-4 p-2 rounded-md hover:bg-accent"
+ >
+ <svg className="h-5 w-5" fill="none" stroke="currentColor">
+ <path strokeLinecap="round" d="M4 6h16M4 12h16M4 18h16" />
+ </svg>
+ </button>
+ <h1 className="text-lg font-semibold">Documentation</h1>
+ </div>
+ </header>
+
+ <main className="flex-1 md:flex">
+ <aside className="hidden md:block w-64 border-r">
+ {/* Sidebar */}
+ </aside>
+ <div className="flex-1 px-4 py-6">
+ {children}
+ </div>
+ </main>
+ </div>
+ )
+}
+```
+
+## Accessibility (WCAG 2.1)
+
+### Semantic HTML Structure
+
+```tsx
+// components/ui/AccessibleContent.tsx
+export function AccessibleContent({ title, children }) {
+ return (
+ <main id="main-content" role="main" aria-labelledby="page-title">
+ <header>
+ <h1 id="page-title" className="sr-only">
+ {title}
+ </h1>
+ </header>
+
+ <div className="prose prose-lg max-w-none">
+ {children}
+ </div>
+
+ <a
+ href="#main-content"
+ className="sr-only focus:not-sr-only focus:absolute focus:top-4"
+ >
+ Skip to main content
+ </a>
+ </main>
+ )
+}
+```
+
+### Keyboard Navigation
+
+```tsx
+// components/ui/KeyboardNavigation.tsx
+import { useEffect } from 'react'
+
+export function KeyboardNavigation() {
+ useEffect(() => {
+ const handleKeyDown = (event: KeyboardEvent) {
+ if (event.key === 'Escape') {
+ const modal = document.querySelector('[role="dialog"]')
+ if (modal) {
+ const closeButton = modal.querySelector('button[aria-label*="Close"]')
+ closeButton?.dispatchEvent(new MouseEvent('click'))
+ }
+ }
+ }
+
+ document.addEventListener('keydown', handleKeyDown)
+ return () => document.removeEventListener('keydown', handleKeyDown)
+ }, [])
+
+ return null
+}
+```
+
+## SEO Optimization
+
+### Dynamic SEO Implementation
+
+```typescript
+// lib/seo.ts
+import type { Metadata } from 'next'
+
+export function generateSEOMetadata({
+ title,
+ description,
+ path = '',
+ image,
+ keywords = []
+}: {
+ title: string
+ description: string
+ path?: string
+ image?: string
+ keywords?: string[]
+}): Metadata {
+ const baseUrl = 'https://docs.example.com'
+ const url = `${baseUrl}${path}`
+
+ return {
+ title,
+ description,
+ keywords: keywords.join(', '),
+ openGraph: {
+ type: 'article',
+ locale: 'en_US',
+ url,
+ title,
+ description,
+ images: image ? [{
+ url: image,
+ width: 1200,
+ height: 630,
+ }] : [],
+ },
+ twitter: {
+ card: 'summary_large_image',
+ title,
+ description,
+ },
+ alternates: {
+ canonical: url,
+ },
+ robots: {
+ index: true,
+ follow: true,
+ },
+ }
+}
+```
+
+## Production Deployment
+
+```bash
+# Build optimization
+npm run build
+
+# Static export
+npm run export
+
+# Deploy to Vercel
+vercel --prod
+
+# Deploy to Netlify
+netlify deploy --prod --dir=out
+```
+
+---
+
+References:
+- [MDN Web Accessibility](https://developer.mozilla.org/en-US/docs/Web/Accessibility)
+- [Google SEO Guide](https://developers.google.com/search/docs/fundamentals/seo-starter-guide)

moai_adk/templates/.claude/skills/moai-library-nextra/modules/advanced-patterns.md

@@ -0,0 +1,17 @@
+# Advanced Patterns
+
+This file contains advanced patterns and use cases for this skill.
+
+## Content Structure
+
+Move advanced content here:
+- Complex implementation patterns
+- Edge cases and error handling
+- Performance optimization techniques
+- Advanced configuration options
+- Troubleshooting guides
+
+## How to organize
+
+Organize advanced patterns in a way that makes sense for this skill's domain.
+Each subsection should be self-contained and referenceable from SKILL.md.

moai_adk/templates/.claude/skills/moai-library-nextra/modules/configuration.md

@@ -0,0 +1,57 @@
+# Configuration Guide
+
+## Overview
+
+Comprehensive configuration options and best practices.
+
+## Basic Configuration
+
+### YAML Configuration
+
+```yaml
+# config.yaml
+skill:
+ name: "skill-name"
+ version: "1.0.0"
+ options:
+ mode: "production"
+ timeout: 60
+ retries: 3
+```
+
+### Environment Variables
+
+```bash
+export SKILL_MODE=production
+export SKILL_TIMEOUT=60
+export SKILL_RETRIES=3
+```
+
+## Advanced Configuration
+
+### Custom Settings
+
+```python
+from moai_adk import Config
+
+config = Config.from_file("config.yaml")
+config.set("custom_option", "value")
+config.save()
+```
+
+### Profile-Based Configuration
+
+```yaml
+# config.yaml
+profiles:
+ development:
+ mode: "debug"
+ timeout: 300
+ production:
+ mode: "strict"
+ timeout: 30
+```
+
+---
+Last Updated: 2025-11-23
+Status: Production Ready