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

package/src/runtime/composables/use-inject.ts

@@ -1,49 +0,0 @@
-import { inject } from '@jasonshimmy/custom-elements-runtime'
-
-const _g = globalThis as Record<string, unknown>
-const _PROVIDES_KEY = '__cerPluginProvides'
-
-/**
- * useInject — reads a value provided by a plugin via plugin.setup()'s provide().
- *
- * Works consistently across all rendering modes:
- *
- * - **SPA/Client**: Uses inject() from the component context tree (established
- *   by cer-layout-view calling provide() for each plugin-provided value).
- *
- * - **SSR/SSG**: Reads from globalThis.__cerPluginProvides, populated when the
- *   server entry runs plugin.setup() before rendering.
- *
- * @example
- * ```ts
- * // In a plugin (app/plugins/my-plugin.ts):
- * export default {
- *   name: 'my-plugin',
- *   setup({ provide }) {
- *     provide('my-service', { greet: () => 'hello' })
- *   }
- * }
- *
- * // In a component:
- * component('my-page', () => {
- *   const service = useInject<{ greet(): string }>('my-service')
- * })
- * ```
- */
-export function useInject<T = unknown>(key: string, defaultValue?: T): T | undefined {
-  // Server-side (SSR/SSG): read from the global plugin provides map.
-  // __cerPluginProvides is populated by the server entry before the render pass.
-  if (typeof document === 'undefined') {
-    const pluginProvides = _g[_PROVIDES_KEY] as Map<PropertyKey, unknown> | undefined
-    const value = pluginProvides?.get(key)
-    return value !== undefined ? (value as T) : defaultValue
-  }
-
-  // Client-side: inject() walks the component context tree established by
-  // cer-layout-view's provide() calls. Falls back to __cerPluginProvides for
-  // reads before cer-layout-view mounts (e.g. during plugin-registered components).
-  const value = inject<T>(key)
-  if (value !== undefined) return value
-  const pluginProvides = _g[_PROVIDES_KEY] as Map<PropertyKey, unknown> | undefined
-  return (pluginProvides?.get(key) as T | undefined) ?? defaultValue
-}

package/src/runtime/composables/use-locale.ts

