@jasonshimmy/vite-plugin-cer-app 0.23.2 → 0.24.0

package/docs/head-management.md

@@ -1,212 +0,0 @@
-# Head Management
-
-The `useHead()` composable manages `<title>`, `<meta>`, `<link>`, `<script>`, and `<style>` tags in the document `<head>`.
-
-- **In SSR/SSG mode** — tags are collected during rendering and injected into the HTML before it is sent to the browser.
-- **In client mode (SPA or after hydration)** — tags are imperatively applied to `document.head`.
-
----
-
-## Import
-
-`useHead` is auto-imported in files inside `app/pages/`, `app/layouts/`, `app/components/`, and root convention files (e.g. `app/loading.ts`). No import statement is needed in those locations.
-
-If you use `useHead` outside those directories, import it explicitly:
-
-```ts
-import { useHead } from '@jasonshimmy/vite-plugin-cer-app/composables'
-```
-
----
-
-## Basic usage
-
-```ts
-component('page-about', () => {
-  useHead({
-    title: 'About Us',
-    meta: [
-      { name: 'description', content: 'Learn more about our team.' },
-      { property: 'og:title', content: 'About Us' },
-      { property: 'og:type', content: 'website' },
-    ],
-    link: [
-      { rel: 'canonical', href: 'https://example.com/about' },
-    ],
-  })
-
-  return html`<h1>About</h1>`
-})
-```
-
----
-
-## `HeadInput` interface
-
-```ts
-interface HeadInput {
-  title?: string
-  meta?: Array<Record<string, string>>
-  link?: Array<Record<string, string>>
-  script?: Array<Record<string, string>>
-  style?: Array<Record<string, string>>
-}
-```
-
-All fields are optional. Each array item is a map of HTML attribute names to values. Use `innerHTML` as a special key to set element inner content for `<script>` and `<style>`.
-
----
-
-## Title
-
-```ts
-useHead({ title: 'My Page' })
-```
-
-- **SSR/SSG:** Rendered as `<title>My Page</title>` injected before `</head>`.
-- **Client:** Sets `document.title = 'My Page'`.
-- **Deduplication:** Last call wins — subsequent `useHead({ title })` calls overwrite the previous title.
-
-HTML entities in the title are escaped automatically (`<`, `>`, `&`).
-
----
-
-## Meta tags
-
-```ts
-useHead({
-  meta: [
-    { name: 'description', content: 'Page description' },
-    { property: 'og:title', content: 'OG Title' },
-    { charset: 'UTF-8' },
-    { name: 'robots', content: 'index, follow' },
-  ],
-})
-```
-
-### Deduplication
-
-Meta tags are deduplicated by their key attribute:
-
-| Attribute present | Dedup key |
-|---|---|
-| `name` | `name` value |
-| `property` | `property` value |
-| `charset` | `charset` value |
-| None of the above | Full JSON serialization |
-
-When the same key is set twice, the later value replaces the earlier one.
-
-### Client mode
-
-- If a `meta[name="…"]` or `meta[property="…"]` element already exists in the DOM, its attributes are updated in place.
-- Otherwise a new `<meta>` element is created and appended to `<head>`.
-- `charset` meta tags are **not** updated on the client (the `name`/`property` check requires one of those attributes).
-
----
-
-## Link tags
-
-```ts
-useHead({
-  link: [
-    { rel: 'canonical', href: 'https://example.com/about' },
-    { rel: 'stylesheet', href: '/styles/extra.css' },
-    { rel: 'preload', href: '/fonts/inter.woff2', as: 'font', type: 'font/woff2', crossorigin: '' },
-  ],
-})
-```
-
-### Deduplication
-
-Deduplicated by `rel` + `href` key. Same `rel`/`href` pair appearing twice results in a single tag.
-
-### Client mode
-
-- If a `link[rel="…"][href="…"]` already exists, its attributes are updated in place.
-- Otherwise a new `<link>` element is created.
-
----
-
-## Script tags
-
-```ts
-useHead({
-  script: [
-    // External script by src
-    { src: '/analytics.js', defer: '', type: 'text/javascript' },
-
-    // Inline script with innerHTML
-    { innerHTML: 'window.__APP_VERSION__ = "1.0.0"' },
-
-    // JSON-LD structured data
-    {
-      type: 'application/ld+json',
-      innerHTML: JSON.stringify({
-        '@context': 'https://schema.org',
-        '@type': 'WebPage',
-        name: 'About Us',
-      }),
-    },
-  ],
-})
-```
-
-Script tags are **not** deduplicated — every call appends a new `<script>` to the output.
-
-### Client mode (script deduplication)
-
-On the client, scripts **with `src`** are deduplicated: a `<script src="…">` is only added if no `script[src="…"]` already exists in the DOM. Scripts without `src` (inline) are always appended.
-
----
-
-## Style tags
-
-```ts
-useHead({
-  style: [
-    { innerHTML: ':root { --color-primary: #007bff }' },
-    { type: 'text/css', innerHTML: 'body { margin: 0 }' },
-  ],
-})
-```
-
-Style tags are not deduplicated.
-
-> **Note:** `style` tag support via `useHead` is SSR/SSG only. Client-side `useHead({ style: [...] })` calls are no-ops — style tags are not injected into `document.head` on the client.
-
----
-
-## SSR: collection and injection
-
-During SSR rendering, `useHead()` calls are collected via a request-scoped array. After rendering is complete, the collected tags are serialized and injected before `</head>` in the HTML shell.
-
-You can use the underlying primitives directly from `@jasonshimmy/vite-plugin-cer-app/composables` if you need manual control:
-
-```ts
-import { beginHeadCollection, endHeadCollection, serializeHeadTags } from '@jasonshimmy/vite-plugin-cer-app/composables'
-
-// Before rendering:
-beginHeadCollection()
-
-// ... render component tree (useHead() calls accumulate) ...
-
-// After rendering:
-const collected = endHeadCollection()
-const headHtml = serializeHeadTags(collected)
-// Inject headHtml into your HTML template
-```
-
----
-
-## Merging rules summary
-
-| Tag type | Deduplication key | Merge behavior |
-|---|---|---|
-| `<title>` | N/A | Last wins |
-| `<meta name>` | `name` value | Later replaces earlier |
-| `<meta property>` | `property` value | Later replaces earlier |
-| `<meta charset>` | `charset` value | Later replaces earlier |
-| `<link>` | `rel` + `href` | Later replaces earlier |
-| `<script>` | None (SSR) / `src` (client) | Accumulated (external deduped on client) |
-| `<style>` | None | Always accumulated |

