@jasonshimmy/vite-plugin-cer-app 0.19.2 → 0.20.0

package/src/runtime/composables/use-content-search.ts

@@ -0,0 +1,121 @@
+import {
+  createComposable,
+  ref,
+  useOnConnected,
+  watch,
+} from '@jasonshimmy/custom-elements-runtime'
+import type { ReactiveState } from '@jasonshimmy/custom-elements-runtime'
+import type { ContentSearchResult } from '../../types/content.js'
+import { contentSearchIndexUrl } from '../content/client.js'
+
+// ─── Module-level singleton ───────────────────────────────────────────────────
+
+// The MiniSearch instance is built lazily on first search from the manifest.
+// The same promise is reused across all mounted instances so we only build once.
+let _indexPromise: Promise<unknown> | null = null
+
+/**
+ * Lazily loads the MiniSearch index from `/_content/search-index.json`.
+ * Returns the same Promise on repeated calls — the index is built at most once
+ * per session regardless of how many search components are mounted.
+ *
+ * @internal Exported for unit testing only.
+ */
+export async function loadIndex(): Promise<unknown> {
+  if (_indexPromise) return _indexPromise
+  _indexPromise = (async () => {
+    const [{ default: MiniSearch }, raw] = await Promise.all([
+      import('minisearch'),
+      fetch(contentSearchIndexUrl()).then((r) => {
+        if (!r.ok) throw new Error(`Failed to fetch search index: ${r.status}`)
+        return r.text()
+      }),
+    ])
+    return MiniSearch.loadJSON(raw, {
+      fields: ['title', 'description'],
+      storeFields: ['_path', 'title', 'description'],
+      idField: '_path',
+    })
+  })()
+  return _indexPromise
+}
+
+/** Resets the module-level singleton. Used in tests only. @internal */
+export function resetIndexSingleton(): void {
+  _indexPromise = null
+}
+
+// ─── Composable ───────────────────────────────────────────────────────────────
+
+export interface UseContentSearchReturn {
+  query: ReactiveState<string>
+  results: ReactiveState<ContentSearchResult[]>
+}
+
+const _factory = createComposable((): UseContentSearchReturn => {
+  const query = ref('')
+  const results = ref<ContentSearchResult[]>([])
+
+  // Pre-warm index on mount
+  useOnConnected(() => {
+    loadIndex().catch(() => {/* silently ignore pre-warm errors */})
+  })
+
+  // Monotonic counter to discard stale async results
+  let _seq = 0
+
+  watch(query, async (q: string) => {
+    const seq = ++_seq
+
+    if (!q || q.length < 2) {
+      results.value = []
+      return
+    }
+
+    try {
+      const index = await loadIndex() as { search(q: string, opts?: { prefix?: boolean }): ContentSearchResult[] }
+      if (seq !== _seq) return // stale — a newer query is in flight
+      results.value = index.search(q, { prefix: true }) as ContentSearchResult[]
+    } catch {
+      if (seq !== _seq) return
+      results.value = []
+    }
+  })
+
+  return { query, results }
+})
+
+/**
+ * Full-text content search composable.
+ *
+ * Loads a pre-built MiniSearch index lazily on first use by fetching
+ * `/_content/search-index.json`. Both MiniSearch and the index are loaded via
+ * dynamic import — neither is in the app bundle.
+ *
+ * Searches `title` and `description` fields. Results are empty until at least
+ * 2 characters are entered.
+ *
+ * **SSR note**: search is always client-side. In SSR mode the component renders
+ * with empty results and hydrates on mount.
+ *
+ * @example
+ * ```ts
+ * component('site-search', () => {
+ *   const { query, results } = useContentSearch()
+ *
+ *   return html`
+ *     <input type="search" :model="${query}" placeholder="Search…" />
+ *     ${when(results.value.length > 0, () => html`
+ *       <ul>
+ *         ${each(results.value, r => html`
+ *           <li><a :href="${r._path}">${r.title}</a></li>
+ *         `)}
+ *       </ul>
+ *     `)}
+ *   `
+ * })
+ * ```
+ */
+export function useContentSearch(): UseContentSearchReturn {
+  return _factory()
+}

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