@@ -1,109 +0,0 @@
-import type { IncomingMessage } from 'node:http'
-
-/** Return value of `useLocale()`. Exposes the active locale and helpers for locale-aware navigation. */
-export interface LocaleComposable {
-  /** The active locale code for the current request / page. */
-  readonly locale: string
-  /** All configured locale codes. */
-  readonly locales: string[]
-  /** The default locale code. */
-  readonly defaultLocale: string
-  /**
-   * Returns the localised version of `path` for `targetLocale`.
-   *
-   * @example
-   * switchLocalePath('fr', '/about') // → '/fr/about'
-   * switchLocalePath('en', '/fr/about') // → '/about'  (when en is default + prefix_except_default)
-   */
-  switchLocalePath(targetLocale: string, path?: string): string
-}
-
-interface I18nVirtualConfig {
-  locales: string[]
-  defaultLocale: string
-  strategy: 'prefix' | 'prefix_except_default' | 'no_prefix'
-}
-
-// ─── Internal helpers ─────────────────────────────────────────────────────────
-
-function _extractLocaleFromPath(pathname: string, locales: string[]): string | null {
-  const first = pathname.split('/')[1]
-  return locales.includes(first) ? first : null
-}
-
-function _stripLocalePrefix(pathname: string, locale: string): string {
-  const prefix = `/${locale}`
-  if (pathname === prefix) return '/'
-  if (pathname.startsWith(`${prefix}/`)) return pathname.slice(prefix.length)
-  return pathname
-}
-
-function _buildLocalePath(
-  pathname: string,
-  targetLocale: string,
-  currentLocale: string,
-  config: I18nVirtualConfig,
-): string {
-  // Strip the current locale prefix (if any) to get the bare path
-  const bare = _stripLocalePrefix(pathname, currentLocale)
-  if (config.strategy === 'no_prefix') return bare
-  if (config.strategy === 'prefix_except_default' && targetLocale === config.defaultLocale) return bare
-  return `/${targetLocale}${bare === '/' ? '' : bare}`
-}
-
-// ─── Composable ───────────────────────────────────────────────────────────────
-
-/**
- * Internationalisation composable. Returns the active locale and helpers for
- * building locale-aware URLs. Requires `i18n` to be configured in `cer.config.ts`.
- *
- * Works isomorphically: on the server it reads the URL path via AsyncLocalStorage;
- * on the client it reads `window.location.pathname`.
- *
- * When `i18n` is not configured, `locale` equals `'default'` and `locales` is `['default']`.
- *
- * @example
- * ```ts
- * const { locale, switchLocalePath } = useLocale()
- * console.log(locale)                           // 'fr'
- * console.log(switchLocalePath('en', '/fr/about')) // '/about'
- * ```
- */
-export function useLocale(): LocaleComposable {
-  // Read i18n config from the virtual module at runtime.
-  // The virtual module is replaced by the bundler at build time.
-  const g = globalThis as Record<string, unknown>
-  const i18nConfig = g['__CER_I18N_CONFIG__'] as I18nVirtualConfig | null | undefined
-
-  const locales = i18nConfig?.locales ?? ['default']
-  const defaultLocale = i18nConfig?.defaultLocale ?? 'default'
-  const strategy = i18nConfig?.strategy ?? 'no_prefix'
-
-  // Resolve the current pathname from the server request context or window.
-  let pathname = '/'
-  const reqStore = g['__CER_REQ_STORE__'] as
-    | { getStore(): { req: IncomingMessage } | null }
-    | undefined
-  if (reqStore) {
-    const ctx = reqStore.getStore()
-    if (ctx?.req.url) {
-      try { pathname = new URL(ctx.req.url, 'http://x').pathname } catch { /* ignore */ }
-    }
-  } else if (typeof window !== 'undefined') {
-    pathname = window.location.pathname
-  }
-
-  const detectedLocale = strategy !== 'no_prefix'
-    ? (_extractLocaleFromPath(pathname, locales) ?? defaultLocale)
-    : defaultLocale
-
-  return {
-    get locale() { return detectedLocale },
-    get locales() { return locales },
-    get defaultLocale() { return defaultLocale },
-    switchLocalePath(targetLocale: string, path?: string): string {
-      const base = path ?? pathname
-      return _buildLocalePath(base, targetLocale, detectedLocale, { locales, defaultLocale, strategy })
-    },
-  }
-}

package/src/runtime/composables/use-navigate.ts

@@ -1,58 +0,0 @@
-/**
- * navigateTo — programmatic navigation.
- *
- * Works isomorphically:
- * - **Server context** (inside a loader or middleware): sends a 302 redirect
- *   immediately by writing to the current request's `res` object via
- *   `AsyncLocalStorage`. The response is ended and the function returns.
- * - **Client context**: delegates to the framework router so the SPA
- *   navigation pipeline (middleware, loaders, isNavigating) runs normally.
- *   Falls back to `window.location.href` if the router is not available.
- *
- * @example
- * ```ts
- * // app/middleware/require-auth.ts
- * export default defineMiddleware(() => {
- *   const { loggedIn } = useAuth()
- *   if (!loggedIn) return navigateTo('/login')
- * })
- * ```
- *
- * @example
- * ```ts
- * // app/pages/dashboard.ts
- * component('page-dashboard', () => {
- *   useOnConnected(() => {
- *     if (someCondition) navigateTo('/home')
- *   })
- * })
- * ```
- */
-
-export function navigateTo(path: string): void | Promise<void> {
-  const g = globalThis as Record<string, unknown>
-
-  // Server: redirect via the request-scoped req/res store.
-  const reqStore = g['__CER_REQ_STORE__'] as {
-    getStore(): { res: { statusCode: number; setHeader(k: string, v: string): void; end(): void; writableEnded?: boolean } } | null
-  } | undefined
-
-  if (reqStore) {
-    const store = reqStore.getStore()
-    if (store?.res && !store.res.writableEnded) {
-      store.res.statusCode = 302
-      store.res.setHeader('Location', path)
-      store.res.end()
-      return
-    }
-  }
-
-  // Client: use the framework router so the full navigation pipeline runs.
-  const router = g['__cerRouter'] as { push(path: string): Promise<void> } | undefined
-  if (router) return router.push(path)
-
-  // Fallback: hard redirect.
-  if (typeof window !== 'undefined') {
-    window.location.href = path
-  }
-}