package/docs/i18n.md

@@ -1,159 +0,0 @@
-# 🌍 Internationalisation (i18n)
-
-`vite-plugin-cer-app` has built-in support for locale-aware URL routing and the `useLocale()` composable. No external package is required.
-
----
-
-## Configuration
-
-Add an `i18n` block to `cer.config.ts`:
-
-```ts
-// cer.config.ts
-import { defineConfig } from '@jasonshimmy/vite-plugin-cer-app'
-
-export default defineConfig({
-  i18n: {
-    locales: ['en', 'fr', 'de'],
-    defaultLocale: 'en',
-    strategy: 'prefix_except_default', // default
-  },
-})
-```
-
-### Options
-
-| Option | Type | Default | Description |
-|---|---|---|---|
-| `locales` | `string[]` | — | All supported locale codes. |
-| `defaultLocale` | `string` | — | The fallback locale. |
-| `strategy` | `'prefix' \| 'prefix_except_default' \| 'no_prefix'` | `'prefix_except_default'` | How locales appear in URLs. |
-
-### Strategies
-
-| Strategy | Default locale URL | Other locale URL |
-|---|---|---|
-| `'prefix'` | `/en/about` | `/fr/about` |
-| `'prefix_except_default'` | `/about` | `/fr/about` |
-| `'no_prefix'` | `/about` | `/about` (locale from cookie/header only) |
-
-> **Recommendation:** Use `'prefix_except_default'` for most projects. It keeps your existing English URLs intact while adding locale prefixes for other languages.
-
----
-
-## How It Works
-
-When `i18n` is configured, the build system automatically generates locale-prefixed route variants for every page. You do **not** need to duplicate your page files.
-
-For example, with `locales: ['en', 'fr']` and `strategy: 'prefix_except_default'`, the page `app/pages/about.ts` generates:
-
-| Path | Locale |
-|---|---|
-| `/about` | `en` (default) |
-| `/fr/about` | `fr` |
-
-Both routes load the same page component — only the detected locale differs.
-
----
-
-## `useLocale()`
-
-The `useLocale()` composable is **auto-imported** in all page, layout, and component files. It works isomorphically: on the server it reads the URL path via AsyncLocalStorage; on the client it reads `window.location.pathname`.
-
-```ts
-const {
-  locale,          // 'fr'            — current locale code
-  locales,         // ['en', 'fr']    — all configured locales
-  defaultLocale,   // 'en'            — the default locale
-  switchLocalePath, // function        — build a URL in another locale
-} = useLocale()
-```
-
-### `switchLocalePath(targetLocale, path?)`
-
-Returns the equivalent path in the target locale. When `path` is omitted the current pathname is used.
-
-```ts
-// On /fr/about
-switchLocalePath('en')         // → '/about'
-switchLocalePath('en', '/fr/about') // → '/about'
-switchLocalePath('de', '/fr/about') // → '/de/about'
-
-// On /about (default locale)
-switchLocalePath('fr')         // → '/fr/about'
-```
-
-### Example — locale switcher component
-
-```ts
-// app/components/locale-switcher.ts
-component('locale-switcher', () => {
-  const { locale, locales, switchLocalePath } = useLocale()
-
-  return html`
-    <nav>
-      ${locales.map((l) => html`
-        <a
-          href="${switchLocalePath(l)}"
-          aria-current="${l === locale ? 'true' : 'false'}"
-        >${l.toUpperCase()}</a>
-      `)}
-    </nav>
-  `
-})
-```
-
-### Example — locale-aware page
-
-```ts
-// app/pages/about.ts
-component('page-about', () => {
-  const { locale } = useLocale()
-
-  const headings = { en: 'About Us', fr: 'À propos', de: 'Über uns' }
-
-  return html`<h1>${headings[locale] ?? headings.en}</h1>`
-})
-```
-
----
-
-## SSR / SSG
-
-`useLocale()` works identically in SSR and SSG mode because it reads the request URL from AsyncLocalStorage on the server rather than from `window`.
-
-For SSG, the build system pre-renders **each locale path** as a separate static HTML file:
-
-```
-dist/
-  index.html          (en — default locale)
-  about/index.html    (en — default locale)
-  fr/
-    index.html
-    about/index.html
-```
-
----
-
-## Detecting Locale Without URL Prefixes (`no_prefix`)
-
-When `strategy: 'no_prefix'` is used, `useLocale()` always returns `defaultLocale` because there is no locale in the URL. To support multi-language content without URL changes you can:
-
-1. Store the user's preferred locale in a cookie and read it in a server middleware.
-2. Use the `Accept-Language` request header in a loader.
-
-```ts
-// app/pages/home.ts
-export const loader = async ({ req }) => {
-  const lang = req.headers['accept-language']?.split(',')[0]?.split('-')[0] ?? 'en'
-  return { lang }
-}
-```
-
----
-
-## Limitations
-
-- Per-route middleware applies to **all** locale variants of a route.
-- `no_prefix` strategy does not auto-detect locale from `Accept-Language` — you must do this manually in a loader or server middleware.
-- Locale switching via `switchLocalePath` generates URLs but does **not** automatically navigate; pair it with `navigateTo()` for programmatic locale changes.

