metaowl 0.1.0

package/modules/app-mounter.js

@@ -0,0 +1,40 @@
+import { mount } from '@odoo/owl'
+import { mergeTemplates } from './templates-manager.js'
+
+const _defaults = {
+  warnIfNoStaticProps: true,
+  willStartTimeout: 10000,
+  translatableAttributes: ['title', 'placeholder', 'label', 'alt']
+}
+
+let _config = { ..._defaults }
+
+/**
+ * Override or extend the default OWL mount configuration.
+ * Call before boot() in your project's metaowl.js.
+ *
+ * @param {object} config - Partial OWL config merged over the defaults.
+ */
+export function configureOwl(config) {
+  _config = { ..._defaults, ...config }
+}
+
+/**
+ * Mount the resolved route's OWL component into `#app`.
+ *
+ * Loads and merges all XML templates (collected at build time by the
+ * metaowl Vite plugin via the `COMPONENTS` define), then mounts the component
+ * using the active OWL config.
+ *
+ * @param {object[]} route - Single-element array returned by `processRoutes()`.
+ * @returns {Promise<void>}
+ */
+export async function mountApp(route) {
+  // COMPONENTS is a string[] injected at build time by the metaowl Vite plugin
+  const components = typeof COMPONENTS !== 'undefined' ? COMPONENTS : []
+  const templates = await mergeTemplates(components)
+  const mountElement = document.getElementById('metaowl')
+  mountElement.innerHTML = ''
+
+  await mount(route[0].component, mountElement, { ..._config, templates })
+}

package/modules/cache.js

@@ -0,0 +1,57 @@
+/**
+ * Async-style localStorage wrapper.
+ *
+ * Values are automatically JSON-serialised on write and deserialised on read.
+ * All methods return Promises so they are interchangeable with IndexedDB-based
+ * alternatives without changing call-sites.
+ */
+export default class Cache {
+  /**
+   * Retrieve a value by key.
+   *
+   * @param {string} key
+   * @returns {Promise<any>} Parsed value, or `null` if the key does not exist.
+   */
+  static async get(key) {
+    return JSON.parse(localStorage.getItem(key))
+  }
+
+  /**
+   * Store a value under the given key.
+   *
+   * @param {string} key
+   * @param {any} value - Must be JSON-serialisable.
+   * @returns {Promise<void>}
+   */
+  static async set(key, value) {
+    localStorage.setItem(key, JSON.stringify(value))
+  }
+
+  /**
+   * Remove a single entry.
+   *
+   * @param {string} key
+   * @returns {Promise<void>}
+   */
+  static async remove(key) {
+    localStorage.removeItem(key)
+  }
+
+  /**
+   * Remove **all** entries from localStorage.
+   *
+   * @returns {Promise<void>}
+   */
+  static async clear() {
+    localStorage.clear()
+  }
+
+  /**
+   * Return all keys currently stored in localStorage.
+   *
+   * @returns {Promise<string[]>}
+   */
+  static async keys() {
+    return Array.from({ length: localStorage.length }, (_, i) => localStorage.key(i))
+  }
+}

package/modules/fetch.js

@@ -0,0 +1,44 @@
+export default class Fetch {
+  static _baseUrl = ''
+  static _onError = null
+
+  /**
+   * Configure the Fetch helper. Call once in your metaowl.js before boot().
+   *
+   * @param {object} options
+   * @param {string} [options.baseUrl=''] - Base URL prepended to every internal request.
+   * @param {function} [options.onError] - Callback invoked on network errors.
+   */
+  static configure({ baseUrl = '', onError = null } = {}) {
+    Fetch._baseUrl = baseUrl
+    Fetch._onError = onError
+  }
+
+  /**
+   * Perform a fetch request.
+   *
+   * @param {string} url - Path or full URL.
+   * @param {'GET'|'POST'|'PUT'|'PATCH'|'DELETE'} [method='GET']
+   * @param {object|null} [data=null] - Request body (JSON-serialised).
+   * @param {boolean} [internal=true] - Prepend baseUrl when true.
+   * @param {boolean} [triggerErrorHandler=true] - Call onError callback on failure.
+   * @returns {Promise<any|null>}
+   */
+  static async url(url, method = 'GET', data = null, internal = true, triggerErrorHandler = true) {
+    const fullUrl = `${internal ? Fetch._baseUrl : ''}${url}`
+
+    const response = await fetch(fullUrl, {
+      method,
+      body: data ? JSON.stringify(data) : null
+    }).catch(error => {
+      console.warn('[metaowl] Fetch error:', error)
+      if (triggerErrorHandler && Fetch._onError) {
+        Fetch._onError(error)
+      }
+    })
+
+    if (!response) return null
+
+    return response.json()
+  }
+}