@@ -0,0 +1,146 @@
+import type { ContentItem, ContentMeta } from '../../types/content.js'
+import { ContentClient } from '../content/client.js'
+
+// ─── QueryBuilder ─────────────────────────────────────────────────────────────
+
+export class QueryBuilder {
+  private _prefix: string | undefined
+  private _predicates: Array<(doc: ContentMeta) => boolean> = []
+  private _sortField: string | undefined
+  private _sortDir: 'asc' | 'desc' = 'asc'
+  private _limit: number | undefined
+  private _skip: number | undefined
+
+  constructor(prefix?: string) {
+    this._prefix = prefix
+  }
+
+  /** Filter results by a predicate. Receives a fully-typed `ContentMeta`. */
+  where(predicate: (doc: ContentMeta) => boolean): this {
+    this._predicates.push(predicate)
+    return this
+  }
+
+  /** Sort by a frontmatter field. Defaults to ascending order. */
+  sortBy(field: string, dir: 'asc' | 'desc' = 'asc'): this {
+    this._sortField = field
+    this._sortDir = dir
+    return this
+  }
+
+  /** Cap the result count. */
+  limit(n: number): this {
+    this._limit = n
+    return this
+  }
+
+  /** Skip the first `n` results (for pagination). */
+  skip(n: number): this {
+    this._skip = n
+    return this
+  }
+
+  /** Returns all matching `ContentMeta` items (no body loaded). */
+  async find(): Promise<ContentMeta[]> {
+    const manifest = await ContentClient.getManifest()
+    return this._applyFilters(manifest)
+  }
+
+  /** Returns the count of matching documents (no body loaded). */
+  async count(): Promise<number> {
+    const manifest = await ContentClient.getManifest()
+    return this._applyFilters(manifest).length
+  }
+
+  /**
+   * Returns the full `ContentItem` (body + toc) for the first matching document.
+   * When a `_path` prefix is provided and no predicates/sort/pagination are set,
+   * this fetches the single document directly by path.
+   */
+  async first(): Promise<ContentItem | null> {
+    // Fast path: no filters, no sort, no pagination — fetch directly by path
+    if (
+      this._prefix !== undefined &&
+      this._predicates.length === 0 &&
+      this._sortField === undefined &&
+      this._limit === undefined &&
+      this._skip === undefined
+    ) {
+      return ContentClient.getItem(this._prefix)
+    }
+
+    // Slow path: apply filters on the manifest, then fetch the first match
+    const manifest = await ContentClient.getManifest()
+    const filtered = this._applyFilters(manifest)
+    if (filtered.length === 0) return null
+    return ContentClient.getItem(filtered[0]._path)
+  }
+
+  private _applyFilters(items: ContentMeta[]): ContentMeta[] {
+    let result = items
+
+    // Prefix filter
+    if (this._prefix !== undefined) {
+      const p = this._prefix
+      result = result.filter(
+        (doc) => doc._path === p || doc._path.startsWith(p + '/'),
+      )
+    }
+
+    // Where predicates
+    for (const pred of this._predicates) {
+      result = result.filter(pred)
+    }
+
+    // Sort
+    if (this._sortField !== undefined) {
+      const field = this._sortField
+      const dir = this._sortDir
+      result = [...result].sort((a, b) => {
+        const av = a[field] as string | number | undefined
+        const bv = b[field] as string | number | undefined
+        if (av === undefined && bv === undefined) return 0
+        if (av === undefined) return 1
+        if (bv === undefined) return -1
+        const cmp = av < bv ? -1 : av > bv ? 1 : 0
+        return dir === 'asc' ? cmp : -cmp
+      })
+    }
+
+    // Skip
+    if (this._skip !== undefined) {
+      result = result.slice(this._skip)
+    }
+
+    // Limit
+    if (this._limit !== undefined) {
+      result = result.slice(0, this._limit)
+    }
+
+    return result
+  }
+}
+
+/**
+ * Content query composable.
+ *
+ * Returns a `QueryBuilder` scoped to the given `_path` prefix. Chain filter,
+ * sort, and pagination methods before calling a terminal method
+ * (`.find()`, `.first()`, or `.count()`).
+ *
+ * @example
+ * ```ts
+ * // Single document
+ * const doc = await queryContent('/blog/hello').first()
+ *
+ * // Listing — no body loaded
+ * const posts = await queryContent('/blog')
+ *   .where(doc => !doc.draft)
+ *   .sortBy('date', 'desc')
+ *   .limit(10)
+ *   .find()
+ * ```
+ */
+export function queryContent(path?: string): QueryBuilder {
+  return new QueryBuilder(path)
+}

package/src/runtime/content/client.ts

