metaowl 0.1.2 → 0.2.0

package/bin/metaowl-create.js

@@ -91,10 +91,10 @@ module.exports = createPostcssConfig()
 write('jsconfig.json', JSON.stringify({
   extends: './node_modules/metaowl/config/jsconfig.base.json',
   compilerOptions: {
-    baseUrl: 'src',
+    baseUrl: '.',
     paths: {
-      '@pages/*': ['pages/*'],
-      '@components/*': ['components/*']
+      '@pages/*': ['src/pages/*'],
+      '@components/*': ['src/components/*']
     }
   },
   include: ['src']
@@ -159,8 +159,7 @@ export default class Index extends Component {
 
 // --- src/pages/index/Index.xml ---
 write('src/pages/index/Index.xml',
-`<?xml version="1.0" encoding="UTF-8"?>
-<templates>
+`<templates>
   <t t-name="Index">
     <div class="layout">
       <AppHeader />
@@ -198,8 +197,7 @@ export default class AppHeader extends Component {
 
 // --- src/components/AppHeader/AppHeader.xml ---
 write('src/components/AppHeader/AppHeader.xml',
-`<?xml version="1.0" encoding="UTF-8"?>
-<templates>
+`<templates>
   <t t-name="AppHeader">
     <header class="app-header">
       <span class="app-header__logo">${name}</span>
@@ -235,8 +233,7 @@ export default class AppFooter extends Component {
 
 // --- src/components/AppFooter/AppFooter.xml ---
 write('src/components/AppFooter/AppFooter.xml',
-`<?xml version="1.0" encoding="UTF-8"?>
-<templates>
+`<templates>
   <t t-name="AppFooter">
     <footer class="app-footer">
       <span>Built with metaowl</span>
@@ -258,6 +255,431 @@ write('src/components/AppFooter/AppFooter.css',
 }
 `)
 
+// --- .cursorrules ---
+write('.cursorrules',
+`# MetaOwl Project Rules
+
+## Framework Overview
+This is a MetaOwl application - a lightweight meta-framework for Odoo OWL built on top of Vite.
+
+## Key Concepts
+
+### File-Based Routing
+- Pages in src/pages/ automatically become routes
+- Directory structure mirrors URL structure
+- Dynamic routes use [param] syntax
+- Index directories map to /
+
+### Components
+- Use OWL (Odoo Web Library) component model
+- Templates defined in .xml files with same name
+- CSS scoped to component in .css files
+- Import components from @components/* alias
+
+### State Management
+- Store: Use Store.define() for Pinia-like stores
+- Cache: localStorage wrapper via Cache class
+- Meta: Document head management via Meta.* helpers
+
+### Routing & Navigation
+- File-based routing via pages/ directory
+- Navigation guards via router.beforeEach()
+- Dynamic routes with [id], [slug?], [...path]
+
+## Code Conventions
+- Use static template property: static template = 'TemplateName'
+- Use static components property for child components
+- Use setup() lifecycle hook for initialization
+- Import from 'metaowl' for framework utilities
+
+## File Structure
+- pages/ - Route components
+- components/ - Reusable components  
+- layouts/ - Page layouts (optional)
+- metaowl.js - App entry point
+
+## Common Patterns
+- API calls: Fetch.url('/api/endpoint')
+- State: store.commit('mutation', payload)
+- Meta tags: Meta.title('Page Title')
+- Routing: router.push('/path')
+
+## Documentation
+- See README.md for full API reference
+- See metaowl module docs for detailed API
+`)
+
+// --- CLAUDE.md ---
+write('CLAUDE.md',
+`# ${name} - MetaOwl Project
+
+## Quick Start for Claude Code
+
+This project uses MetaOwl, a meta-framework for Odoo OWL on Vite.
+
+### Architecture
+- **Frontend**: OWL (Odoo Web Library) - reactive components
+- **Build Tool**: Vite with MetaOwl plugin
+- **Routing**: File-based (pages/ directory)
+- **State**: Store pattern with mutations/actions
+
+### Key Files
+\`\`\`
+src/
+├── metaowl.js          # App bootstrap
+├── pages/              # Route components (file-based routing)
+│   └── index/
+│       ├── Index.js    # Page component
+│       ├── Index.xml   # OWL template
+│       └── index.css   # Scoped styles
+├── components/         # Reusable components
+│   ├── AppHeader/
+│   └── AppFooter/
+└── css.js              # Global styles
+\`\`\`
+
+### Development Commands
+- \`npm run dev\` - Start dev server
+- \`npm run build\` - Production build
+- \`npm run generate\` - Static site generation
+- \`npm run lint\` - Lint with Prettier + ESLint
+
+### OWL Component Pattern
+\`\`\`javascript
+import { Component } from '@odoo/owl'
+import { Meta, Store } from 'metaowl'
+
+export default class MyPage extends Component {
+  static template = 'MyPage'
+  static components = { ChildComponent }
+  
+  setup() {
+    // Lifecycle hook
+    Meta.title('Page Title')
+  }
+}
+\`\`\`
+
+### Store Pattern
+\`\`\`javascript
+const useCounterStore = Store.define('counter', {
+  state: () => ({ count: 0 }),
+  mutations: {
+    increment: (state) => state.count++
+  },
+  actions: {
+    async fetchData({ commit }) { }
+  }
+})
+
+// In component:
+const store = useCounterStore()
+store.commit('increment')
+\`\`\`
+
+### Navigation Guard Pattern
+\`\`\`javascript
+import { router } from 'metaowl'
+
+router.beforeEach((to, from, next) => {
+  if (to.meta.requiresAuth && !isLoggedIn) {
+    next('/login')
+  } else {
+    next()
+  }
+})
+\`\`\`
+
+### Dynamic Routes
+- File: pages/user/[id]/User.js → URL: /user/:id
+- File: pages/blog/[slug]/Blog.js → URL: /blog/:slug
+- File: pages/[...path]/NotFound.js → URL: /:path(.*)
+
+### API Requests
+\`\`\`javascript
+import { Fetch } from 'metaowl'
+
+const data = await Fetch.url('/api/users', 'GET')
+const result = await Fetch.url('/api/users', 'POST', { name: 'John' })
+\`\`\`
+
+### Meta Tags
+\`\`\`javascript
+import { Meta } from 'metaowl'
+
+Meta.title('Page Title')
+Meta.description('Page description')
+Meta.ogTitle('Social Title')
+Meta.canonical('https://example.com/page')
+\`\`\`
+
+### Best Practices
+1. Keep components small and focused
+2. Use stores for shared state
+3. Use Meta helpers for SEO
+4. Leverage file-based routing
+5. Scope CSS to components
+6. Use navigation guards for auth
+
+### Common Gotchas
+- Templates must match t-name attribute exactly
+- File-based routing uses directory name, not file name
+- OWL uses xml templates, not JSX
+- Static properties are required (template, components)
+`)
+
+// --- llms.txt ---
+write('llms.txt',
+`# MetaOwl LLM Context
+
+## Framework Identity
+MetaOwl is a lightweight meta-framework for Odoo OWL (Odoo Web Library) applications, built on Vite. It provides file-based routing, state management, and app mounting.
+
+## Core Concepts
+
+### OWL (Odoo Web Library)
+- Reactive component framework
+- XML-based templates (not JSX)
+- Class-based components with static properties
+- Lifecycle: setup(), willStart(), mounted(), etc.
+
+### File-Based Routing
+Convention: 
+- pages/index/Index.js → /
+- pages/about/About.js → /about  
+- pages/user/[id]/User.js → /user/:id
+- pages/[...404]/NotFound.js → catch-all
+
+### Project Structure
+${name}/
+├── src/
+│   ├── metaowl.js          # App entry
+│   ├── index.html          # HTML shell
+│   ├── css.js              # Global styles
+│   ├── pages/              # Route components
+│   │   └── index/
+│   │       ├── Index.js
+│   │       ├── Index.xml
+│   │       └── index.css
+│   ├── components/         # Shared components
+│   │   ├── AppHeader/
+│   │   └── AppFooter/
+│   └── layouts/            # Page layouts (optional)
+├── vite.config.js
+└── package.json
+
+## API Reference
+
+### boot(routes)
+Mounts app to #metaowl element.
+\`\`\`javascript
+import { boot } from 'metaowl'
+boot() // auto file-based routing
+\`\`\`
+
+### Fetch
+HTTP client with base URL.
+\`\`\`javascript
+Fetch.configure({ baseUrl: '/api' })
+await Fetch.url('/users', 'GET')
+await Fetch.url('/users', 'POST', data)
+\`\`\`
+
+### Cache
+localStorage wrapper.
+\`\`\`javascript
+await Cache.set('key', value)
+const value = await Cache.get('key')
+\`\`\`
+
+### Store
+State management.
+\`\`\`javascript
+const useStore = Store.define('store', {
+  state: () => ({ count: 0 }),
+  getters: { double: (s) => s.count * 2 },
+  mutations: { inc: (s) => s.count++ },
+  actions: { async fetch({ commit }) {} }
+})
+\`\`\`
+
+### Meta
+Document head management.
+\`\`\`javascript
+Meta.title('Title')
+Meta.description('Desc')
+Meta.ogTitle('Social Title')
+\`\`\`
+
+### router
+Navigation guards and helpers.
+\`\`\`javascript
+router.beforeEach((to, from, next) => next())
+router.push('/path')
+router.back()
+\`\`\`
+
+## Component Template
+\`\`\`javascript
+import { Component } from '@odoo/owl'
+import { Meta } from 'metaowl'
+
+export default class ComponentName extends Component {
+  static template = 'ComponentName'
+  static components = { /* child components */ }
+  
+  setup() {
+    // Initialize
+    Meta.title('Page')
+  }
+}
+\`\`\`
+
+## Template Format (XML)
+\`\`\`xml
+<templates>
+  <t t-name="ComponentName">
+    <div class="component">
+      <ChildComponent />
+      <span t-esc="someValue" />
+    </div>
+  </t>
+</templates>
+\`\`\`
+
+## CLI Commands
+- metaowl-create - Scaffold project
+- metaowl-dev - Dev server
+- metaowl-build - Production build  
+- metaowl-generate - SSG
+- metaowl-lint - Linting
+
+## See Also
+- README.md - Full documentation
+- https://github.com/odoo/owl - OWL framework
+- https://vitejs.dev - Vite documentation
+`)
+
+// --- .github/copilot-instructions.md ---
+write('.github/copilot-instructions.md',
+`# GitHub Copilot Instructions for MetaOwl
+
+## About This Project
+This is a MetaOwl application - a lightweight meta-framework for Odoo OWL (Odoo Web Library) built on Vite.
+
+## Framework Overview
+
+### OWL Components
+- Class-based components extending Component from '@odoo/owl'
+- Templates defined in separate .xml files
+- CSS scoped to component in .css files
+- Static properties: template, components
+- Lifecycle: setup(), willStart(), mounted(), willUnmount()
+
+### File-Based Routing
+- src/pages/ directory structure maps to URLs
+- pages/index/Index.js → /
+- pages/about/About.js → /about
+- pages/user/[id]/User.js → /user/:id (dynamic)
+- pages/[...path]/NotFound.js → catch-all
+
+### State Management
+Use Store for application state:
+\`\`\`javascript
+const useStore = Store.define('storeName', {
+  state: () => ({ count: 0 }),
+  getters: { double: (state) => state.count * 2 },
+  mutations: { increment: (state) => state.count++ },
+  actions: { async fetch({ commit }) {} }
+})
+\`\`\`
+
+### Common Tasks
+
+When generating components:
+1. Create .js file with Component class
+2. Create matching .xml file with template
+3. Create .css file for scoped styles
+4. Update parent component's static components
+
+When adding pages:
+1. Create directory in src/pages/
+2. Add Page.js, Page.xml, page.css
+3. Route is auto-generated from directory name
+
+When using stores:
+1. Define store with Store.define()
+2. Use in component: const store = useStore()
+3. Read state: store.state.property
+4. Call mutations: store.commit('mutationName', payload)
+5. Call actions: await store.dispatch('actionName', payload)
+
+When setting meta tags:
+1. Import { Meta } from 'metaowl'
+2. Call in setup(): Meta.title('Title')
+
+### Code Patterns
+
+**New Page Component:**
+\`\`\`javascript
+// pages/Feature/Feature.js
+import { Component } from '@odoo/owl'
+import { Meta } from 'metaowl'
+
+export default class Feature extends Component {
+  static template = 'Feature'
+  
+  setup() {
+    Meta.title('Feature Page')
+  }
+}
+\`\`\`
+
+**New Child Component:**
+\`\`\`javascript
+// components/MyComponent/MyComponent.js
+import { Component } from '@odoo/owl'
+
+export default class MyComponent extends Component {
+  static template = 'MyComponent'
+}
+\`\`\`
+
+**Navigation Guard:**
+\`\`\`javascript
+// In metaowl.js
+import { router } from 'metaowl'
+
+router.beforeEach((to, from, next) => {
+  if (to.meta.requiresAuth && !isLoggedIn) {
+    next('/login')
+  } else {
+    next()
+  }
+})
+\`\`\`
+
+## File Conventions
+- Component class names: PascalCase
+- Template names: match class name
+- CSS classes: kebab-case
+- Store names: camelCase
+- Page components: default export
+
+## Do Not
+- Use JSX (OWL uses XML templates)
+- Import React or Vue
+- Modify prototype-based inheritance
+- Use JSX-style event handlers (onclick -> t-on-click)
+
+## Do
+- Use OWL's reactive system
+- Follow file-based routing conventions
+- Scope CSS to components
+- Use Meta helpers for SEO
+- Leverage Store for shared state
+`)
+
 // --- Done ---
 console.log()
 success(`Project "${name}" ready`)

package/index.js

@@ -1,4 +1,3 @@
-import { processRoutes } from './modules/router.js'
 import { mountApp } from './modules/app-mounter.js'
 import { buildRoutes } from './modules/file-router.js'
 
@@ -7,6 +6,161 @@ export { default as Cache } from './modules/cache.js'
 export { configureOwl } from './modules/app-mounter.js'
 export * as Meta from './modules/meta.js'
 export { buildRoutes }
+export { Store, createPersistencePlugin, createStore } from './modules/store.js'
+export {
+  registerLayout,
+  unregisterLayout,
+  getLayout,
+  hasLayout,
+  getLayoutNames,
+  setDefaultLayout,
+  getDefaultLayout,
+  resolveLayout,
+  setRouteLayout,
+  getRouteLayout,
+  createLayoutWrapper,
+  mountWithLayout,
+  getCurrentLayout,
+  subscribeToLayouts,
+  clearLayouts,
+  layout,
+  defineLayout,
+  buildLayouts,
+  discoverLayouts
+} from './modules/layouts.js'
+export {
+  processRoutes,
+  beforeEach,
+  afterEach,
+  getCurrentRoute,
+  getPreviousRoute,
+  isNavigating,
+  cancelNavigation,
+  navigate,
+  push,
+  replace,
+  back,
+  forward,
+  go,
+  router
+} from './modules/router.js'
+export {
+  matchRoute,
+  isDynamicRoute,
+  findRoute,
+  generateUrl,
+  validateRouteParams,
+  createCatchAllRoute,
+  createRedirectRoute,
+  defineRoute,
+  route
+} from './modules/file-router.js'
+export {
+  onError,
+  setErrorContext,
+  getErrorContext,
+  clearErrorContext,
+  captureError,
+  initGlobalErrorHandling,
+  errorBoundary
+} from './modules/error-boundary.js'
+export {
+  configureI18n,
+  t,
+  getLocale,
+  setLocale,
+  i18n,
+  loadLocaleMessages,
+  formatDate,
+  formatNumber,
+  formatCurrency,
+  formatRelativeTime,
+  createNamespacedT
+} from './modules/i18n.js'
+export {
+  useForm,
+  validators,
+  createSchema,
+  fieldProps
+} from './modules/forms.js'
+export {
+  generateComponentMap,
+  generateImports,
+  generateComponentsObject,
+  createAutoImportPlugin,
+  scanComponents,
+  generateComponentDts
+} from './modules/auto-import.js'
+export {
+  OdooService,
+  configure,
+  authenticate,
+  logout,
+  searchRead,
+  call,
+  read,
+  create,
+  write,
+  unlink,
+  searchCount,
+  listDatabases,
+  versionInfo,
+  isAuthenticated,
+  getSession,
+  onAuthChange
+} from './modules/odoo-rpc.js'
+export {
+  useAuth,
+  useLocalStorage,
+  useFetch,
+  useDebounce,
+  useThrottle,
+  useWindowSize,
+  useOnlineStatus,
+  useAsyncState,
+  useCache,
+  Composables
+} from './modules/composables.js'
+export {
+  createMockStore,
+  mockRouter,
+  mountComponent,
+  wait,
+  nextTick,
+  flushPromises,
+  userEvent,
+  dom,
+  TestUtils
+} from './modules/test-utils.js'
+export {
+  generateSitemap,
+  generateRobotsTxt,
+  jsonLd,
+  createCanonicalUrl,
+  generateOpenGraph,
+  generateTwitterCard,
+  validateSitemap,
+  getPriorityByDepth,
+  generateSitemapIndex,
+  SEO
+} from './modules/seo.js'
+export {
+  generateManifest,
+  registerServiceWorker,
+  unregisterServiceWorker,
+  isStandalone,
+  isOnline,
+  subscribeToConnectivity,
+  requestPersistentStorage,
+  getStorageInfo,
+  sync,
+  subscribeToPush,
+  unsubscribeFromPush,
+  showNotification,
+  cache,
+  checkCapabilities,
+  PWA
+} from './modules/pwa.js'
 
 /**
  * Boots the metaowl application.

package/modules/app-mounter.js

@@ -1,3 +1,10 @@
+/**
+ * @module AppMounter
+ *
+ * OWL application mounting with template merging.
+ * Handles the low-level mounting of components into the DOM with
+ * merged XML templates from the build process.
+ */
 import { mount } from '@odoo/owl'
 import { mergeTemplates } from './templates-manager.js'