package/src/runtime/composables/use-page-data.ts

@@ -1,93 +0,0 @@
-/**
- * usePageData — reads SSR-injected loader data for the current page.
- *
- * During SSR/SSG the server calls the matched route's `loader()` function
- * and makes the result available in two ways:
- *
- * 1. **Server render pass** — the data is stored in a per-request
- *    `AsyncLocalStorage` context (set via `_cerDataStore.run(data, ...)` in the
- *    entry-server template). `usePageData()` reads this store so the component
- *    renders with real data in the initial SSR/SSG HTML.
- *
- * 2. **Client hydration** — the server also serializes the data as
- *    `window.__CER_DATA__` in the page `<head>`. On first component render
- *    `usePageData()` returns that value, caches it on the component context, and
- *    returns the same cached value on all subsequent re-renders of that component
- *    instance. The data remains available for the initial hydrated route until
- *    the next client-side navigation clears it before loading new page data.
- *
- * **Why caching is necessary**: the render function passed to `component()` is
- * called on every re-render (it is the render function, not a setup function).
- * Without caching, `usePageData()` could return `null` on later re-renders if a
- * browser upgrades or re-renders the hydrated page after the initial read,
- * flip the `ssrData` guard from truthy → null, and re-trigger client-side fetches.
- *
- * @returns The serialized loader result, or `null` if no SSR data is present.
- *
- * @example
- * ```ts
- * component('page-blog-slug', () => {
- *   const ssrData = usePageData<{ title: string; body: string }>()
- *   const title = ref(ssrData?.title ?? '')
- *   const body  = ref(ssrData?.body  ?? '')
- *
- *   useOnConnected(() => {
- *     if (ssrData) return          // already hydrated from SSR — skip fetch
- *     fetch(`/api/posts/${props.slug}`).then(r => r.json()).then(post => {
- *       title.value = post.title
- *       body.value  = post.body
- *     })
- *   })
- * })
- * ```
- */
-import { getCurrentComponentContext } from '@jasonshimmy/custom-elements-runtime'
-
-// Key used to cache the page data on the component context object across re-renders.
-const _PAGE_DATA_KEY = '_cerPageData'
-
-export function usePageData<T = unknown>(): T | null {
-  const g = globalThis as Record<string, unknown>
-
-  // Server-side: read from the per-request AsyncLocalStorage context.
-  // __CER_DATA_STORE__ is set by the entry-server template and is only present
-  // in Node.js, so this branch is tree-shaken out of the client bundle.
-  const store = g['__CER_DATA_STORE__'] as { getStore(): unknown } | undefined
-  if (store) {
-    const ssrData = store.getStore() as T | null | undefined
-    if (ssrData !== undefined && ssrData !== null) return ssrData
-  }
-
-  // Client-side: check the component context cache first.
-  // getCurrentComponentContext() returns the context object for the component
-  // whose renderFn is currently executing (set by the component() runtime
-  // before calling renderFn). Caching on the context ensures the same value is
-  // returned on every re-render of the same element instance even if the
-  // browser performs a later hydration-time re-render.
-  const ctx = getCurrentComponentContext() as Record<string, unknown> | null
-  if (ctx) {
-    if (_PAGE_DATA_KEY in ctx) {
-      return ctx[_PAGE_DATA_KEY] as T | null
-    }
-  }
-
-  // Read the raw value from the global set by the server-rendered <script> tag.
-  const data = g['__CER_DATA__'] as T | undefined | null
-  const result: T | null = (data === undefined || data === null) ? null : data
-
-  // Cache on the component context so subsequent re-renders of this element
-  // instance return the same value without reading __CER_DATA__ again.
-  // Use Object.defineProperty to bypass the reactive Proxy set-trap on context,
-  // which would otherwise schedule a spurious re-render (and risk an infinite loop)
-  // every time we first cache the value.
-  if (ctx) {
-    Object.defineProperty(ctx, _PAGE_DATA_KEY, {
-      value: result,
-      writable: false,
-      enumerable: false,
-      configurable: true,
-    })
-  }
-
-  return result
-}