@@ -0,0 +1,168 @@
+import type { ContentItem, ContentMeta } from '../../types/content.js'
+
+// ─── Types ─────────────────────────────────────────────────────────────────────
+
+/** Reads `router.base` from `virtual:cer-app-config` at module initialisation. */
+let _base: string = ''
+
+try {
+  // Dynamic import is not viable for a module-level side effect, so we read from
+  // globalThis where the virtual module writes it during app bootstrap.
+  const g = globalThis as Record<string, unknown>
+  const appConfig = g['__CER_APP_CONFIG__'] as { router?: { base?: string } } | undefined
+  _base = appConfig?.router?.base ?? ''
+  // Normalise: strip trailing slash, keep empty string for no base
+  if (_base === '/') _base = ''
+} catch {
+  _base = ''
+}
+
+// ─── Path helpers ─────────────────────────────────────────────────────────────
+
+function contentPathToJsonFile(path: string): string {
+  if (path === '/') return 'index.json'
+  return path.slice(1) + '.json'
+}
+
+/** Returns the full URL for the search index (includes router.base prefix). */
+export function contentSearchIndexUrl(): string {
+  return `${_base}/_content/search-index.json`
+}
+
+// ─── Lazy manifest cache ──────────────────────────────────────────────────────
+
+let _manifestPromise: Promise<ContentMeta[]> | null = null
+
+function fetchManifest(): Promise<ContentMeta[]> {
+  if (_manifestPromise) return _manifestPromise
+  _manifestPromise = fetch(`${_base}/_content/manifest.json`).then((r) => {
+    if (!r.ok) throw new Error(`Failed to fetch content manifest: ${r.status}`)
+    return r.json() as Promise<ContentMeta[]>
+  })
+  return _manifestPromise
+}
+
+// ─── Server-side production caches ───────────────────────────────────────────
+// In production SSR the Vite build process is not running, so __CER_CONTENT_STORE__
+// is absent.  We cache the manifest and per-document reads here to avoid repeated
+// disk I/O on every request — critical at 10k+ pages where manifest.json is ~2MB.
+
+let _ssrManifest: ContentMeta[] | null = null
+const _ssrItemCache = new Map<string, ContentItem | null>()
+
+// ─── ContentClient ────────────────────────────────────────────────────────────
+
+/**
+ * Low-level content data access layer. Used by `queryContent()`.
+ *
+ * Resolution strategy:
+ * - **Server (dev + SSG build-time)**: reads from `globalThis.__CER_CONTENT_STORE__`
+ *   populated by the `cerContent()` Vite plugin's `buildStart` hook.
+ * - **Server (production SSR runtime)**: `__CER_CONTENT_STORE__` is absent (no
+ *   Vite build process at runtime), so falls back to `node:fs` reads from
+ *   `dist/_content/`.
+ * - **Client (SPA / browser navigation)**: lazy-fetches `/_content/manifest.json`
+ *   once (cached) for listing; fetches `/_content/[path].json` per `.first()`.
+ */
+export const ContentClient = {
+  async getManifest(): Promise<ContentMeta[]> {
+    const g = globalThis as Record<string, unknown>
+
+    // Server: in-memory store (dev + SSG build-time rendering)
+    const store = g['__CER_CONTENT_STORE__'] as ContentItem[] | undefined
+    if (store) {
+      return store.map((item) => {
+        // eslint-disable-next-line @typescript-eslint/no-unused-vars
+        const { _file, body, toc, excerpt, ...meta } = item
+        return meta as ContentMeta
+      })
+    }
+
+    // Server: production SSR runtime — resolve content files from the app root.
+    // The preview CLI sets process.env.__CER_APP_ROOT__ to the project root before
+    // loading the server bundle. Content files are written to dist/server/_content/
+    // and dist/client/_content/ by cerContent's closeBundle hook.
+    // _ssrManifest is a module-level cache — populated once and reused for the
+    // lifetime of the process so manifest.json is only read and parsed once at scale.
+    if (typeof window === 'undefined' && typeof process !== 'undefined') {
+      if (_ssrManifest) return _ssrManifest
+      try {
+        const { readFileSync, existsSync } = await import('node:fs')
+        const { join } = await import('node:path')
+        const appRoot = process.env.__CER_APP_ROOT__ ?? process.cwd()
+        const candidates = [
+          join(appRoot, 'dist', 'server', '_content', 'manifest.json'),
+          join(appRoot, 'dist', 'client', '_content', 'manifest.json'),
+          join(appRoot, 'dist', '_content', 'manifest.json'),
+        ]
+        for (const p of candidates) {
+          if (!existsSync(p)) continue
+          try {
+            const raw = readFileSync(p, 'utf-8')
+            _ssrManifest = JSON.parse(raw) as ContentMeta[]
+            return _ssrManifest
+          } catch { /* try next */ }
+        }
+        _ssrManifest = []
+        return _ssrManifest
+      } catch {
+        return []
+      }
+    }
+
+    // Client: fetch manifest (cached)
+    return fetchManifest()
+  },
+
+  async getItem(path: string): Promise<ContentItem | null> {
+    const g = globalThis as Record<string, unknown>
+
+    // Server: in-memory store
+    const store = g['__CER_CONTENT_STORE__'] as ContentItem[] | undefined
+    if (store) {
+      return store.find((item) => item._path === path) ?? null
+    }
+
+    // Server: production SSR runtime — see getManifest() for path resolution strategy.
+    // _ssrItemCache is a module-level Map so each document is read and parsed at
+    // most once per process lifetime, regardless of how many concurrent requests
+    // ask for the same path.
+    if (typeof window === 'undefined' && typeof process !== 'undefined') {
+      if (_ssrItemCache.has(path)) return _ssrItemCache.get(path) ?? null
+      try {
+        const { readFileSync, existsSync } = await import('node:fs')
+        const { join } = await import('node:path')
+        const appRoot = process.env.__CER_APP_ROOT__ ?? process.cwd()
+        const jsonFile = contentPathToJsonFile(path)
+        const candidates = [
+          join(appRoot, 'dist', 'server', '_content', jsonFile),
+          join(appRoot, 'dist', 'client', '_content', jsonFile),
+          join(appRoot, 'dist', '_content', jsonFile),
+        ]
+        for (const p of candidates) {
+          if (!existsSync(p)) continue
+          try {
+            const raw = readFileSync(p, 'utf-8')
+            const item = JSON.parse(raw) as ContentItem
+            _ssrItemCache.set(path, item)
+            return item
+          } catch { /* try next */ }
+        }
+        _ssrItemCache.set(path, null)
+        return null
+      } catch {
+        return null
+      }
+    }
+
+    // Client: fetch individual document
+    const jsonFile = contentPathToJsonFile(path)
+    try {
+      const res = await fetch(`${_base}/_content/${jsonFile}`)
+      if (!res.ok) return null
+      return (await res.json()) as ContentItem
+    } catch {
+      return null
+    }
+  },
+}