package/modules/file-router.js

@@ -0,0 +1,60 @@
+/**
+ * Derives a URL path from an import.meta.glob key.
+ *
+ * Convention (mirrors Nuxt/Next.js file-based routing):
+ *   './pages/index/Index.js'     → '/'
+ *   './pages/about/About.js'     → '/about'
+ *   './pages/about/bla/Bla.js'  → '/about/bla'
+ *
+ * Rule: the *directory* path relative to pages/ becomes the URL.
+ * A top-level directory named 'index' maps to '/'.
+ *
+ * @param {string} key - import.meta.glob key, e.g. './pages/about/About.js'
+ * @returns {string} URL path
+ */
+function pathFromKey(key) {
+  // Strip leading './' and 'pages/' prefix
+  const rel = key.replace(/^\.\/pages\//, '')
+  // Drop the filename, keep directory segments
+  const dirParts = rel.split('/').slice(0, -1)
+  if (dirParts.length === 1 && dirParts[0] === 'index') return '/'
+  return '/' + dirParts.join('/')
+}
+
+/**
+ * Extracts the page component from an eagerly-imported module.
+ * Prefers default export, falls back to the first function export.
+ *
+ * @param {object} mod - Eagerly imported module
+ * @param {string} key - Glob key (for error messages)
+ * @returns {Function}
+ */
+function componentFromModule(mod, key) {
+  if (typeof mod.default === 'function') return mod.default
+  const named = Object.values(mod).find(v => typeof v === 'function')
+  if (!named) throw new Error(`[metaowl] No component export found in "${key}"`)
+  return named
+}
+
+/**
+ * Builds a metaowl route table from an import.meta.glob result.
+ *
+ * Usage in src/metaowl.js:
+ *
+ *   import { boot } from 'metaowl'
+ *   boot(import.meta.glob('./pages/**\/*.js', { eager: true }))
+ *
+ * @param {Record<string, object>} modules - Result of import.meta.glob({ eager: true })
+ * @returns {object[]} Route table for processRoutes()
+ */
+export function buildRoutes(modules) {
+  return Object.entries(modules).map(([key, mod]) => {
+    const path = pathFromKey(key)
+    const name = path === '/' ? 'index' : path.slice(1).replace(/\//g, '-')
+    return {
+      name,
+      path: [path],
+      component: componentFromModule(mod, key)
+    }
+  })
+}

package/modules/meta.js

@@ -0,0 +1,119 @@
+/**
+ * @module Meta
+ *
+ * Programmatic helpers for managing document meta tags at runtime.
+ *
+ * Each function is idempotent: the relevant `<meta>` or `<link>` element is
+ * created on first call if it does not already exist, then its content is
+ * updated on every subsequent call as well.
+ *
+ * Import the entire namespace via:
+ *   import { Meta } from 'metaowl'
+ *   Meta.title('My Page')
+ */
+
+function _nameMeta(name, value) {
+  if (!value) return
+  let el = document.querySelector(`meta[name="${name}"]`)
+  if (!el) {
+    el = document.createElement('meta')
+    el.name = name
+    document.head.appendChild(el)
+  }
+  el.content = value
+}
+
+function _propMeta(property, value) {
+  if (!value) return
+  let el = document.querySelector(`meta[property="${property}"]`)
+  if (!el) {
+    el = document.createElement('meta')
+    el.setAttribute('property', property)
+    document.head.appendChild(el)
+  }
+  el.content = value
+}
+
+/** Set the document `<title>`. @param {string} title */
+export function title(title) {
+  if (!title) return
+  document.title = title
+}
+
+/** @param {string} description */
+export function description(description) { _nameMeta('description', description) }
+
+/** @param {string} keywords */
+export function keywords(keywords) { _nameMeta('keywords', keywords) }
+
+/** @param {string} author */
+export function author(author) { _nameMeta('author', author) }
+
+/** @param {string} url */
+export function canonical(url) {
+  if (!url) return
+  let el = document.querySelector('link[rel="canonical"]')
+  if (!el) {
+    el = document.createElement('link')
+    el.rel = 'canonical'
+    document.head.appendChild(el)
+  }
+  el.href = url
+}
+
+/** @param {string} title */
+export function ogTitle(title) { _propMeta('og:title', title) }
+
+/** @param {string} description */
+export function ogDescription(description) { _propMeta('og:description', description) }
+
+/** @param {string} image */
+export function ogImage(image) { _propMeta('og:image', image) }
+
+/** @param {string} url */
+export function ogUrl(url) { _propMeta('og:url', url) }
+
+/** @param {string} type */
+export function ogType(type) { _propMeta('og:type', type) }
+
+/** @param {string} siteName */
+export function ogSiteName(siteName) { _propMeta('og:site_name', siteName) }
+
+/** @param {string} locale */
+export function ogLocale(locale) { _propMeta('og:locale', locale) }
+
+/** @param {string|number} width */
+export function ogImageWidth(width) { _propMeta('og:image:width', width) }
+
+/** @param {string|number} height */
+export function ogImageHeight(height) { _propMeta('og:image:height', height) }
+
+/** @param {string} card */
+export function twitterCard(card) { _nameMeta('twitter:card', card) }
+
+/** @param {string} site */
+export function twitterSite(site) { _nameMeta('twitter:site', site) }
+
+/** @param {string} creator */
+export function twitterCreator(creator) { _nameMeta('twitter:creator', creator) }
+
+/** @param {string} title */
+export function twitterTitle(title) { _nameMeta('twitter:title', title) }
+
+/** @param {string} description */
+export function twitterDescription(description) { _nameMeta('twitter:description', description) }
+
+/** @param {string} image */
+export function twitterImage(image) { _nameMeta('twitter:image', image) }
+
+/** @param {string} alt */
+export function twitterImageAlt(alt) { _nameMeta('twitter:image:alt', alt) }
+
+/** @param {string} url */
+export function twitterUrl(url) { _nameMeta('twitter:url', url) }
+
+/** @param {string} siteId */
+export function twitterSiteId(siteId) { _nameMeta('twitter:site:id', siteId) }
+
+/** @param {string} creatorId */
+export function twitterCreatorId(creatorId) { _nameMeta('twitter:creator:id', creatorId) }

package/modules/router.js

@@ -0,0 +1,62 @@
+/**
+ * Resolves the current URL against a route table.
+ * Used internally by processRoutes().
+ */
+class Router {
+  constructor(routes) {
+    this.routes = routes
+  }
+
+  resolve() {
+    const match = this.routes.filter(route =>
+      (typeof route.path === 'string' && document.location.pathname === route.path) ||
+      (Array.isArray(route.path) && route.path.includes(document.location.pathname))
+    )
+
+    if (match.length !== 1) {
+      throw new Error(`No route found for "${document.location.pathname}".`)
+    }
+
+    return match
+  }
+}
+
+/**
+ * Injects SSG-compatible path variants for a route:
+ * trailing slash, .html suffix, /index.html suffix.
+ *
+ * @param {object} route
+ * @param {string} path
+ * @returns {object}
+ */
+function injectSystemRoutes(route, path) {
+  if (path === '/') {
+    if (!route.path.includes('/index.html')) route.path.push('/index.html')
+  } else {
+    if (!route.path.includes(`${path}.html`)) route.path.push(`${path}.html`)
+    if (!route.path.includes(`${path}/`)) route.path.push(`${path}/`)
+    if (!route.path.includes(`${path}/index.html`)) route.path.push(`${path}/index.html`)
+  }
+
+  return route
+}
+
+/**
+ * Expands all routes with SSG path variants, then resolves the current URL.
+ *
+ * @param {object[]} routes
+ * @returns {Promise<object[]>}
+ */
+export async function processRoutes(routes) {
+  for (const route of routes) {
+    const originalPaths = [...route.path]
+    for (const path of originalPaths) {
+      if (typeof path === 'string') {
+        injectSystemRoutes(route, path)
+      }
+    }
+  }
+
+  return new Router(routes).resolve()
+}
+

package/modules/templates-manager.js

@@ -0,0 +1,20 @@
+import { loadFile } from '@odoo/owl'
+
+/**
+ * Loads and concatenates a list of OWL XML template files into a single
+ * `<templates>` string ready to be passed to OWL's mount() options.
+ *
+ * @param {string[]} files - Array of URL-style XML paths, e.g. ['/owl/components/Header/Header.xml']
+ * @returns {Promise<string>}
+ */
+export async function mergeTemplates(files) {
+  let templates = '<templates>'
+  for (const file of files) {
+    try {
+      templates += await loadFile(file)
+    } catch (e) {
+      console.error(`[metaowl] Failed to load template: ${file}`, e)
+    }
+  }
+  return templates + '</templates>'
+}

package/package.json

@@ -0,0 +1,68 @@
+{
+  "name": "metaowl",
+  "version": "0.1.0",
+  "description": "Lightweight meta-framework for Odoo OWL — file-based routing, app mounting, Fetch helper, Cache, Meta tags, SSG generator, and a Vite plugin.",
+  "type": "module",
+  "main": "index.js",
+  "exports": {
+    ".": "./index.js",
+    "./vite": "./vite/plugin.js",
+    "./eslint": "./eslint.js",
+    "./postcss": "./postcss.cjs"
+  },
+  "bin": {
+    "metaowl-create": "./bin/metaowl-create.js",
+    "metaowl-dev": "./bin/metaowl-dev.js",
+    "metaowl-build": "./bin/metaowl-build.js",
+    "metaowl-generate": "./bin/metaowl-generate.js",
+    "metaowl-lint": "./bin/metaowl-lint.js"
+  },
+  "keywords": [
+    "owl",
+    "odoo",
+    "framework",
+    "vite",
+    "meta-framework"
+  ],
+  "author": "Dennis Schott",
+  "license": "LGPL-3.0-only",
+  "sideEffects": false,
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/dennisschott/metaowl"
+  },
+  "homepage": "https://github.com/dennisschott/metaowl#readme",
+  "bugs": {
+    "url": "https://github.com/dennisschott/metaowl/issues"
+  },
+  "dependencies": {
+    "@eslint/js": "^9.20.1",
+    "@fullhuman/postcss-purgecss": "^6.0.0",
+    "@odoo/owl": "^2.8.2",
+    "@typescript-eslint/eslint-plugin": "^8.24.1",
+    "@typescript-eslint/parser": "^8.24.1",
+    "dotenv": "^16.4.7",
+    "eslint": "^9.20.1",
+    "eslint-plugin-import": "^2.31.0",
+    "eslint-plugin-n": "^17.15.1",
+    "eslint-plugin-promise": "^7.2.1",
+    "glob": "^13.0.6",
+    "globals": "^13.24.0",
+    "prettier": "3.5.1",
+    "vite": "^7.3.1",
+    "vite-plugin-handlebars": "^2.0.0",
+    "vite-plugin-restart": "^2.0.0",
+    "vite-tsconfig-paths": "^6.1.1"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "scripts": {
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "devDependencies": {
+    "jsdom": "^28.1.0",
+    "vitest": "^4.0.18"
+  }
+}

package/postcss.cjs

@@ -0,0 +1,43 @@
+// CommonJS PostCSS config factory for metaowl projects.
+// Usage in postcss.config.cjs:
+//
+//   const { createPostcssConfig } = require('metaowl/postcss')
+//   module.exports = createPostcssConfig()
+//
+// Override safelist or add content globs:
+//
+//   module.exports = createPostcssConfig({
+//     safelist: [/^my-custom-class/],
+//     content: ['./templates/**/*.html']
+//   })
+
+const defaultSafelist = []
+
+function createPostcssConfig(options = {}) {
+  const {
+    safelist = [],
+    content = [],
+    additionalPlugins = []
+  } = options
+
+  return {
+    plugins: [
+      ...process.env.NODE_ENV === 'production'
+        ? [
+            require('@fullhuman/postcss-purgecss')({
+              content: [
+                './**/*.xml',
+                './**/*.html',
+                './src/**/*.js',
+                ...content
+              ],
+              safelist: [...defaultSafelist, ...safelist]
+            })
+          ]
+        : [],
+      ...additionalPlugins
+    ]
+  }
+}
+
+module.exports = { createPostcssConfig }

package/test/cache.test.js

@@ -0,0 +1,55 @@
+import { describe, it, expect, beforeEach } from 'vitest'
+import Cache from '../modules/cache.js'
+
+// Minimal localStorage stub
+const store = {}
+const localStorageMock = {
+  getItem: (k) => store[k] ?? null,
+  setItem: (k, v) => { store[k] = v },
+  removeItem: (k) => { delete store[k] },
+  clear: () => { Object.keys(store).forEach(k => delete store[k]) },
+  get length() { return Object.keys(store).length },
+  key: (i) => Object.keys(store)[i] ?? null
+}
+Object.defineProperty(globalThis, 'localStorage', { value: localStorageMock, writable: true })
+
+beforeEach(() => localStorageMock.clear())
+
+describe('Cache', () => {
+  it('set and get a string value', async () => {
+    await Cache.set('name', 'metaowl')
+    expect(await Cache.get('name')).toBe('metaowl')
+  })
+
+  it('set and get an object', async () => {
+    await Cache.set('obj', { a: 1, b: [2, 3] })
+    expect(await Cache.get('obj')).toEqual({ a: 1, b: [2, 3] })
+  })
+
+  it('get returns null for missing key', async () => {
+    expect(await Cache.get('missing')).toBeNull()
+  })
+
+  it('remove deletes the key', async () => {
+    await Cache.set('tmp', 'x')
+    await Cache.remove('tmp')
+    expect(await Cache.get('tmp')).toBeNull()
+  })
+
+  it('clear removes all keys', async () => {
+    await Cache.set('a', 1)
+    await Cache.set('b', 2)
+    await Cache.clear()
+    expect(await Cache.get('a')).toBeNull()
+    expect(await Cache.get('b')).toBeNull()
+  })
+
+  it('keys returns all stored keys', async () => {
+    await Cache.set('x', 1)
+    await Cache.set('y', 2)
+    const keys = await Cache.keys()
+    expect(keys).toContain('x')
+    expect(keys).toContain('y')
+    expect(keys).toHaveLength(2)
+  })
+})

package/test/fetch.test.js

@@ -0,0 +1,100 @@
+import { describe, it, expect, beforeEach, vi } from 'vitest'
+import Fetch from '../modules/fetch.js'
+
+beforeEach(() => {
+  Fetch.configure({ baseUrl: '', onError: null })
+  vi.restoreAllMocks()
+})
+
+describe('Fetch.configure', () => {
+  it('sets baseUrl', () => {
+    Fetch.configure({ baseUrl: 'https://api.example.com' })
+    expect(Fetch._baseUrl).toBe('https://api.example.com')
+  })
+
+  it('sets onError callback', () => {
+    const handler = vi.fn()
+    Fetch.configure({ onError: handler })
+    expect(Fetch._onError).toBe(handler)
+  })
+
+  it('defaults baseUrl to empty string', () => {
+    Fetch.configure({})
+    expect(Fetch._baseUrl).toBe('')
+  })
+})
+
+describe('Fetch.url', () => {
+  it('prepends baseUrl for internal requests', async () => {
+    Fetch.configure({ baseUrl: 'https://api.example.com' })
+    const mockFetch = vi.fn().mockResolvedValue({
+      json: () => Promise.resolve({ ok: true })
+    })
+    vi.stubGlobal('fetch', mockFetch)
+
+    await Fetch.url('/items')
+    expect(mockFetch).toHaveBeenCalledWith(
+      'https://api.example.com/items',
+      expect.objectContaining({ method: 'GET' })
+    )
+  })
+
+  it('does not prepend baseUrl when internal=false', async () => {
+    Fetch.configure({ baseUrl: 'https://api.example.com' })
+    const mockFetch = vi.fn().mockResolvedValue({
+      json: () => Promise.resolve({})
+    })
+    vi.stubGlobal('fetch', mockFetch)
+
+    await Fetch.url('https://other.com/data', 'GET', null, false)
+    expect(mockFetch).toHaveBeenCalledWith(
+      'https://other.com/data',
+      expect.anything()
+    )
+  })
+
+  it('sends JSON body for POST requests', async () => {
+    const mockFetch = vi.fn().mockResolvedValue({
+      json: () => Promise.resolve({})
+    })
+    vi.stubGlobal('fetch', mockFetch)
+
+    await Fetch.url('/items', 'POST', { name: 'test' })
+    expect(mockFetch).toHaveBeenCalledWith(
+      '/items',
+      expect.objectContaining({
+        method: 'POST',
+        body: JSON.stringify({ name: 'test' })
+      })
+    )
+  })
+
+  it('returns null and calls onError on network failure', async () => {
+    const onError = vi.fn()
+    Fetch.configure({ onError })
+    vi.stubGlobal('fetch', vi.fn().mockRejectedValue(new Error('network down')))
+
+    const result = await Fetch.url('/fail')
+    expect(result).toBeNull()
+    expect(onError).toHaveBeenCalledOnce()
+  })
+
+  it('returns null and skips onError when triggerErrorHandler=false', async () => {
+    const onError = vi.fn()
+    Fetch.configure({ onError })
+    vi.stubGlobal('fetch', vi.fn().mockRejectedValue(new Error('network down')))
+
+    const result = await Fetch.url('/fail', 'GET', null, true, false)
+    expect(result).toBeNull()
+    expect(onError).not.toHaveBeenCalled()
+  })
+
+  it('returns parsed JSON on success', async () => {
+    vi.stubGlobal('fetch', vi.fn().mockResolvedValue({
+      json: () => Promise.resolve({ id: 42 })
+    }))
+
+    const result = await Fetch.url('/item/42')
+    expect(result).toEqual({ id: 42 })
+  })
+})