package/src/runtime/composables/use-route.ts

@@ -1,71 +0,0 @@
-/**
- * useRoute — returns the current route's path, params, query, and meta.
- *
- * Works isomorphically:
- * - **Server render pass** — reads from `globalThis.__CER_ROUTE_STORE__`
- *   (AsyncLocalStorage populated by the entry-server handler before rendering).
- * - **Client** — reads from the global router instance exposed by the app
- *   entry (`globalThis.__cerRouter`).
- *
- * @example
- * ```ts
- * // app/layouts/default.ts
- * component('layout-default', () => {
- *   const route = useRoute()
- *   return html`
- *     <nav>${route.meta?.title ?? 'My App'}</nav>
- *     <slot></slot>
- *   `
- * })
- * ```
- *
- * @example
- * ```ts
- * // app/pages/post.ts
- * component('page-post', () => {
- *   const { params } = useRoute()
- *   const { data: post } = useFetch(\`/api/posts/\${params.id}\`)
- * })
- * ```
- */
-
-export interface RouteInfo {
-  /** Current URL path, e.g. `'/posts/42'`. */
-  path: string
-  /** Dynamic route params, e.g. `{ id: '42' }`. */
-  params: Record<string, string>
-  /** Parsed query string params, e.g. `{ page: '2' }`. */
-  query: Record<string, string>
-  /** Static route meta object exported by the matched page module. */
-  meta: Record<string, unknown> | null
-}
-
-export function useRoute(): RouteInfo {
-  const g = globalThis as Record<string, unknown>
-
-  // Server: read from the per-request AsyncLocalStorage context.
-  const routeStore = g['__CER_ROUTE_STORE__'] as { getStore(): unknown } | undefined
-  if (routeStore) {
-    const info = routeStore.getStore() as RouteInfo | null
-    if (info) return info
-  }
-
-  // Client: read from the global router set by the app entry.
-  const router = g['__cerRouter'] as {
-    getCurrent(): { path: string; query?: Record<string, string> }
-    matchRoute(path: string): { route?: { meta?: unknown }; params?: Record<string, string> } | null
-  } | undefined
-
-  if (router) {
-    const current = router.getCurrent()
-    const matched = router.matchRoute(current.path)
-    return {
-      path: current.path,
-      params: (matched?.params ?? {}) as Record<string, string>,
-      query: (current.query ?? {}) as Record<string, string>,
-      meta: (matched?.route?.meta as Record<string, unknown>) ?? null,
-    }
-  }
-
-  return { path: '/', params: {}, query: {}, meta: null }
-}

package/src/runtime/composables/use-runtime-config.ts