package/src/types/config.ts

@@ -222,6 +222,8 @@ export interface RuntimeConfig {
 export interface CerAppConfig {
   mode?: 'spa' | 'ssr' | 'ssg'
   srcDir?: string // defaults to 'app'
+  /** File-based content layer configuration. Reads from `content/` at the project root by default. */
+  content?: import('./content.js').CerContentConfig
   /**
    * Internationalisation (i18n) routing configuration.
    * When set, the framework generates locale-aware URL routes and enables `useLocale()`.

package/src/types/content.ts

@@ -0,0 +1,66 @@
+/** Heading extracted from Markdown during parsing. The `id` is slugified from the heading text and added as an HTML `id` attribute. */
+export interface ContentHeading {
+  depth: 1 | 2 | 3 | 4 | 5 | 6
+  /** Slugified heading text — matches the `id` attribute in the rendered body HTML. */
+  id: string
+  /** Plain text of the heading. */
+  text: string
+}
+
+/**
+ * Lean per-document metadata — returned by `.find()` and `.count()`.
+ * Kept small deliberately: no `body`, no `toc`, no `excerpt`.
+ * Use `description` for listing previews; set it in frontmatter.
+ */
+export interface ContentMeta {
+  /** URL path (e.g. `"/blog/hello"`). */
+  _path: string
+  /** Source file type. */
+  _type: 'markdown' | 'json'
+  title?: string
+  /** Use for listing previews — included in search index. */
+  description?: string
+  date?: string
+  draft?: boolean
+  /** Any other frontmatter key. */
+  [key: string]: unknown
+}
+
+/**
+ * Full document — returned by `.first()`.
+ * Superset of `ContentMeta`; includes `body`, `toc`, `_file`, and optional `excerpt`.
+ */
+export interface ContentItem extends ContentMeta {
+  /** Relative path from `content/` at the project root (e.g. `"blog/hello.md"`). */
+  _file: string
+  /** Rendered HTML (Markdown) or the raw file contents (JSON files). */
+  body: string
+  /** Extracted headings. Empty array for JSON files. */
+  toc: ContentHeading[]
+  /** HTML content before `<!-- more -->`. Absent when the marker is not present. */
+  excerpt?: string
+}
+
+/**
+ * Search result item returned by `useContentSearch()`.
+ * Contains only the MiniSearch stored fields: `_path`, `title`, `description`.
+ */
+export interface ContentSearchResult {
+  _path: string
+  title: string
+  description?: string
+}
+
+/** Content layer configuration. Controls the directory and draft behaviour. */
+export interface CerContentConfig {
+  /**
+   * Content directory relative to the project root. Defaults to `'content'`,
+   * which resolves to `{root}/content/` — at the same level as `app/`, `server/`, and `public/`.
+   */
+  dir?: string
+  /**
+   * When `true`, draft items (`draft: true` in frontmatter) are included in
+   * production builds. Defaults to `false`.
+   */
+  drafts?: boolean
+}