@jasonshimmy/vite-plugin-cer-app 0.19.3 → 0.20.1

package/dist/types/content.d.ts

@@ -0,0 +1,63 @@
+/** 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;
+}
+//# sourceMappingURL=content.d.ts.map

package/dist/types/content.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"content.d.ts","sourceRoot":"","sources":["../../src/types/content.ts"],"names":[],"mappings":"AAAA,uIAAuI;AACvI,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAA;IAC5B,qFAAqF;IACrF,EAAE,EAAE,MAAM,CAAA;IACV,iCAAiC;IACjC,IAAI,EAAE,MAAM,CAAA;CACb;AAED;;;;GAIG;AACH,MAAM,WAAW,WAAW;IAC1B,uCAAuC;IACvC,KAAK,EAAE,MAAM,CAAA;IACb,wBAAwB;IACxB,KAAK,EAAE,UAAU,GAAG,MAAM,CAAA;IAC1B,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,2DAA2D;IAC3D,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,KAAK,CAAC,EAAE,OAAO,CAAA;IACf,iCAAiC;IACjC,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAA;CACvB;AAED;;;GAGG;AACH,MAAM,WAAW,WAAY,SAAQ,WAAW;IAC9C,kFAAkF;IAClF,KAAK,EAAE,MAAM,CAAA;IACb,sEAAsE;IACtE,IAAI,EAAE,MAAM,CAAA;IACZ,sDAAsD;IACtD,GAAG,EAAE,cAAc,EAAE,CAAA;IACrB,kFAAkF;IAClF,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB;AAED;;;GAGG;AACH,MAAM,WAAW,mBAAmB;IAClC,KAAK,EAAE,MAAM,CAAA;IACb,KAAK,EAAE,MAAM,CAAA;IACb,WAAW,CAAC,EAAE,MAAM,CAAA;CACrB;AAED,+EAA+E;AAC/E,MAAM,WAAW,gBAAgB;IAC/B;;;OAGG;IACH,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ;;;OAGG;IACH,MAAM,CAAC,EAAE,OAAO,CAAA;CACjB"}

package/dist/types/content.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=content.js.map

package/dist/types/content.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"content.js","sourceRoot":"","sources":["../../src/types/content.ts"],"names":[],"mappings":""}

package/docs/composables.md

@@ -145,9 +145,9 @@ component('page-posts', () => {
   const { data: posts, pending, error } = useFetch<Post[]>('/api/posts')
 
   return html`
-    ${pending.value ? html`<p>Loading…</p>` : ''}
-    ${error.value ? html`<p>Error: ${error.value.message}</p>` : ''}
-    <ul>${posts.value?.map(p => html`<li>${p.title}</li>`)}</ul>
+    ${when(pending.value, () => html`<p>Loading…</p>`)}
+    ${when(!!error.value, () => html`<p>Error: ${error.value!.message}</p>`)}
+    <ul>${each(posts.value ?? [], p => html`<li>${p.title}</li>`)}</ul>
   `
 })
 ```
@@ -165,10 +165,10 @@ component('page-nav', () => {
   const { user, loggedIn, login, logout } = useAuth()
 
   return html`
-    ${loggedIn
-      ? html`<span>${user?.name}</span><button @click="${logout}">Log out</button>`
-      : html`<button @click="${() => login('github')}">Log in</button>`
-    }
+    ${match()
+      .when(loggedIn, () => html`<span>${user?.name}</span><button @click="${logout}">Log out</button>`)
+      .otherwise(() => html`<button @click="${() => login('github')}">Log in</button>`)
+      .done()}
   `
 })
 ```
@@ -736,10 +736,10 @@ component('locale-switcher', () => {
 
   return html`
     <nav>
-      ${locales.map((l) => html`
+      ${each(locales, (l) => html`
         <a
-          href="${switchLocalePath(l)}"
-          aria-current="${l === locale ? 'true' : 'false'}"
+          :href="${switchLocalePath(l)}"
+          :aria-current="${l === locale ? 'true' : 'false'}"
         >${l.toUpperCase()}</a>
       `)}
     </nav>
@@ -798,3 +798,108 @@ If you need it outside auto-imported directories:
 ```ts
 import { navigateTo } from '@jasonshimmy/vite-plugin-cer-app/composables'
 ```
+
+---
+
+### `queryContent(path?)`
+
+Queries content items from the file-based content layer. Returns a `QueryBuilder` that can be filtered, sorted, paginated, and terminated with `.find()`, `.first()`, or `.count()`.
+
+Requires `content: {}` in `cer.config.ts`. See [content.md](./content.md) for full configuration, type reference, and rendering-mode behavior.
+
+```ts
+// All items
+const all = await queryContent().find()
+
+// Blog posts only (path prefix)
+const posts = await queryContent('/blog').sortBy('date', 'desc').find()
+
+// Single full document (includes body + TOC)
+const doc = await queryContent('/docs/getting-started').first()
+
+// Count
+const total = await queryContent().count()
+```
+
+**QueryBuilder methods:**
+
+| Method | Returns | Description |
+|---|---|---|
+| `.where(predicate)` | `QueryBuilder` | Predicate function — `(doc: ContentMeta) => boolean`. |
+| `.sortBy(field, order?)` | `QueryBuilder` | Sort ascending (`'asc'`) or descending (`'desc'`). |
+| `.limit(n)` | `QueryBuilder` | Return at most `n` items. |
+| `.skip(n)` | `QueryBuilder` | Skip the first `n` items (pagination). |
+| `.find()` | `Promise<ContentMeta[]>` | Execute, return lean metadata array. |
+| `.first()` | `Promise<ContentItem \| null>` | Execute, return first full document with body and TOC. |
+| `.count()` | `Promise<number>` | Execute, return count only. |
+
+**Usage with a page loader:**
+
+```ts
+component('page-blog', () => {
+  const ssrData = usePageData<{ posts: ContentMeta[] }>()
+  const posts = ref<ContentMeta[]>(ssrData?.posts ?? [])
+
+  useOnConnected(async () => {
+    if (ssrData) return // hydrated from loader
+    posts.value = await queryContent('/blog').find()
+  })
+
+  return html`
+    <ul>
+      ${each(posts.value, p => html`<li><a :href="${p._path}">${p.title}</a></li>`)}
+    </ul>
+  `
+})
+
+export const loader = async () => {
+  const posts = await queryContent('/blog').find()
+  return { posts }
+}
+```
+
+If you need it outside auto-imported directories:
+
+```ts
+import { queryContent } from '@jasonshimmy/vite-plugin-cer-app/composables'
+```
+
+---
+
+### `useContentSearch()`
+
+Reactive full-text search over the content layer. Loads the MiniSearch index lazily on first use. Returns `query` and `results` refs that update reactively as the user types.
+
+Requires `content: {}` in `cer.config.ts`. See [content.md](./content.md) for full documentation.
+
+```ts
+component('page-search', () => {
+  const { query, results } = useContentSearch()
+
+  return html`
+    <input type="search" :model="${query}" placeholder="Search…" />
+    <ul>
+      ${each(results.value, r => html`
+        <li><a :href="${r._path}">${r.title}</a></li>
+      `)}
+    </ul>
+  `
+})
+```
+
+**Return value:**
+
+```ts
+interface UseContentSearchReturn {
+  query: Ref<string>                   // bind with :model
+  results: Ref<ContentSearchResult[]>  // reactive search results
+}
+```
+
+Search activates when `query.value.length >= 2`. MiniSearch is loaded once and cached for the lifetime of the page. Searched fields are `title` and `description`.
+
+If you need it outside auto-imported directories:
+
+```ts
+import { useContentSearch } from '@jasonshimmy/vite-plugin-cer-app/composables'
+```

package/docs/configuration.md

@@ -220,6 +220,8 @@ import {
   useCookie,
   useSession,
   useLocale,
+  queryContent,
+  useContentSearch,
   defineMiddleware,
   defineServerMiddleware,
   navigateTo,
@@ -284,6 +286,37 @@ See [cli.md](./cli.md#cer-app-adapt) for full details.
 
 ---
 
+## `content` options
+
+Enables the file-based content layer. Drop Markdown or JSON files into `content/` at the project root and query them with `queryContent()` or search with `useContentSearch()`.
+
+```ts
+export default defineConfig({
+  content: {
+    dir: 'content',  // default
+    drafts: false,   // default
+  },
+})
+```
+
+### `content.dir`
+
+**Type:** `string`
+**Default:** `'content'`
+
+Content directory relative to the project root. The default resolves to `{root}/content/`.
+
+### `content.drafts`
+
+**Type:** `boolean`
+**Default:** `false`
+
+When `false`, files with `draft: true` in their frontmatter are excluded from the content store and search index in production builds.
+
+See [content.md](./content.md) for full documentation.
+
+---
+
 ## `i18n` options
 
 Enables locale-aware URL routing and the `useLocale()` composable. No external package is required.