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

moai_adk/templates/.claude/skills/moai-library-nextra/optimization.md

@@ -0,0 +1,303 @@
+---
+name: moai-library-nextra/optimization
+description: Performance optimization for Nextra sites, caching, static generation, and deployment
+---
+
+# Nextra Architecture Optimization (v5.0.0)
+
+## Static Generation and Caching
+
+### 1. Incremental Static Regeneration (ISR)
+
+```typescript
+// pages/docs/[...slug].tsx
+import { GetStaticProps, GetStaticPaths } from 'next';
+
+interface DocsPageProps {
+ content: string;
+ meta: PageMetadata;
+}
+
+export const getStaticPaths: GetStaticPaths = async () => {
+ // Generate paths for all documentation pages
+ const pages = await getAllDocumentationPages();
+
+ return {
+ paths: pages.map(page => ({
+ params: { slug: page.path.split('/').filter(Boolean) }
+ })),
+ fallback: 'blocking' // Generate on-demand
+ };
+};
+
+export const getStaticProps: GetStaticProps<DocsPageProps> = async ({ params }) => {
+ const slug = Array.isArray(params?.slug) ? params.slug.join('/') : params?.slug;
+
+ try {
+ const { content, meta } = await getDocumentationPage(slug);
+
+ return {
+ props: { content, meta },
+ revalidate: 3600 // ISR: revalidate every hour
+ };
+ } catch (error) {
+ return {
+ notFound: true,
+ revalidate: 60 // Retry failed pages more frequently
+ };
+ }
+};
+
+export default function DocsPage({ content, meta }: DocsPageProps) {
+ return (
+ <article>
+ <h1>{meta.title}</h1>
+ <div dangerouslySetInnerHTML={{ __html: content }} />
+ </article>
+ );
+}
+```
+
+### 2. Build-Time Optimization
+
+```typescript
+// next.config.js
+module.exports = {
+ // Optimize images
+ images: {
+ formats: ['image/avif', 'image/webp'],
+ unoptimized: false
+ },
+
+ // Compression
+ compress: true,
+ poweredByHeader: false,
+
+ // SWC minification (faster than Terser)
+ swcMinify: true,
+
+ // React optimization
+ reactStrictMode: true,
+
+ // Font optimization
+ optimizeFonts: true,
+
+ // Experimental features for better performance
+ experimental: {
+ optimizePackageImports: [
+ '@mui/material',
+ '@mui/icons-material'
+ ]
+ },
+
+ // Custom webpack config
+ webpack: (config, { isServer }) => {
+ // Tree shaking optimization
+ config.optimization.usedExports = true;
+
+ return config;
+ }
+};
+```
+
+## Content Caching Strategy
+
+### 1. Multi-Layer Caching
+
+```typescript
+class DocumentationCache {
+ private fileCache = new Map<string, CacheEntry>();
+ private renderCache = new Map<string, CacheEntry>();
+
+ async getDocumentationPage(slug: string): Promise<PageContent> {
+ // Layer 1: In-memory render cache (milliseconds)
+ const renderCached = this.renderCache.get(slug);
+ if (renderCached && !this.isExpired(renderCached)) {
+ return renderCached.data;
+ }
+
+ // Layer 2: File system cache (seconds)
+ const fileCached = this.fileCache.get(slug);
+ if (fileCached && !this.isExpired(fileCached)) {
+ return fileCached.data;
+ }
+
+ // Layer 3: Read from disk
+ const content = await this.readFromDisk(slug);
+
+ // Cache to all layers
+ this.fileCache.set(slug, {
+ data: content,
+ timestamp: Date.now(),
+ ttl: 3600000 // 1 hour
+ });
+
+ this.renderCache.set(slug, {
+ data: content,
+ timestamp: Date.now(),
+ ttl: 60000 // 1 minute
+ });
+
+ return content;
+ }
+
+ private isExpired(entry: CacheEntry): boolean {
+ return Date.now() - entry.timestamp > entry.ttl;
+ }
+}
+```
+
+## Search Performance Optimization
+
+### 1. Index Compression and Caching
+
+```typescript
+class OptimizedSearchIndex {
+ async buildCompressedIndex(documents: SearchableContent[]): Promise<Buffer> {
+ // Create optimized index structure
+ const index = {
+ documents: documents.map(doc => ({
+ id: doc.id,
+ title: doc.title,
+ tokens: this.tokenize(doc.content)
+ })),
+ invertedIndex: this.buildInvertedIndex(documents),
+ metadata: {
+ version: 1,
+ generated: Date.now(),
+ count: documents.length
+ }
+ };
+
+ // Compress with brotli (better compression than gzip)
+ const json = JSON.stringify(index);
+ const compressed = await this.brotliCompress(json);
+
+ // Cache compressed index
+ await this.cacheIndex(compressed);
+
+ return compressed;
+ }
+
+ private buildInvertedIndex(
+ documents: SearchableContent[]
+ ): Map<string, number[]> {
+ const invertedIndex = new Map<string, number[]>();
+
+ documents.forEach((doc, idx) => {
+ const tokens = this.tokenize(doc.content);
+
+ for (const token of tokens) {
+ if (!invertedIndex.has(token)) {
+ invertedIndex.set(token, []);
+ }
+
+ invertedIndex.get(token)!.push(idx);
+ }
+ });
+
+ return invertedIndex;
+ }
+
+ private tokenize(text: string): string[] {
+ return text
+ .toLowerCase()
+ .match(/\b\w+\b/g) || [];
+ }
+
+ private async brotliCompress(data: string): Promise<Buffer> {
+ return new Promise((resolve, reject) => {
+ require('brotli').compress(Buffer.from(data), (err: any, output: Buffer) => {
+ if (err) reject(err);
+ else resolve(output);
+ });
+ });
+ }
+}
+```
+
+## Deployment Optimization
+
+### 1. Vercel Deployment Configuration
+
+```typescript
+// vercel.json
+{
+ "buildCommand": "next build",
+ "outputDirectory": ".next",
+ "devCommand": "next dev",
+ "env": {
+ "SEARCH_ENABLED": "@search_enabled"
+ },
+ "functions": {
+ "pages/api/": {
+ "memory": 256,
+ "maxDuration": 30
+ }
+ },
+ "redirects": [
+ {
+ "source": "/docs/:slug*",
+ "destination": "/:slug*"
+ }
+ ],
+ "headers": [
+ {
+ "source": "/(_next|public)/:path*",
+ "headers": [
+ {
+ "key": "Cache-Control",
+ "value": "public, max-age=31536000, immutable"
+ }
+ ]
+ },
+ {
+ "source": "/:path*",
+ "headers": [
+ {
+ "key": "Cache-Control",
+ "value": "public, max-age=3600, s-maxage=86400"
+ }
+ ]
+ }
+ ]
+}
+```
+
+### 2. Performance Monitoring
+
+```typescript
+class NextraPerformanceMonitor {
+ async trackPageLoad(slug: string, duration: number) {
+ metrics.observe('page.load.duration', duration, {
+ page: slug,
+ bucket: this.getDurationBucket(duration)
+ });
+
+ // Alert if exceeds budget
+ if (duration > 3000) {
+ metrics.increment('page.load.slow');
+ logger.warn('Slow page load', { slug, duration });
+ }
+ }
+
+ async trackBuildTime(buildDuration: number) {
+ metrics.observe('build.duration', buildDuration);
+
+ if (buildDuration > 600000) { // 10 minutes
+ metrics.increment('build.slow');
+ logger.warn('Slow build detected', { buildDuration });
+ }
+ }
+
+ private getDurationBucket(duration: number): string {
+ if (duration < 1000) return 'fast';
+ if (duration < 3000) return 'normal';
+ return 'slow';
+ }
+}
+```
+
+---
+
+Version: 5.0.0 | Last Updated: 2025-11-22 | Enterprise Ready:

moai_adk/templates/.claude/skills/moai-library-shadcn/SKILL.md

@@ -0,0 +1,370 @@
+---
+name: moai-library-shadcn
+aliases: [moai-library-shadcn]
+category: library
+description: Moai Lib Shadcn Ui - Professional implementation guide
+version: 2.0.0
+modularized: true
+tags:
+ - library
+ - shadcn
+ - enterprise
+ - development
+ - ui
+updated: 2025-11-27
+status: active
+## Quick Reference (30 seconds)
+
+# Enterprise shadcn/ui Component Library Expert
+
+Comprehensive shadcn/ui expertise with AI-powered design system architecture, Context7 integration, and intelligent component orchestration for modern React applications.
+
+Core Capabilities:
+- AI-Powered Component Architecture using Context7 MCP
+- Intelligent Design System with automated theme customization
+- Advanced Component Orchestration with accessibility and performance
+- Enterprise UI Framework with zero-configuration design tokens
+- Predictive Component Analytics with usage insights
+
+When to Use:
+- shadcn/ui component library discussions
+- React component architecture planning
+- Tailwind CSS integration and design tokens
+- Accessibility implementation
+- Design system customization
+
+Module Organization:
+- Core Concepts: This file (shadcn/ui overview, architecture, ecosystem)
+- Components: [shadcn Components](modules/shadcn-components.md) (component library, advanced patterns)
+- Theming: [shadcn Theming](modules/shadcn-theming.md) (theme system, customization)
+- Advanced Patterns: [Advanced Patterns](modules/advanced-patterns.md) (complex implementations)
+- Optimization: [Optimization](modules/optimization.md) (performance tuning)
+
+---
+
+## Implementation Guide
+
+### shadcn/ui Overview
+
+What is shadcn/ui:
+shadcn/ui is a collection of re-usable components built with Radix UI and Tailwind CSS. Unlike traditional component libraries, it's not an npm package but rather a collection of components you copy into your project.
+
+Key Benefits:
+- Full control and ownership of components
+- Zero dependencies (only Radix UI primitives)
+- Complete customization with Tailwind CSS
+- TypeScript-first with excellent type safety
+- Built-in accessibility with WCAG 2.1 AA compliance
+
+Architecture Philosophy:
+```
+shadcn/ui Components
+ Radix UI Primitives (unstyled, accessible)
+ Tailwind CSS (utility-first styling)
+ TypeScript (type safety)
+ Your Customization (full control)
+```
+
+### Core Component Categories
+
+1. Form Components:
+- Input, Select, Checkbox, Radio, Textarea
+- Form validation with react-hook-form + Zod
+- Accessibility with proper ARIA labels
+
+2. Display Components:
+- Card, Dialog, Sheet, Drawer, Popover
+- Responsive design patterns
+- Dark mode support
+
+3. Navigation Components:
+- Navigation Menu, Breadcrumb, Tabs, Pagination
+- Keyboard navigation support
+- Focus management
+
+4. Data Components:
+- Table, Calendar, DatePicker, Charts
+- Virtual scrolling for large datasets
+- TanStack Table integration
+
+5. Feedback Components:
+- Alert, Toast, Progress, Badge, Avatar
+- Loading states and skeletons
+- Error boundaries
+
+### Installation & Setup
+
+Step 1: Initialize shadcn/ui:
+```bash
+npx shadcn-ui@latest init
+```
+
+Step 2: Configure components.json:
+```json
+{
+ "$schema": "https://ui.shadcn.com/schema.json",
+ "style": "default",
+ "rsc": true,
+ "tsx": true,
+ "tailwind": {
+ "config": "tailwind.config.js",
+ "css": "app/globals.css",
+ "baseColor": "slate",
+ "cssVariables": true,
+ "prefix": ""
+ },
+ "aliases": {
+ "components": "@/components",
+ "utils": "@/lib/utils",
+ "ui": "@/components/ui"
+ }
+}
+```
+
+Step 3: Add Components:
+```bash
+npx shadcn-ui@latest add button
+npx shadcn-ui@latest add form
+npx shadcn-ui@latest add dialog
+```
+
+### Foundation Technologies (November 2025)
+
+React 19:
+- Server Components support
+- Concurrent rendering features
+- Automatic batching improvements
+- Streaming SSR enhancements
+
+TypeScript 5.5:
+- Full type safety across components
+- Improved inference for generics
+- Better error messages
+- Enhanced developer experience
+
+Tailwind CSS 3.4:
+- JIT (Just-In-Time) compilation
+- CSS variable support
+- Dark mode variants
+- Container queries
+
+Radix UI:
+- Unstyled, accessible primitives
+- Keyboard navigation
+- Focus management
+- ARIA attributes
+
+Integration Stack:
+- React Hook Form: Form state management
+- Zod: Schema validation
+- class-variance-authority: Variant management
+- Framer Motion: Animation library
+- Lucide React: Icon library
+
+### AI-Powered Architecture Design
+
+```python
+# AI-powered shadcn/ui architecture optimization with Context7
+class ShadcnUIArchitectOptimizer:
+ def __init__(self):
+ self.context7_client = Context7Client()
+ self.component_analyzer = ComponentAnalyzer()
+ self.theme_optimizer = ThemeOptimizer()
+ 
+ async def design_optimal_shadcn_architecture(self, 
+ requirements: DesignSystemRequirements) -> ShadcnUIArchitecture:
+ """Design optimal shadcn/ui architecture using AI analysis."""
+ 
+ # Get latest shadcn/ui and React documentation via Context7
+ shadcn_docs = await self.context7_client.get_library_docs(
+ context7_library_id='/shadcn-ui/docs',
+ topic="component library design system theming accessibility 2025",
+ tokens=3000
+ )
+ 
+ react_docs = await self.context7_client.get_library_docs(
+ context7_library_id='/react/docs',
+ topic="hooks server-components performance optimization 2025",
+ tokens=2000
+ )
+ 
+ # Optimize component selection
+ component_selection = self.component_analyzer.optimize_component_selection(
+ requirements.ui_components,
+ requirements.user_needs,
+ shadcn_docs
+ )
+ 
+ # Optimize theme configuration
+ theme_configuration = self.theme_optimizer.optimize_theme_system(
+ requirements.brand_guidelines,
+ requirements.accessibility_requirements,
+ shadcn_docs
+ )
+ 
+ return ShadcnUIArchitecture(
+ component_library=component_selection,
+ theme_system=theme_configuration,
+ accessibility_compliance=self._ensure_accessibility_compliance(
+ requirements.accessibility_requirements
+ ),
+ performance_optimization=self._optimize_component_performance(
+ component_selection
+ ),
+ integration_patterns=self._design_integration_patterns(
+ requirements.framework_stack
+ ),
+ customization_strategy=self._plan_customization_strategy(
+ requirements.customization_needs
+ )
+ )
+```
+
+### Best Practices
+
+Requirements:
+- Use CSS variables for theme customization
+- Implement proper TypeScript types
+- Follow accessibility guidelines (WCAG 2.1 AA)
+- Use Radix UI primitives for complex interactions
+- Test components with React Testing Library
+- Optimize bundle size with tree-shaking
+- Implement responsive design patterns
+
+Critical Implementation Standards:
+
+[HARD] Use CSS variables exclusively for color values
+WHY: Enables dynamic theming, supports dark mode transitions, and maintains design system consistency across all components
+IMPACT: Without CSS variables, theme changes require code modifications, dark mode fails, and brand customization becomes unmaintainable
+
+[HARD] Include accessibility attributes on all interactive elements
+WHY: Ensures WCAG 2.1 AA compliance, screen reader compatibility, and inclusive user experience for users with disabilities
+IMPACT: Missing accessibility attributes excludes users with disabilities, violates legal compliance requirements, and reduces application usability by 15-20% of potential users
+
+[HARD] Implement keyboard navigation for all interactive components
+WHY: Provides essential navigation method for keyboard users, supports assistive technologies, and improves overall user experience efficiency
+IMPACT: Without keyboard navigation, power users cannot efficiently use the application, accessibility compliance fails, and user productivity decreases by 30-40% for keyboard-dependent workflows
+
+[SOFT] Provide loading states for asynchronous operations
+WHY: Communicates operation progress to users, reduces perceived latency, and improves user confidence in application responsiveness
+IMPACT: Missing loading states create user uncertainty, increase perceived application slowness by 2-3x, and lead to duplicate action submissions
+
+[HARD] Implement error boundaries around component trees
+WHY: Prevents entire application crashes from isolated component failures, enables graceful error recovery, and maintains application stability
+IMPACT: Without error boundaries, single component failures crash the entire application, user data loss occurs, and recovery requires full page refresh
+
+[HARD] Apply Tailwind CSS classes instead of inline styles
+WHY: Maintains consistency with design system, enables JIT compilation benefits, supports responsive design variants, and improves bundle size optimization
+IMPACT: Inline styles bypass Tailwind optimization, increase CSS bundle size by 40-60%, prevent design token usage, and break theme customization
+
+[SOFT] Implement dark mode support across all components
+WHY: Provides user preference respect, reduces eye strain in low-light environments, and aligns with modern UI expectations
+IMPACT: Missing dark mode support limits usability in 60% of usage contexts, increases user eye strain, and reduces user satisfaction scores by 20-30%
+
+### Performance Optimization
+
+Bundle Size:
+- Tree-shaking removes unused components
+- Code splitting for large components
+- Lazy loading with React.lazy
+- Dynamic imports for heavy dependencies
+
+Runtime Performance:
+- React.memo for expensive components
+- useMemo/useCallback for computations
+- Virtual scrolling for large lists
+- Debouncing user interactions
+
+Accessibility:
+- ARIA attributes for all interactive elements
+- Keyboard navigation support
+- Focus management
+- Screen reader testing
+
+---
+
+## Advanced Patterns
+
+### Component Composition
+
+Composable Pattern:
+```typescript
+import { Card, CardHeader, CardTitle, CardContent } from "@/components/ui/card";
+
+export function DashboardCard({ title, children }) {
+ return (
+ <Card>
+ <CardHeader>
+ <CardTitle>{title}</CardTitle>
+ </CardHeader>
+ <CardContent>
+ {children}
+ </CardContent>
+ </Card>
+ );
+}
+```
+
+### Form Validation
+
+Zod + React Hook Form:
+```typescript
+import { useForm } from "react-hook-form";
+import { zodResolver } from "@hookform/resolvers/zod";
+import { z } from "zod";
+
+const formSchema = z.object({
+ email: z.string().email(),
+ password: z.string().min(8),
+});
+
+type FormValues = z.infer<typeof formSchema>;
+
+export function LoginForm() {
+ const form = useForm<FormValues>({
+ resolver: zodResolver(formSchema),
+ });
+
+ return (
+ <form onSubmit={form.handleSubmit(onSubmit)}>
+ {/* Form fields */}
+ </form>
+ );
+}
+```
+
+---
+
+## Works Well With
+
+- [shadcn Components](modules/shadcn-components.md) - Advanced component patterns and implementation
+- [shadcn Theming](modules/shadcn-theming.md) - Theme system and customization strategies
+- `moai-domain-uiux` - Design system architecture and principles
+- `moai-lang-unified` - TypeScript best practices
+- `code-frontend` - Frontend development patterns
+
+---
+
+## Context7 Integration
+
+Related Libraries:
+- [shadcn/ui](/shadcn-ui/ui): Re-usable components built with Radix UI and Tailwind
+- [Radix UI](/radix-ui/primitives): Unstyled, accessible component primitives
+- [Tailwind CSS](/tailwindlabs/tailwindcss): Utility-first CSS framework
+
+Official Documentation:
+- [shadcn/ui Documentation](https://ui.shadcn.com/docs)
+- [API Reference](https://ui.shadcn.com/docs/components)
+- [Radix UI Documentation](https://www.radix-ui.com/)
+- [Tailwind CSS Documentation](https://tailwindcss.com/)
+
+Latest Versions (November 2025):
+- React 19
+- TypeScript 5.5
+- Tailwind CSS 3.4
+- Radix UI Latest
+
+---
+
+Last Updated: 2025-11-21
+Status: Production Ready