package/docs/layouts.md

@@ -1,224 +0,0 @@
-# Layouts
-
-Layouts wrap page content in a shared shell — header, footer, navigation, etc. They live in `app/layouts/` and use `<slot>` to inject the page.
-
----
-
-## Defining a layout
-
-```ts
-// app/layouts/default.ts
-component('layout-default', () => {
-  return html`
-    <header>
-      <nav>
-        <router-link to="/">Home</router-link>
-        <router-link to="/about">About</router-link>
-      </nav>
-    </header>
-    <main>
-      <slot></slot>
-    </main>
-    <footer>
-      <p>© 2025 My App</p>
-    </footer>
-  `
-})
-```
-
-The `<slot>` is where the current page's output is injected.
-
----
-
-## Naming conventions
-
-| File | Layout name | Custom element tag |
-|---|---|---|
-| `app/layouts/default.ts` | `'default'` | `layout-default` |
-| `app/layouts/minimal.ts` | `'minimal'` | `layout-minimal` |
-| `app/layouts/blog/post.ts` | `'blog-post'` | `layout-blog-post` |
-
-The **layout name** (the key in the map) is the path relative to `app/layouts/`, with slashes replaced by dashes and the extension stripped:
-- `default.ts` → `'default'`
-- `blog/post.ts` → `'blog-post'`
-
-The **tag name** is `layout-` prefixed:
-- `default.ts` → `layout-default`
-- `blog/post.ts` → `layout-blog-post`
-
----
-
-## Assigning a layout to a page
-
-Set `meta.layout` in any page file:
-
-```ts
-// app/pages/about.ts
-component('page-about', () => html`<h1>About</h1>`)
-
-export const meta = {
-  layout: 'default',   // uses app/layouts/default.ts
-}
-```
-
-If `meta.layout` is omitted and `app/layouts/default.ts` exists, the default layout is used automatically.
-
-To render a page without any layout, explicitly set `layout` to an empty string or `false`:
-
-```ts
-export const meta = {
-  layout: '',  // no layout
-}
-```
-
----
-
-## Multiple layouts
-
-You can have as many layout files as needed:
-
-```
-app/layouts/
-  default.ts      # full-page layout (header + footer)
-  minimal.ts      # no header/footer (used for login, error pages)
-  dashboard.ts    # sidebar + main area
-```
-
-Choose per page:
-
-```ts
-// app/pages/(auth)/login.ts
-export const meta = { layout: 'minimal' }
-
-// app/pages/dashboard/index.ts
-export const meta = { layout: 'dashboard' }
-```
-
----
-
-## Accessing layouts in code
-
-The layout map is available via `virtual:cer-layouts`:
-
-```ts
-import layouts from 'virtual:cer-layouts'
-// { default: 'layout-default', minimal: 'layout-minimal', ... }
-```
-
----
-
-## Layout switching and DOM preservation
-
-When navigating between pages with different layouts, the framework uses `<cer-keep-alive>` to preserve the layout DOM and avoid unnecessary teardown/remount cycles. This means transitions between pages sharing the same layout are smooth with no layout flash.
-
----
-
-## 🪆 Nested layouts
-
-Place a `_layout.ts` file inside any page subdirectory to add an inner layout that wraps pages in that subtree. The outer layout (from `meta.layout` or the default) wraps the inner layout, which wraps `<router-view>`.
-
-### File convention
-
-```
-app/
-  layouts/
-    default.ts      # outer layout — full shell (header, footer)
-    minimal.ts      # outer layout — bare minimum
-    sidebar.ts      # inner layout — adds a sidebar panel
-  pages/
-    index.ts        # uses 'default' layout only
-    admin/
-      _layout.ts    # ← inner layout override for all /admin/* pages
-      index.ts      # layout chain: ['default', 'sidebar']
-      users.ts      # layout chain: ['default', 'sidebar']
-      settings.ts   # layout chain: ['default', 'sidebar']
-```
-
-### `_layout.ts` syntax
-
-`_layout.ts` supports two forms:
-
-**Legacy — export default string (inner layout only)**
-
-```ts
-// app/pages/admin/_layout.ts
-export default 'sidebar'
-```
-
-**Group meta — export const meta (middleware + layout defaults)**
-
-```ts
-// app/pages/admin/_layout.ts
-export const meta = {
-  // All pages in this directory inherit this middleware unless they declare their own
-  middleware: ['auth', 'admin'],
-  // All pages in this directory use this outer layout by default
-  layout: 'admin',
-}
-```
-
-You can also mix both forms in the same file:
-
-```ts
-// app/pages/admin/_layout.ts
-export default 'sidebar'           // inner layout (chain)
-export const meta = {
-  middleware: ['auth'],             // group middleware
-  layout: 'admin',                 // outer layout override
-}
-```
-
-**Precedence rules:**
-- Page-level `meta.middleware` completely overrides group middleware (no merging).
-- Page-level `meta.layout` overrides the group layout default.
-- The group-level `export default` sets the inner layout for the chain — this is never overridden by page meta.
-
-The value must match a filename (without extension) in `app/layouts/`.
-
-### Rendered structure
-
-For a page at `app/pages/admin/users.ts` with the above setup:
-
-```html
-<layout-default>
-  <layout-sidebar>
-    <router-view></router-view>
-  </layout-sidebar>
-</layout-default>
-```
-
-Each layout receives the inner content via `<slot>`.
-
-### Overriding the outer layout
-
-If a page in a nested subtree needs a different outer layout, declare it in `meta.layout` as usual:
-
-```ts
-// app/pages/admin/login.ts
-export const meta = {
-  layout: 'minimal',   // overrides outer; chain = ['minimal', 'sidebar']
-}
-```
-
-### Multiple nesting levels
-
-Nesting is resolved recursively. Each ancestor directory that contains a `_layout.ts` contributes one level to the chain:
-
-```
-app/pages/
-  admin/
-    _layout.ts      → 'sidebar'
-    settings/
-      _layout.ts    → 'settings-tabs'
-      profile.ts    # chain: ['default', 'sidebar', 'settings-tabs']
-```
-
-### `meta.layoutChain` in routes
-
-The framework emits the resolved chain as `meta.layoutChain` on the route object at build time. You can read it at runtime:
-
-```ts
-import routes from 'virtual:cer-routes'
-const adminUsers = routes.find(r => r.path === '/admin/users')
-// adminUsers.meta.layoutChain → ['default', 'sidebar']
-```