@@ -1,123 +0,0 @@
-/** Resolved public runtime config values. Available on both server and client. */
-export interface RuntimeConfigPublic {
-  [key: string]: unknown
-}
-
-/** Resolved private runtime config values. Available on the server only — never present on the client. */
-export interface RuntimeConfigPrivate {
-  [key: string]: string | string[]
-}
-
-/** Return value of `useRuntimeConfig()`. */
-export interface RuntimeConfigResult {
-  public: RuntimeConfigPublic
-  private?: RuntimeConfigPrivate
-}
-
-/**
- * Returns the runtime configuration set in `cer.config.ts`.
- *
- * - `public` — available on both server and client.
- * - `private` — available on the server only (resolved from `process.env` at
- *   startup). Never present on the client.
- *
- * @example
- * // cer.config.ts
- * export default defineConfig({
- *   runtimeConfig: {
- *     public: { apiBase: process.env.VITE_API_BASE ?? '/api' },
- *     private: { dbUrl: '', secretKey: '' },
- *   },
- * })
- *
- * // app/pages/index.ts (loader — server-only)
- * const { private: priv } = useRuntimeConfig()
- * const rows = await db.query(priv.dbUrl)
- */
-export function useRuntimeConfig(): RuntimeConfigResult {
-  // Dynamic import resolved at runtime — avoids a static circular dependency
-  // between the composable and the virtual module.
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  const mod = (globalThis as any).__cerRuntimeConfig
-  const config: RuntimeConfigResult = mod ? (mod as RuntimeConfigResult) : { public: {} }
-
-  // In browser contexts, wrap the result in a Proxy that throws a clear,
-  // actionable error if any code attempts to read `runtimeConfig.private`.
-  // Private values are server-only secrets and are never serialized into the
-  // client bundle — accessing them client-side is always a bug.
-  if (typeof window !== 'undefined') {
-    return new Proxy(config, {
-      get(target, prop) {
-        if (prop === 'private') {
-          throw new Error(
-            '[cer-app] runtimeConfig.private is not available in the browser. ' +
-            'Move this access into a server-only loader, middleware, or API handler.',
-          )
-        }
-        return Reflect.get(target, prop)
-      },
-    })
-  }
-
-  return config
-}
-
-/**
- * Called once during app bootstrap to store the resolved runtimeConfig on
- * globalThis so useRuntimeConfig() can access it synchronously in any context
- * (component render, composable, server handler).
- */
-export function initRuntimeConfig(config: RuntimeConfigResult): void {
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  ;(globalThis as any).__cerRuntimeConfig = config
-}
-
-/**
- * Converts a camelCase or mixed key to UPPER_SNAKE_CASE for env var lookup.
- * Examples: `dbUrl` → `DB_URL`, `secretKey` → `SECRET_KEY`, `API_KEY` → `API_KEY`.
- */
-function toUpperSnakeCase(key: string): string {
-  return key
-    .replace(/([a-z])([A-Z])/g, '$1_$2')
-    .toUpperCase()
-}
-
-/**
- * Resolves a private config object by looking up each key in the supplied
- * environment variable map, with the following precedence:
- *
- * 1. `env[key]`                   — exact case (e.g. `process.env.dbUrl`)
- * 2. `env[UPPER_SNAKE_CASE(key)]` — conventional env var form (e.g. `process.env.DB_URL`)
- * 3. `defaultValue`               — the declared default from `cer.config.ts`
- *
- * Array values (e.g. `sessionSecret: [newSecret, oldSecret]`) are passed
- * through unchanged — they are already resolved by the caller at config time.
- *
- * Accepts an optional `env` parameter so the function is unit-testable
- * without mutating `process.env`.
- */
-export function resolvePrivateConfig(
-  defaults: Record<string, string | string[]>,
-  env: Record<string, string | undefined> = process.env as Record<string, string | undefined>,
-): Record<string, string | string[]> {
-  return Object.fromEntries(
-    Object.entries(defaults).map(([key, defaultValue]) => {
-      // Array values are already fully resolved at config build time — pass through.
-      if (Array.isArray(defaultValue)) {
-        return [key, defaultValue.filter(Boolean)]
-      }
-      const envKey = toUpperSnakeCase(key)
-      const resolved = env[key] ?? env[envKey] ?? defaultValue
-      // Warn when no env var was found and the declared default is an empty string.
-      // An empty-string default is the conventional way to declare a required secret
-      // (the key exists for typing purposes but has no safe default value).
-      if (resolved === '' && env[key] === undefined && env[envKey] === undefined) {
-        console.warn(
-          `[cer-app] runtimeConfig.private: "${key}" is an empty string — ` +
-          `set ${envKey} in the environment to provide a value.`,
-        )
-      }
-      return [key, resolved]
-    }),
-  )
-}

package/src/runtime/composables/use-seo-meta.ts

@@ -1,80 +0,0 @@
-import { useHead } from './use-head.js'
-
-/**
- * Convenience input for common SEO meta tags.
- * Pass to `useSeoMeta()` — it maps each field to the correct `<meta>` or `<title>` tag automatically.
- * All fields are optional.
- */
-export interface SeoMetaInput {
-  /** Sets the document title. */
-  title?: string
-  /** Sets the meta description. */
-  description?: string
-  // Open Graph
-  ogTitle?: string
-  ogDescription?: string
-  ogImage?: string
-  ogUrl?: string
-  /** e.g. `'website'`, `'article'`. No tag is emitted when omitted. */
-  ogType?: string
-  ogSiteName?: string
-  // Twitter / X
-  /** e.g. `'summary'`, `'summary_large_image'`. No tag is emitted when omitted. */
-  twitterCard?: string
-  twitterTitle?: string
-  twitterDescription?: string
-  twitterImage?: string
-  /** Twitter/X site handle, e.g. '@mysite'. */
-  twitterSite?: string
-  /** Canonical URL injected as <link rel="canonical">. */
-  canonical?: string
-}
-
-/**
- * Thin wrapper over `useHead()` for common SEO tags.
- *
- * Sets the page title, meta description, Open Graph tags, Twitter Card tags,
- * and a canonical link element. Only tags with a non-undefined value are emitted.
- *
- * It is auto-imported, so you don't need to import it manually.
- *
- * @example
- * ```ts
- * useSeoMeta({
- *   title: 'My page',
- *   description: 'A great page.',
- *   ogImage: 'https://example.com/og.png',
- *   canonical: 'https://example.com/my-page',
- * })
- * ```
- */
-export function useSeoMeta(input: SeoMetaInput): void {
-  const meta: Array<Record<string, string>> = []
-  const link: Array<Record<string, string>> = []
-
-  if (input.description !== undefined) meta.push({ name: 'description', content: input.description })
-
-  // Open Graph
-  if (input.ogTitle !== undefined) meta.push({ property: 'og:title', content: input.ogTitle })
-  if (input.ogDescription !== undefined) meta.push({ property: 'og:description', content: input.ogDescription })
-  if (input.ogImage !== undefined) meta.push({ property: 'og:image', content: input.ogImage })
-  if (input.ogUrl !== undefined) meta.push({ property: 'og:url', content: input.ogUrl })
-  if (input.ogType !== undefined) meta.push({ property: 'og:type', content: input.ogType })
-  if (input.ogSiteName !== undefined) meta.push({ property: 'og:site_name', content: input.ogSiteName })
-
-  // Twitter / X
-  if (input.twitterCard !== undefined) meta.push({ name: 'twitter:card', content: input.twitterCard })
-  if (input.twitterTitle !== undefined) meta.push({ name: 'twitter:title', content: input.twitterTitle })
-  if (input.twitterDescription !== undefined) meta.push({ name: 'twitter:description', content: input.twitterDescription })
-  if (input.twitterImage !== undefined) meta.push({ name: 'twitter:image', content: input.twitterImage })
-  if (input.twitterSite !== undefined) meta.push({ name: 'twitter:site', content: input.twitterSite })
-
-  // Canonical link
-  if (input.canonical !== undefined) link.push({ rel: 'canonical', href: input.canonical })
-
-  useHead({
-    title: input.title,
-    meta: meta.length > 0 ? meta : undefined,
-    link: link.length > 0 ? link : undefined,
-  })
-}