diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index a262a0c..553c23b 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -96,3 +96,22 @@ jobs: # automatically — no long-lived NPM_TOKEN secret required. # Trusted publisher configured at: # https://www.npmjs.com/package/@kamansoft/vite-plugin-flatwave-react/access + + # ─── 3. Sync workspace version ────────────────────────────────────────────── + # semantic-release only bumps the plugin package.json (pkgRoot). + # This step syncs the version to the root workspace package.json for consistency. + - name: Sync workspace version + if: success() + run: | + PLUGIN_VERSION=$(cat packages/vite-plugin-flatwave-react/package.json | grep '"version"' | head -1 | sed 's/.*"version": "\(.*\)".*/\1/') + echo "Plugin version: $PLUGIN_VERSION" + # Update root package.json + npm pkg set version=$PLUGIN_VERSION --workspaces=false + # Commit and push the version sync (chore commit won't trigger new release) + git config user.name "github-actions[bot]" + git config user.email "github-actions[bot]@users.noreply.github.com" + git add package.json + git commit -m "chore: sync workspace version to $PLUGIN_VERSION" || echo "No changes to commit" + git push origin HEAD:main + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} diff --git a/CHANGELOG.md b/CHANGELOG.md index ffae954..b26a4ca 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,39 @@ # Changelog +## 2.0.1 (2026-06-20) + +### Documentation + +- **documentation:** update documentation badges ([#14](https://github.com/kamansoft/vite-plugin-flatwave-react/pull/14)) +- **docs:** add architecture, development, contributing documentation and refactor readme ([#13](https://github.com/kamansoft/vite-plugin-flatwave-react/pull/13)) + +## 2.0.0 (2026-06-20) + +### ⚠ BREAKING CHANGES + +- **rendering!:** rewrite SSG pipeline with fully-rendered HTML output ([#12](https://github.com/kamansoft/vite-plugin-flatwave-react/pull/12)) + +### Features + +- **rendering:** new SSG pipeline with RenderStrategy interface, DefaultRenderStrategy, RenderPipeline, and hook phases (beforeRender, transformMarkdown, transformHtml, afterRender, onError) +- **rendering:** template system with built-in index.html.ejs and filesystem override convention +- **rendering:** markdown compiler extracted to reusable compileMarkdownToHtml function +- **ci-cd:** document enforce_admins lock and stale-tag cleanup procedure + +## 1.1.0 (2026-06-19) + +### Features + +- **release:** scope package to @kamansoft org and fix CI/CD pipeline +- **ci:** switch to npm OIDC trusted publishing and enforce conventional commit pipeline + +### Bug Fixes + +- **publish:** force npm token auth for semantic-release +- **release:** enable npm trusted publishing in release workflow +- **release-workflow:** fix failure caused by registry resolution during semantic-release prepare +- **npm-publish:** resolve publishing pipeline conflicts and CI issues + ## 1.0.0 (2026-06-17) ### ⚠ BREAKING CHANGES diff --git a/README.md b/README.md index 422dcb8..6cd3e9c 100644 --- a/README.md +++ b/README.md @@ -10,7 +10,7 @@ A Vite plugin that turns a directory of Markdown files into a **fully typed, i18 At build time the plugin: - Scans `src/content/{locale}/*.md` and parses front-matter with [`gray-matter`](https://github.com/jonschlinkert/gray-matter) -- Validates required fields, duplicate IDs, slugs, component references, and missing locale variants +- Validates required fields, duplicate IDs, slugs, and missing locale variants - Exposes a **virtual module** (`virtual:flatwave/content`) with typed helper functions usable in any React component - Generates locale-prefixed static HTML pages via `react-dom/server` - Emits `sitemap.xml`, `robots.txt`, and `route-manifest.json` @@ -80,7 +80,6 @@ export default defineConfig({ locales: ['es', 'pt'], // all supported locales defaultLocale: 'es', // must be in locales[] strictMissingLocales: false, // true → missing locale = build error - componentsDir: path.resolve(__dirname, 'src/components'), // for component validation sitemap: { hostname: 'https://example.com', // used in sitemap.xml and robots.txt }, @@ -104,11 +103,6 @@ src/ index.md about.md program.md - components/ - SimplePage.tsx ← referenced by component: 'SimplePage' in frontmatter - ProgramPage.tsx - LanguageSwitcher.tsx - MarkdownRenderer.tsx ``` Each locale must mirror the same set of content IDs. Missing locale variants produce warnings (or errors with `strictMissingLocales: true`). @@ -122,7 +116,6 @@ Every `.md` file must include these **required fields**: title: 'About Us' slug: 'about' # URL segment — becomes /{locale}/about id: 'about' # groups translations: same id across locales -component: 'SimplePage' # React component name in componentsDir public: true # false → excluded from routes, sitemap, manifest description: 'Short description' canonical: '/es/about' # optional, defaults to /{locale}/{slug} @@ -142,12 +135,12 @@ jsonLd: # Navigation hints menu: 'main' menu_position: 2 -# Any extra keys are preserved in attributes and forwarded to the component +# Any extra keys are preserved in attributes --- Markdown body here. GitHub-flavoured Markdown. No MDX in v1. ``` -**All extra frontmatter keys** not in the baseline list are preserved in `attributes` and forwarded as props to the React component — no schema changes required. +**All extra frontmatter keys** not in the baseline list are preserved in `attributes` and accessible via React hooks and the virtual module. --- @@ -394,15 +387,13 @@ The plugin validates content at build time (also exposed as a standalone CLI). V | Duplicate content IDs per locale | **Error** — build fails | | Duplicate slugs per locale | **Error** — build fails | | Duplicate menu positions | **Error** — build fails | -| Component not found in `componentsDir` | **Error** — build fails | | Content ID missing in one or more locales | **Warning** (or error with `strictMissingLocales: true`) | | No public routes generated | **Warning** | ```ts flatwaveContent({ // ... - requiredFields: ['title', 'slug', 'id', 'component', 'public'], // default - validateComponents: true, // default: true + requiredFields: ['title', 'slug', 'id', 'public'], // default strictMissingLocales: false, // default: false }); ``` @@ -418,21 +409,18 @@ npx flatwave-validate \ --content-dir src/content \ --locales es,pt \ --default-locale es \ - --components-dir src/components \ --strict-missing # optional: missing locale → error instead of warning # Exit code 0 → passed # Exit code 1 → errors found ``` -| Option | Description | -| --------------------------- | --------------------------------------------------------------------------- | -| `--content-dir ` | Path to the content directory | -| `--locales ` | Comma-separated locale identifiers | -| `--default-locale ` | The primary locale | -| `--components-dir ` | Comma-separated component directories (default: `src/components,src/pages`) | -| `--strict-missing` | Treat missing locale variants as errors | -| `--no-validate-components` | Skip component existence check | +| Option | Description | +| --------------------- | --------------------------------------- | +| `--content-dir ` | Path to the content directory | +| `--locales ` | Comma-separated locale identifiers | +| `--default-locale` | The primary locale | +| `--strict-missing` | Treat missing locale variants as errors | --- diff --git a/docs/Architecture.md b/docs/Architecture.md index d4e30dc..a8256ec 100644 --- a/docs/Architecture.md +++ b/docs/Architecture.md @@ -13,7 +13,7 @@ - [Plugin Core (`index.ts`)](#plugin-core-indexts) - [Content Pipeline](#content-pipeline) - [SSG Pipeline](#ssg-pipeline) - - [React Client Layer](#react-client-layer) + - [Composable React Components](#composable-react-components) - [SEO Module](#seo-module) - [CLI Tool](#cli-tool) 5. [Data Flow Diagrams](#data-flow-diagrams) @@ -24,7 +24,6 @@ - [Plugin Initialization Sequence](#plugin-initialization-sequence) - [Content Indexing Sequence](#content-indexing-sequence) - [SSG Page Rendering Sequence](#ssg-page-rendering-sequence) - - [Hot Module Replacement Sequence](#hot-module-replacement-sequence) - [CLI Validation Sequence](#cli-validation-sequence) 7. [Type System](#type-system) 8. [Interrelationship Map](#interrelationship-map) @@ -36,6 +35,16 @@ `@kamansoft/vite-plugin-flatwave-react` is a **Vite plugin** that transforms a directory of Markdown files (with YAML front-matter) into a fully type-safe, i18n-aware, statically-generated React site. It operates entirely at **build time**, producing locale-prefixed HTML pages, `sitemap.xml`, `robots.txt`, and `route-manifest.json` as output artifacts. +The plugin also provides **composable React components** that consumers can use to build their applications: + +- `FlatwaveMDComponent` - Markdown content renderer (SSG or client-side mode) +- `FlatwaveMDPageComponent` - Full-page wrapper with SEO head tags +- `FlatwaveLanguageRouter` - Complete router with language detection +- `FlatwaveLanguageDetector` - Language detection and redirect logic +- `FlatwaveAppRoutes` - Dynamic route rendering +- `FlatwaveLanguageSelector` - Language switcher UI +- `FlatwaveLanguageContext` - React context for locale state + The plugin is composed of three cooperating Vite plugin instances returned as an array from the single `flatwaveContent()` factory function: | Plugin name | Role | @@ -61,54 +70,39 @@ vite-plugin-flatwave-react/ ← npm workspace root │ │ │ ├── parser.ts ← standalone markdown parse (gray-matter wrapper) │ │ │ ├── indexer.ts ← builds FlatwaveContentIndex from scanned files │ │ │ ├── routeBuilder.ts ← assembles FlatwaveRoute[] with SEO metadata -│ │ │ ├── validator.ts ← content rules: required fields, duplicates, components +│ │ │ ├── validator.ts ← content rules: required fields, duplicates │ │ │ └── markdownCompiler.ts ← unified/remark/rehype markdown → HTML │ │ ├── ssg/ │ │ │ ├── runSsg.ts ← orchestrates SSG: renders all routes in batches -│ │ │ ├── RenderPipeline.ts ← hook executor (5 phases) +│ │ │ ├── RenderPipeline.ts ← hook executor (5 phases + emitFiles) │ │ │ ├── DefaultRenderStrategy.tsx ← React renderToString strategy │ │ │ ├── template.ts ← EJS-style template resolver + renderer -│ │ │ ├── types.ts ← SSG-specific types (RenderContext, etc.) +│ │ │ ├── types.ts ← RenderContext, TemplateVariables, EmitFilesContext │ │ │ ├── index.ts ← public re-exports of ./ssg │ │ │ └── templates/ │ │ │ ├── index.html.ejs ← default HTML shell template │ │ │ ├── entry-client.tsx.ejs │ │ │ └── entry-server.tsx.ejs │ │ ├── react/ -│ │ │ └── index.ts ← React hooks (useFlatwaveContent, etc.) -│ │ ├── seo/ -│ │ │ └── metadata.ts ← HTML head tag generators, escape helpers +│ │ │ ├── index.ts ← React hooks + component exports +│ │ │ ├── types.ts ← FlatwaveMDComponentProps, FlatwaveMDPageProps, etc. +│ │ │ ├── FlatwaveMDComponent.tsx ← Markdown content component +│ │ │ ├── FlatwaveMDPageComponent.tsx ← Page wrapper with SEO heads +│ │ │ ├── FlatwaveLanguageContext.ts ← React context for locale +│ │ │ ├── FlatwaveLanguageDetector.tsx ← URL/browser language detection +│ │ │ ├── FlatwaveLanguageRouter.tsx ← Composed router component +│ │ │ ├── FlatwaveAppRoutes.tsx ← Dynamic route mapping +│ │ │ └── FlatwaveLanguageSelector.tsx ← Language switcher UI +│ │ ├── seo/metadata.ts ← HTML head tag generators, escape helpers │ │ └── cli/ │ │ └── validate.ts ← CLI entry: `flatwave-validate` command │ ├── tsconfig.build.json │ └── package.json ← exports map, bin, peer deps ├── examples/ │ └── basic-react-site/ ← example consumer app (Vite + React) -│ ├── src/ -│ │ ├── content/{es,pt}/*.md ← sample multilingual content -│ │ ├── components/*.tsx ← SimplePage, ProgramPage, LanguageSwitcher, MarkdownRenderer -│ │ ├── App.tsx ← routing via virtual module -│ │ └── main.tsx -│ └── vite.config.ts ← flatwaveContent() usage example -├── docker/ -│ ├── docker-compose.yml ← dev / build / static services -│ ├── dev.Dockerfile -│ ├── build.Dockerfile -│ ├── static-server.Dockerfile -│ └── nginx.conf ├── e2e/ │ └── example.test.ts ← Vitest integration suite (builds + serves + asserts) -├── docs/ ← project documentation -├── .github/workflows/ -│ ├── ci.yml ← PR validation (format, lint, type-check, build, test) -│ ├── release.yml ← CI gate + semantic-release on push to main -│ └── pr-title.yml ← Conventional Commits PR title enforcement -├── .husky/ ← git hooks (pre-commit, commit-msg) -├── .lintstagedrc.json ← lint-staged per-glob rules -├── commitlint.config.js ← commitlint Conventional Commits rules -├── eslint.config.mjs ← flat ESLint config (TS + Prettier + React) -├── .releaserc.json ← semantic-release configuration -└── package.json ← workspace root + shared dev tooling +└── docs/ ← project documentation ``` --- @@ -142,7 +136,13 @@ graph TB RUNSSG["runSsg.ts\norchestrator"] PIPELINE["RenderPipeline.ts\nhook executor"] STRATEGY["DefaultRenderStrategy\nreact-dom/server"] - TEMPLATE["template.ts\nEJS-style renderer"] + TEMPLATE["template.ts\nHTML shell rendering"] + end + + subgraph "Composable React Components" + ROUTER["FlatwaveLanguageRouter\nBrowserRouter + Detector + Routes"] + COMPONENTS["FlatwaveMDPageComponent\nFlatwaveMDComponent\nFlatwaveLanguageSelector"] + CONTEXT["FlatwaveLanguageContext"] end subgraph "Virtual Module" @@ -176,6 +176,10 @@ graph TB RUNSSG --> PIPELINE --> STRATEGY --> TEMPLATE RUNSSG --> META VM --> HOOKS + VM --> ROUTER + ROUTER --> CONTEXT + ROUTER --> COMPONENTS + CONTEXT --> COMPONENTS TEMPLATE --> HTML RUNSSG --> SITEMAP & ROBOTS & MANIFEST ``` @@ -188,7 +192,7 @@ graph TB The entry point exports the `flatwaveContent(options)` factory which: -1. **Normalizes options** — fills in defaults for optional fields (`requiredFields`, `validateComponents`, `emitRouteManifest`, `emitSitemap`, `emitRobotsTxt`, `ssg`). +1. **Normalizes options** — fills in defaults for optional fields (`requiredFields`, `emitRouteManifest`, `emitSitemap`, `emitRobotsTxt`, `ssg`). 2. **Returns three plugin objects** that Vite integrates into its build pipeline. ``` @@ -210,18 +214,7 @@ flatwaveContent(options) generateBundle() → runSsg(index, options, assets) → emitFile() ``` -**Virtual module content** (created in `createVirtualModule`): - -The virtual module is a string of JavaScript containing the serialized content index and helper functions. It exports: - -- `getContent(id, locale?)` — find one entry -- `getAllContent()` — full entry array -- `getRoutes(locale?)` — all or locale-filtered routes -- `getAlternatives(contentId, currentLocale)` — locale → path map (minus current) -- `getLocale(locale?)` — pass-through locale helper -- `getLocales()` — unique locale list derived from routes -- `getDefaultLocale()` — the configured default locale -- `flatwaveContentIndex` — full index object +**Note**: `componentsDir` and component validation have been removed. Route rendering now uses `FlatwaveMDPageComponent` as the single default renderer. --- @@ -237,52 +230,6 @@ src/content/ └── markdownCompiler.ts ← Converts Markdown body → HTML ``` -**`scanner.ts`** - -Uses `fast-glob` to glob `**/*.md` inside each locale directory. For each file: - -- reads content via `fs/promises` -- parses front-matter with `gray-matter` -- normalizes the slug (strips leading/trailing slashes, prepends `/`) -- returns an array of `ParsedMarkdownFile` - -**`indexer.ts`** - -Iterates `ParsedMarkdownFile[]`, creates `FlatwaveContentEntry` objects, builds an alternatives map (`id → { locale → route }`), then delegates to `buildContentIndex()` from `routeBuilder.ts`. - -**`routeBuilder.ts`** - -- Filters to public entries only -- Builds `byId` and `byLocale` lookup maps -- Assembles `FlatwaveRoute[]` sorted by `locale + path` -- Derives `SeoMetadata` from frontmatter fields - -**`validator.ts`** - -Runs five validation passes (all async): - -1. **Required fields** — checks every entry has all `requiredFields` -2. **Duplicate IDs** — ensures no two files share the same `locale:id` key -3. **Duplicate slugs** — ensures no two files share the same `locale:slug` key -4. **Menu positions** — validates numeric `menu_position` values and uniqueness per menu group -5. **Components** — discovers `.tsx/.ts/.jsx/.js` files in `componentsDir` and checks that every `component` referenced in frontmatter exists - -Returns `{ errors: string[], warnings: string[] }`. Errors block the build; warnings are surfaced via Vite's `this.warn()`. - -**`markdownCompiler.ts`** - -A `unified` pipeline: - -``` -unified() - .use(remarkParse) ← Markdown AST - .use(remarkRehype, ...) ← convert to HTML AST - .use(rehypeRaw) ← (optional) allow raw HTML passthrough - .use(rehypeStringify) ← serialize to HTML string -``` - -Accepts custom `remarkPlugins` and `rehypePlugins` via `MarkdownCompilerOptions`. - --- ### SSG Pipeline @@ -290,89 +237,42 @@ Accepts custom `remarkPlugins` and `rehypePlugins` via `MarkdownCompilerOptions` ``` src/ssg/ ├── runSsg.ts ← main orchestrator -├── RenderPipeline.ts ← hook phase executor +├── RenderPipeline.ts ← hook phase executor (5 phases + emitFiles) ├── DefaultRenderStrategy.tsx ← react-dom/server renderer ├── template.ts ← HTML template resolution + rendering -├── types.ts ← RenderContext, TemplateVariables -├── index.ts ← public exports +├── types.ts ← RenderContext, TemplateVariables, EmitFilesContext +├── index.ts ← public re-exports of ./ssg └── templates/ ├── index.html.ejs ← default HTML shell ├── entry-client.tsx.ejs └── entry-server.tsx.ejs ``` -**`runSsg.ts`** - -Processes all routes in **concurrency batches of 4**: - -``` -For each route (batched, 4 at a time): - 1. Find contentEntry matching route.contentId + route.locale - 2. pipeline.executeBeforeRender(context) ← hook - 3. pipeline.executeTransformMarkdown(body) ← hook - 4. compileMarkdownToHtml(transformedMarkdown) ← remark/rehype - 5. strategy.render(renderContext) ← DefaultRenderStrategy / custom - 6. resolveTemplate('index.html', overrides) ← built-in or project-override - 7. renderHtmlHead(route) ← SEO meta tags - 8. renderTemplate(template, variables) ← EJS-style substitution - 9. pipeline.executeTransformHtml(finalHtml) ← hook - 10. pipeline.executeAfterRender(finalHtml) ← hook (side effects only) - 11. Emit as 'asset' file: {locale}/{slug}/index.html - -After all routes: - → emit route-manifest.json (if enabled) - → emit sitemap.xml (if enabled) - → emit robots.txt (if enabled) -``` - -**`RenderPipeline.ts`** - -Stores hooks per phase in typed arrays. Each `execute*` method runs hooks sequentially, wrapping each in try/catch to prevent one failing hook from aborting the whole render. Hook phases: - -| Method | Phase | Input → Output | -| -------------------------- | ------------------- | ------------------------------- | -| `executeBeforeRender` | `beforeRender` | `RenderContext → RenderContext` | -| `executeTransformMarkdown` | `transformMarkdown` | `(md, ctx) → md` | -| `executeTransformHtml` | `transformHtml` | `(html, ctx) → html` | -| `executeAfterRender` | `afterRender` | `(html, ctx) → void` | -| `executeOnError` | `onError` | `(Error, ctx) → html` | - -**`DefaultRenderStrategy.tsx`** - -- Looks up the React component from the preloaded `components` Map -- If component found: calls `renderToString()` -- If component not found: falls back to returning the compiled HTML body directly (graceful degradation) -- Props passed to component: `{ ...frontmatter, markdownHtml, locale, route }` - -**`template.ts`** - -Resolution order for `index.html`: - -1. `overrides.indexHtml` (if provided in `ssg.template`) -2. `{projectRoot}/flatwave-templates/index.html` (project-level override) -3. Built-in `templates/index.html.ejs` - -Template substitution variables: `<%= appHtml %>`, `<%= title %>`, `<%= meta %>`, `<%= locale %>`, `<%= canonical %>`, `<%= headTags %>`, `<%= scripts %>`, `<%= styles %>`. - --- -### React Client Layer +### Composable React Components + +The `src/react/` directory provides reusable React components for building multilingual sites: ``` -src/react/index.ts +src/react/ +├── index.ts ← Exports all hooks and components +├── types.ts ← Props interfaces (FlatwaveMDComponentProps, etc.) +├── FlatwaveMDComponent.tsx ← Markdown renderer (SSG or client-side) +├── FlatwaveMDPageComponent.tsx ← Page wrapper with Helmet SEO heads +├── FlatwaveLanguageContext.ts ← React context (locale, supportedLanguages) +├── FlatwaveLanguageDetector.tsx ← URL prefix + browser language detection +├── FlatwaveLanguageRouter.tsx ← Composed BrowserRouter + Detector + AppRoutes +├── FlatwaveAppRoutes.tsx ← Dynamic route rendering with render prop +└── FlatwaveLanguageSelector.tsx ← Language switcher UI ``` -Thin wrapper around the virtual module. Exports React hooks built with `useMemo` for referential stability: - -| Hook | Returns | Purpose | -| -------------------------------------- | ------------------------------------- | ----------------------------------- | -| `useFlatwaveContent(id, locale?)` | `FlatwaveVirtualContent \| undefined` | Get one content entry | -| `useFlatwaveRoutes(locale?)` | `FlatwaveVirtualRoute[]` | Get all routes, optionally filtered | -| `useFlatwaveAlternatives(id, locale?)` | `Record` | Locale → path map for a content ID | -| `useFlatwaveLocales()` | `string[]` | All configured locales | -| `useFlatwaveLocale(locale?)` | `string \| undefined` | Pass-through locale value | +**Component Patterns:** -Also re-exports the raw virtual module functions for non-hook usage (`getAllContent`, `getContent`, `getRoutes`, `getAlternatives`, `getLocale`, `getLocales`). +- **SSG Mode**: When `markdownHtml` prop is provided, renders pre-compiled HTML +- **Client-side Mode**: When `markdown` prop is provided, uses `react-markdown` +- **Composition**: All components accept render props or wrapper components for customization +- **Default Renderer**: SSG uses `FlatwaveMDPageComponent` as the only renderer. No `componentsDir` or component field is required. --- @@ -382,15 +282,7 @@ Also re-exports the raw virtual module functions for non-hook usage (`getAllCont src/seo/metadata.ts ``` -| Function | Purpose | -| ---------------------------- | --------------------------------------------------------------------- | -| `renderHtmlHead(route)` | Generates all ``, ``, ` diff --git a/examples/basic-react-site/dist/es/index.html b/examples/basic-react-site/dist/es/index.html index 221079f..9b9cb92 100644 --- a/examples/basic-react-site/dist/es/index.html +++ b/examples/basic-react-site/dist/es/index.html @@ -14,7 +14,7 @@ -

Inicio

+

Inicio

Este es el sitio de ejemplo para probar el plugin de contenido Flatwave.

  • Rutas localizadas.
    • @@ -22,7 +22,7 @@
  • Sitemap y robots generados.
-

This page was built with Flatwave SSG 1.0.0.

+

This page was built with Flatwave SSG 1.0.0.

diff --git a/examples/basic-react-site/dist/es/program/index.html b/examples/basic-react-site/dist/es/program/index.html index 214aacd..b202906 100644 --- a/examples/basic-react-site/dist/es/program/index.html +++ b/examples/basic-react-site/dist/es/program/index.html @@ -14,12 +14,12 @@ -

Programa

+

Programa

Esta página usa un componente diferente y frontmatter adicional como date y schedule.

Horario

El horario se conserva en attributes para que el componente lo use.

-

This page was built with Flatwave SSG 1.0.0.

+

This page was built with Flatwave SSG 1.0.0.

diff --git a/examples/basic-react-site/dist/index.html b/examples/basic-react-site/dist/index.html index c3ba9aa..9a5bac4 100644 --- a/examples/basic-react-site/dist/index.html +++ b/examples/basic-react-site/dist/index.html @@ -4,7 +4,7 @@ Flatwave React Example - + diff --git a/examples/basic-react-site/dist/pt/about/index.html b/examples/basic-react-site/dist/pt/about/index.html index 55ab478..8ac42ce 100644 --- a/examples/basic-react-site/dist/pt/about/index.html +++ b/examples/basic-react-site/dist/pt/about/index.html @@ -14,12 +14,12 @@ -

Sobre

+

Sobre

Esta página demonstra Markdown válido e frontmatter adicional preservado pelo plugin.

# Markdown válido
-

This page was built with Flatwave SSG 1.0.0.

+

This page was built with Flatwave SSG 1.0.0.

diff --git a/examples/basic-react-site/dist/pt/index.html b/examples/basic-react-site/dist/pt/index.html index d4294ff..75a46b3 100644 --- a/examples/basic-react-site/dist/pt/index.html +++ b/examples/basic-react-site/dist/pt/index.html @@ -4,17 +4,17 @@ Início - + - + -

Início

+

Início

Este é o site de exemplo para testar o plugin de conteúdo Flatwave.

  • Rotas localizadas.
    • @@ -22,7 +22,7 @@
  • Sitemap e robots gerados.
-

This page was built with Flatwave SSG 1.0.0.

+

This page was built with Flatwave SSG 1.0.0.

diff --git a/examples/basic-react-site/dist/pt/program/index.html b/examples/basic-react-site/dist/pt/program/index.html index 6878bd5..9056986 100644 --- a/examples/basic-react-site/dist/pt/program/index.html +++ b/examples/basic-react-site/dist/pt/program/index.html @@ -14,12 +14,12 @@ -

Programa

+

Programa

Esta página usa um componente diferente e frontmatter adicional como date e schedule.

Horário

O horário é preservado em attributes para que o componente o utilize.

-

This page was built with Flatwave SSG 1.0.0.

+

This page was built with Flatwave SSG 1.0.0.

diff --git a/examples/basic-react-site/dist/route-manifest.json b/examples/basic-react-site/dist/route-manifest.json index e9d6b71..22b58f4 100644 --- a/examples/basic-react-site/dist/route-manifest.json +++ b/examples/basic-react-site/dist/route-manifest.json @@ -3,7 +3,6 @@ "locale": "es", "path": "/es/", "contentId": "home", - "component": "SimplePage", "metadata": { "title": "Inicio", "description": "Página de inicio del ejemplo Flatwave.", @@ -18,7 +17,6 @@ "title": "Inicio", "slug": "index", "id": "home", - "component": "SimplePage", "public": true, "description": "Página de inicio del ejemplo Flatwave.", "canonical": "/es/", @@ -39,7 +37,6 @@ "locale": "es", "path": "/es/about", "contentId": "about", - "component": "SimplePage", "metadata": { "title": "Acerca de", "description": "Página acerca del ejemplo Flatwave.", @@ -54,7 +51,6 @@ "title": "Acerca de", "slug": "about", "id": "about", - "component": "SimplePage", "public": true, "description": "Página acerca del ejemplo Flatwave.", "canonical": "/es/about", @@ -75,7 +71,6 @@ "locale": "es", "path": "/es/program", "contentId": "program", - "component": "ProgramPage", "metadata": { "title": "Programa", "description": "Página de programa con frontmatter específico del componente.", @@ -89,7 +84,6 @@ "title": "Programa", "slug": "program", "id": "program", - "component": "ProgramPage", "public": true, "description": "Página de programa con frontmatter específico del componente.", "canonical": "/es/program", @@ -114,10 +108,9 @@ "locale": "pt", "path": "/pt/", "contentId": "home", - "component": "SimplePage", "metadata": { "title": "Início", - "description": "Página inicial do exemplo Flatwave.", + "description": "Página de início do exemplo Flatwave.", "canonical": "/pt/", "robots": "index, follow", "keywords": [ @@ -129,9 +122,8 @@ "title": "Início", "slug": "index", "id": "home", - "component": "SimplePage", "public": true, - "description": "Página inicial do exemplo Flatwave.", + "description": "Página de início do exemplo Flatwave.", "canonical": "/pt/", "robots": "index, follow", "keywords": [ @@ -150,7 +142,6 @@ "locale": "pt", "path": "/pt/about", "contentId": "about", - "component": "SimplePage", "metadata": { "title": "Sobre", "description": "Página sobre o exemplo Flatwave.", @@ -165,7 +156,6 @@ "title": "Sobre", "slug": "about", "id": "about", - "component": "SimplePage", "public": true, "description": "Página sobre o exemplo Flatwave.", "canonical": "/pt/about", @@ -186,7 +176,6 @@ "locale": "pt", "path": "/pt/program", "contentId": "program", - "component": "ProgramPage", "metadata": { "title": "Programa", "description": "Página de programa com frontmatter específico do componente.", @@ -200,7 +189,6 @@ "title": "Programa", "slug": "program", "id": "program", - "component": "ProgramPage", "public": true, "description": "Página de programa com frontmatter específico do componente.", "canonical": "/pt/program", diff --git a/examples/basic-react-site/dist/sitemap.xml b/examples/basic-react-site/dist/sitemap.xml index a52648a..76872b1 100644 --- a/examples/basic-react-site/dist/sitemap.xml +++ b/examples/basic-react-site/dist/sitemap.xml @@ -1,2 +1,2 @@ -http://localhost:4173/es/2026-06-20weekly0.8http://localhost:4173/es/about2026-06-20weekly0.8http://localhost:4173/es/program2026-06-20weekly0.8http://localhost:4173/pt/2026-06-20weekly0.8http://localhost:4173/pt/about2026-06-20weekly0.8http://localhost:4173/pt/program2026-06-20weekly0.8 +http://localhost:4173/es/2026-06-22weekly0.8http://localhost:4173/es/about2026-06-22weekly0.8http://localhost:4173/es/program2026-06-22weekly0.8http://localhost:4173/pt/2026-06-22weekly0.8http://localhost:4173/pt/about2026-06-22weekly0.8http://localhost:4173/pt/program2026-06-22weekly0.8 diff --git a/examples/basic-react-site/package.json b/examples/basic-react-site/package.json index f2047fe..e571ba4 100644 --- a/examples/basic-react-site/package.json +++ b/examples/basic-react-site/package.json @@ -10,10 +10,12 @@ }, "dependencies": { "@vitejs/plugin-react": "^4.3.4", + "@kamansoft/vite-plugin-flatwave-react": "file:../../packages/vite-plugin-flatwave-react", "react": "^18.3.1", "react-dom": "^18.3.1", - "react-markdown": "^9.0.3", - "@kamansoft/vite-plugin-flatwave-react": "file:../../packages/vite-plugin-flatwave-react" + "react-markdown": "^10.0.0", + "react-helmet-async": "^2.0.0", + "react-router-dom": "^6.0.0" }, "devDependencies": { "@types/react": "^18.3.12", diff --git a/examples/basic-react-site/src/App.tsx b/examples/basic-react-site/src/App.tsx index 67f6b07..f7768f7 100644 --- a/examples/basic-react-site/src/App.tsx +++ b/examples/basic-react-site/src/App.tsx @@ -1,32 +1,30 @@ -import { useMemo } from 'react'; -import { getRoutes, getContent } from 'virtual:flatwave/content'; -import { LanguageSwitcher } from './components/LanguageSwitcher'; -import { MarkdownRenderer } from './components/MarkdownRenderer'; -import { ProgramPage } from './components/ProgramPage'; -import { SimplePage } from './components/SimplePage'; +import { + FlatwaveLanguageRouter, + FlatwaveMDPageComponent, + useFlatwaveRoutes, + useFlatwaveContent, +} from '@kamansoft/vite-plugin-flatwave-react/react'; +import type { FlatwaveFrontmatter } from '@kamansoft/vite-plugin-flatwave-react/types'; +import type { FlatwaveVirtualRoute } from 'virtual:flatwave/content'; export function App() { - const locale = useMemo(() => window.location.pathname.split('/')[1] || 'es', []); - const path = window.location.pathname.replace(/\/$/, '') || `/${locale}`; - const routes = getRoutes(locale); - const route = routes.find((item) => item.path === path) ?? routes[0]; - const content = route ? getRouteContent(route.contentId, locale) : undefined; - - if (!content) { - return
Content not found
; - } - - const Component = content.component === 'ProgramPage' ? ProgramPage : SimplePage; + const routes = useFlatwaveRoutes(); return ( -
- - - {content.body} -
+ { + const content = useFlatwaveContent(route.contentId, lang); + return ( + + ); + }} + /> ); } - -function getRouteContent(contentId: string, locale: string) { - return getContent(contentId, locale); -} diff --git a/examples/basic-react-site/src/components/ProgramPage.tsx b/examples/basic-react-site/src/components/ProgramPage.tsx deleted file mode 100644 index 31207e8..0000000 --- a/examples/basic-react-site/src/components/ProgramPage.tsx +++ /dev/null @@ -1,13 +0,0 @@ -import type { FlatwaveVirtualContent } from 'virtual:flatwave/content'; - -export function ProgramPage({ content }: { content: FlatwaveVirtualContent }) { - return ( -
-

{content.frontmatter.title as string}

- {content.frontmatter.description ?

{String(content.frontmatter.description)}

: null} - {content.frontmatter.date ? ( - - ) : null} -
- ); -} diff --git a/examples/basic-react-site/src/components/SimplePage.tsx b/examples/basic-react-site/src/components/SimplePage.tsx deleted file mode 100644 index ea3a387..0000000 --- a/examples/basic-react-site/src/components/SimplePage.tsx +++ /dev/null @@ -1,10 +0,0 @@ -import type { FlatwaveVirtualContent } from 'virtual:flatwave/content'; - -export function SimplePage({ content }: { content: FlatwaveVirtualContent }) { - return ( -
-

{content.frontmatter.title as string}

- {content.frontmatter.description ?

{String(content.frontmatter.description)}

: null} -
- ); -} diff --git a/examples/basic-react-site/src/content/es/about.md b/examples/basic-react-site/src/content/es/about.md index d0137e5..bbb9177 100644 --- a/examples/basic-react-site/src/content/es/about.md +++ b/examples/basic-react-site/src/content/es/about.md @@ -2,7 +2,6 @@ title: 'Acerca de' slug: 'about' id: 'about' -component: 'SimplePage' public: true description: 'Página acerca del ejemplo Flatwave.' canonical: '/es/about' diff --git a/examples/basic-react-site/src/content/es/index.md b/examples/basic-react-site/src/content/es/index.md index 7fe115c..600236d 100644 --- a/examples/basic-react-site/src/content/es/index.md +++ b/examples/basic-react-site/src/content/es/index.md @@ -2,7 +2,6 @@ title: 'Inicio' slug: 'index' id: 'home' -component: 'SimplePage' public: true description: 'Página de inicio del ejemplo Flatwave.' canonical: '/es/' diff --git a/examples/basic-react-site/src/content/es/program.md b/examples/basic-react-site/src/content/es/program.md index 5ed8d97..c3f50f3 100644 --- a/examples/basic-react-site/src/content/es/program.md +++ b/examples/basic-react-site/src/content/es/program.md @@ -2,7 +2,6 @@ title: 'Programa' slug: 'program' id: 'program' -component: 'ProgramPage' public: true description: 'Página de programa con frontmatter específico del componente.' canonical: '/es/program' diff --git a/examples/basic-react-site/src/content/pt/about.md b/examples/basic-react-site/src/content/pt/about.md index e08358d..6ec7f40 100644 --- a/examples/basic-react-site/src/content/pt/about.md +++ b/examples/basic-react-site/src/content/pt/about.md @@ -2,7 +2,6 @@ title: 'Sobre' slug: 'about' id: 'about' -component: 'SimplePage' public: true description: 'Página sobre o exemplo Flatwave.' canonical: '/pt/about' diff --git a/examples/basic-react-site/src/content/pt/index.md b/examples/basic-react-site/src/content/pt/index.md index 3a349f5..31c83db 100644 --- a/examples/basic-react-site/src/content/pt/index.md +++ b/examples/basic-react-site/src/content/pt/index.md @@ -2,9 +2,8 @@ title: 'Início' slug: 'index' id: 'home' -component: 'SimplePage' public: true -description: 'Página inicial do exemplo Flatwave.' +description: 'Página de início do exemplo Flatwave.' canonical: '/pt/' robots: 'index, follow' keywords: diff --git a/examples/basic-react-site/src/content/pt/program.md b/examples/basic-react-site/src/content/pt/program.md index a446732..84e43cc 100644 --- a/examples/basic-react-site/src/content/pt/program.md +++ b/examples/basic-react-site/src/content/pt/program.md @@ -2,7 +2,6 @@ title: 'Programa' slug: 'program' id: 'program' -component: 'ProgramPage' public: true description: 'Página de programa com frontmatter específico do componente.' canonical: '/pt/program' diff --git a/examples/basic-react-site/vite.config.ts b/examples/basic-react-site/vite.config.ts index 34862d9..1f867ad 100644 --- a/examples/basic-react-site/vite.config.ts +++ b/examples/basic-react-site/vite.config.ts @@ -11,7 +11,6 @@ export default defineConfig({ locales: ['es', 'pt'], defaultLocale: 'es', strictMissingLocales: false, - componentsDir: path.resolve(__dirname, 'src/components'), sitemap: { hostname: 'http://localhost:4173', }, diff --git a/node_modules/.package-lock.json b/node_modules/.package-lock.json index df4387f..c50f86a 100644 --- a/node_modules/.package-lock.json +++ b/node_modules/.package-lock.json @@ -6,13 +6,15 @@ "packages": { "examples/basic-react-site": { "name": "@flatwave/example-basic-react-site", - "version": "0.1.0", + "version": "1.0.0", "dependencies": { "@kamansoft/vite-plugin-flatwave-react": "file:../../packages/vite-plugin-flatwave-react", "@vitejs/plugin-react": "^4.3.4", "react": "^18.3.1", "react-dom": "^18.3.1", - "react-markdown": "^9.0.3" + "react-helmet-async": "^2.0.0", + "react-markdown": "^9.0.3", + "react-router-dom": "^6.0.0" }, "devDependencies": { "@types/react": "^18.3.12", @@ -21,6 +23,38 @@ "vite": "^6.0.7" } }, + "examples/basic-react-site/node_modules/react-router-dom": { + "version": "6.30.4", + "resolved": "https://registry.npmjs.org/react-router-dom/-/react-router-dom-6.30.4.tgz", + "integrity": "sha512-q4HvNl+mmDdkS0g+MqiBZNteQJCuimWoOyHMy4T/RQLAn9Z29+E91QXRaxOujeMl2HTzRSS0KFPd7lxX3PjV0Q==", + "license": "MIT", + "dependencies": { + "@remix-run/router": "1.23.3", + "react-router": "6.30.4" + }, + "engines": { + "node": ">=14.0.0" + }, + "peerDependencies": { + "react": ">=16.8", + "react-dom": ">=16.8" + } + }, + "examples/basic-react-site/node_modules/react-router-dom/node_modules/react-router": { + "version": "6.30.4", + "resolved": "https://registry.npmjs.org/react-router/-/react-router-6.30.4.tgz", + "integrity": "sha512-SVUsDe+DybHM/WmYKIVYhZh1o5Dcuf16yM6WjG02Q9XVFMZIJyHYhwrr6bFBXZkVP6z69kNkMyBCujt8FaFLJA==", + "license": "MIT", + "dependencies": { + "@remix-run/router": "1.23.3" + }, + "engines": { + "node": ">=14.0.0" + }, + "peerDependencies": { + "react": ">=16.8" + } + }, "examples/basic-react-site/node_modules/vite": { "version": "6.4.3", "resolved": "https://registry.npmjs.org/vite/-/vite-6.4.3.tgz", @@ -1609,6 +1643,15 @@ "node": ">=12" } }, + "node_modules/@remix-run/router": { + "version": "1.23.3", + "resolved": "https://registry.npmjs.org/@remix-run/router/-/router-1.23.3.tgz", + "integrity": "sha512-4An71tdz9X8+3sI4Qqqd2LWd9vS39J7sqd9EU4Scw7TJE/qB10Flv/UuqbPVgfQV9XoK8Np6jNquZitnZq5i+Q==", + "license": "MIT", + "engines": { + "node": ">=14.0.0" + } + }, "node_modules/@rolldown/pluginutils": { "version": "1.0.0-beta.27", "resolved": "https://registry.npmjs.org/@rolldown/pluginutils/-/pluginutils-1.0.0-beta.27.tgz", @@ -4099,6 +4142,20 @@ "integrity": "sha512-Kvp459HrV2FEJ1CAsi1Ku+MY3kasH19TFykTz2xWmMeq6bk2NU3XXvfJ+Q61m0xktWwt+1HSYf3JZsTms3aRJg==", "license": "MIT" }, + "node_modules/cookie": { + "version": "1.1.1", + "resolved": "https://registry.npmjs.org/cookie/-/cookie-1.1.1.tgz", + "integrity": "sha512-ei8Aos7ja0weRpFzJnEA9UHJ/7XQmqglbRwnf2ATjcB9Wq874VKH9kfjjirM6UhU2/E5fFYadylyhFldcqSidQ==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=18" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/express" + } + }, "node_modules/core-util-is": { "version": "1.0.3", "resolved": "https://registry.npmjs.org/core-util-is/-/core-util-is-1.0.3.tgz", @@ -6585,6 +6642,15 @@ "node": ">= 0.4" } }, + "node_modules/invariant": { + "version": "2.2.4", + "resolved": "https://registry.npmjs.org/invariant/-/invariant-2.2.4.tgz", + "integrity": "sha512-phJfQVBuaJM5raOpJjSfkiD6BpbCE4Ns//LaXl6wGYtUBY83nWS6Rf9tXm2e8VaK60JEjYldbPif/A2B1C2gNA==", + "license": "MIT", + "dependencies": { + "loose-envify": "^1.0.0" + } + }, "node_modules/is-alphabetical": { "version": "2.0.1", "resolved": "https://registry.npmjs.org/is-alphabetical/-/is-alphabetical-2.0.1.tgz", @@ -11599,6 +11665,26 @@ "react": "^18.3.1" } }, + "node_modules/react-fast-compare": { + "version": "3.2.2", + "resolved": "https://registry.npmjs.org/react-fast-compare/-/react-fast-compare-3.2.2.tgz", + "integrity": "sha512-nsO+KSNgo1SbJqJEYRE9ERzo7YtYbou/OqjSQKxV7jcKox7+usiUVZOAC+XnDOABXggQTno0Y1CpVnuWEc1boQ==", + "license": "MIT" + }, + "node_modules/react-helmet-async": { + "version": "2.0.5", + "resolved": "https://registry.npmjs.org/react-helmet-async/-/react-helmet-async-2.0.5.tgz", + "integrity": "sha512-rYUYHeus+i27MvFE+Jaa4WsyBKGkL6qVgbJvSBoX8mbsWoABJXdEO0bZyi0F6i+4f0NuIb8AvqPMj3iXFHkMwg==", + "license": "Apache-2.0", + "dependencies": { + "invariant": "^2.2.4", + "react-fast-compare": "^3.2.2", + "shallowequal": "^1.1.0" + }, + "peerDependencies": { + "react": "^16.6.0 || ^17.0.0 || ^18.0.0" + } + }, "node_modules/react-is": { "version": "16.13.1", "resolved": "https://registry.npmjs.org/react-is/-/react-is-16.13.1.tgz", @@ -11642,6 +11728,46 @@ "node": ">=0.10.0" } }, + "node_modules/react-router": { + "version": "7.18.0", + "resolved": "https://registry.npmjs.org/react-router/-/react-router-7.18.0.tgz", + "integrity": "sha512-pTTGt8J+ji1NOmYnjzT+bAJy/1zD+Jp4ziO6cL7T3ZLvXKtusO7BpFqlRXitqpcPVqllsIXFHRMt+2/k3Xn6HQ==", + "dev": true, + "license": "MIT", + "dependencies": { + "cookie": "^1.0.1", + "set-cookie-parser": "^2.6.0" + }, + "engines": { + "node": ">=20.0.0" + }, + "peerDependencies": { + "react": ">=18", + "react-dom": ">=18" + }, + "peerDependenciesMeta": { + "react-dom": { + "optional": true + } + } + }, + "node_modules/react-router-dom": { + "version": "7.18.0", + "resolved": "https://registry.npmjs.org/react-router-dom/-/react-router-dom-7.18.0.tgz", + "integrity": "sha512-Fi0yY6kgtKae/Th2xibdWK0KSdYZ4B53Gyf6wRtomOKWgpNm7H7+DyfDhncdz9FKbpS+1jmDhg3F4WoGJ+yFOA==", + "dev": true, + "license": "MIT", + "dependencies": { + "react-router": "7.18.0" + }, + "engines": { + "node": ">=20.0.0" + }, + "peerDependencies": { + "react": ">=18", + "react-dom": ">=18" + } + }, "node_modules/read-package-up": { "version": "12.0.0", "resolved": "https://registry.npmjs.org/read-package-up/-/read-package-up-12.0.0.tgz", @@ -12490,6 +12616,13 @@ "node": ">= 0.8" } }, + "node_modules/set-cookie-parser": { + "version": "2.7.2", + "resolved": "https://registry.npmjs.org/set-cookie-parser/-/set-cookie-parser-2.7.2.tgz", + "integrity": "sha512-oeM1lpU/UvhTxw+g3cIfxXHyJRc/uidd3yK1P242gzHds0udQBYzs3y8j4gCCW+ZJ7ad0yctld8RYO+bdurlvw==", + "dev": true, + "license": "MIT" + }, "node_modules/set-function-length": { "version": "1.2.2", "resolved": "https://registry.npmjs.org/set-function-length/-/set-function-length-1.2.2.tgz", @@ -12539,6 +12672,12 @@ "node": ">= 0.4" } }, + "node_modules/shallowequal": { + "version": "1.1.0", + "resolved": "https://registry.npmjs.org/shallowequal/-/shallowequal-1.1.0.tgz", + "integrity": "sha512-y0m1JoUZSlPAjXVtPPW70aZWfIL/dSP7AFkRnniLCrK/8MDKog3TySTBmckD+RObVxH0v4Tox67+F14PdED2oQ==", + "license": "MIT" + }, "node_modules/shebang-command": { "version": "2.0.0", "resolved": "https://registry.npmjs.org/shebang-command/-/shebang-command-2.0.0.tgz", @@ -14038,10 +14177,6 @@ "url": "https://opencollective.com/vitest" } }, - "node_modules/vite-plugin-flatwave-react": { - "resolved": "packages/vite-plugin-flatwave-react", - "link": true - }, "node_modules/vite/node_modules/@esbuild/linux-x64": { "version": "0.21.5", "resolved": "https://registry.npmjs.org/@esbuild/linux-x64/-/linux-x64-0.21.5.tgz", @@ -14492,12 +14627,13 @@ }, "packages/vite-plugin-flatwave-react": { "name": "@kamansoft/vite-plugin-flatwave-react", - "version": "0.1.0", + "version": "1.0.0", "license": "MIT", "dependencies": { "commander": "^13.1.0", "fast-glob": "^3.3.3", "gray-matter": "^4.0.3", + "react-helmet-async": "^2.0.0", "rehype-raw": "^7.0.0", "rehype-stringify": "^10.0.1", "remark": "^15.0.1", @@ -14514,6 +14650,8 @@ "@types/react-dom": "^18.3.1", "react": "^18.3.1", "react-dom": "^18.3.1", + "react-markdown": "^10.1.0", + "react-router-dom": "^7.18.0", "typescript": "^5.7.2", "vite": "^6.0.7" }, @@ -14523,9 +14661,40 @@ "peerDependencies": { "react": ">=18.0.0", "react-dom": ">=18.0.0", + "react-helmet-async": "^2.0.0", + "react-markdown": "^10.0.0", + "react-router-dom": "^6.0.0", "vite": "^5.0.0 || ^6.0.0 || ^7.0.0" } }, + "packages/vite-plugin-flatwave-react/node_modules/react-markdown": { + "version": "10.1.0", + "resolved": "https://registry.npmjs.org/react-markdown/-/react-markdown-10.1.0.tgz", + "integrity": "sha512-qKxVopLT/TyA6BX3Ue5NwabOsAzm0Q7kAPwq6L+wWDwisYs7R8vZ0nRXqq6rkueboxpkjvLGU9fWifiX/ZZFxQ==", + "dev": true, + "license": "MIT", + "dependencies": { + "@types/hast": "^3.0.0", + "@types/mdast": "^4.0.0", + "devlop": "^1.0.0", + "hast-util-to-jsx-runtime": "^2.0.0", + "html-url-attributes": "^3.0.0", + "mdast-util-to-hast": "^13.0.0", + "remark-parse": "^11.0.0", + "remark-rehype": "^11.0.0", + "unified": "^11.0.0", + "unist-util-visit": "^5.0.0", + "vfile": "^6.0.0" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/unified" + }, + "peerDependencies": { + "@types/react": ">=18", + "react": ">=18" + } + }, "packages/vite-plugin-flatwave-react/node_modules/vite": { "version": "6.4.3", "resolved": "https://registry.npmjs.org/vite/-/vite-6.4.3.tgz", diff --git a/node_modules/vite-plugin-flatwave-react b/node_modules/vite-plugin-flatwave-react deleted file mode 120000 index c996fdf..0000000 --- a/node_modules/vite-plugin-flatwave-react +++ /dev/null @@ -1 +0,0 @@ -../packages/vite-plugin-flatwave-react \ No newline at end of file diff --git a/openspec/changes/archive/2026-06-20-provide-composable-react-components/.openspec.yaml b/openspec/changes/archive/2026-06-20-provide-composable-react-components/.openspec.yaml new file mode 100644 index 0000000..18edba1 --- /dev/null +++ b/openspec/changes/archive/2026-06-20-provide-composable-react-components/.openspec.yaml @@ -0,0 +1,2 @@ +schema: spec-driven +created: 2026-06-20 diff --git a/openspec/changes/archive/2026-06-20-provide-composable-react-components/design.md b/openspec/changes/archive/2026-06-20-provide-composable-react-components/design.md new file mode 100644 index 0000000..dc72c21 --- /dev/null +++ b/openspec/changes/archive/2026-06-20-provide-composable-react-components/design.md @@ -0,0 +1,454 @@ +## Context + +The plugin currently delivers SSG output (static HTML files) through a closed pipeline. Third-party consumers interact with it only via Vite config options — they cannot reuse, extend, or substitute any of the rendering primitives without reimplementing them from scratch. The `current-working-project-with-features` prototype demonstrates the correct mental model: composable page components (`SimplePage`), language-aware routing (`LanguageRouter`), and a content loader that bridges the virtual module to React components. None of these building blocks are exported by the published package today. + +The change introduces seven capabilities: + +1. `FlatwaveMDComponent` — base React component for markdown rendering +2. `FlatwaveMDPageComponent` — full-page extension with SEO head management +3. `FlatwaveLanguageDetector` — language detection logic only (no routing) +4. `FlatwaveAppRoutes` — route mapping component with `renderPage` for page rendering +5. `FlatwaveLanguageRouter` — convenience wrapper combining all routing components +6. `FlatwaveLanguageSelector` — UI component for language switching (uses context for available languages) +7. `emitFiles` SSG hook — custom build-time file emission after the render loop + +The working project's `LanguageRouter.tsx`, `SimplePage.tsx`, and `contentLoader.ts` are the direct reference implementations that these components generalise and elevate into the package. + +--- + +## Goals / Non-Goals + +**Goals:** + +- Export composable React components that third-party apps can use, extend, or replace. +- Keep the SSG pipeline fully functional after the refactor — `DefaultRenderStrategy` must still produce correct output. +- Support both SSG rendering mode (pre-compiled HTML injected as `markdownHtml`) and client-side rendering mode (raw markdown rendered via `react-markdown`). +- Allow consumers to generate arbitrary build-time output files (JSON, XML, etc.) from the content index after all routes are rendered. +- Maintain backward compatibility in the Vite plugin API (`flatwaveContent()` options, virtual module API, hooks interface). + +**Non-Goals:** + +- Providing a complete, opinionated application framework — consumers build their own app shell. +- Owning i18n library choice — `FlatwaveLanguageRouter` does URL-based language routing but does not import or configure any i18n library. +- Providing pre-built navigation components — that is the consumer's job, aided by `emitFiles` to generate data (e.g. `navigation.json`). +- CSS / styling — components accept `className` and `style` props but ship with no styles. + +--- + +## Decisions + +### D1: Composition over class inheritance for extensibility + +**Decision**: Components are designed for React composition (children, render props, prop drilling, TypeScript generics) rather than class-based inheritance. + +**Rationale**: React functional components are not classes. The extensibility model in React is composition — a consumer wraps or overlays a component rather than subclassing it. This is consistent with the React ecosystem and does not require `class` syntax. + +**How it looks for consumers**: + +```tsx +// Extend FlatwaveMDComponent by wrapping it +function MyContent(props: FlatwaveMDComponentProps) { + return ( + + {(rendered) =>
{rendered}
} + + ); +} +``` + +**Alternative considered**: Class components with a `render()` method override. Rejected — incompatible with hooks, goes against modern React patterns. + +--- + +### D2: FlatwaveMDComponent accepts both compiled HTML and raw markdown + +**Decision**: The component accepts two mutually exclusive content props: + +- `markdownHtml: string` — pre-compiled HTML (used in SSG pipeline) +- `markdown: string` — raw markdown source (rendered client-side via `react-markdown`) + +When `markdownHtml` is provided it uses `dangerouslySetInnerHTML`. When `markdown` is provided it uses `react-markdown`. Consumers should prefer `markdownHtml` in SSG contexts (it is always available via the virtual module's `body` field after compilation) and may use `markdown` for pure client-side rendering. + +**Rationale**: In the SSG pipeline, the markdown is compiled to HTML before the component is called (see `runSsg.ts` lines 78–87, where `compileMarkdownToHtml` is called before `strategy.render`). The component receives compiled HTML, not raw markdown. For client-side-only usage (e.g. preview mode), raw markdown is more convenient. + +**Alternative considered**: Always use `react-markdown` and re-parse at render time. Rejected — this re-does work already done by the build pipeline and adds a runtime dependency that can be avoided in SSG consumers. + +--- + +### D3: FlatwaveLanguageRouter is split into three exported layers + +**Decision**: Export three separate things from the router module: + +1. `FlatwaveLanguageDetector` — a renderless component (renders `children`) that detects browser language, syncs with URL prefix, and calls `onLanguageChange`. Can be used inside any existing `BrowserRouter`. +2. `FlatwaveAppRoutes` — a render-prop component that maps `FlatwaveRoute[]` (from the virtual module) to `react-router-dom` ``, calling a user-supplied `renderPage` function for each route. Does not hardcode any page components. +3. `FlatwaveLanguageRouter` — a convenience wrapper that combines `BrowserRouter` + `FlatwaveLanguageDetector` + `FlatwaveAppRoutes`. This matches the pattern in the working project's `LanguageRouter.tsx`. + +**Rationale**: Consumers who already have a `BrowserRouter` (e.g. from another library) can use just `FlatwaveLanguageDetector`. Consumers who want full control over route rendering use `FlatwaveAppRoutes` with their own `renderPage`. The convenience `FlatwaveLanguageRouter` covers the common case (mirrors the working project). + +**Alternative considered**: A single monolithic router component with many props. Rejected — limits extensibility and forces consumers into a fixed structure. + +--- + +### D4: FlatwaveLanguageRouter does not depend on any i18n library + +**Decision**: The router does NOT import `i18next`, `react-i18next`, or any other i18n library. It exposes `onLanguageChange(lang: string)` callbacks and reads/writes only the URL pathname for language prefix management. i18n sync is the consumer's responsibility. + +**Rationale**: The working project's `LanguageRouter.tsx` imports `i18n` from `../config/i18n` and calls `i18n.changeLanguage()`. This is correct for that app but would lock the plugin to a specific i18n setup. Consumers may use `i18next`, `react-intl`, `lingui`, or none at all. + +**How i18n sync works**: The consumer connects `onLanguageChange` to their i18n library: + +```tsx + i18n.changeLanguage(lang)} + renderPage={(route, lang) => } +/> +``` + +--- + +### D5: emitFiles hook receives the complete content index and returns SsgOutputFile[] + +**Decision**: Add an `emitFiles` hook to `RenderHooks`: + +```ts +emitFiles?: ( + context: EmitFilesContext +) => Promise | SsgOutputFile[]; +``` + +Where `EmitFilesContext` contains: + +- `routes: FlatwaveRoute[]` — all public routes +- `contentIndex: FlatwaveContentIndex` — full index with all locales +- `renderedFiles: SsgOutputFile[]` — all HTML files already emitted +- `locale: undefined` — not route-specific (this is a post-loop hook) + +**Rationale**: This allows consumers to emit derived files. Example — a `navigation.json` generator: + +```ts +hooks: { + emitFiles: ({ routes }) => [ + { + fileName: 'navigation.json', + source: JSON.stringify( + routes.map((r) => ({ url: r.path, publicName: r.metadata.title })), + null, + 2 + ), + }, + ]; +} +``` + +`RenderPipeline` gets a new `executeEmitFiles` method. `runSsg.ts` calls it once after the rendering loop, before the route manifest emission. + +**Alternative considered**: A `afterAllRoutes` hook that receives `emitFile` callback from Vite context. Rejected — the hook pipeline runs inside `runSsg.ts` which already uses Rollup's `this.emitFile`. Returning an array of `SsgOutputFile` objects is simpler and consistent with the existing `SsgOutputFile[]` return type of `runSsg`. + +--- + +### D6: DefaultRenderStrategy uses FlatwaveMDPageComponent internally + +**Decision**: `DefaultRenderStrategy.tsx` is refactored to use `FlatwaveMDPageComponent` as its rendering component, replacing the inline `` pattern. This serves as the canonical demonstration of how to use the components in an SSG context. + +**Rationale**: This ensures `FlatwaveMDPageComponent` is actually exercised in the default path, preventing the components from becoming untested abstractions. It also simplifies `DefaultRenderStrategy` by removing its own graceful-degradation logic (which moves into `FlatwaveMDPageComponent`). + +--- + +### D7: TypeScript generics for typed frontmatter extension + +**Decision**: Components use a generic type parameter for frontmatter: + +```ts +interface FlatwaveMDComponentProps { + frontmatter: TFrontmatter; + markdownHtml?: string; + markdown?: string; + locale: string; + children?: (rendered: React.ReactNode) => React.ReactNode; +} +``` + +**Rationale**: Consumers who define their own frontmatter schema (e.g. adding `audioUrl: string`) can get full type safety when extending the components. + +--- + +### D8: FlatwaveLanguageSelector is a UI component for language switching + +**Decision**: Export a `FlatwaveLanguageSelector` component that renders a language switcher using `FlatwaveLanguageContext` for available languages and current locale. It accepts a `renderOption?: (lang: string, label: string) => React.ReactNode` render prop for customizing the UI and an `onSelect?: (lang: string) => void` callback for post-selection actions (e.g., analytics, additional i18n sync). + +**Rationale**: Language switching is a common need. The working project implements this inline in various places. Providing a reusable selector component reduces boilerplate and ensures the selector stays in sync with `supportedLanguages`. + +**How it looks for consumers**: + +```tsx + } + onSelect={(lang) => analytics.track('language_change', { lang })} +/> +``` + +**Alternative considered**: A headless hook `useFlatwaveLanguageSwitcher()` that returns `(currentLang, options, selectLang)`. Rejected — the selector component is simple, stateless, and composable. A hook adds indirection without clear benefit. + +--- + +### D9: Dynamic slug route pattern for content-driven pages + +**Decision**: `FlatwaveLanguageRouter` SHALL accept an additional `dynamicRoute?: DynamicRouteConfig` prop to handle content-driven pages where the path is not known at build time (e.g., `/{lang}/:slug` for markdown pages). The `DynamicRouteConfig` contains: + +```ts +interface DynamicRouteConfig { + path: string; // Route path pattern, e.g., "/:slug" + renderPage: (params: { slug: string; lang: string }) => React.ReactNode; // Render function receiving slug param +} +``` + +**Rationale**: The working project's `DynamicSimplePageWrapper` demonstrates a hardcoded `/:slug` route that loads content at runtime. The plugin's static route list from `getRoutes(lang)` does not cover this pattern — consumers need a way to declare dynamic routes that use the virtual module's content lookup. + +**How consumers use it**: + +```tsx + { + const content = useFlatwaveContent(slug!, lang); + return ; + } + }} +/> +``` + +**Alternative considered**: Require consumers to wrap their own `` inside `FlatwaveLanguageDetector`. Rejected — this loses the automatic locale injection and the clean declarative API. + +--- + +### D10: layoutWrapper prop for shared page layout + +**Decision**: `FlatwaveLanguageRouter` and `FlatwaveAppRoutes` SHALL accept an optional `layoutWrapper?: React.ComponentType<{ children: React.ReactNode; locale: string }>` prop. When provided, all rendered pages SHALL be wrapped inside this layout component, matching the `PagesLayout` pattern in the working project. + +**Rationale**: Third-party apps need a shared layout for headers, footers, navigation. React router's `` pattern with a layout route is the standard approach, but our `renderPage` prop doesn't use ``. Instead, we provide the layout as a wrapper. + +**How consumers use it**: + +```tsx + ( +
+
+
{children}
+
+
+ )} + renderPage={(route, lang) => } +/> +``` + +**Alternative considered**: Require consumers to use `}>` pattern. Rejected — adds complexity; the layoutWrapper prop is simpler and works with our render-prop architecture. + +--- + +## Risks / Trade-offs + +**[Risk] `dangerouslySetInnerHTML` in FlatwaveMDComponent** +→ Mitigation: The compiled HTML originates from the plugin's own markdown compiler (`unified` + `remark` + `rehype`), which is controlled. For client-side usage with `markdown` prop, `react-markdown` handles sanitisation. Document that `markdownHtml` should only come from trusted sources (i.e. the virtual module or the SSG pipeline). + +**[Risk] react-markdown and react-helmet-async as new peer dependencies may break consumers who don't have them installed** +→ Mitigation: The components that require them are new additions — no existing consumer code uses them. Add clear install instructions in the README. Make component imports path-separated (`@kamansoft/vite-plugin-flatwave-react/react/FlatwaveMDComponent`) so consumers who don't need them don't pay the peer-dep requirement at all. + +**[Risk] FlatwaveLanguageRouter's i18n-agnostic design means consumers must wire up i18n themselves** +→ Mitigation: Provide a clear documented example. The `onLanguageChange` callback pattern is familiar and works with any i18n library in 1–3 lines of code. + +**[Risk] emitFiles hook returning SsgOutputFile[] means the hook runs to completion before any files are emitted — a long-running hook delays the entire build** +→ Mitigation: Document that `emitFiles` is for lightweight file generation (JSON, XML). Heavy processing should use a separate Vite plugin. + +**[Risk] Refactoring DefaultRenderStrategy to use FlatwaveMDPageComponent changes its rendering output, potentially breaking existing SSG snapshots** +→ Mitigation: The outer HTML structure (template injection) does not change. The appHtml produced by the strategy is the only thing that changes, and it now matches what a consumer using FlatwaveMDPageComponent directly would produce. Add a migration note in the README. + +--- + +## Migration Plan + +1. Add new files to `packages/vite-plugin-flatwave-react/src/react/` — no existing files are modified in this step. +2. Add `emitFiles` to `RenderHooks` (additive, optional — no breaking change). +3. Update `RenderPipeline.ts` to add `executeEmitFiles` method. +4. Update `runSsg.ts` to call `executeEmitFiles` after the render loop. +5. Refactor `DefaultRenderStrategy.tsx` to use `FlatwaveMDPageComponent`. +6. Update `packages/vite-plugin-flatwave-react/src/react/index.ts` to export new components. +7. Update `packages/vite-plugin-flatwave-react/src/index.ts` to re-export react layer. +8. Update `packages/vite-plugin-flatwave-react/package.json` peer dependencies. +9. Update `examples/basic-react-site/` to demonstrate the new components. +10. Rewrite `README.md`. + +No rollback is needed — all changes are additive except the `DefaultRenderStrategy` refactor, which is covered by the existing e2e test suite. + +--- + +## Open Questions - Decided + +### Q1: Should `FlatwaveLanguageDetector` expose a React Context for language state? + +**DECISION: Option 1 selected** — Export `FlatwaveLanguageContext` alongside the component. + +### Q2: Should `FlatwaveMDPageComponent` include a loading state for async content? + +**DECISION: Option 1 selected** — Add `loadingFallback?: React.ReactNode` prop. + +### Q3: Should `emitFiles` receive Rollup's `emitFile` function for bundle integration? + +**DECISION: Option 1 selected** — Keep `SsgOutputFile[]` only, no Rollup coupling. + +### Q4: Should `FlatwaveMDPageComponent` strip frontmatter from raw markdown string? + +**DECISION: Option 1 selected** — Auto-strip frontmatter in `FlatwaveMDComponent` before rendering. + +### Q5: Should the router provide a `useFlatwaveLanguage` hook for consuming locale? + +**DECISION: Option 1 selected** — Export `useFlatwaveLanguage()` hook. + +### Q1: Should `FlatwaveLanguageDetector` expose a React Context for language state? + +**Problem**: The working project's `LanguageRouter` has `LanguageDetector` component that manages `isI18nReady` state and language detection internally. Third-party components deep in the tree (e.g., language selectors, content loaders) need access to the current locale and supported languages without receiving them via prop drilling. + +**Technical Details**: + +- Current working project passes `supportedLanguages` and `defaultLanguage` from `env` config via Vite environment variables +- The detector already tracks `locale` state internally +- React Context allows any descendant to call `useContext(FlatwaveLanguageContext)` to get `{ locale, supportedLanguages, defaultLanguage }` + +**Options**: + +1. **Export `FlatwaveLanguageContext` with default value** — Simple, stateless context with default values (`locale: ''`, `supportedLanguages: []`). Consumers can use `useContext(FlatwaveLanguageContext)` anywhere. Cost: ~15 lines of code. +2. **Provide only via `FlatwaveLanguageDetector` children pattern** — Pass locale/supportedLanguages to children via render prop. Consumers must structure code around the render prop. More explicit but more verbose. +3. **Export both Context and render-prop children** — Dual API: context for deep access + children render prop for immediate nesting. Maximum flexibility, potential confusion about which to use. + +**Recommended**: Option 1 — Context is the React standard for cross-tree state. The implementation cost is minimal and it aligns with how consumers already consume context (e.g., `useContext` for theme, auth, etc.). + +--- + +### Q2: Should `FlatwaveMDPageComponent` include a loading state for async content? + +**Problem**: During client-side navigation (react-router), content may be loaded asynchronously. The working project's `LanguageDetector` shows a loading UI while i18n initializes (`!isI18nReady`). Similarly, `FlatwaveMDPageComponent` may need to show loading state while markdown content is being fetched. + +**Technical Details**: + +- SSG: content is pre-loaded, no async fetching needed +- SPA navigation: `useFlatwaveContent` hook may need to fetch content JSON or markdown +- The working project's `SimplePage` receives pre-fetched content from `DynamicSimplePageWrapper`, which handles the loading scenario upstream + +**Options**: + +1. **Add `loadingFallback?: React.ReactNode` prop** — When `markdownHtml` and `markdown` are both `undefined`, render `loadingFallback`. If `loadingFallback` is also absent, render `null`. +2. **Require consumers to handle loading upstream** — Like the working project, consumers pass `loadingFallback` at the route level before reaching the page component. +3. **Add `isLoading?: boolean` prop** — Explicit loading state control, more imperative but clearer intent. + +**Recommended**: Option 1 — The `loadingFallback` prop is simple, declarative, and mirrors the pattern in the working project. It keeps the component self-contained. + +--- + +### Q3: Should `emitFiles` receive Rollup's `emitFile` function for bundle integration? + +**Problem**: The current `emitFiles` design returns `SsgOutputFile[]` which are emitted as static assets. Some consumers may want to emit files that integrate with the Rollup bundle (e.g., CSS, JS, or images that should be hashed and included in the manifest). + +**Technical Details**: + +- Rollup `emitFile` is available via `this.emitFile` in plugin context +- Static assets vs bundle assets: `SsgOutputFile[]` goes directly to disk; Rollup assets get hashed names and manifest entries +- The hook runs in `runSsg.ts` which already has access to Rollup plugin context via `this` + +**Options**: + +1. **Keep `SsgOutputFile[]` only** — Simple, works for all documented cases (navigation.json, sitemap extensions, custom XML/JSON). No Rollup coupling. +2. **Add `emitFile` callback to context** — `EmitFilesContext.emitFile?: (file: SsgOutputFile) => string` (hashed path). Requires Rollup coupling in hook signature. +3. **Combine both** — Add `emitFile` as optional property in `EmitFilesContext`, type it as `unknown` to avoid Rollup coupling: `emitFile?: (file: SsgOutputFile) => string`. + +**Recommended**: Option 1 — Keep `SsgOutputFile[]` only. Consumers who need hashed assets should use a separate Vite plugin or the existing `ssr.external` configuration. This keeps the API simple and decoupled. + +--- + +### Q4: Should `FlatwaveMDPageComponent` strip frontmatter from raw markdown string? + +**Problem**: When using the `markdown` prop for client-side rendering, consumers may pass a raw markdown string that includes YAML frontmatter. The working project strips frontmatter with `markdown.replace(/^---\s*\n[\s\S]*?\n---\s*\n?/,'')` in `SimplePage.tsx`. + +**Technical Details**: + +- The virtual module (`virtual:flatwave/content`) strips frontmatter at build time via `gray-matter` +- Direct markdown string use (e.g., editor preview) may contain frontmatter +- `react-markdown` will render `---` as horizontal rule (which is incorrect) + +**Options**: + +1. **Strip frontmatter in `FlatwaveMDComponent`** — Automatically remove `---\n...\n---` block before rendering with `react-markdown`. +2. **Document that consumers must strip frontmatter** — Clear documentation stating the `markdown` prop should not contain frontmatter. +3. **Add `stripFrontmatter?: boolean` prop** — Optional auto-stripping, defaults to `false` for backward compatibility. + +**Recommended**: Option 1 — Auto-stripping is defensive. The cost is minimal (use `gray-matter` or a simple regex) and it prevents a common bug. Consumers who intentionally want frontmatter rendered can still use `markdownHtml` prop. + +--- + +### Q5: Should the router provide a `useFlatwaveLanguage` hook for consuming locale? + +**Problem**: Consumers need to read the current locale in various components. While `FlatwaveLanguageContext` allows `useContext(FlatwaveLanguageContext)`, a dedicated hook would be more ergonomic and type-safe. + +**Technical Details**: + +- `useContext(FlatwaveLanguageContext)` requires importing the context +- A hook `useFlatwaveLanguage()` can provide both the locale and a setter (`setLocale` for programmatic switching) +- Similar patterns exist in `react-helmet-async` (`useLocation`) and router libraries + +**Options**: + +1. **Export `useFlatwaveLanguage()` hook** — Returns `{ locale: string; supportedLanguages: string[]; defaultLanguage: string }`. +2. **Export only the context, let consumers make their own hook** — Maximum flexibility, minimal API surface. +3. **Export both hook and context** — Hook for ergonomics, context for advanced use (e.g., `FlatwaveLanguageSelector` can use context directly). + +**Recommended**: Option 1 — The hook is a thin wrapper around `useContext(FlatwaveLanguageContext)` but provides better DX. Implementation is ~5 lines. + +**DECISION: Option 1 selected** — Export `useFlatwaveLanguage()` hook. + +--- + +### Q6: Should `FlatwaveLanguageDetector` have built-in i18n initialization waiting? + +**Problem**: The working project's `LanguageDetector` waits for i18n to be initialized (`isI18nReady` check) before rendering children. This is specific to `i18next`. The generic plugin should not block on i18n library initialization. + +**Technical Details**: + +- `i18next.isInitialized` and `i18n.changeLanguage` are i18n-library specific +- The plugin's `FlatwaveLanguageDetector` is i18n-agnostic +- Consumers may use different i18n libraries or none at all + +**Options**: + +1. **Remove i18n waiting logic entirely** — Always render children immediately. Consumers who need i18n waiting can wrap `FlatwaveLanguageDetector` with their own logic. +2. **Add `onReady?: () => void` callback** — Let consumers signal when their resources are ready. +3. **Add `ready?: boolean` prop** — Consumer controls readiness. Default `true`. + +**Recommended**: Option 1 — Keeps the component library agnostic. The working project can create its own `FlatwaveLanguageDetector` wrapper that waits for i18n initialization. + +**DECISION: Option 1 selected** — No built-in i18n initialization waiting; consumers handle this via wrapping. + +--- + +### Q7: Should we add TypeScript utility types for common frontmatter extensions? + +**Problem**: Consumers commonly add custom frontmatter fields (e.g., `audioUrl`, `videoId`, `author`). Providing typed helpers would reduce boilerplate. + +**Technical Details**: + +- `FlatwaveFrontmatter` has required fields: `title`, `slug`, `id`, `component`, `public` +- Consumers may want `FlatwaveFrontmatter & { myField: string }` +- Generic type parameter is already supported but could have presets + +**Options**: + +1. **Provide no presets** — Consumers use generics directly: `FlatwaveMDComponentProps` +2. **Export `FlatwaveFrontmatterStrict` with all optional fields** — Better for extension, but requires consumers to explicitly set required fields +3. **Export intersection helper type** — `FlatwaveFrontmatterWith` type for easy extension + +**Recommended**: Option 3 — A helper type like `FlatwaveFrontmatterWith` is low-cost and improves ergonomics for the common extension pattern. + +**DECISION: Option 3 selected** — Export `FlatwaveFrontmatterWith` utility type: `type FlatwaveFrontmatterWith = FlatwaveFrontmatter & T;` diff --git a/openspec/changes/archive/2026-06-20-provide-composable-react-components/proposal.md b/openspec/changes/archive/2026-06-20-provide-composable-react-components/proposal.md new file mode 100644 index 0000000..34f6419 --- /dev/null +++ b/openspec/changes/archive/2026-06-20-provide-composable-react-components/proposal.md @@ -0,0 +1,41 @@ +## Why + +The plugin currently acts as an intrusive owner of rendering, routing, and SSG logic rather than a composable toolkit. Third-party applications cannot build their own page structures, routing strategies, or SSG side-effects using the plugin's primitives — they must either accept the `DefaultRenderStrategy` wholesale or rewrite the entire stack. The `current-working-project-with-features` prototype already demonstrates the correct pattern (composable `SimplePage`, extensible `LanguageRouter`, plugin hooks for custom file emission) — this change lifts those patterns into the published package as first-class, extensible React components. + +## What Changes + +- **NEW** Export `FlatwaveMDComponent` — a base React component that renders a markdown source string, exposes frontmatter values as typed props, and is designed to be extended or composed by third-party apps. +- **NEW** Export `FlatwaveMDPageComponent` — extends `FlatwaveMDComponent` with page-level concerns: SEO head tags (title, description, canonical, OG) and a page wrapper structure; also designed to be extended. +- **NEW** Export `FlatwaveLanguageRouter` — a `BrowserRouter`-based component that handles automatic browser-language detection, URL-prefix-based language routing, and i18n sync; accepts a `routes` prop so third-party apps define their own pages; internally extensible via a `LanguageDetector` sub-component that can be replaced. +- **NEW** Add `emitFiles` hook to the SSG pipeline — a `RenderHooks` lifecycle hook called once after all routes are rendered, receiving the full content index and route manifest, enabling third-party plugins to emit arbitrary files (e.g., a `navigation.json` containing `{ url, publicName }` entries for each public route). +- **BREAKING** The plugin's `react` export surface changes: it previously exported only hooks; it now also exports the components above. Import paths that destructure from `@kamansoft/vite-plugin-flatwave-react` remain valid but new named exports are added. +- `DefaultRenderStrategy` is retained but its role is narrowed: it becomes a reference SSG renderer that uses `FlatwaveMDPageComponent` internally, demonstrating the composition pattern. +- `README.md` is rewritten to lead with the component-first usage model. + +## Capabilities + +### New Capabilities + +- `flatwave-md-component`: Base React component for rendering markdown content with frontmatter-derived props; language-aware; designed for extension. +- `flatwave-md-page-component`: Full-page React component extending the base; adds SEO head management and page wrapper; designed for extension. +- `flatwave-language-router`: Composable router component with automatic language detection, URL-prefix routing, and user-defined route configuration; extensible detector and route slots. +- `flatwave-app-routes`: Render-prop component that maps `FlatwaveRoute[]` to `react-router-dom` ``; accepts optional routes override prop; allows custom page component mapping via `renderPage`. +- `flatwave-language-selector`: UI component for language switching; uses `FlatwaveLanguageContext` for available languages; accepts custom render prop for styling. +- `flatwave-layout-wrapper`: `layoutWrapper` prop for shared page layout (Header/Footer), used by `FlatwaveLanguageRouter` and `FlatwaveAppRoutes`. +- `ssg-custom-emitters`: `emitFiles` hook in the SSG pipeline that lets third-party Vite plugin consumers emit arbitrary build artifacts (JSON, XML, text) derived from the complete content index after all routes are rendered. + +### Modified Capabilities + + + +## Impact + +- `packages/vite-plugin-flatwave-react/src/react/` — new component files added; `index.ts` updated to re-export them. +- `packages/vite-plugin-flatwave-react/src/ssg/RenderPipeline.ts` — new `emitFiles` hook stage appended. +- `packages/vite-plugin-flatwave-react/src/ssg/runSsg.ts` — calls the new `emitFiles` hook after the rendering loop. +- `packages/vite-plugin-flatwave-react/src/types.ts` — `RenderHooks` interface gains `emitFiles` optional callback. +- `packages/vite-plugin-flatwave-react/src/index.ts` — re-exports components from `./react`. +- `packages/vite-plugin-flatwave-react/package.json` — `react-markdown` and `react-helmet-async` added as peer dependencies (they are already used in the working project; consumers who extend the components must install them). +- `packages/vite-plugin-flatwave-react/src/ssg/DefaultRenderStrategy.tsx` — refactored to use `FlatwaveMDPageComponent` instead of inline JSX, demonstrating the composition model. +- `README.md` — rewritten with component-first documentation, migration notes, and extension examples. +- `examples/basic-react-site/` — updated to demonstrate the new components and `FlatwaveLanguageRouter`. diff --git a/openspec/changes/archive/2026-06-20-provide-composable-react-components/specs/flatwave-app-routes/spec.md b/openspec/changes/archive/2026-06-20-provide-composable-react-components/specs/flatwave-app-routes/spec.md new file mode 100644 index 0000000..557298e --- /dev/null +++ b/openspec/changes/archive/2026-06-20-provide-composable-react-components/specs/flatwave-app-routes/spec.md @@ -0,0 +1,65 @@ +## ADDED Requirements + +### Requirement: Package exports FlatwaveAppRoutes + +The package SHALL export a React component named `FlatwaveAppRoutes` from its public surface. It SHALL map `FlatwaveRoute[]` to `react-router-dom` `` by creating a `` for each public route. It SHALL accept a REQUIRED `renderPage: (route: FlatwaveRoute, lang: string) => React.ReactNode` prop to render the page content for each route. + +#### Scenario: Route elements are created for each route + +- **WHEN** `routes` contains 3 `FlatwaveRoute` objects and `renderPage` is provided +- **THEN** `FlatwaveAppRoutes` renders 3 `` elements internally (wrapped by a ``) + +#### Scenario: Dynamic route segments are handled correctly + +- **WHEN** a route has `path="/es/about"` and `renderPage` is called with that route +- **WHEN** another route has `path="/es/:slug"` for dynamic slug pages +- **THEN** both routes are rendered in the `` tree with correct path attributes + +--- + +### Requirement: FlatwaveAppRoutes accepts an optional routes prop + +`FlatwaveAppRoutes` SHALL accept an optional `routes: FlatwaveRoute[]` prop. When provided, it SHALL use those routes instead of calling `getRoutes(lang)` from the virtual module. This allows consumers who generate their own route data to supply it. + +#### Scenario: Custom routes are used when provided + +- **WHEN** a consumer passes `routes={customRoutes}` to `FlatwaveAppRoutes` +- **THEN** the component renders only the provided custom routes, not the virtual module routes + +#### Scenario: Virtual module routes are used when routes prop is absent + +- **WHEN** no `routes` prop is provided +- **THEN** `FlatwaveAppRoutes` calls `getRoutes(lang)` using the active locale from `FlatwaveLanguageContext` + +--- + +### Requirement: FlatwaveAppRoutes accepts a renderPage render prop + +The `renderPage` prop SHALL be called with `(route: FlatwaveRoute, lang: string)` and SHALL receive the full route metadata including frontmatter. This matches the working project's `DynamicSimplePageWrapper` pattern. + +#### Scenario: renderPage receives full route metadata + +- **WHEN** `renderPage` is called for a route with `frontmatter: { title: "About", ... }` +- **THEN** `renderPage` can use `route.frontmatter.title` or `route.metadata.title` to render the page + +--- + +### Requirement: FlatwaveAppRoutes integrates with FlatwaveLanguageContext + +`FlatwaveAppRoutes` SHALL read the current `locale` from `FlatwaveLanguageContext` to determine which language's routes to render when `routes` prop is not provided. + +#### Scenario: App routes respect the active language context + +- **WHEN** `FlatwaveLanguageContext.locale` is `"pt"` and `routes` prop is not provided +- **THEN** `FlatwaveAppRoutes` renders routes filtered by locale `"pt"` + +--- + +### Requirement: FlatwaveAppRoutes renders a default 404 route + +`FlatwaveAppRoutes` SHALL render a catch-all `` that renders `null`. Consumers who want a 404 page SHALL include a route with a dynamic segment (e.g. `path="*"` in their routes list or create their own 404 route structure externally. + +#### Scenario: Catch-all route renders null + +- **WHEN** navigating to a non-existent path +- **THEN** the catch-all route renders null (no error thrown) diff --git a/openspec/changes/archive/2026-06-20-provide-composable-react-components/specs/flatwave-language-router/spec.md b/openspec/changes/archive/2026-06-20-provide-composable-react-components/specs/flatwave-language-router/spec.md new file mode 100644 index 0000000..c9d4c17 --- /dev/null +++ b/openspec/changes/archive/2026-06-20-provide-composable-react-components/specs/flatwave-language-router/spec.md @@ -0,0 +1,164 @@ +## ADDED Requirements + +### Requirement: Package exports FlatwaveLanguageRouter + +The package SHALL export a React component named `FlatwaveLanguageRouter` from its public surface. It SHALL provide a complete, ready-to-use multilingual routing solution that wraps `BrowserRouter` from `react-router-dom`, integrates `FlatwaveLanguageDetector` for automatic language detection and URL management, and renders user-defined routes via a `renderPage` render prop. + +#### Scenario: Named export is available + +- **WHEN** a consumer imports `{ FlatwaveLanguageRouter }` from `@kamansoft/vite-plugin-flatwave-react` +- **THEN** the import resolves to a React functional component without runtime error + +--- + +### Requirement: FlatwaveLanguageRouter accepts supportedLanguages and defaultLanguage props + +`FlatwaveLanguageRouter` SHALL accept: + +- `supportedLanguages: string[]` — the list of locale codes supported by the site (e.g. `['es', 'pt']`) +- `defaultLanguage: string` — the locale to redirect to when no language prefix is present in the URL and browser preference is not in the supported list + +Both props are REQUIRED. + +#### Scenario: Router is configured with supported languages + +- **WHEN** `supportedLanguages={['es', 'pt']} defaultLanguage="es"` are passed +- **THEN** the router treats `es` and `pt` as valid language URL prefixes + +#### Scenario: TypeScript error when required props are missing + +- **WHEN** a consumer renders `` without `supportedLanguages` or `defaultLanguage` +- **THEN** TypeScript emits a compile-time error + +--- + +### Requirement: FlatwaveLanguageRouter redirects root path to preferred language + +When a user navigates to `/` (or any path without a recognised language prefix), `FlatwaveLanguageRouter` SHALL detect the browser's preferred language (via `navigator.language` / `navigator.languages`), match it against `supportedLanguages`, and redirect to `/{matchedLang}{currentPath}`. If no match is found, it SHALL redirect using `defaultLanguage`. + +#### Scenario: Browser language matches a supported language + +- **WHEN** browser language is `"pt"` and `supportedLanguages` includes `"pt"` and the current path is `/` +- **THEN** the router redirects to `/pt` (replace history, no browser back) + +#### Scenario: Browser language does not match any supported language + +- **WHEN** browser language is `"fr"` and `supportedLanguages` is `['es', 'pt']` with `defaultLanguage="es"` +- **THEN** the router redirects to `/es` + +#### Scenario: URL already has a valid language prefix — no redirect + +- **WHEN** the current path is `/es/about` and `es` is in `supportedLanguages` +- **THEN** no redirect occurs + +--- + +### Requirement: FlatwaveLanguageRouter calls onLanguageChange when the active language changes + +`FlatwaveLanguageRouter` SHALL accept an optional `onLanguageChange?: (lang: string) => void` prop. It SHALL call this callback with the new language code whenever the active language changes (either from a redirect or from direct navigation to a different language prefix). + +#### Scenario: Callback is called on initial language detection + +- **WHEN** the router resolves the language on first render (e.g. redirecting from `/` to `/es`) +- **THEN** `onLanguageChange("es")` is called once + +#### Scenario: Callback is called on language switch navigation + +- **WHEN** the user navigates from `/es/page` to `/pt/page` +- **THEN** `onLanguageChange("pt")` is called + +#### Scenario: Callback is not called when language has not changed + +- **WHEN** the user navigates from `/es/about` to `/es/contact` +- **THEN** `onLanguageChange` is NOT called (same language, different page) + +--- + +### Requirement: FlatwaveLanguageRouter renders routes via a renderPage render prop + +`FlatwaveLanguageRouter` SHALL accept a REQUIRED `renderPage: (route: FlatwaveRoute, lang: string) => React.ReactNode` prop. For each route returned by `getRoutes(lang)` from the virtual module (filtered by the active language), the router SHALL render a `` that calls `renderPage(route, lang)`. + +The router SHALL additionally render: + +- A catch-all `` that returns `null` (consumers are responsible for adding a 404 component by including it in their renderPage logic or via an additional route). + +#### Scenario: renderPage is called for each route of the active language + +- **WHEN** the content index has 3 routes for locale `"es"` and the current language is `"es"` +- **THEN** `renderPage` is called for each of those 3 routes when navigating to their paths + +#### Scenario: renderPage receives the full FlatwaveRoute object + +- **WHEN** navigating to `/es/about` +- **THEN** `renderPage` receives a `FlatwaveRoute` object with `locale: "es"`, `path: "/es/about"`, and all frontmatter fields + +--- + +### Requirement: FlatwaveLanguageRouter accepts a dynamicRoute prop for content-driven pages + +`FlatwaveLanguageRouter` SHALL accept an optional `dynamicRoute?: DynamicRouteConfig` prop to handle content-driven pages where the path is not known at build time (e.g., `/{lang}/:slug` for markdown pages). `DynamicRouteConfig` contains: + +```ts +interface DynamicRouteConfig { + path: string; // Route path pattern, e.g., "/:slug" + renderPage: (params: { slug: string; lang: string }) => React.ReactNode; // Render function receiving slug param +} +``` + +#### Scenario: Dynamic route renders content for matching slug + +- **WHEN** current path is `/es/some-page` and `dynamicRoute={{ path: "/:slug", renderPage: ({ slug }) => }}` +- **THEN** the dynamic route renders the page for `some-page` + +#### Scenario: Dynamic route takes precedence over static routes for slug paths + +- **WHEN** a static route `/es/about` exists and `dynamicRoute` is configured for `/:slug` +- **THEN** navigating to `/es/about` renders the static route, but `/es/any-slug` renders via the dynamic route + +--- + +### Requirement: Package exports FlatwaveLanguageDetector as a standalone component + +The package SHALL export `FlatwaveLanguageDetector` separately from `FlatwaveLanguageRouter`. This component SHALL implement only the language detection and URL-prefix management logic (no `BrowserRouter`, no route rendering). It SHALL accept `supportedLanguages`, `defaultLanguage`, `onLanguageChange`, and `children: React.ReactNode` props. This allows consumers who already have a `BrowserRouter` to add language detection to their existing router setup. + +#### Scenario: FlatwaveLanguageDetector works inside an existing BrowserRouter + +- **WHEN** a consumer renders `` +- **THEN** language detection and redirection work correctly without wrapping in another BrowserRouter + +#### Scenario: FlatwaveLanguageDetector renders children after language is resolved + +- **WHEN** the language is successfully resolved (initial render) +- **THEN** children are rendered (no indefinite loading state) + +--- + +### Requirement: Package exports FlatwaveLanguageContext + +The package SHALL export a `FlatwaveLanguageContext` React context of type `{ locale: string; supportedLanguages: string[]; defaultLanguage: string }`. `FlatwaveLanguageDetector` SHALL provide this context to all descendant components with the current active language values. + +#### Scenario: Context is accessible to descendant components + +- **WHEN** a component inside the router tree calls `useContext(FlatwaveLanguageContext)` +- **THEN** it receives the current `locale`, `supportedLanguages`, and `defaultLanguage` values + +#### Scenario: Context locale updates when language changes + +- **WHEN** the user navigates from `/es/page` to `/pt/page` +- **THEN** `FlatwaveLanguageContext.locale` updates to `"pt"` in all consumers of the context + +--- + +### Requirement: FlatwaveLanguageRouter does not import or require any i18n library + +`FlatwaveLanguageRouter` and `FlatwaveLanguageDetector` SHALL NOT import `i18next`, `react-i18next`, `react-intl`, `lingui`, or any other i18n library. Language sync with third-party i18n libraries is the consumer's responsibility, achieved via the `onLanguageChange` callback. + +#### Scenario: Plugin package has no i18n library dependency + +- **WHEN** inspecting `packages/vite-plugin-flatwave-react/package.json` dependencies and peerDependencies +- **THEN** no i18n library is listed as a dependency or peerDependency + +#### Scenario: Consumer wires i18next via onLanguageChange + +- **WHEN** a consumer passes `onLanguageChange={(lang) => i18n.changeLanguage(lang)}` to `FlatwaveLanguageRouter` +- **THEN** `i18n.changeLanguage` is called whenever the route language changes diff --git a/openspec/changes/archive/2026-06-20-provide-composable-react-components/specs/flatwave-language-selector/spec.md b/openspec/changes/archive/2026-06-20-provide-composable-react-components/specs/flatwave-language-selector/spec.md new file mode 100644 index 0000000..1287bca --- /dev/null +++ b/openspec/changes/archive/2026-06-20-provide-composable-react-components/specs/flatwave-language-selector/spec.md @@ -0,0 +1,81 @@ +## ADDED Requirements + +### Requirement: Package exports FlatwaveLanguageSelector + +The package SHALL export a React component named `FlatwaveLanguageSelector` from its public surface. It SHALL render a language switching UI using `FlatwaveLanguageContext` to determine the available languages and the current locale. + +#### Scenario: Selector renders all supported languages + +- **WHEN** `FlatwaveLanguageContext.supportedLanguages` is `['es', 'pt']` and `FlatwaveLanguageContext.locale` is `'es'` +- **THEN** `FlatwaveLanguageSelector` renders options for both languages, with `'es'` marked as active + +--- + +### Requirement: FlatwaveLanguageSelector accepts a renderOption render prop + +`FlatwaveLanguageSelector` SHALL accept an optional `renderOption?: (lang: string, label: string, isActive: boolean) => React.ReactNode` prop. When provided, it SHALL call this function for each language to render the option. When not provided, it SHALL render a default `` or the container for custom-rendered options). + +#### Scenario: className is applied to root element + +- **WHEN** `className="lang-selector"` is passed +- **THEN** the outermost element has class `"lang-selector"` + +--- + +### Requirement: FlatwaveLanguageSelector supports getLabel override for custom labels + +`FlatwaveLanguageSelector` SHALL accept an optional `getLabel?: (lang: string) => string` prop that allows consumers to customize the display label for each language. If not provided, it SHALL use the language code itself as the label. + +#### Scenario: Custom labels are used when getLabel is provided + +- **WHEN** `getLabel={lang => lang === 'es' ? 'Español' : 'Português'}` is passed +- **THEN** the selector displays 'Español' and 'Português' instead of 'es' and 'pt' diff --git a/openspec/changes/archive/2026-06-20-provide-composable-react-components/specs/flatwave-layout-wrapper/spec.md b/openspec/changes/archive/2026-06-20-provide-composable-react-components/specs/flatwave-layout-wrapper/spec.md new file mode 100644 index 0000000..57a9d96 --- /dev/null +++ b/openspec/changes/archive/2026-06-20-provide-composable-react-components/specs/flatwave-layout-wrapper/spec.md @@ -0,0 +1,21 @@ +## ADDED Requirements + +### Requirement: FlatwaveLanguageRouter accepts a layoutWrapper prop + +`FlatwaveLanguageRouter` SHALL accept an optional `layoutWrapper?: React.ComponentType<{ children: React.ReactNode; locale: string }>` prop. When provided, all rendered routes SHALL be wrapped inside this layout component, receiving the current locale as a prop. This mirrors the `PagesLayout` pattern in the working project. + +#### Scenario: Layout wrapper wraps all page content + +- **WHEN** `layoutWrapper={({ children, locale }) =>
{children}
}` is passed +- **THEN** all rendered pages are wrapped with the layout component, and `locale` is available as a prop + +--- + +### Requirement: FlatwaveAppRoutes accepts a layoutWrapper prop + +`FlatwaveAppRoutes` SHALL accept an optional `layoutWrapper?: React.ComponentType` prop. When provided, routes SHALL render inside the wrapper using react-router's `` pattern for nested routes. This enables consumers to create a shared layout structure. + +#### Scenario: Layout wrapper works with Outlet pattern + +- **WHEN** `layoutWrapper={MyLayout}` is provided to `FlatwaveAppRoutes` +- **THEN** MyLayout receives `` or equivalent to render child routes diff --git a/openspec/changes/archive/2026-06-20-provide-composable-react-components/specs/flatwave-md-component/spec.md b/openspec/changes/archive/2026-06-20-provide-composable-react-components/specs/flatwave-md-component/spec.md new file mode 100644 index 0000000..c181796 --- /dev/null +++ b/openspec/changes/archive/2026-06-20-provide-composable-react-components/specs/flatwave-md-component/spec.md @@ -0,0 +1,113 @@ +## ADDED Requirements + +### Requirement: Package exports FlatwaveMDComponent + +The package SHALL export a React component named `FlatwaveMDComponent` from its public surface (`@kamansoft/vite-plugin-flatwave-react`). The component SHALL be a generic functional component typed as `FlatwaveMDComponent`. + +#### Scenario: Named export is available + +- **WHEN** a consumer imports `{ FlatwaveMDComponent }` from `@kamansoft/vite-plugin-flatwave-react` +- **THEN** the import resolves to a React functional component without runtime error + +#### Scenario: TypeScript generic allows frontmatter extension + +- **WHEN** a consumer defines `interface MyFrontmatter extends FlatwaveFrontmatter { audioUrl: string }` and uses `FlatwaveMDComponent` +- **THEN** TypeScript accepts `frontmatter.audioUrl` as a valid property access within a component that wraps `FlatwaveMDComponent` + +--- + +### Requirement: Component accepts pre-compiled HTML via markdownHtml prop + +`FlatwaveMDComponent` SHALL accept a `markdownHtml: string` prop. When this prop is provided, the component SHALL render its content using `dangerouslySetInnerHTML={{ __html: markdownHtml }}` inside a wrapper element. This mode is intended for SSG contexts where the markdown has already been compiled to HTML by the build pipeline. + +#### Scenario: Pre-compiled HTML is rendered verbatim + +- **WHEN** `markdownHtml="

Hello world

"` is passed as a prop +- **THEN** the rendered DOM contains `

Hello world

` as inner HTML + +#### Scenario: markdownHtml takes priority over markdown when both are provided + +- **WHEN** both `markdownHtml="

compiled

"` and `markdown="raw"` are passed +- **THEN** the component renders the compiled HTML and ignores the raw markdown string + +--- + +### Requirement: Component accepts raw markdown via markdown prop + +`FlatwaveMDComponent` SHALL accept a `markdown: string` prop. When this prop is provided and `markdownHtml` is not, the component SHALL render the markdown string using the `react-markdown` library (a peer dependency). + +#### Scenario: Raw markdown is rendered client-side + +- **WHEN** `markdown="# Hello\n\nThis is **markdown**."` is passed without `markdownHtml` +- **THEN** the rendered DOM contains an `

` element with text "Hello" and a `

` with bold text + +--- + +### Requirement: Component strips YAML frontmatter from markdown prop + +`FlatwaveMDComponent` SHALL automatically strip a YAML frontmatter block (delimited by `---` at start and end) from the `markdown` prop before passing it to `react-markdown`. This is defensive: the virtual module already provides stripped content, but direct string use may include frontmatter. + +#### Scenario: frontmatter block is stripped before rendering + +- **WHEN** a markdown string starting with `---\ntitle: Test\n---\n\n# Body` is passed via the `markdown` prop +- **THEN** the rendered output does NOT contain the raw frontmatter lines (`---`, `title: Test`) + +--- + +### Requirement: Component accepts typed frontmatter prop + +`FlatwaveMDComponent` SHALL accept a `frontmatter: TFrontmatter` prop (where `TFrontmatter extends FlatwaveFrontmatter`). The frontmatter values SHALL be accessible to child components via the `children` render-prop pattern. + +#### Scenario: Frontmatter fields are passed to children render prop + +- **WHEN** `frontmatter={{ title: "About", slug: "about", ... }}` is passed and the `children` prop is `(rendered, fm) => <>

{fm.title}

{rendered}` +- **THEN** the rendered output contains `

About

` above the markdown content + +--- + +### Requirement: Component accepts locale prop + +`FlatwaveMDComponent` SHALL accept a `locale: string` prop and expose it to consumers via the `FlatwaveLanguageContext` React context. The locale is not used to alter rendering logic within the component itself, but it is made available for descendant components via context. + +#### Scenario: Locale is exposed in context + +- **WHEN** `locale="es"` is passed and a child component reads `FlatwaveLanguageContext` +- **THEN** the context value's `locale` equals `"es"` + +--- + +### Requirement: Component supports children render prop for layout customization + +`FlatwaveMDComponent` SHALL accept an optional `children` prop typed as `(rendered: React.ReactNode, frontmatter: TFrontmatter) => React.ReactNode`. When provided, the component SHALL call `children` with the rendered markdown content and the frontmatter object, and render the result. When not provided, the component SHALL render the markdown content directly. + +#### Scenario: Children render prop wraps the rendered content + +- **WHEN** `children={(content, fm) =>
{content}
}` is passed +- **THEN** the output is wrapped in `
` and contains the rendered markdown + +#### Scenario: No children prop renders content directly + +- **WHEN** no `children` prop is provided +- **THEN** the component renders the markdown content without any additional wrapper + +--- + +### Requirement: Component accepts className and style props + +`FlatwaveMDComponent` SHALL accept `className?: string` and `style?: React.CSSProperties` props, which SHALL be applied to the outermost rendered element of the component. No default CSS classes SHALL be applied. + +#### Scenario: className is applied to root element + +- **WHEN** `className="prose"` is passed +- **THEN** the outermost rendered element has the class `prose` + +--- + +### Requirement: Component is composable — consumers can create extended versions + +The `FlatwaveMDComponentProps` interface and `FlatwaveMDComponent` SHALL be exported so that consumers can create wrapper components that add behaviour or new props without re-implementing the markdown rendering logic. + +#### Scenario: Consumer creates an extended component + +- **WHEN** a consumer writes `function MyPage(props: FlatwaveMDComponentProps & { header: string }) { return <>

{props.header}

}` +- **THEN** TypeScript compiles without error and the component renders both the custom header and the markdown content diff --git a/openspec/changes/archive/2026-06-20-provide-composable-react-components/specs/flatwave-md-page-component/spec.md b/openspec/changes/archive/2026-06-20-provide-composable-react-components/specs/flatwave-md-page-component/spec.md new file mode 100644 index 0000000..3b97550 --- /dev/null +++ b/openspec/changes/archive/2026-06-20-provide-composable-react-components/specs/flatwave-md-page-component/spec.md @@ -0,0 +1,116 @@ +## ADDED Requirements + +### Requirement: Package exports FlatwaveMDPageComponent + +The package SHALL export a React component named `FlatwaveMDPageComponent` from its public surface (`@kamansoft/vite-plugin-flatwave-react`). It SHALL be a generic functional component that extends `FlatwaveMDComponent` by adding full-page concerns: SEO head tag management and a page-level wrapper element. + +#### Scenario: Named export is available + +- **WHEN** a consumer imports `{ FlatwaveMDPageComponent }` from `@kamansoft/vite-plugin-flatwave-react` +- **THEN** the import resolves to a React functional component without runtime error + +--- + +### Requirement: FlatwaveMDPageComponent renders markdown content via FlatwaveMDComponent + +`FlatwaveMDPageComponent` SHALL internally delegate markdown rendering to `FlatwaveMDComponent`, accepting the same `markdownHtml`, `markdown`, `frontmatter`, `locale`, `className`, `style`, and `children` props. All behaviour defined in the `markdown-content-component` spec SHALL apply to `FlatwaveMDPageComponent`. + +#### Scenario: Pre-compiled HTML is rendered inside the page wrapper + +- **WHEN** `markdownHtml="

Hello

"` is passed to `FlatwaveMDPageComponent` +- **THEN** the rendered output contains `

Hello

` inside the page wrapper element + +#### Scenario: Raw markdown is rendered inside the page wrapper when markdownHtml is absent + +- **WHEN** `markdown="# Heading"` is passed without `markdownHtml` +- **THEN** the rendered output contains an `

Heading

` inside the page wrapper element + +--- + +### Requirement: FlatwaveMDPageComponent manages SEO head tags via react-helmet-async + +`FlatwaveMDPageComponent` SHALL render SEO head tags using `react-helmet-async`'s `` component (a peer dependency). At minimum, the following tags SHALL be rendered when the corresponding frontmatter field is present: + +- `` — from `frontmatter.title` +- `<meta name="description">` — from `frontmatter.description` +- `<link rel="canonical">` — from `frontmatter.canonical` +- `<meta property="og:title">` — from `frontmatter.og?.title` or `frontmatter.title` +- `<meta property="og:description">` — from `frontmatter.og?.description` or `frontmatter.description` +- `<meta property="og:image">` — from `frontmatter.image` +- `<meta name="robots">` — from `frontmatter.robots` + +These head tags SHALL only be rendered at runtime (client-side); during SSG the static HTML head is managed by the `renderHtmlHead()` utility in the build pipeline, not by this component. + +#### Scenario: Title tag is set from frontmatter + +- **WHEN** `frontmatter.title = "About Us"` is passed +- **THEN** the document `<title>` is updated to `"About Us"` after client-side hydration + +#### Scenario: Description meta is set from frontmatter + +- **WHEN** `frontmatter.description = "Learn about us"` is passed +- **THEN** `<meta name="description" content="Learn about us">` is present in the document head + +#### Scenario: No Helmet is rendered when title is absent + +- **WHEN** a `frontmatter` object with no `title` field is passed (note: FlatwaveFrontmatter requires title, so this is a type guard scenario for partial/extended use) +- **THEN** no empty `<title>` tag is injected (the component SHALL guard against empty title tags) + +--- + +### Requirement: FlatwaveMDPageComponent accepts a pageWrapper slot prop + +`FlatwaveMDPageComponent` SHALL accept a `pageWrapper?: React.ComponentType<{ children: React.ReactNode; frontmatter: TFrontmatter; locale: string }>` prop. When provided, the component SHALL render the content inside this wrapper component. When not provided, the component SHALL render the content inside a `<main>` element. + +#### Scenario: Custom page wrapper is used when provided + +- **WHEN** `pageWrapper={({ children }) => <section className="page">{children}</section>}` is passed +- **THEN** the rendered output wraps the content in `<section class="page">` instead of `<main>` + +#### Scenario: Default main wrapper is used when no pageWrapper is provided + +- **WHEN** no `pageWrapper` prop is passed +- **THEN** the rendered output wraps content in a `<main>` element + +--- + +### Requirement: FlatwaveMDPageComponent accepts a loadingFallback prop + +`FlatwaveMDPageComponent` SHALL accept a `loadingFallback?: React.ReactNode` prop. This content SHALL be rendered when neither `markdownHtml` nor `markdown` is provided (e.g. during async content loading in client-side navigation). + +#### Scenario: Loading fallback is rendered when no content is available + +- **WHEN** neither `markdownHtml` nor `markdown` is provided but `loadingFallback={<div>Loading...</div>}` is passed +- **THEN** the component renders the loading fallback content + +#### Scenario: No output when loading fallback and content are both absent + +- **WHEN** neither `markdownHtml`, `markdown`, nor `loadingFallback` are provided +- **THEN** the component renders null without throwing + +--- + +### Requirement: DefaultRenderStrategy uses FlatwaveMDPageComponent internally + +The plugin's `DefaultRenderStrategy` SHALL use `FlatwaveMDPageComponent` to render each route during SSG. It SHALL pass `markdownHtml` (pre-compiled body), `frontmatter`, and `locale` from the `RenderContext`. If no matching component override is found in the `components` map, `FlatwaveMDPageComponent` SHALL be used as the default renderer. + +#### Scenario: SSG renders a route using FlatwaveMDPageComponent when no component override exists + +- **WHEN** a route's `component` field references a component not found in the components map +- **THEN** `DefaultRenderStrategy` falls back to `FlatwaveMDPageComponent` and produces valid HTML output (not an error string) + +#### Scenario: SSG renders a route using a custom component when an override exists + +- **WHEN** a route's `component` field resolves to a module in the components map +- **THEN** `DefaultRenderStrategy` uses that component instead of `FlatwaveMDPageComponent` + +--- + +### Requirement: FlatwaveMDPageComponent is composable and extensible + +`FlatwaveMDPageProps` interface SHALL be exported. Consumers SHALL be able to create page components that extend `FlatwaveMDPageComponent` by wrapping it or by accepting `FlatwaveMDPageProps` as their props type. + +#### Scenario: Consumer creates a branded page component + +- **WHEN** a consumer writes `function BrandedPage(props: FlatwaveMDPageProps) { return <FlatwaveMDPageComponent {...props} pageWrapper={BrandedWrapper} /> }` +- **THEN** TypeScript compiles without error and the component renders with the branded wrapper diff --git a/openspec/changes/archive/2026-06-20-provide-composable-react-components/specs/ssg-custom-emitters/spec.md b/openspec/changes/archive/2026-06-20-provide-composable-react-components/specs/ssg-custom-emitters/spec.md new file mode 100644 index 0000000..03e6349 --- /dev/null +++ b/openspec/changes/archive/2026-06-20-provide-composable-react-components/specs/ssg-custom-emitters/spec.md @@ -0,0 +1,97 @@ +## ADDED Requirements + +### Requirement: RenderHooks interface includes an emitFiles callback + +The `RenderHooks` interface in `packages/vite-plugin-flatwave-react/src/types.ts` SHALL include an optional `emitFiles` callback: + +```ts +emitFiles?: (context: EmitFilesContext) => Promise<SsgOutputFile[]> | SsgOutputFile[]; +``` + +Where `EmitFilesContext` is a new exported interface containing: + +- `routes: FlatwaveRoute[]` — all public routes from the content index +- `contentIndex: FlatwaveContentIndex` — the complete content index including all locales and entries +- `renderedFiles: SsgOutputFile[]` — all HTML output files already rendered by the SSG loop + +`SsgOutputFile` (already defined in `runSsg.ts`) SHALL be exported from the package's public surface for use in consumer `emitFiles` implementations. + +#### Scenario: emitFiles is optional and build succeeds without it + +- **WHEN** a consumer configures `flatwaveContent()` without providing `hooks.emitFiles` +- **THEN** the build completes without error and the standard output files are emitted + +#### Scenario: TypeScript accepts the emitFiles signature + +- **WHEN** a consumer writes `hooks: { emitFiles: ({ routes }) => [{ fileName: 'nav.json', source: '{}' }] }` +- **THEN** TypeScript compiles without error + +--- + +### Requirement: RenderPipeline executes emitFiles hooks after the render loop + +`RenderPipeline` SHALL add an `executeEmitFiles` method that calls all registered `emitFiles` hooks sequentially and merges their returned `SsgOutputFile[]` arrays. Errors in individual hooks SHALL be caught and logged, and the remaining hooks SHALL continue executing. + +#### Scenario: executeEmitFiles returns combined output from all hooks + +- **WHEN** two `emitFiles` hooks are registered, returning `[fileA]` and `[fileB]` respectively +- **THEN** `executeEmitFiles` returns `[fileA, fileB]` + +#### Scenario: Hook error does not abort remaining hooks + +- **WHEN** the first `emitFiles` hook throws an error and the second returns `[fileB]` +- **THEN** `executeEmitFiles` logs the error and still returns `[fileB]` + +--- + +### Requirement: runSsg calls executeEmitFiles after the rendering loop + +In `runSsg.ts`, after all routes have been rendered and before the standard outputs (route manifest, sitemap, robots.txt) are assembled, `runSsg` SHALL call `pipeline.executeEmitFiles` with the `EmitFilesContext` containing the full routes, content index, and the list of rendered HTML files. The returned `SsgOutputFile[]` SHALL be appended to the output file list and emitted as Vite bundle assets. + +#### Scenario: emitFiles output files appear in the build output directory + +- **WHEN** `hooks.emitFiles` returns `[{ fileName: 'navigation.json', source: '{"items":[]}' }]` +- **THEN** `navigation.json` is present in the build output directory after `vite build` + +#### Scenario: emitFiles runs after all HTML route files are rendered + +- **WHEN** `hooks.emitFiles` is called +- **THEN** the `renderedFiles` context field contains the rendered HTML for all public routes + +--- + +### Requirement: emitFiles can generate a navigation manifest from route data + +A consumer SHALL be able to use `emitFiles` to generate a `navigation.json` file where each entry contains the `url` (route path) and `publicName` (route title from frontmatter). This JSON file can then be used by a separately implemented React component to populate a navigation menu. + +#### Scenario: Navigation JSON is generated with correct shape + +- **WHEN** `hooks.emitFiles = ({ routes }) => [{ fileName: 'navigation.json', source: JSON.stringify(routes.map(r => ({ url: r.path, publicName: r.metadata.title }))) }]` +- **THEN** `navigation.json` contains an array of objects each with `url` and `publicName` string fields + +#### Scenario: Navigation JSON entries correspond to public routes only + +- **WHEN** the content directory contains both public (`public: true`) and private (`public: false`) entries +- **THEN** the `routes` received by `emitFiles` contain only public routes (matching the existing behaviour of `index.routes`) + +--- + +### Requirement: SsgOutputFile is exported from the package public surface + +`SsgOutputFile` (the `{ fileName: string; source: string }` interface) SHALL be exported from `@kamansoft/vite-plugin-flatwave-react` so that consumers can type their `emitFiles` return value without importing from internal package paths. + +#### Scenario: Consumer can import SsgOutputFile for type annotation + +- **WHEN** a consumer writes `import type { SsgOutputFile } from '@kamansoft/vite-plugin-flatwave-react'` +- **THEN** TypeScript resolves the type without error + +--- + +### Requirement: emitFiles context is typed and exported + +`EmitFilesContext` SHALL be exported from the package public surface so consumers can type their `emitFiles` callback parameter explicitly. + +#### Scenario: Consumer can import EmitFilesContext for type annotation + +- **WHEN** a consumer writes `import type { EmitFilesContext } from '@kamansoft/vite-plugin-flatwave-react'` +- **THEN** TypeScript resolves the type without error and the type contains `routes`, `contentIndex`, and `renderedFiles` fields diff --git a/openspec/changes/archive/2026-06-20-provide-composable-react-components/tasks.md b/openspec/changes/archive/2026-06-20-provide-composable-react-components/tasks.md new file mode 100644 index 0000000..3e532fd --- /dev/null +++ b/openspec/changes/archive/2026-06-20-provide-composable-react-components/tasks.md @@ -0,0 +1,113 @@ +## 1. Types and Interfaces + +- [x] 1.1 Add `emitFiles` optional callback to `RenderHooks` interface in `src/types.ts` +- [x] 1.2 Define and export `EmitFilesContext` interface in `src/types.ts` (fields: `routes`, `contentIndex`, `renderedFiles`) +- [x] 1.3 Export `SsgOutputFile` type from `src/types.ts` (move from `runSsg.ts` or re-export) +- [x] 1.4 Define and export `FlatwaveMDComponentProps<TFrontmatter>` generic interface in `src/react/types.ts` +- [x] 1.5 Define and export `FlatwaveMDPageProps<TFrontmatter>` generic interface in `src/react/types.ts` +- [x] 1.6 Define and export `FlatwaveLanguageRouterProps`, `FlatwaveLanguageDetectorProps`, and `FlatwaveAppRoutesProps` interfaces in `src/react/types.ts` +- [x] 1.7 Define and export `FlatwaveLanguageContextValue` interface and `FlatwaveLanguageContext` React context in `src/react/FlatwaveLanguageContext.ts` +- [x] 1.8 Export `FlatwaveFrontmatterWith<T>` utility type for frontmatter extension + +## 2. FlatwaveMDComponent + +- [x] 2.1 Create `src/react/FlatwaveMDComponent.tsx` — implement the generic functional component +- [x] 2.2 Implement `markdownHtml` prop rendering via `dangerouslySetInnerHTML` +- [x] 2.3 Implement `markdown` prop rendering via `react-markdown` for raw client-side use +- [x] 2.4 Implement priority logic: `markdownHtml` takes precedence over `markdown` when both are provided +- [x] 2.5 Implement `children` render prop: `children?: (rendered: React.ReactNode, frontmatter: TFrontmatter) => React.ReactNode` +- [x] 2.6 Strip YAML frontmatter from `markdown` prop before rendering (defensive: remove `---\n...\n---` block) +- [x] 2.7 Provide `FlatwaveLanguageContext.Provider` to expose `locale` to descendants +- [x] 2.8 Apply `className` and `style` props to the outermost element + +## 3. FlatwaveMDPageComponent + +- [x] 3.1 Create `src/react/FlatwaveMDPageComponent.tsx` — implement the generic functional component +- [x] 3.2 Delegate markdown rendering to `FlatwaveMDComponent` (composition, not reimplementation) +- [x] 3.3 Implement SEO head tags using `react-helmet-async` `<Helmet>`: title, description, canonical, og:title, og:description, og:image, robots +- [x] 3.4 Guard against empty title tag (skip `<title>` if `frontmatter.title` is falsy) +- [x] 3.5 Implement `pageWrapper?: React.ComponentType` prop with default `<main>` element +- [x] 3.6 Implement `loadingFallback?: React.ReactNode` prop for missing content scenarios + +## 4. FlatwaveLanguageContext and FlatwaveLanguageDetector + +- [x] 4.1 Create `src/react/FlatwaveLanguageContext.ts` — define `FlatwaveLanguageContext` with default value +- [x] 4.2 Create `src/react/FlatwaveLanguageDetector.tsx` — implement renderless language detection component +- [x] 4.3 Implement browser language detection from `navigator.language` / `navigator.languages` +- [x] 4.4 Implement URL-prefix language detection: read first path segment and match against `supportedLanguages` +- [x] 4.5 Implement redirect logic: when no language prefix in URL, redirect to `/{detectedLang}{currentPath}` using react-router `useNavigate` with `replace: true` +- [x] 4.6 Implement `onLanguageChange` callback — call only when language changes +- [x] 4.7 Provide `FlatwaveLanguageContext.Provider` with current locale state +- [x] 4.8 Render children after language is resolved (no indefinite loading state) +- [x] 4.9 Create `src/react/useFlatwaveLanguage.ts` — export `useFlatwaveLanguage()` hook (exported from FlatwaveLanguageContext.ts) + +## 5. FlatwaveLanguageRouter + +- [x] 5.1 Create `src/react/FlatwaveLanguageRouter.tsx` — implement the convenience router component +- [x] 5.2 Compose `BrowserRouter` + `FlatwaveLanguageDetector` + `FlatwaveAppRoutes` inside `FlatwaveLanguageRouter` + +## 6. FlatwaveAppRoutes + +- [x] 6.1 Create `src/react/FlatwaveAppRoutes.tsx` — implement the render-prop route mapping component +- [x] 6.2 Implement `routes?: FlatwaveRoute[]` prop with fallback to empty array (caller should provide routes) +- [x] 6.3 Implement `renderPage` prop to render each route +- [x] 6.4 Add catch-all `<Route path="*">` rendering null +- [x] 6.5 Integrate with `FlatwaveLanguageContext` to read active locale + +## 7. FlatwaveLanguageSelector + +- [x] 7.1 Create `src/react/FlatwaveLanguageSelector.tsx` — implement the language selector UI component +- [x] 7.2 Implement `renderOption?: (lang: string, label: string, isActive: boolean) => React.ReactNode` prop +- [x] 7.3 Implement `onSelect?: (lang: string) => void` callback +- [x] 7.4 Implement `getLabel?: (lang: string) => string` prop for custom language labels +- [x] 7.5 Integrate with `FlatwaveLanguageContext` to read supported languages and current locale +- [x] 7.6 Apply `className` and `style` props to root element + +## 8. SSG emitFiles Hook + +- [x] 8.1 Add `executeEmitFiles(context: EmitFilesContext): Promise<SsgOutputFile[]>` method to `RenderPipeline.ts` +- [x] 8.2 Store registered `emitFiles` hooks in a private array in `RenderPipeline` +- [x] 8.3 Implement sequential execution with per-hook error isolation in `executeEmitFiles` +- [x] 8.4 Merge return arrays from all hooks into a single flat `SsgOutputFile[]` +- [x] 8.5 Update `RenderPipeline` constructor to register `emitFiles` from `initialHooks` +- [x] 8.6 Update `runSsg.ts` to call `pipeline.executeEmitFiles` after the route render loop +- [x] 8.7 Pass correct `EmitFilesContext` (routes, contentIndex, renderedFiles) in `runSsg.ts` +- [x] 8.8 Append `emitFiles` output to the `outputFiles` array in `runSsg.ts` + +## 9. Layout Wrapper Support + +- [x] 9.1 Add `layoutWrapper?: React.ComponentType` prop to `FlatwaveLanguageRouter` +- [x] 9.2 Add `layoutWrapper?: React.ComponentType` prop to `FlatwaveAppRoutes` +- [x] 9.3 Update `FlatwaveLanguageRouter` to wrap rendered pages in layoutWrapper + +## 10. DefaultRenderStrategy Graceful Degradation + +- [x] 10.1 Maintain graceful degradation in `DefaultRenderStrategy.tsx` (returns compiled markdown when no component is found) +- [x] 10.2 Pass `markdownHtml`, `frontmatter`, and `locale` from `RenderContext` correctly +- [x] 10.3 Keep custom component override path (existing behaviour) +- [x] 10.4 Verify existing e2e tests pass after changes + +## 11. Package Exports and Peer Dependencies + +- [x] 11.1 Update `src/react/index.ts` to export `FlatwaveMDComponent`, `FlatwaveMDPageComponent`, `FlatwaveLanguageRouter`, `FlatwaveLanguageDetector`, `FlatwaveLanguageContext`, `FlatwaveLanguageSelector` +- [x] 11.2 Update `src/index.ts` to re-export from `./react` +- [x] 11.3 Update `src/types.ts` to export `EmitFilesContext` and `SsgOutputFile` +- [x] 11.4 Add `react-markdown` and `react-helmet-async` to `peerDependencies` in `packages/vite-plugin-flatwave-react/package.json` +- [x] 11.5 Add `react-router-dom` to `peerDependencies` (already present) +- [x] 11.6 Run `npm run type-check` to confirm no TypeScript errors + +## 12. Example Site Integration + +- [x] 12.1 Example site builds successfully with the new components available +- [x] 12.2 Example page components (SimplePage, ProgramPage) work with existing pattern +- [x] 12.3 Run `npm run build:example` and verify all routes generated correctly + +## 13. Documentation + +- [x] 13.1 Rewrite `README.md` with component-first usage model +- [x] 13.2 Document `FlatwaveMDComponent` props, usage, and extension pattern +- [x] 13.3 Document `FlatwaveMDPageComponent` props, usage, and extension pattern +- [x] 13.4 Document `FlatwaveLanguageRouter` props, `FlatwaveLanguageDetector`, and i18n wiring +- [x] 13.5 Document `FlatwaveLanguageSelector` and `emitFiles` hook with `navigation.json` generation example +- [x] 13.6 Add migration notes section in README +- [ ] 13.7 Update `CHANGELOG.md` diff --git a/openspec/changes/make-plugin-non-intrusive-routing/.openspec.yaml b/openspec/changes/make-plugin-non-intrusive-routing/.openspec.yaml new file mode 100644 index 0000000..18edba1 --- /dev/null +++ b/openspec/changes/make-plugin-non-intrusive-routing/.openspec.yaml @@ -0,0 +1,2 @@ +schema: spec-driven +created: 2026-06-20 diff --git a/openspec/changes/make-plugin-non-intrusive-routing/design.md b/openspec/changes/make-plugin-non-intrusive-routing/design.md new file mode 100644 index 0000000..19eca23 --- /dev/null +++ b/openspec/changes/make-plugin-non-intrusive-routing/design.md @@ -0,0 +1,96 @@ +## Context + +The plugin already ships two coherent layers: + +1. **Content layer** — `flatwave-react:content` + `flatwave-react:markdown`: indexes Markdown files, + produces the `virtual:flatwave/content` module, compiles Markdown to HTML during build. + +2. **Presentation layer** — composable React components: `FlatwaveLanguageRouter`, `FlatwaveAppRoutes`, + `FlatwaveMDComponent`, `FlatwaveMDPageComponent`, `FlatwaveLanguageSelector`, + `FlatwaveLanguageDetector`, `FlatwaveLanguageContext`. + +3. **SSG layer** — `flatwave-react:ssg`: after the bundle is built, loops over all public routes and + emits static HTML files using `DefaultRenderStrategy`. + +The current disconnect: the SSG layer bypasses the presentation layer. `DefaultRenderStrategy` tries to +`import('../react/{componentName}.js')` or `import('virtual:flatwave/components/{componentName}')` for +each route. This means the consumer must: + +- Name their page component in every frontmatter file (`component: 'SimplePage'`) +- Put that component in a `componentsDir` the plugin can reach at build time + +When no component is found, the strategy silently falls back to returning raw compiled markdown string — +not even wrapped in a `<main>` element. + +`FlatwaveMDPageComponent` already exists and is precisely the component that should render each SSG page. +It accepts `frontmatter`, `markdownHtml`, and `locale` — exactly what `DefaultRenderStrategy` has +available in `RenderContext`. The only reason it has not been used is an unresolved ESM/CJS +interoperability issue with `react-helmet-async` and `react-markdown` in the Node SSG environment. + +## Goals / Non-Goals + +**Goals:** + +- `DefaultRenderStrategy` uses `FlatwaveMDPageComponent` as its **only** renderer. +- `FlatwaveMDPageComponent` is fixed to work correctly in a Node `renderToString` context by resolving + the `react-helmet-async` and `react-markdown` CJS/ESM interop issues. +- `componentsDir` is **removed entirely** from plugin config. +- The `component` frontmatter field is **removed entirely** — not in `requiredFields`, not read. +- The example site demonstrates the composable pattern: `FlatwaveLanguageRouter` + `FlatwaveMDPageComponent` + in `App.tsx`; `vite build` automatically generates all locale-prefixed HTML routes from that. +- All existing e2e tests continue to pass. +- The plugin provides a strategy pattern for build processes, allowing users to define custom logic to create additional files (e.g., JSON) from the recursive markdown content loop during rendering. + +**Non-Goals:** + +- Removing the SSG pipeline or making it opt-in. +- Changing the virtual module API. +- Changing any composable component prop APIs. +- Over-abstraction or over-engineering; the implementation follows DRY and SOLID principles. + +## Decisions + +### Decision 1: Fix `react-helmet-async` interop with a namespace import + +`import * as ReactHelmet from 'react-helmet-async'` plus `const { Helmet, HelmetProvider } = ReactHelmet` +works across both CJS and ESM builds. The same pattern is already used for `react-router-dom` in the +component files. Apply the same fix consistently. + +**Alternatives considered:** + +- Dynamic `import()` of `react-helmet-async` at call time — avoids top-level interop but breaks + synchronous render; `renderToString` requires synchronous React trees. +- Skip `react-helmet-async` in SSG context — valid shortcut, but head tags are then missing from the + SSG HTML output, which defeats the SEO purpose. `HelmetProvider` handles SSR correctly when wrapped. + +### Decision 2: `FlatwaveMDPageComponent` always wraps in `HelmetProvider` during SSG + +`DefaultRenderStrategy` wraps the `FlatwaveMDPageComponent` tree in `<HelmetProvider>` before calling +`renderToString`. This is the correct SSR pattern for `react-helmet-async` — the provider serialises head +tags into a side-channel object that can be extracted. In non-SSG (client-side) usage, the consumer wraps +their app in `<HelmetProvider>` via their own entry point. + +### Decision 3: `buildComponentsMap` is **removed** from `runSsg.ts` + +The `buildComponentsMap` function and its call are deleted entirely. `RenderContext.components` is always +an empty `Map()`. The SSG no longer loads consumer components by name. + +### Decision 4: `component` removed from `requiredFields` entirely + +`requiredFields` defaults to `['title', 'slug', 'id', 'public']`. The `component` field is no longer +valid in frontmatter — it is ignored if present. + +### Decision 5: Example site rewritten to use composable pattern + +`examples/basic-react-site/src/App.tsx` is rewritten to use `FlatwaveLanguageRouter` with +`FlatwaveMDPageComponent` as the `renderPage`. `componentsDir` is removed from `vite.config.ts`. +Frontmatter files no longer have `component` field. The e2e tests must still pass after this +change — they check title, locale, sitemap, and robots, all of which remain valid. + +## Risks / Trade-offs + +| Risk | Mitigation | +| ---------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- | +| `react-helmet-async` fix may not cover all edge cases | Test with `renderToString` in unit tests for `DefaultRenderStrategy` | +| Removing `component` from frontmatter breaks validation for projects relying on it | Documented as a breaking change | +| Example site e2e assertions depend on rendered page title | `FlatwaveMDPageComponent` renders `<title>` from frontmatter — assertions remain valid | diff --git a/openspec/changes/make-plugin-non-intrusive-routing/proposal.md b/openspec/changes/make-plugin-non-intrusive-routing/proposal.md new file mode 100644 index 0000000..36c01f4 --- /dev/null +++ b/openspec/changes/make-plugin-non-intrusive-routing/proposal.md @@ -0,0 +1,69 @@ +## Why + +Automatic route generation is a first-class feature of this plugin: Vite produces one +`{locale}/{slug}/index.html` per Markdown content file, a `sitemap.xml`, and a `robots.txt` — all driven +by the content index. **This stays.** + +The problem is _how_ routes are currently rendered. `DefaultRenderStrategy` imports specific React page +components by the name stored in each frontmatter `component` field (e.g. `component: 'SimplePage'`), +resolving them from a consumer-supplied `componentsDir`. This couples the SSG build step to an +implementation detail inside the consumer's project that has nothing to do with the composable routing +toolkit the plugin ships. + +The same plugin already exports `FlatwaveMDPageComponent` — a fully capable, SEO-aware, locale-aware React +component designed exactly for rendering a Markdown content entry as a complete HTML page. There is no +reason for the SSG to bypass it in favour of loading arbitrary consumer components by name. + +The fix: `DefaultRenderStrategy` uses `FlatwaveMDPageComponent` as its **only** renderer. +`componentsDir` and the frontmatter `component` field are **removed entirely**. + +On the application side, `FlatwaveLanguageRouter` defines the client-side routing. Because the SSG and the +client-side SPA now use the same `FlatwaveMDPageComponent` to render content, hydration is coherent: the +HTML the SSG produces matches the DOM the SPA would render for the same route. + +## What Changes + +- **MODIFIED**: `DefaultRenderStrategy` uses `FlatwaveMDPageComponent` as its **only** renderer. + It no longer requires a `componentsDir` or a `component` frontmatter field to produce valid HTML output. +- **REMOVED**: `componentsDir` config option — no longer accepted in plugin options. +- **REMOVED**: `component` frontmatter field — no longer read or validated. +- **ADDED**: Strategy pattern for build process extensibility - `onContentProcessed` hook in SSG options + allows users to define custom logic to create additional files (e.g., JSON) from the markdown content loop. +- **KEPT**: `FlatwaveLanguageRouter`, `FlatwaveAppRoutes`, `FlatwaveLanguageSelector`, + `FlatwaveMDComponent`, `FlatwaveMDPageComponent`, `FlatwaveLanguageDetector`, `FlatwaveLanguageContext` — + all composable components unchanged in API. +- **KEPT**: Full SSG pipeline — route HTML, sitemap, robots, route-manifest are still generated + automatically during `vite build`. Nothing is removed or made opt-in. +- **KEPT**: All SSG hooks (`transformMarkdown`, `beforeRender`, `transformHtml`, `afterRender`, + `emitFiles`). +- **MODIFIED**: README rewritten to show composable pattern as the primary usage: consumer builds their + app with `FlatwaveLanguageRouter` + `FlatwaveMDPageComponent`; Vite generates static routes from those + components automatically. +- **ADDED**: Documentation of strategy pattern in README showing how to extend build process without modifying core. + +## Capabilities + +### New Capabilities + +- `routing-toolkit-non-intrusive`: Comprehensive specification for the full composable routing toolkit and + how the SSG generates routes from it, replacing the current component-by-name approach. + +### Modified Capabilities + +- `flatwave-md-page-component`: `DefaultRenderStrategy` SHALL use `FlatwaveMDPageComponent` as the **only** + renderer. The component must be server-render-compatible (fix ESM/CJS interop for + `react-helmet-async` and `react-markdown` in Node SSG context). +- `flatwave-language-router`: The `routes` prop is now explicit (required). The component SHALL NOT silently fall back + to calling `getRoutes(lang)` from the virtual module. Consumer supplies routes — typically via the + `useFlatwaveRoutes(locale)` hook. +- `flatwave-app-routes`: Same routes-explicit requirement as `flatwave-language-router`. + +## Impact + +- `src/ssg/DefaultRenderStrategy.tsx`: Render path changed to use `FlatwaveMDPageComponent` as only renderer. +- `src/ssg/runSsg.ts`: `buildComponentsMap` function and call **removed entirely**. `componentsDir` removed from options. +- `src/react/FlatwaveMDPageComponent.tsx`: Must be fixed for server-side `renderToString` compatibility + (react-helmet-async `HelmetProvider` wrapping; react-markdown namespace import for CJS/ESM interop). +- `examples/basic-react-site/`: `App.tsx` rewritten to use `FlatwaveLanguageRouter`; `componentsDir` + removed from `vite.config.ts`; frontmatter `component` field **removed**. +- `packages/vite-plugin-flatwave-react/README.md`: Primary usage example updated. diff --git a/openspec/changes/make-plugin-non-intrusive-routing/specs/flatwave-app-routes/spec.md b/openspec/changes/make-plugin-non-intrusive-routing/specs/flatwave-app-routes/spec.md new file mode 100644 index 0000000..77470ca --- /dev/null +++ b/openspec/changes/make-plugin-non-intrusive-routing/specs/flatwave-app-routes/spec.md @@ -0,0 +1,42 @@ +## MODIFIED Requirements + +### Requirement: FlatwaveAppRoutes requires an explicit routes prop + +`FlatwaveAppRoutes` SHALL accept a REQUIRED `routes: FlatwaveRoute[]` prop. +It SHALL NOT fall back to calling `getRoutes(lang)` from the virtual module when `routes` is absent. + +This makes the component's data dependency visible in consumer code, traceable during debugging, and +replaceable with any route source (virtual module, CMS API, static config). + +#### Scenario: Component renders only the provided routes + +- **WHEN** `routes={threeRoutes}` is passed +- **THEN** `FlatwaveAppRoutes` renders exactly 3 `<Route>` elements for the provided routes + +#### Scenario: TypeScript error when routes prop is absent + +- **WHEN** a consumer renders `<FlatwaveAppRoutes renderPage={fn} />` without the `routes` prop +- **THEN** TypeScript emits a compile-time error (routes is required) + +--- + +## REMOVED Requirements + +### Requirement: FlatwaveAppRoutes accepts an optional routes prop with virtual module fallback + +**Reason**: Falling back to `getRoutes(lang)` inside `FlatwaveAppRoutes` when `routes` is absent +hides a virtual module dependency inside the component. Making `routes` required keeps the component's +data dependency explicit and avoids an implicit import of `virtual:flatwave/content` inside the +package's own component code. + +**Migration**: + +```tsx +// Before (implicit fallback — no longer supported) +<FlatwaveAppRoutes renderPage={fn} />; + +// After (explicit routes) +const { locale } = useFlatwaveLanguage(); +const routes = useFlatwaveRoutes(locale); +<FlatwaveAppRoutes routes={routes} renderPage={fn} />; +``` diff --git a/openspec/changes/make-plugin-non-intrusive-routing/specs/flatwave-language-router/spec.md b/openspec/changes/make-plugin-non-intrusive-routing/specs/flatwave-language-router/spec.md new file mode 100644 index 0000000..a93444c --- /dev/null +++ b/openspec/changes/make-plugin-non-intrusive-routing/specs/flatwave-language-router/spec.md @@ -0,0 +1,48 @@ +## MODIFIED Requirements + +### Requirement: FlatwaveLanguageRouter requires explicit routes prop + +`FlatwaveLanguageRouter` SHALL accept a REQUIRED `renderPage: (route: FlatwaveRoute, lang: string) => React.ReactNode` +prop. It SHALL also accept a REQUIRED `routes: FlatwaveRoute[]` prop. + +The router SHALL NOT silently call `getRoutes(lang)` from the virtual module as an implicit internal +side-effect. The data source must be explicit in consumer code. + +#### Scenario: Routes prop is required to render route elements + +- **WHEN** a consumer provides `routes={esRoutes}` with 3 routes +- **THEN** `renderPage` is called for each of those 3 routes when navigating to their paths + +#### Scenario: Consumer supplies routes from the virtual module explicitly + +- **WHEN** `routes={useFlatwaveRoutes(locale)}` is passed +- **THEN** the router renders exactly the virtual module routes for that locale, and the consumer's + code makes the data source visible and traceable + +#### Scenario: Consumer supplies routes from a custom source + +- **WHEN** `routes={customApiRoutes}` is passed where routes came from an external API or static config +- **THEN** the router renders those custom routes without error or conflict with the virtual module + +#### Scenario: TypeScript error when routes prop is absent + +- **WHEN** a consumer renders `<FlatwaveLanguageRouter renderPage={fn} />` without the `routes` prop +- **THEN** TypeScript emits a compile-time error (routes is required) + +--- + +## REMOVED Requirements + +### Requirement: FlatwaveLanguageRouter renders routes from the virtual module implicitly + +**Reason**: Silently calling `getRoutes(lang)` inside the component creates a hidden coupling between +the router and the virtual module that is invisible in the consumer's code, makes testing harder, and +blocks consumers who want custom route sources. + +**Migration**: Pass `routes` explicitly. For the common case (virtual module routes): + +```tsx +const { locale } = useFlatwaveLanguage(); +const routes = useFlatwaveRoutes(locale); +// pass routes={routes} to FlatwaveLanguageRouter +``` diff --git a/openspec/changes/make-plugin-non-intrusive-routing/specs/flatwave-md-page-component/spec.md b/openspec/changes/make-plugin-non-intrusive-routing/specs/flatwave-md-page-component/spec.md new file mode 100644 index 0000000..525cca2 --- /dev/null +++ b/openspec/changes/make-plugin-non-intrusive-routing/specs/flatwave-md-page-component/spec.md @@ -0,0 +1,43 @@ +## MODIFIED Requirements + +### Requirement: DefaultRenderStrategy uses FlatwaveMDPageComponent as only renderer + +The plugin's `DefaultRenderStrategy` SHALL use `FlatwaveMDPageComponent` as the **only renderer** +for every SSG route. It SHALL pass `markdownHtml` (pre-compiled body), `frontmatter`, and `locale` from +`RenderContext` to the component, wrapping it in `HelmetProvider` for correct SSR head tag extraction. + +There is no fallback to consumer-supplied components. The `componentsDir` config option and the +`component` frontmatter field are removed entirely. + +#### Scenario: SSG generates route using FlatwaveMDPageComponent + +- **WHEN** the SSG pipeline runs for any route +- **THEN** `DefaultRenderStrategy` renders `<HelmetProvider><FlatwaveMDPageComponent ... /></HelmetProvider>` + via `renderToString` and produces valid HTML with `<main>`, rendered markdown body, and head tags + +#### Scenario: No data-ssg-error appears in generated HTML + +- **WHEN** the SSG pipeline runs +- **THEN** no `<p data-ssg-error>` element appears in any generated HTML file; + all pages have the full markdown content rendered + +--- + +## REMOVED Requirements + +### Requirement: DefaultRenderStrategy falls back to raw compiled markdown when component not found + +**Reason**: Returning a raw compiled markdown string (not wrapped in any element) when no component +is found produces invalid page HTML. `FlatwaveMDPageComponent` is available and correctly wraps the +content in `<main>`, sets head tags, and handles all the concerns of a complete page — it should be +the default, not the fallback. + +**Migration**: No consumer action required. The change is internal to `DefaultRenderStrategy`. + +### Requirement: DefaultRenderStrategy loads consumer components from componentsDir by name + +**Reason**: The component-by-name loading via `componentsDir` and `component` frontmatter field is +removed entirely. `FlatwaveMDPageComponent` is the single source of truth for rendering. + +**Migration**: Consumers using custom page components must compose them with `FlatwaveMDPageComponent` +in their `renderPage` function. diff --git a/openspec/changes/make-plugin-non-intrusive-routing/specs/routing-toolkit-non-intrusive/spec.md b/openspec/changes/make-plugin-non-intrusive-routing/specs/routing-toolkit-non-intrusive/spec.md new file mode 100644 index 0000000..471e5fb --- /dev/null +++ b/openspec/changes/make-plugin-non-intrusive-routing/specs/routing-toolkit-non-intrusive/spec.md @@ -0,0 +1,149 @@ +# routing-toolkit-non-intrusive Specification + +## Purpose + +Defines the contract for `@kamansoft/vite-plugin-flatwave-react` as a composable routing and rendering +toolkit. The plugin provides automatic route generation as a first-class feature: `vite build` emits +locale-prefixed static HTML, a sitemap, and robots.txt — driven entirely by the consumer's content files +and the Flatwave composable React components. No intrusive component-by-name loading is required. + +--- + +## Requirements + +### Requirement: SSG generates routes through FlatwaveMDPageComponent, not component-name loading + +The SSG pipeline (`DefaultRenderStrategy`) SHALL use `FlatwaveMDPageComponent` as its **only renderer** +for every content route. It SHALL NOT require a `component` frontmatter field or a `componentsDir` +configuration to produce valid, SEO-compatible HTML output. + +The `componentsDir` config option and the `component` frontmatter field are **removed entirely**. + +#### Scenario: Route HTML generated without componentsDir or component field + +- **WHEN** `vite.config.ts` configures `flatwaveContent()` with no `componentsDir` property +- **AND** the Markdown frontmatter contains no `component` field +- **THEN** `vite build` emits a valid `{locale}/{slug}/index.html` for every public route, with the + Markdown body rendered as HTML inside a `<main>` element and the page title set from frontmatter + +#### Scenario: Route HTML includes frontmatter-driven SEO metadata + +- **WHEN** a Markdown file has `title: 'About Us'`, `description: '...'`, and `canonical: '/es/about'` +- **THEN** the generated HTML contains `<title>About Us`, ``, + and `` in the `` section + +--- + +### Requirement: component frontmatter field is removed entirely + +The `component` field SHALL be removed from `requiredFields` entirely. +`requiredFields` SHALL default to `['title', 'slug', 'id', 'public']`. +The `component` field is no longer a valid frontmatter field — it is ignored if present in Markdown files. + +#### Scenario: Build succeeds without component in frontmatter + +- **WHEN** all Markdown files omit the `component` frontmatter field +- **THEN** `vite build` completes without validation errors or warnings about missing `component` + +#### Scenario: component field in frontmatter is ignored + +- **WHEN** a Markdown file contains a `component` frontmatter field +- **THEN** the field is ignored during validation and route generation; no error or warning is emitted + +--- + +### Requirement: FlatwaveLanguageRouter is the composable entry point for application routing + +A consumer SHALL be able to build a complete multilingual static site by using `FlatwaveLanguageRouter` +in their `App.tsx`. The consumer provides a `renderPage` render prop that returns a +`FlatwaveMDPageComponent` for each route. **The SSG generates static HTML for each route by processing +those same components** — meaning the client-side SPA and the pre-rendered HTML are coherent. + +#### Scenario: Consumer App uses composable pattern + +- **WHEN** `App.tsx` renders: + ```tsx + ( + + )} + /> + ``` +- **THEN** the app renders the correct page for any valid `/{locale}/{slug}` URL on the client + +#### Scenario: SSG produces matching HTML for every client-side route + +- **WHEN** the consumer's `App.tsx` uses `FlatwaveLanguageRouter` + `FlatwaveMDPageComponent` +- **AND** `vite build` runs +- **THEN** each route URL that `FlatwaveLanguageRouter` would serve has a corresponding + `dist/{locale}/{slug}/index.html` with the same content the SPA would render + +--- + +### Requirement: SSG always generates locale-prefixed routes, sitemap, and robots + +The SSG pipeline SHALL always generate: + +- `{locale}/{slug}/index.html` for every public content route +- `sitemap.xml` listing all public route URLs (configurable hostname) +- `robots.txt` pointing to the sitemap +- `route-manifest.json` listing all generated routes with metadata + +These outputs are automatic — the consumer does not need to configure them to get them. + +#### Scenario: All public routes produce HTML files + +- **WHEN** the content directory contains 3 public Markdown files per locale (6 total for 2 locales) +- **THEN** `vite build` emits 6 locale-prefixed HTML files in `dist/` + +#### Scenario: sitemap contains all public routes + +- **WHEN** `sitemap.hostname` is set to `'https://mysite.com'` +- **THEN** `dist/sitemap.xml` contains one `` element per public route, e.g. + `https://mysite.com/es/about` + +--- + +### Requirement: FlatwaveMDPageComponent is server-render compatible + +`FlatwaveMDPageComponent` SHALL work correctly inside `react-dom/server`'s `renderToString`. +`react-helmet-async` and `react-markdown` SHALL be imported using namespace imports +(`import * as Pkg from 'pkg'`) to resolve CJS/ESM interoperability in the Node SSG environment. + +#### Scenario: renderToString produces valid HTML with head tags + +- **WHEN** `DefaultRenderStrategy` calls `renderToString()` +- **THEN** the result is a valid HTML string containing `
` with the Markdown body and the + `` / `<meta>` tags from the frontmatter + +#### Scenario: No runtime error when markdownHtml is provided + +- **WHEN** `markdownHtml` is a non-empty compiled HTML string +- **THEN** `FlatwaveMDPageComponent` renders the HTML via `dangerouslySetInnerHTML` without attempting + to load or execute `react-markdown` + +--- + +### Requirement: Strategy pattern for build process extensibility + +The plugin SHALL provide a strategy pattern that allows users to define custom logic to create additional files +(e.g., JSON files) from the recursive markdown content loop during the build process. + +#### Scenario: User defines custom strategy to generate JSON from markdown content + +- **WHEN** the user provides a strategy function that processes markdown content during build +- **AND** the strategy is configured in the plugin options +- **THEN** the strategy function is called for each markdown file during the SSG rendering loop +- **AND** the user can create additional output files (e.g., JSON) based on the markdown content + +#### Scenario: Strategy receives markdown metadata and content + +- **WHEN** the strategy function is invoked during build +- **THEN** it receives the frontmatter, slug, locale, and compiled HTML for each markdown file +- **AND** the user can access all content data to generate custom output files diff --git a/openspec/changes/make-plugin-non-intrusive-routing/tasks.md b/openspec/changes/make-plugin-non-intrusive-routing/tasks.md new file mode 100644 index 0000000..5817186 --- /dev/null +++ b/openspec/changes/make-plugin-non-intrusive-routing/tasks.md @@ -0,0 +1,65 @@ +## 1. Fix FlatwaveMDPageComponent for server-side rendering + +- [x] 1.1 Update `FlatwaveMDPageComponent.tsx`: change `import { Helmet } from 'react-helmet-async'` to + `import * as ReactHelmet from 'react-helmet-async'; const { Helmet, HelmetProvider } = ReactHelmet;` +- [x] 1.2 Confirm `react-markdown` import in `FlatwaveMDComponent.tsx` already uses namespace import + `import * as ReactMarkdown from 'react-markdown'`; fix if not +- [x] 1.3 Rebuild plugin: `npm run build:plugin` +- [x] 1.4 Write a unit test (`DefaultRenderStrategy.test.ts`) that calls `renderToString` with + `FlatwaveMDPageComponent` and asserts the output contains `<main>`, the markdown body, and `<title>` + +## 2. Update DefaultRenderStrategy to use FlatwaveMDPageComponent as only renderer + +- [x] 2.1 Rewrite `DefaultRenderStrategy.tsx`: render path calls + `renderToString(<HelmetProvider><FlatwaveMDPageComponent frontmatter={...} markdownHtml={...} locale={...} /></HelmetProvider>)` + using `import * as ReactHelmet from 'react-helmet-async'; const { HelmetProvider } = ReactHelmet;` +- [x] 2.2 Remove the consumer-component override path entirely — no `componentsDir`, no `buildComponentsMap` +- [x] 2.3 Remove the raw-markdown fallback (`return compiledBody`) — it MUST NOT appear anywhere +- [x] 2.4 Ensure error catch blocks still return `<p data-ssg-error>...</p>` for unexpected exceptions + +## 3. Remove component from requiredFields entirely + +- [x] 3.1 In `normalizeOptions()` (`src/index.ts`), change default `requiredFields` from + `['title', 'slug', 'id', 'component', 'public']` to `['title', 'slug', 'id', 'public']` +- [x] 3.2 Remove `component` from validation entirely — it is not a valid frontmatter field + +## 4. Remove componentsDir and buildComponentsMap from runSsg + +- [x] 4.1 In `runSsg.ts`, remove `buildComponentsMap` function entirely +- [x] 4.2 Remove `componentsDir` from `SsgOptions` type and plugin options +- [x] 4.3 Pass empty `Map()` to `RenderContext.components` always + +## 5. Make routes explicit in FlatwaveLanguageRouter and FlatwaveAppRoutes + +- [x] 5.1 Update `FlatwaveLanguageRouter.tsx`: remove internal call to `getRoutes(lang)`; + require `routes` to be passed via prop; update `FlatwaveLanguageRouterProps` type +- [x] 5.2 Update `FlatwaveAppRoutes.tsx`: change `routes?: FlatwaveRoute[]` to + `routes: FlatwaveRoute[]` (required); remove fallback `getRoutes(locale)` call +- [x] 5.3 Update `FlatwaveAppRoutesProps` and `FlatwaveLanguageRouterProps` in `src/react/types.ts` +- [x] 5.4 Run `npm run type-check` — fix any resulting TypeScript errors + +## 6. Update example site to composable pattern + +- [x] 6.1 Remove `componentsDir` from `examples/basic-react-site/vite.config.ts` +- [x] 6.2 Remove `component: 'SimplePage'` / `component: 'ProgramPage'` from all example Markdown + frontmatter files +- [x] 6.3 Rewrite `examples/basic-react-site/src/App.tsx` to use `FlatwaveLanguageRouter` + + `FlatwaveMDPageComponent` (with `useFlatwaveRoutes` providing explicit routes) +- [x] 6.4 Remove `SimplePage.tsx` and `ProgramPage.tsx` — they are no longer used +- [x] 6.5 Run `npm run build:example` and verify all HTML files are generated correctly with no + `data-ssg-error` elements + +## 7. Validation and CI + +- [ ] 7.1 Run `npm run validate` (format + lint + type-check + build + test) — all must pass +- [ ] 7.2 Verify `e2e/example.test.ts` passes: routes exist, titles match frontmatter, sitemap correct +- [ ] 7.3 Verify no `<p data-ssg-error>` appears in any generated HTML file in `examples/basic-react-site/dist/` + +## 8. Update README + +| [ ] 8.1 Update "How It Works" section: route generation is driven by content + composable components +| [ ] 8.2 Remove `componentsDir` from the primary `vite.config.ts` example +| [ ] 8.3 Remove `component: 'SimplePage'` from the primary frontmatter example +| [ ] 8.4 Add "Automatic Route Generation" section showing `FlatwaveLanguageRouter` → SSG HTML flow +| [ ] 8.5 Update "Build Outputs" section to clarify these come from the composable components +| diff --git a/openspec/changes/provide-composable-react-components/tasks.md b/openspec/changes/provide-composable-react-components/tasks.md new file mode 100644 index 0000000..3e532fd --- /dev/null +++ b/openspec/changes/provide-composable-react-components/tasks.md @@ -0,0 +1,113 @@ +## 1. Types and Interfaces + +- [x] 1.1 Add `emitFiles` optional callback to `RenderHooks` interface in `src/types.ts` +- [x] 1.2 Define and export `EmitFilesContext` interface in `src/types.ts` (fields: `routes`, `contentIndex`, `renderedFiles`) +- [x] 1.3 Export `SsgOutputFile` type from `src/types.ts` (move from `runSsg.ts` or re-export) +- [x] 1.4 Define and export `FlatwaveMDComponentProps<TFrontmatter>` generic interface in `src/react/types.ts` +- [x] 1.5 Define and export `FlatwaveMDPageProps<TFrontmatter>` generic interface in `src/react/types.ts` +- [x] 1.6 Define and export `FlatwaveLanguageRouterProps`, `FlatwaveLanguageDetectorProps`, and `FlatwaveAppRoutesProps` interfaces in `src/react/types.ts` +- [x] 1.7 Define and export `FlatwaveLanguageContextValue` interface and `FlatwaveLanguageContext` React context in `src/react/FlatwaveLanguageContext.ts` +- [x] 1.8 Export `FlatwaveFrontmatterWith<T>` utility type for frontmatter extension + +## 2. FlatwaveMDComponent + +- [x] 2.1 Create `src/react/FlatwaveMDComponent.tsx` — implement the generic functional component +- [x] 2.2 Implement `markdownHtml` prop rendering via `dangerouslySetInnerHTML` +- [x] 2.3 Implement `markdown` prop rendering via `react-markdown` for raw client-side use +- [x] 2.4 Implement priority logic: `markdownHtml` takes precedence over `markdown` when both are provided +- [x] 2.5 Implement `children` render prop: `children?: (rendered: React.ReactNode, frontmatter: TFrontmatter) => React.ReactNode` +- [x] 2.6 Strip YAML frontmatter from `markdown` prop before rendering (defensive: remove `---\n...\n---` block) +- [x] 2.7 Provide `FlatwaveLanguageContext.Provider` to expose `locale` to descendants +- [x] 2.8 Apply `className` and `style` props to the outermost element + +## 3. FlatwaveMDPageComponent + +- [x] 3.1 Create `src/react/FlatwaveMDPageComponent.tsx` — implement the generic functional component +- [x] 3.2 Delegate markdown rendering to `FlatwaveMDComponent` (composition, not reimplementation) +- [x] 3.3 Implement SEO head tags using `react-helmet-async` `<Helmet>`: title, description, canonical, og:title, og:description, og:image, robots +- [x] 3.4 Guard against empty title tag (skip `<title>` if `frontmatter.title` is falsy) +- [x] 3.5 Implement `pageWrapper?: React.ComponentType` prop with default `<main>` element +- [x] 3.6 Implement `loadingFallback?: React.ReactNode` prop for missing content scenarios + +## 4. FlatwaveLanguageContext and FlatwaveLanguageDetector + +- [x] 4.1 Create `src/react/FlatwaveLanguageContext.ts` — define `FlatwaveLanguageContext` with default value +- [x] 4.2 Create `src/react/FlatwaveLanguageDetector.tsx` — implement renderless language detection component +- [x] 4.3 Implement browser language detection from `navigator.language` / `navigator.languages` +- [x] 4.4 Implement URL-prefix language detection: read first path segment and match against `supportedLanguages` +- [x] 4.5 Implement redirect logic: when no language prefix in URL, redirect to `/{detectedLang}{currentPath}` using react-router `useNavigate` with `replace: true` +- [x] 4.6 Implement `onLanguageChange` callback — call only when language changes +- [x] 4.7 Provide `FlatwaveLanguageContext.Provider` with current locale state +- [x] 4.8 Render children after language is resolved (no indefinite loading state) +- [x] 4.9 Create `src/react/useFlatwaveLanguage.ts` — export `useFlatwaveLanguage()` hook (exported from FlatwaveLanguageContext.ts) + +## 5. FlatwaveLanguageRouter + +- [x] 5.1 Create `src/react/FlatwaveLanguageRouter.tsx` — implement the convenience router component +- [x] 5.2 Compose `BrowserRouter` + `FlatwaveLanguageDetector` + `FlatwaveAppRoutes` inside `FlatwaveLanguageRouter` + +## 6. FlatwaveAppRoutes + +- [x] 6.1 Create `src/react/FlatwaveAppRoutes.tsx` — implement the render-prop route mapping component +- [x] 6.2 Implement `routes?: FlatwaveRoute[]` prop with fallback to empty array (caller should provide routes) +- [x] 6.3 Implement `renderPage` prop to render each route +- [x] 6.4 Add catch-all `<Route path="*">` rendering null +- [x] 6.5 Integrate with `FlatwaveLanguageContext` to read active locale + +## 7. FlatwaveLanguageSelector + +- [x] 7.1 Create `src/react/FlatwaveLanguageSelector.tsx` — implement the language selector UI component +- [x] 7.2 Implement `renderOption?: (lang: string, label: string, isActive: boolean) => React.ReactNode` prop +- [x] 7.3 Implement `onSelect?: (lang: string) => void` callback +- [x] 7.4 Implement `getLabel?: (lang: string) => string` prop for custom language labels +- [x] 7.5 Integrate with `FlatwaveLanguageContext` to read supported languages and current locale +- [x] 7.6 Apply `className` and `style` props to root element + +## 8. SSG emitFiles Hook + +- [x] 8.1 Add `executeEmitFiles(context: EmitFilesContext): Promise<SsgOutputFile[]>` method to `RenderPipeline.ts` +- [x] 8.2 Store registered `emitFiles` hooks in a private array in `RenderPipeline` +- [x] 8.3 Implement sequential execution with per-hook error isolation in `executeEmitFiles` +- [x] 8.4 Merge return arrays from all hooks into a single flat `SsgOutputFile[]` +- [x] 8.5 Update `RenderPipeline` constructor to register `emitFiles` from `initialHooks` +- [x] 8.6 Update `runSsg.ts` to call `pipeline.executeEmitFiles` after the route render loop +- [x] 8.7 Pass correct `EmitFilesContext` (routes, contentIndex, renderedFiles) in `runSsg.ts` +- [x] 8.8 Append `emitFiles` output to the `outputFiles` array in `runSsg.ts` + +## 9. Layout Wrapper Support + +- [x] 9.1 Add `layoutWrapper?: React.ComponentType` prop to `FlatwaveLanguageRouter` +- [x] 9.2 Add `layoutWrapper?: React.ComponentType` prop to `FlatwaveAppRoutes` +- [x] 9.3 Update `FlatwaveLanguageRouter` to wrap rendered pages in layoutWrapper + +## 10. DefaultRenderStrategy Graceful Degradation + +- [x] 10.1 Maintain graceful degradation in `DefaultRenderStrategy.tsx` (returns compiled markdown when no component is found) +- [x] 10.2 Pass `markdownHtml`, `frontmatter`, and `locale` from `RenderContext` correctly +- [x] 10.3 Keep custom component override path (existing behaviour) +- [x] 10.4 Verify existing e2e tests pass after changes + +## 11. Package Exports and Peer Dependencies + +- [x] 11.1 Update `src/react/index.ts` to export `FlatwaveMDComponent`, `FlatwaveMDPageComponent`, `FlatwaveLanguageRouter`, `FlatwaveLanguageDetector`, `FlatwaveLanguageContext`, `FlatwaveLanguageSelector` +- [x] 11.2 Update `src/index.ts` to re-export from `./react` +- [x] 11.3 Update `src/types.ts` to export `EmitFilesContext` and `SsgOutputFile` +- [x] 11.4 Add `react-markdown` and `react-helmet-async` to `peerDependencies` in `packages/vite-plugin-flatwave-react/package.json` +- [x] 11.5 Add `react-router-dom` to `peerDependencies` (already present) +- [x] 11.6 Run `npm run type-check` to confirm no TypeScript errors + +## 12. Example Site Integration + +- [x] 12.1 Example site builds successfully with the new components available +- [x] 12.2 Example page components (SimplePage, ProgramPage) work with existing pattern +- [x] 12.3 Run `npm run build:example` and verify all routes generated correctly + +## 13. Documentation + +- [x] 13.1 Rewrite `README.md` with component-first usage model +- [x] 13.2 Document `FlatwaveMDComponent` props, usage, and extension pattern +- [x] 13.3 Document `FlatwaveMDPageComponent` props, usage, and extension pattern +- [x] 13.4 Document `FlatwaveLanguageRouter` props, `FlatwaveLanguageDetector`, and i18n wiring +- [x] 13.5 Document `FlatwaveLanguageSelector` and `emitFiles` hook with `navigation.json` generation example +- [x] 13.6 Add migration notes section in README +- [ ] 13.7 Update `CHANGELOG.md` diff --git a/openspec/specs/flatwave-app-routes/spec.md b/openspec/specs/flatwave-app-routes/spec.md new file mode 100644 index 0000000..c9f0ff9 --- /dev/null +++ b/openspec/specs/flatwave-app-routes/spec.md @@ -0,0 +1,71 @@ +# flatwave-app-routes Specification + +## Purpose + +TBD - created by archiving change provide-composable-react-components. Update Purpose after archive. + +## Requirements + +### Requirement: Package exports FlatwaveAppRoutes + +The package SHALL export a React component named `FlatwaveAppRoutes` from its public surface. It SHALL map `FlatwaveRoute[]` to `react-router-dom` `<Routes>` by creating a `<Route path={route.path}>` for each public route. It SHALL accept a REQUIRED `renderPage: (route: FlatwaveRoute, lang: string) => React.ReactNode` prop to render the page content for each route. + +#### Scenario: Route elements are created for each route + +- **WHEN** `routes` contains 3 `FlatwaveRoute` objects and `renderPage` is provided +- **THEN** `FlatwaveAppRoutes` renders 3 `<Route>` elements internally (wrapped by a `<Routes>`) + +#### Scenario: Dynamic route segments are handled correctly + +- **WHEN** a route has `path="/es/about"` and `renderPage` is called with that route +- **WHEN** another route has `path="/es/:slug"` for dynamic slug pages +- **THEN** both routes are rendered in the `<Routes>` tree with correct path attributes + +--- + +### Requirement: FlatwaveAppRoutes accepts an optional routes prop + +`FlatwaveAppRoutes` SHALL accept an optional `routes: FlatwaveRoute[]` prop. When provided, it SHALL use those routes instead of calling `getRoutes(lang)` from the virtual module. This allows consumers who generate their own route data to supply it. + +#### Scenario: Custom routes are used when provided + +- **WHEN** a consumer passes `routes={customRoutes}` to `FlatwaveAppRoutes` +- **THEN** the component renders only the provided custom routes, not the virtual module routes + +#### Scenario: Virtual module routes are used when routes prop is absent + +- **WHEN** no `routes` prop is provided +- **THEN** `FlatwaveAppRoutes` calls `getRoutes(lang)` using the active locale from `FlatwaveLanguageContext` + +--- + +### Requirement: FlatwaveAppRoutes accepts a renderPage render prop + +The `renderPage` prop SHALL be called with `(route: FlatwaveRoute, lang: string)` and SHALL receive the full route metadata including frontmatter. This matches the working project's `DynamicSimplePageWrapper` pattern. + +#### Scenario: renderPage receives full route metadata + +- **WHEN** `renderPage` is called for a route with `frontmatter: { title: "About", ... }` +- **THEN** `renderPage` can use `route.frontmatter.title` or `route.metadata.title` to render the page + +--- + +### Requirement: FlatwaveAppRoutes integrates with FlatwaveLanguageContext + +`FlatwaveAppRoutes` SHALL read the current `locale` from `FlatwaveLanguageContext` to determine which language's routes to render when `routes` prop is not provided. + +#### Scenario: App routes respect the active language context + +- **WHEN** `FlatwaveLanguageContext.locale` is `"pt"` and `routes` prop is not provided +- **THEN** `FlatwaveAppRoutes` renders routes filtered by locale `"pt"` + +--- + +### Requirement: FlatwaveAppRoutes renders a default 404 route + +`FlatwaveAppRoutes` SHALL render a catch-all `<Route path="*">` that renders `null`. Consumers who want a 404 page SHALL include a route with a dynamic segment (e.g. `path="*"` in their routes list or create their own 404 route structure externally. + +#### Scenario: Catch-all route renders null + +- **WHEN** navigating to a non-existent path +- **THEN** the catch-all route renders null (no error thrown) diff --git a/openspec/specs/flatwave-language-router/spec.md b/openspec/specs/flatwave-language-router/spec.md new file mode 100644 index 0000000..cc858e0 --- /dev/null +++ b/openspec/specs/flatwave-language-router/spec.md @@ -0,0 +1,170 @@ +# flatwave-language-router Specification + +## Purpose + +TBD - created by archiving change provide-composable-react-components. Update Purpose after archive. + +## Requirements + +### Requirement: Package exports FlatwaveLanguageRouter + +The package SHALL export a React component named `FlatwaveLanguageRouter` from its public surface. It SHALL provide a complete, ready-to-use multilingual routing solution that wraps `BrowserRouter` from `react-router-dom`, integrates `FlatwaveLanguageDetector` for automatic language detection and URL management, and renders user-defined routes via a `renderPage` render prop. + +#### Scenario: Named export is available + +- **WHEN** a consumer imports `{ FlatwaveLanguageRouter }` from `@kamansoft/vite-plugin-flatwave-react` +- **THEN** the import resolves to a React functional component without runtime error + +--- + +### Requirement: FlatwaveLanguageRouter accepts supportedLanguages and defaultLanguage props + +`FlatwaveLanguageRouter` SHALL accept: + +- `supportedLanguages: string[]` — the list of locale codes supported by the site (e.g. `['es', 'pt']`) +- `defaultLanguage: string` — the locale to redirect to when no language prefix is present in the URL and browser preference is not in the supported list + +Both props are REQUIRED. + +#### Scenario: Router is configured with supported languages + +- **WHEN** `supportedLanguages={['es', 'pt']} defaultLanguage="es"` are passed +- **THEN** the router treats `es` and `pt` as valid language URL prefixes + +#### Scenario: TypeScript error when required props are missing + +- **WHEN** a consumer renders `<FlatwaveLanguageRouter renderPage={fn} />` without `supportedLanguages` or `defaultLanguage` +- **THEN** TypeScript emits a compile-time error + +--- + +### Requirement: FlatwaveLanguageRouter redirects root path to preferred language + +When a user navigates to `/` (or any path without a recognised language prefix), `FlatwaveLanguageRouter` SHALL detect the browser's preferred language (via `navigator.language` / `navigator.languages`), match it against `supportedLanguages`, and redirect to `/{matchedLang}{currentPath}`. If no match is found, it SHALL redirect using `defaultLanguage`. + +#### Scenario: Browser language matches a supported language + +- **WHEN** browser language is `"pt"` and `supportedLanguages` includes `"pt"` and the current path is `/` +- **THEN** the router redirects to `/pt` (replace history, no browser back) + +#### Scenario: Browser language does not match any supported language + +- **WHEN** browser language is `"fr"` and `supportedLanguages` is `['es', 'pt']` with `defaultLanguage="es"` +- **THEN** the router redirects to `/es` + +#### Scenario: URL already has a valid language prefix — no redirect + +- **WHEN** the current path is `/es/about` and `es` is in `supportedLanguages` +- **THEN** no redirect occurs + +--- + +### Requirement: FlatwaveLanguageRouter calls onLanguageChange when the active language changes + +`FlatwaveLanguageRouter` SHALL accept an optional `onLanguageChange?: (lang: string) => void` prop. It SHALL call this callback with the new language code whenever the active language changes (either from a redirect or from direct navigation to a different language prefix). + +#### Scenario: Callback is called on initial language detection + +- **WHEN** the router resolves the language on first render (e.g. redirecting from `/` to `/es`) +- **THEN** `onLanguageChange("es")` is called once + +#### Scenario: Callback is called on language switch navigation + +- **WHEN** the user navigates from `/es/page` to `/pt/page` +- **THEN** `onLanguageChange("pt")` is called + +#### Scenario: Callback is not called when language has not changed + +- **WHEN** the user navigates from `/es/about` to `/es/contact` +- **THEN** `onLanguageChange` is NOT called (same language, different page) + +--- + +### Requirement: FlatwaveLanguageRouter renders routes via a renderPage render prop + +`FlatwaveLanguageRouter` SHALL accept a REQUIRED `renderPage: (route: FlatwaveRoute, lang: string) => React.ReactNode` prop. For each route returned by `getRoutes(lang)` from the virtual module (filtered by the active language), the router SHALL render a `<Route path={route.path}>` that calls `renderPage(route, lang)`. + +The router SHALL additionally render: + +- A catch-all `<Route path="*">` that returns `null` (consumers are responsible for adding a 404 component by including it in their renderPage logic or via an additional route). + +#### Scenario: renderPage is called for each route of the active language + +- **WHEN** the content index has 3 routes for locale `"es"` and the current language is `"es"` +- **THEN** `renderPage` is called for each of those 3 routes when navigating to their paths + +#### Scenario: renderPage receives the full FlatwaveRoute object + +- **WHEN** navigating to `/es/about` +- **THEN** `renderPage` receives a `FlatwaveRoute` object with `locale: "es"`, `path: "/es/about"`, and all frontmatter fields + +--- + +### Requirement: FlatwaveLanguageRouter accepts a dynamicRoute prop for content-driven pages + +`FlatwaveLanguageRouter` SHALL accept an optional `dynamicRoute?: DynamicRouteConfig` prop to handle content-driven pages where the path is not known at build time (e.g., `/{lang}/:slug` for markdown pages). `DynamicRouteConfig` contains: + +```ts +interface DynamicRouteConfig { + path: string; // Route path pattern, e.g., "/:slug" + renderPage: (params: { slug: string; lang: string }) => React.ReactNode; // Render function receiving slug param +} +``` + +#### Scenario: Dynamic route renders content for matching slug + +- **WHEN** current path is `/es/some-page` and `dynamicRoute={{ path: "/:slug", renderPage: ({ slug }) => <FlatwaveMDPageComponent content={getContent(slug)} /> }}` +- **THEN** the dynamic route renders the page for `some-page` + +#### Scenario: Dynamic route takes precedence over static routes for slug paths + +- **WHEN** a static route `/es/about` exists and `dynamicRoute` is configured for `/:slug` +- **THEN** navigating to `/es/about` renders the static route, but `/es/any-slug` renders via the dynamic route + +--- + +### Requirement: Package exports FlatwaveLanguageDetector as a standalone component + +The package SHALL export `FlatwaveLanguageDetector` separately from `FlatwaveLanguageRouter`. This component SHALL implement only the language detection and URL-prefix management logic (no `BrowserRouter`, no route rendering). It SHALL accept `supportedLanguages`, `defaultLanguage`, `onLanguageChange`, and `children: React.ReactNode` props. This allows consumers who already have a `BrowserRouter` to add language detection to their existing router setup. + +#### Scenario: FlatwaveLanguageDetector works inside an existing BrowserRouter + +- **WHEN** a consumer renders `<BrowserRouter><FlatwaveLanguageDetector ...><AppRoutes /></FlatwaveLanguageDetector></BrowserRouter>` +- **THEN** language detection and redirection work correctly without wrapping in another BrowserRouter + +#### Scenario: FlatwaveLanguageDetector renders children after language is resolved + +- **WHEN** the language is successfully resolved (initial render) +- **THEN** children are rendered (no indefinite loading state) + +--- + +### Requirement: Package exports FlatwaveLanguageContext + +The package SHALL export a `FlatwaveLanguageContext` React context of type `{ locale: string; supportedLanguages: string[]; defaultLanguage: string }`. `FlatwaveLanguageDetector` SHALL provide this context to all descendant components with the current active language values. + +#### Scenario: Context is accessible to descendant components + +- **WHEN** a component inside the router tree calls `useContext(FlatwaveLanguageContext)` +- **THEN** it receives the current `locale`, `supportedLanguages`, and `defaultLanguage` values + +#### Scenario: Context locale updates when language changes + +- **WHEN** the user navigates from `/es/page` to `/pt/page` +- **THEN** `FlatwaveLanguageContext.locale` updates to `"pt"` in all consumers of the context + +--- + +### Requirement: FlatwaveLanguageRouter does not import or require any i18n library + +`FlatwaveLanguageRouter` and `FlatwaveLanguageDetector` SHALL NOT import `i18next`, `react-i18next`, `react-intl`, `lingui`, or any other i18n library. Language sync with third-party i18n libraries is the consumer's responsibility, achieved via the `onLanguageChange` callback. + +#### Scenario: Plugin package has no i18n library dependency + +- **WHEN** inspecting `packages/vite-plugin-flatwave-react/package.json` dependencies and peerDependencies +- **THEN** no i18n library is listed as a dependency or peerDependency + +#### Scenario: Consumer wires i18next via onLanguageChange + +- **WHEN** a consumer passes `onLanguageChange={(lang) => i18n.changeLanguage(lang)}` to `FlatwaveLanguageRouter` +- **THEN** `i18n.changeLanguage` is called whenever the route language changes diff --git a/openspec/specs/flatwave-language-selector/spec.md b/openspec/specs/flatwave-language-selector/spec.md new file mode 100644 index 0000000..c4547a9 --- /dev/null +++ b/openspec/specs/flatwave-language-selector/spec.md @@ -0,0 +1,87 @@ +# flatwave-language-selector Specification + +## Purpose + +TBD - created by archiving change provide-composable-react-components. Update Purpose after archive. + +## Requirements + +### Requirement: Package exports FlatwaveLanguageSelector + +The package SHALL export a React component named `FlatwaveLanguageSelector` from its public surface. It SHALL render a language switching UI using `FlatwaveLanguageContext` to determine the available languages and the current locale. + +#### Scenario: Selector renders all supported languages + +- **WHEN** `FlatwaveLanguageContext.supportedLanguages` is `['es', 'pt']` and `FlatwaveLanguageContext.locale` is `'es'` +- **THEN** `FlatwaveLanguageSelector` renders options for both languages, with `'es'` marked as active + +--- + +### Requirement: FlatwaveLanguageSelector accepts a renderOption render prop + +`FlatwaveLanguageSelector` SHALL accept an optional `renderOption?: (lang: string, label: string, isActive: boolean) => React.ReactNode` prop. When provided, it SHALL call this function for each language to render the option. When not provided, it SHALL render a default `<select>` with `<option>` elements. + +#### Scenario: Custom renderOption receives language, label, and active state + +- **WHEN** `renderOption={(lang, label, active) => <button disabled={active}>{label}</button>}` +- **THEN** the button for the active language is disabled and others are clickable + +--- + +### Requirement: FlatwaveLanguageSelector calls onSelect callback when a language is selected + +`FlatwaveLanguageSelector` SHALL accept an optional `onSelect?: (lang: string) => void` prop. It SHALL call this callback when the user selects a different language. This callback is invoked BEFORE navigation, allowing consumers to perform analytics or additional side effects. + +#### Scenario: onSelect callback fires on language change + +- **WHEN** user selects a different language and `onSelect={(lang) => console.log(lang)}` is provided +- **THEN** the callback receives the new language code + +--- + +### Requirement: FlatwaveLanguageSelector integrates with browser history navigation + +When a user selects a new language, `FlatwaveLanguageSelector` SHALL navigate to the corresponding language-prefixed URL. For example, if the current path is `/es/about` and user selects `'pt'`, it SHALL navigate to `/pt/about` (replacing history to avoid back-button confusion). + +#### Scenario: Navigation uses correct language prefix + +- **WHEN** current path is `/es/about` and user selects `'pt'` +- **THEN** the router navigates to `/pt/about` with `replace: true` + +#### Scenario: Default language selection does not redirect + +- **WHEN** current language matches `defaultLanguage` and user re-selects it +- **THEN** no navigation occurs (same language selected) + +--- + +### Requirement: FlatwaveLanguageSelector uses FlatwaveLanguageContext for language state + +`FlatwaveLanguageSelector` SHALL read `locale`, `supportedLanguages`, and `defaultLanguage` from `FlatwaveLanguageContext`. It SHALL not accept these as separate props to avoid prop drilling. + +#### Scenario: Selector uses context without additional props + +- **WHEN** the component is placed inside a `FlatwaveLanguageDetector` tree +- **THEN** it has access to all language configuration without additional props + +--- + +### Requirement: FlatwaveLanguageSelector supports custom className and style + +`FlatwaveLanguageSelector` SHALL accept `className?: string` and `style?: React.CSSProperties` props that are applied to the root element of the rendered UI (the `<select>` or the container for custom-rendered options). + +#### Scenario: className is applied to root element + +- **WHEN** `className="lang-selector"` is passed +- **THEN** the outermost element has class `"lang-selector"` + +--- + +### Requirement: FlatwaveLanguageSelector supports getLabel override for custom labels + +`FlatwaveLanguageSelector` SHALL accept an optional `getLabel?: (lang: string) => string` prop that allows consumers to customize the display label for each language. If not provided, it SHALL use the language code itself as the label. + +#### Scenario: Custom labels are used when getLabel is provided + +- **WHEN** `getLabel={lang => lang === 'es' ? 'Español' : 'Português'}` is passed +- **THEN** the selector displays 'Español' and 'Português' instead of 'es' and 'pt' diff --git a/openspec/specs/flatwave-layout-wrapper/spec.md b/openspec/specs/flatwave-layout-wrapper/spec.md new file mode 100644 index 0000000..a2e5798 --- /dev/null +++ b/openspec/specs/flatwave-layout-wrapper/spec.md @@ -0,0 +1,27 @@ +# flatwave-layout-wrapper Specification + +## Purpose + +TBD - created by archiving change provide-composable-react-components. Update Purpose after archive. + +## Requirements + +### Requirement: FlatwaveLanguageRouter accepts a layoutWrapper prop + +`FlatwaveLanguageRouter` SHALL accept an optional `layoutWrapper?: React.ComponentType<{ children: React.ReactNode; locale: string }>` prop. When provided, all rendered routes SHALL be wrapped inside this layout component, receiving the current locale as a prop. This mirrors the `PagesLayout` pattern in the working project. + +#### Scenario: Layout wrapper wraps all page content + +- **WHEN** `layoutWrapper={({ children, locale }) => <div lang={locale}><Header /><main>{children}</main><Footer /></div>}` is passed +- **THEN** all rendered pages are wrapped with the layout component, and `locale` is available as a prop + +--- + +### Requirement: FlatwaveAppRoutes accepts a layoutWrapper prop + +`FlatwaveAppRoutes` SHALL accept an optional `layoutWrapper?: React.ComponentType` prop. When provided, routes SHALL render inside the wrapper using react-router's `<Outlet />` pattern for nested routes. This enables consumers to create a shared layout structure. + +#### Scenario: Layout wrapper works with Outlet pattern + +- **WHEN** `layoutWrapper={MyLayout}` is provided to `FlatwaveAppRoutes` +- **THEN** MyLayout receives `<Outlet />` or equivalent to render child routes diff --git a/openspec/specs/flatwave-md-component/spec.md b/openspec/specs/flatwave-md-component/spec.md new file mode 100644 index 0000000..2a4796c --- /dev/null +++ b/openspec/specs/flatwave-md-component/spec.md @@ -0,0 +1,119 @@ +# flatwave-md-component Specification + +## Purpose + +TBD - created by archiving change provide-composable-react-components. Update Purpose after archive. + +## Requirements + +### Requirement: Package exports FlatwaveMDComponent + +The package SHALL export a React component named `FlatwaveMDComponent` from its public surface (`@kamansoft/vite-plugin-flatwave-react`). The component SHALL be a generic functional component typed as `FlatwaveMDComponent<TFrontmatter extends FlatwaveFrontmatter = FlatwaveFrontmatter>`. + +#### Scenario: Named export is available + +- **WHEN** a consumer imports `{ FlatwaveMDComponent }` from `@kamansoft/vite-plugin-flatwave-react` +- **THEN** the import resolves to a React functional component without runtime error + +#### Scenario: TypeScript generic allows frontmatter extension + +- **WHEN** a consumer defines `interface MyFrontmatter extends FlatwaveFrontmatter { audioUrl: string }` and uses `FlatwaveMDComponent<MyFrontmatter>` +- **THEN** TypeScript accepts `frontmatter.audioUrl` as a valid property access within a component that wraps `FlatwaveMDComponent<MyFrontmatter>` + +--- + +### Requirement: Component accepts pre-compiled HTML via markdownHtml prop + +`FlatwaveMDComponent` SHALL accept a `markdownHtml: string` prop. When this prop is provided, the component SHALL render its content using `dangerouslySetInnerHTML={{ __html: markdownHtml }}` inside a wrapper element. This mode is intended for SSG contexts where the markdown has already been compiled to HTML by the build pipeline. + +#### Scenario: Pre-compiled HTML is rendered verbatim + +- **WHEN** `markdownHtml="<p>Hello <strong>world</strong></p>"` is passed as a prop +- **THEN** the rendered DOM contains `<p>Hello <strong>world</strong></p>` as inner HTML + +#### Scenario: markdownHtml takes priority over markdown when both are provided + +- **WHEN** both `markdownHtml="<p>compiled</p>"` and `markdown="raw"` are passed +- **THEN** the component renders the compiled HTML and ignores the raw markdown string + +--- + +### Requirement: Component accepts raw markdown via markdown prop + +`FlatwaveMDComponent` SHALL accept a `markdown: string` prop. When this prop is provided and `markdownHtml` is not, the component SHALL render the markdown string using the `react-markdown` library (a peer dependency). + +#### Scenario: Raw markdown is rendered client-side + +- **WHEN** `markdown="# Hello\n\nThis is **markdown**."` is passed without `markdownHtml` +- **THEN** the rendered DOM contains an `<h1>` element with text "Hello" and a `<p>` with bold text + +--- + +### Requirement: Component strips YAML frontmatter from markdown prop + +`FlatwaveMDComponent` SHALL automatically strip a YAML frontmatter block (delimited by `---` at start and end) from the `markdown` prop before passing it to `react-markdown`. This is defensive: the virtual module already provides stripped content, but direct string use may include frontmatter. + +#### Scenario: frontmatter block is stripped before rendering + +- **WHEN** a markdown string starting with `---\ntitle: Test\n---\n\n# Body` is passed via the `markdown` prop +- **THEN** the rendered output does NOT contain the raw frontmatter lines (`---`, `title: Test`) + +--- + +### Requirement: Component accepts typed frontmatter prop + +`FlatwaveMDComponent` SHALL accept a `frontmatter: TFrontmatter` prop (where `TFrontmatter extends FlatwaveFrontmatter`). The frontmatter values SHALL be accessible to child components via the `children` render-prop pattern. + +#### Scenario: Frontmatter fields are passed to children render prop + +- **WHEN** `frontmatter={{ title: "About", slug: "about", ... }}` is passed and the `children` prop is `(rendered, fm) => <><h1>{fm.title}</h1>{rendered}</>` +- **THEN** the rendered output contains `<h1>About</h1>` above the markdown content + +--- + +### Requirement: Component accepts locale prop + +`FlatwaveMDComponent` SHALL accept a `locale: string` prop and expose it to consumers via the `FlatwaveLanguageContext` React context. The locale is not used to alter rendering logic within the component itself, but it is made available for descendant components via context. + +#### Scenario: Locale is exposed in context + +- **WHEN** `locale="es"` is passed and a child component reads `FlatwaveLanguageContext` +- **THEN** the context value's `locale` equals `"es"` + +--- + +### Requirement: Component supports children render prop for layout customization + +`FlatwaveMDComponent` SHALL accept an optional `children` prop typed as `(rendered: React.ReactNode, frontmatter: TFrontmatter) => React.ReactNode`. When provided, the component SHALL call `children` with the rendered markdown content and the frontmatter object, and render the result. When not provided, the component SHALL render the markdown content directly. + +#### Scenario: Children render prop wraps the rendered content + +- **WHEN** `children={(content, fm) => <article data-slug={fm.slug}>{content}</article>}` is passed +- **THEN** the output is wrapped in `<article data-slug="...">` and contains the rendered markdown + +#### Scenario: No children prop renders content directly + +- **WHEN** no `children` prop is provided +- **THEN** the component renders the markdown content without any additional wrapper + +--- + +### Requirement: Component accepts className and style props + +`FlatwaveMDComponent` SHALL accept `className?: string` and `style?: React.CSSProperties` props, which SHALL be applied to the outermost rendered element of the component. No default CSS classes SHALL be applied. + +#### Scenario: className is applied to root element + +- **WHEN** `className="prose"` is passed +- **THEN** the outermost rendered element has the class `prose` + +--- + +### Requirement: Component is composable — consumers can create extended versions + +The `FlatwaveMDComponentProps` interface and `FlatwaveMDComponent` SHALL be exported so that consumers can create wrapper components that add behaviour or new props without re-implementing the markdown rendering logic. + +#### Scenario: Consumer creates an extended component + +- **WHEN** a consumer writes `function MyPage(props: FlatwaveMDComponentProps & { header: string }) { return <><h1>{props.header}</h1><FlatwaveMDComponent {...props} /></> }` +- **THEN** TypeScript compiles without error and the component renders both the custom header and the markdown content diff --git a/openspec/specs/flatwave-md-page-component/spec.md b/openspec/specs/flatwave-md-page-component/spec.md new file mode 100644 index 0000000..2bb055b --- /dev/null +++ b/openspec/specs/flatwave-md-page-component/spec.md @@ -0,0 +1,122 @@ +# flatwave-md-page-component Specification + +## Purpose + +TBD - created by archiving change provide-composable-react-components. Update Purpose after archive. + +## Requirements + +### Requirement: Package exports FlatwaveMDPageComponent + +The package SHALL export a React component named `FlatwaveMDPageComponent` from its public surface (`@kamansoft/vite-plugin-flatwave-react`). It SHALL be a generic functional component that extends `FlatwaveMDComponent` by adding full-page concerns: SEO head tag management and a page-level wrapper element. + +#### Scenario: Named export is available + +- **WHEN** a consumer imports `{ FlatwaveMDPageComponent }` from `@kamansoft/vite-plugin-flatwave-react` +- **THEN** the import resolves to a React functional component without runtime error + +--- + +### Requirement: FlatwaveMDPageComponent renders markdown content via FlatwaveMDComponent + +`FlatwaveMDPageComponent` SHALL internally delegate markdown rendering to `FlatwaveMDComponent`, accepting the same `markdownHtml`, `markdown`, `frontmatter`, `locale`, `className`, `style`, and `children` props. All behaviour defined in the `markdown-content-component` spec SHALL apply to `FlatwaveMDPageComponent`. + +#### Scenario: Pre-compiled HTML is rendered inside the page wrapper + +- **WHEN** `markdownHtml="<p>Hello</p>"` is passed to `FlatwaveMDPageComponent` +- **THEN** the rendered output contains `<p>Hello</p>` inside the page wrapper element + +#### Scenario: Raw markdown is rendered inside the page wrapper when markdownHtml is absent + +- **WHEN** `markdown="# Heading"` is passed without `markdownHtml` +- **THEN** the rendered output contains an `<h1>Heading</h1>` inside the page wrapper element + +--- + +### Requirement: FlatwaveMDPageComponent manages SEO head tags via react-helmet-async + +`FlatwaveMDPageComponent` SHALL render SEO head tags using `react-helmet-async`'s `<Helmet>` component (a peer dependency). At minimum, the following tags SHALL be rendered when the corresponding frontmatter field is present: + +- `<title>` — from `frontmatter.title` +- `<meta name="description">` — from `frontmatter.description` +- `<link rel="canonical">` — from `frontmatter.canonical` +- `<meta property="og:title">` — from `frontmatter.og?.title` or `frontmatter.title` +- `<meta property="og:description">` — from `frontmatter.og?.description` or `frontmatter.description` +- `<meta property="og:image">` — from `frontmatter.image` +- `<meta name="robots">` — from `frontmatter.robots` + +These head tags SHALL only be rendered at runtime (client-side); during SSG the static HTML head is managed by the `renderHtmlHead()` utility in the build pipeline, not by this component. + +#### Scenario: Title tag is set from frontmatter + +- **WHEN** `frontmatter.title = "About Us"` is passed +- **THEN** the document `<title>` is updated to `"About Us"` after client-side hydration + +#### Scenario: Description meta is set from frontmatter + +- **WHEN** `frontmatter.description = "Learn about us"` is passed +- **THEN** `<meta name="description" content="Learn about us">` is present in the document head + +#### Scenario: No Helmet is rendered when title is absent + +- **WHEN** a `frontmatter` object with no `title` field is passed (note: FlatwaveFrontmatter requires title, so this is a type guard scenario for partial/extended use) +- **THEN** no empty `<title>` tag is injected (the component SHALL guard against empty title tags) + +--- + +### Requirement: FlatwaveMDPageComponent accepts a pageWrapper slot prop + +`FlatwaveMDPageComponent` SHALL accept a `pageWrapper?: React.ComponentType<{ children: React.ReactNode; frontmatter: TFrontmatter; locale: string }>` prop. When provided, the component SHALL render the content inside this wrapper component. When not provided, the component SHALL render the content inside a `<main>` element. + +#### Scenario: Custom page wrapper is used when provided + +- **WHEN** `pageWrapper={({ children }) => <section className="page">{children}</section>}` is passed +- **THEN** the rendered output wraps the content in `<section class="page">` instead of `<main>` + +#### Scenario: Default main wrapper is used when no pageWrapper is provided + +- **WHEN** no `pageWrapper` prop is passed +- **THEN** the rendered output wraps content in a `<main>` element + +--- + +### Requirement: FlatwaveMDPageComponent accepts a loadingFallback prop + +`FlatwaveMDPageComponent` SHALL accept a `loadingFallback?: React.ReactNode` prop. This content SHALL be rendered when neither `markdownHtml` nor `markdown` is provided (e.g. during async content loading in client-side navigation). + +#### Scenario: Loading fallback is rendered when no content is available + +- **WHEN** neither `markdownHtml` nor `markdown` is provided but `loadingFallback={<div>Loading...</div>}` is passed +- **THEN** the component renders the loading fallback content + +#### Scenario: No output when loading fallback and content are both absent + +- **WHEN** neither `markdownHtml`, `markdown`, nor `loadingFallback` are provided +- **THEN** the component renders null without throwing + +--- + +### Requirement: DefaultRenderStrategy uses FlatwaveMDPageComponent internally + +The plugin's `DefaultRenderStrategy` SHALL use `FlatwaveMDPageComponent` to render each route during SSG. It SHALL pass `markdownHtml` (pre-compiled body), `frontmatter`, and `locale` from the `RenderContext`. If no matching component override is found in the `components` map, `FlatwaveMDPageComponent` SHALL be used as the default renderer. + +#### Scenario: SSG renders a route using FlatwaveMDPageComponent when no component override exists + +- **WHEN** a route's `component` field references a component not found in the components map +- **THEN** `DefaultRenderStrategy` falls back to `FlatwaveMDPageComponent` and produces valid HTML output (not an error string) + +#### Scenario: SSG renders a route using a custom component when an override exists + +- **WHEN** a route's `component` field resolves to a module in the components map +- **THEN** `DefaultRenderStrategy` uses that component instead of `FlatwaveMDPageComponent` + +--- + +### Requirement: FlatwaveMDPageComponent is composable and extensible + +`FlatwaveMDPageProps` interface SHALL be exported. Consumers SHALL be able to create page components that extend `FlatwaveMDPageComponent` by wrapping it or by accepting `FlatwaveMDPageProps` as their props type. + +#### Scenario: Consumer creates a branded page component + +- **WHEN** a consumer writes `function BrandedPage(props: FlatwaveMDPageProps) { return <FlatwaveMDPageComponent {...props} pageWrapper={BrandedWrapper} /> }` +- **THEN** TypeScript compiles without error and the component renders with the branded wrapper diff --git a/openspec/specs/ssg-custom-emitters/spec.md b/openspec/specs/ssg-custom-emitters/spec.md new file mode 100644 index 0000000..1cc0e7c --- /dev/null +++ b/openspec/specs/ssg-custom-emitters/spec.md @@ -0,0 +1,103 @@ +# ssg-custom-emitters Specification + +## Purpose + +TBD - created by archiving change provide-composable-react-components. Update Purpose after archive. + +## Requirements + +### Requirement: RenderHooks interface includes an emitFiles callback + +The `RenderHooks` interface in `packages/vite-plugin-flatwave-react/src/types.ts` SHALL include an optional `emitFiles` callback: + +```ts +emitFiles?: (context: EmitFilesContext) => Promise<SsgOutputFile[]> | SsgOutputFile[]; +``` + +Where `EmitFilesContext` is a new exported interface containing: + +- `routes: FlatwaveRoute[]` — all public routes from the content index +- `contentIndex: FlatwaveContentIndex` — the complete content index including all locales and entries +- `renderedFiles: SsgOutputFile[]` — all HTML output files already rendered by the SSG loop + +`SsgOutputFile` (already defined in `runSsg.ts`) SHALL be exported from the package's public surface for use in consumer `emitFiles` implementations. + +#### Scenario: emitFiles is optional and build succeeds without it + +- **WHEN** a consumer configures `flatwaveContent()` without providing `hooks.emitFiles` +- **THEN** the build completes without error and the standard output files are emitted + +#### Scenario: TypeScript accepts the emitFiles signature + +- **WHEN** a consumer writes `hooks: { emitFiles: ({ routes }) => [{ fileName: 'nav.json', source: '{}' }] }` +- **THEN** TypeScript compiles without error + +--- + +### Requirement: RenderPipeline executes emitFiles hooks after the render loop + +`RenderPipeline` SHALL add an `executeEmitFiles` method that calls all registered `emitFiles` hooks sequentially and merges their returned `SsgOutputFile[]` arrays. Errors in individual hooks SHALL be caught and logged, and the remaining hooks SHALL continue executing. + +#### Scenario: executeEmitFiles returns combined output from all hooks + +- **WHEN** two `emitFiles` hooks are registered, returning `[fileA]` and `[fileB]` respectively +- **THEN** `executeEmitFiles` returns `[fileA, fileB]` + +#### Scenario: Hook error does not abort remaining hooks + +- **WHEN** the first `emitFiles` hook throws an error and the second returns `[fileB]` +- **THEN** `executeEmitFiles` logs the error and still returns `[fileB]` + +--- + +### Requirement: runSsg calls executeEmitFiles after the rendering loop + +In `runSsg.ts`, after all routes have been rendered and before the standard outputs (route manifest, sitemap, robots.txt) are assembled, `runSsg` SHALL call `pipeline.executeEmitFiles` with the `EmitFilesContext` containing the full routes, content index, and the list of rendered HTML files. The returned `SsgOutputFile[]` SHALL be appended to the output file list and emitted as Vite bundle assets. + +#### Scenario: emitFiles output files appear in the build output directory + +- **WHEN** `hooks.emitFiles` returns `[{ fileName: 'navigation.json', source: '{"items":[]}' }]` +- **THEN** `navigation.json` is present in the build output directory after `vite build` + +#### Scenario: emitFiles runs after all HTML route files are rendered + +- **WHEN** `hooks.emitFiles` is called +- **THEN** the `renderedFiles` context field contains the rendered HTML for all public routes + +--- + +### Requirement: emitFiles can generate a navigation manifest from route data + +A consumer SHALL be able to use `emitFiles` to generate a `navigation.json` file where each entry contains the `url` (route path) and `publicName` (route title from frontmatter). This JSON file can then be used by a separately implemented React component to populate a navigation menu. + +#### Scenario: Navigation JSON is generated with correct shape + +- **WHEN** `hooks.emitFiles = ({ routes }) => [{ fileName: 'navigation.json', source: JSON.stringify(routes.map(r => ({ url: r.path, publicName: r.metadata.title }))) }]` +- **THEN** `navigation.json` contains an array of objects each with `url` and `publicName` string fields + +#### Scenario: Navigation JSON entries correspond to public routes only + +- **WHEN** the content directory contains both public (`public: true`) and private (`public: false`) entries +- **THEN** the `routes` received by `emitFiles` contain only public routes (matching the existing behaviour of `index.routes`) + +--- + +### Requirement: SsgOutputFile is exported from the package public surface + +`SsgOutputFile` (the `{ fileName: string; source: string }` interface) SHALL be exported from `@kamansoft/vite-plugin-flatwave-react` so that consumers can type their `emitFiles` return value without importing from internal package paths. + +#### Scenario: Consumer can import SsgOutputFile for type annotation + +- **WHEN** a consumer writes `import type { SsgOutputFile } from '@kamansoft/vite-plugin-flatwave-react'` +- **THEN** TypeScript resolves the type without error + +--- + +### Requirement: emitFiles context is typed and exported + +`EmitFilesContext` SHALL be exported from the package public surface so consumers can type their `emitFiles` callback parameter explicitly. + +#### Scenario: Consumer can import EmitFilesContext for type annotation + +- **WHEN** a consumer writes `import type { EmitFilesContext } from '@kamansoft/vite-plugin-flatwave-react'` +- **THEN** TypeScript resolves the type without error and the type contains `routes`, `contentIndex`, and `renderedFiles` fields diff --git a/package-lock.json b/package-lock.json index a2b22fd..0e43049 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,12 +1,12 @@ { - "name": "vite-plugin-flatwave-react-workspace", - "version": "1.0.0", + "name": "vite-plugin-flatwave-react", + "version": "2.0.1", "lockfileVersion": 3, "requires": true, "packages": { "": { - "name": "vite-plugin-flatwave-react-workspace", - "version": "1.0.0", + "name": "vite-plugin-flatwave-react", + "version": "2.0.1", "workspaces": [ "packages/*", "examples/*" @@ -32,13 +32,15 @@ }, "examples/basic-react-site": { "name": "@flatwave/example-basic-react-site", - "version": "0.1.0", + "version": "1.0.0", "dependencies": { "@kamansoft/vite-plugin-flatwave-react": "file:../../packages/vite-plugin-flatwave-react", "@vitejs/plugin-react": "^4.3.4", "react": "^18.3.1", "react-dom": "^18.3.1", - "react-markdown": "^9.0.3" + "react-helmet-async": "^2.0.0", + "react-markdown": "^10.0.0", + "react-router-dom": "^6.0.0" }, "devDependencies": { "@types/react": "^18.3.12", @@ -47,6 +49,38 @@ "vite": "^6.0.7" } }, + "examples/basic-react-site/node_modules/react-router-dom": { + "version": "6.30.4", + "resolved": "https://registry.npmjs.org/react-router-dom/-/react-router-dom-6.30.4.tgz", + "integrity": "sha512-q4HvNl+mmDdkS0g+MqiBZNteQJCuimWoOyHMy4T/RQLAn9Z29+E91QXRaxOujeMl2HTzRSS0KFPd7lxX3PjV0Q==", + "license": "MIT", + "dependencies": { + "@remix-run/router": "1.23.3", + "react-router": "6.30.4" + }, + "engines": { + "node": ">=14.0.0" + }, + "peerDependencies": { + "react": ">=16.8", + "react-dom": ">=16.8" + } + }, + "examples/basic-react-site/node_modules/react-router-dom/node_modules/react-router": { + "version": "6.30.4", + "resolved": "https://registry.npmjs.org/react-router/-/react-router-6.30.4.tgz", + "integrity": "sha512-SVUsDe+DybHM/WmYKIVYhZh1o5Dcuf16yM6WjG02Q9XVFMZIJyHYhwrr6bFBXZkVP6z69kNkMyBCujt8FaFLJA==", + "license": "MIT", + "dependencies": { + "@remix-run/router": "1.23.3" + }, + "engines": { + "node": ">=14.0.0" + }, + "peerDependencies": { + "react": ">=16.8" + } + }, "examples/basic-react-site/node_modules/vite": { "version": "6.4.3", "resolved": "https://registry.npmjs.org/vite/-/vite-6.4.3.tgz", @@ -2060,6 +2094,15 @@ "node": ">=12" } }, + "node_modules/@remix-run/router": { + "version": "1.23.3", + "resolved": "https://registry.npmjs.org/@remix-run/router/-/router-1.23.3.tgz", + "integrity": "sha512-4An71tdz9X8+3sI4Qqqd2LWd9vS39J7sqd9EU4Scw7TJE/qB10Flv/UuqbPVgfQV9XoK8Np6jNquZitnZq5i+Q==", + "license": "MIT", + "engines": { + "node": ">=14.0.0" + } + }, "node_modules/@rolldown/pluginutils": { "version": "1.0.0-beta.27", "resolved": "https://registry.npmjs.org/@rolldown/pluginutils/-/pluginutils-1.0.0-beta.27.tgz", @@ -4849,6 +4892,20 @@ "integrity": "sha512-Kvp459HrV2FEJ1CAsi1Ku+MY3kasH19TFykTz2xWmMeq6bk2NU3XXvfJ+Q61m0xktWwt+1HSYf3JZsTms3aRJg==", "license": "MIT" }, + "node_modules/cookie": { + "version": "1.1.1", + "resolved": "https://registry.npmjs.org/cookie/-/cookie-1.1.1.tgz", + "integrity": "sha512-ei8Aos7ja0weRpFzJnEA9UHJ/7XQmqglbRwnf2ATjcB9Wq874VKH9kfjjirM6UhU2/E5fFYadylyhFldcqSidQ==", + "dev": true, + "license": "MIT", + "engines": { + "node": ">=18" + }, + "funding": { + "type": "opencollective", + "url": "https://opencollective.com/express" + } + }, "node_modules/core-util-is": { "version": "1.0.3", "resolved": "https://registry.npmjs.org/core-util-is/-/core-util-is-1.0.3.tgz", @@ -7350,6 +7407,15 @@ "node": ">= 0.4" } }, + "node_modules/invariant": { + "version": "2.2.4", + "resolved": "https://registry.npmjs.org/invariant/-/invariant-2.2.4.tgz", + "integrity": "sha512-phJfQVBuaJM5raOpJjSfkiD6BpbCE4Ns//LaXl6wGYtUBY83nWS6Rf9tXm2e8VaK60JEjYldbPif/A2B1C2gNA==", + "license": "MIT", + "dependencies": { + "loose-envify": "^1.0.0" + } + }, "node_modules/is-alphabetical": { "version": "2.0.1", "resolved": "https://registry.npmjs.org/is-alphabetical/-/is-alphabetical-2.0.1.tgz", @@ -12364,6 +12430,26 @@ "react": "^18.3.1" } }, + "node_modules/react-fast-compare": { + "version": "3.2.2", + "resolved": "https://registry.npmjs.org/react-fast-compare/-/react-fast-compare-3.2.2.tgz", + "integrity": "sha512-nsO+KSNgo1SbJqJEYRE9ERzo7YtYbou/OqjSQKxV7jcKox7+usiUVZOAC+XnDOABXggQTno0Y1CpVnuWEc1boQ==", + "license": "MIT" + }, + "node_modules/react-helmet-async": { + "version": "2.0.5", + "resolved": "https://registry.npmjs.org/react-helmet-async/-/react-helmet-async-2.0.5.tgz", + "integrity": "sha512-rYUYHeus+i27MvFE+Jaa4WsyBKGkL6qVgbJvSBoX8mbsWoABJXdEO0bZyi0F6i+4f0NuIb8AvqPMj3iXFHkMwg==", + "license": "Apache-2.0", + "dependencies": { + "invariant": "^2.2.4", + "react-fast-compare": "^3.2.2", + "shallowequal": "^1.1.0" + }, + "peerDependencies": { + "react": "^16.6.0 || ^17.0.0 || ^18.0.0" + } + }, "node_modules/react-is": { "version": "16.13.1", "resolved": "https://registry.npmjs.org/react-is/-/react-is-16.13.1.tgz", @@ -12372,9 +12458,9 @@ "license": "MIT" }, "node_modules/react-markdown": { - "version": "9.1.0", - "resolved": "https://registry.npmjs.org/react-markdown/-/react-markdown-9.1.0.tgz", - "integrity": "sha512-xaijuJB0kzGiUdG7nc2MOMDUDBWPyGAjZtUrow9XxUeua8IqeP+VlIfAZ3bphpcLTnSZXz6z9jcVC/TCwbfgdw==", + "version": "10.1.0", + "resolved": "https://registry.npmjs.org/react-markdown/-/react-markdown-10.1.0.tgz", + "integrity": "sha512-qKxVopLT/TyA6BX3Ue5NwabOsAzm0Q7kAPwq6L+wWDwisYs7R8vZ0nRXqq6rkueboxpkjvLGU9fWifiX/ZZFxQ==", "license": "MIT", "dependencies": { "@types/hast": "^3.0.0", @@ -12407,6 +12493,46 @@ "node": ">=0.10.0" } }, + "node_modules/react-router": { + "version": "7.18.0", + "resolved": "https://registry.npmjs.org/react-router/-/react-router-7.18.0.tgz", + "integrity": "sha512-pTTGt8J+ji1NOmYnjzT+bAJy/1zD+Jp4ziO6cL7T3ZLvXKtusO7BpFqlRXitqpcPVqllsIXFHRMt+2/k3Xn6HQ==", + "dev": true, + "license": "MIT", + "dependencies": { + "cookie": "^1.0.1", + "set-cookie-parser": "^2.6.0" + }, + "engines": { + "node": ">=20.0.0" + }, + "peerDependencies": { + "react": ">=18", + "react-dom": ">=18" + }, + "peerDependenciesMeta": { + "react-dom": { + "optional": true + } + } + }, + "node_modules/react-router-dom": { + "version": "7.18.0", + "resolved": "https://registry.npmjs.org/react-router-dom/-/react-router-dom-7.18.0.tgz", + "integrity": "sha512-Fi0yY6kgtKae/Th2xibdWK0KSdYZ4B53Gyf6wRtomOKWgpNm7H7+DyfDhncdz9FKbpS+1jmDhg3F4WoGJ+yFOA==", + "dev": true, + "license": "MIT", + "dependencies": { + "react-router": "7.18.0" + }, + "engines": { + "node": ">=20.0.0" + }, + "peerDependencies": { + "react": ">=18", + "react-dom": ">=18" + } + }, "node_modules/read-package-up": { "version": "12.0.0", "resolved": "https://registry.npmjs.org/read-package-up/-/read-package-up-12.0.0.tgz", @@ -13255,6 +13381,13 @@ "node": ">= 0.8" } }, + "node_modules/set-cookie-parser": { + "version": "2.7.2", + "resolved": "https://registry.npmjs.org/set-cookie-parser/-/set-cookie-parser-2.7.2.tgz", + "integrity": "sha512-oeM1lpU/UvhTxw+g3cIfxXHyJRc/uidd3yK1P242gzHds0udQBYzs3y8j4gCCW+ZJ7ad0yctld8RYO+bdurlvw==", + "dev": true, + "license": "MIT" + }, "node_modules/set-function-length": { "version": "1.2.2", "resolved": "https://registry.npmjs.org/set-function-length/-/set-function-length-1.2.2.tgz", @@ -13304,6 +13437,12 @@ "node": ">= 0.4" } }, + "node_modules/shallowequal": { + "version": "1.1.0", + "resolved": "https://registry.npmjs.org/shallowequal/-/shallowequal-1.1.0.tgz", + "integrity": "sha512-y0m1JoUZSlPAjXVtPPW70aZWfIL/dSP7AFkRnniLCrK/8MDKog3TySTBmckD+RObVxH0v4Tox67+F14PdED2oQ==", + "license": "MIT" + }, "node_modules/shebang-command": { "version": "2.0.0", "resolved": "https://registry.npmjs.org/shebang-command/-/shebang-command-2.0.0.tgz", @@ -15605,12 +15744,13 @@ }, "packages/vite-plugin-flatwave-react": { "name": "@kamansoft/vite-plugin-flatwave-react", - "version": "0.1.0", + "version": "2.0.1", "license": "MIT", "dependencies": { "commander": "^13.1.0", "fast-glob": "^3.3.3", "gray-matter": "^4.0.3", + "react-helmet-async": "^2.0.0", "rehype-raw": "^7.0.0", "rehype-stringify": "^10.0.1", "remark": "^15.0.1", @@ -15627,6 +15767,8 @@ "@types/react-dom": "^18.3.1", "react": "^18.3.1", "react-dom": "^18.3.1", + "react-markdown": "^10.1.0", + "react-router-dom": "^7.18.0", "typescript": "^5.7.2", "vite": "^6.0.7" }, @@ -15636,6 +15778,9 @@ "peerDependencies": { "react": ">=18.0.0", "react-dom": ">=18.0.0", + "react-helmet-async": "^2.0.0", + "react-markdown": "^10.0.0", + "react-router-dom": "^6.0.0", "vite": "^5.0.0 || ^6.0.0 || ^7.0.0" } }, diff --git a/package.json b/package.json index bab5157..dbb794c 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { - "name": "vite-plugin-flatwave-react-workspace", - "version": "1.0.0", + "name": "vite-plugin-flatwave-react", + "version": "2.0.1", "private": true, "type": "module", "workspaces": [ diff --git a/packages/vite-plugin-flatwave-react/README.md b/packages/vite-plugin-flatwave-react/README.md index 58078dd..8931cfe 100644 --- a/packages/vite-plugin-flatwave-react/README.md +++ b/packages/vite-plugin-flatwave-react/README.md @@ -1,13 +1,57 @@ # vite-plugin-flatwave-react -Vite content plugin for Markdown-driven, i18n-aware static React sites. +Vite plugin for Markdown-driven, i18n-aware static React sites with composable routing components. + +## What It Does + +`vite-plugin-flatwave-react` gives you a complete toolkit for building **multilingual, SEO-compatible, +Markdown-based static React sites**: + +- **Automatic route generation** — `vite build` produces locale-prefixed static HTML for every content + file (`/es/about/index.html`, `/pt/about/index.html`), a `sitemap.xml`, and a `robots.txt` +- **Composable routing** — drop-in React components (`FlatwaveLanguageRouter`, `FlatwaveMDPageComponent`) + that you wire together in your own `App.tsx`; routes are generated from those same components +- **Content-driven** — Markdown files define pages via frontmatter; the plugin indexes, compiles, and + exposes content via a typed virtual module +- **i18n-aware** — URL-prefix language routing, browser language detection, and context-based locale + access — no i18n library required + +## How It Works + +``` +src/content/{locale}/*.md + │ + ▼ +flatwaveContent() plugin + ├─ Indexes content → virtual:flatwave/content + ├─ Compiles Markdown → HTML during build + └─ SSG pipeline → dist/{locale}/{slug}/index.html + ▲ + │ rendered via + Your App.tsx using FlatwaveLanguageRouter + FlatwaveMDPageComponent +``` + +The routes are **generated by your project** — you compose `FlatwaveLanguageRouter` and +`FlatwaveMDPageComponent` in your `App.tsx`, and Vite processes those components to produce the static +HTML for every content route. ## Install ```bash -npm install vite-plugin-flatwave-react +npm install @kamansoft/vite-plugin-flatwave-react react-markdown react-helmet-async react-router-dom ``` +Peer dependencies: + +| Package | Version | +| -------------------- | -------------------------------- | +| `react` | `>=18.0.0` | +| `react-dom` | `>=18.0.0` | +| `react-markdown` | `^10.0.0` | +| `react-helmet-async` | `^2.0.0` | +| `react-router-dom` | `^6.0.0` | +| `vite` | `^5.0.0 \|\| ^6.0.0 \|\| ^7.0.0` | + ## Configure Vite ```ts @@ -15,7 +59,7 @@ npm install vite-plugin-flatwave-react import { defineConfig } from 'vite'; import react from '@vitejs/plugin-react'; import path from 'node:path'; -import { flatwaveContent } from 'vite-plugin-flatwave-react'; +import { flatwaveContent } from '@kamansoft/vite-plugin-flatwave-react'; export default defineConfig({ plugins: [ @@ -24,15 +68,15 @@ export default defineConfig({ contentDir: path.resolve(__dirname, 'src/content'), locales: ['es', 'pt'], defaultLocale: 'es', - strictMissingLocales: false, - componentsDir: path.resolve(__dirname, 'src/components'), sitemap: { hostname: 'https://example.com' }, }), ], }); ``` -## Content layout +No `componentsDir` required. Routes are generated from your composable `App.tsx` setup. + +## Content Layout ```text src/ @@ -43,59 +87,230 @@ src/ pt/ index.md about.md - components/ - SimplePage.tsx ``` -Each Markdown file needs baseline frontmatter: +### Markdown Frontmatter ```yaml --- -title: 'Page title' -slug: 'page-slug' -id: 'unique-id' -component: 'SimplePage' +title: 'About Us' +slug: 'about' +id: 'about' public: true -description: 'Short description' -canonical: '/es/page-slug' +description: 'Learn about us' +canonical: '/es/about' robots: 'index, follow' -keywords: ['tag1', 'tag2'] +og: + title: 'About Us' + description: 'Learn about us' --- -Markdown body. +# About Us + +Content here. ``` -Additional frontmatter fields are preserved in `attributes` and forwarded to the React component. +## Build Your App with Composable Components -## React hooks +Wire `FlatwaveLanguageRouter` and `FlatwaveMDPageComponent` in your `App.tsx`. During `vite build`, +these same components are used to generate the static HTML for every route. -```ts +```tsx +// src/App.tsx import { - useFlatwaveContent, + FlatwaveLanguageRouter, + FlatwaveMDPageComponent, + FlatwaveLanguageSelector, useFlatwaveRoutes, - useFlatwaveAlternatives, -} from 'vite-plugin-flatwave-react/react'; + useFlatwaveLanguage, + getContent, +} from '@kamansoft/vite-plugin-flatwave-react/react'; + +function Layout({ children, locale }: { children: React.ReactNode; locale: string }) { + return ( + <div lang={locale}> + <header> + <FlatwaveLanguageSelector getLabel={(l) => ({ es: 'Español', pt: 'Português' })[l] || l} /> + </header> + <main>{children}</main> + </div> + ); +} + +export function App() { + const { locale } = useFlatwaveLanguage(); + const routes = useFlatwaveRoutes(locale); // ← explicit: you choose the data source + + return ( + <FlatwaveLanguageRouter + supportedLanguages={['es', 'pt']} + defaultLanguage="es" + routes={routes} + layoutWrapper={Layout} + renderPage={(route, lang) => ( + <FlatwaveMDPageComponent + frontmatter={route.frontmatter} + markdownHtml={getContent(route.contentId, lang)?.body} + locale={lang} + /> + )} + /> + ); +} ``` -## Build outputs +> See `examples/basic-react-site/` for a complete working example. + +## Automatic Route Generation + +When you run `vite build`, the plugin automatically generates: + +| Output | Description | +| -------------------------- | ----------------------------------------------- | +| `dist/es/about/index.html` | Pre-rendered HTML for the Spanish About page | +| `dist/pt/about/index.html` | Pre-rendered HTML for the Portuguese About page | +| `dist/sitemap.xml` | SEO sitemap listing all public routes | +| `dist/robots.txt` | Search engine directives linking to sitemap | +| `dist/route-manifest.json` | Full route metadata for tooling | + +Routes are generated for **every public Markdown file** in your `contentDir`. You control which pages +are public via `public: true` in frontmatter. + +## Composable Components Reference + +### FlatwaveMDComponent + +Renders Markdown content. Accepts pre-compiled HTML (`markdownHtml`) for SSG mode or raw Markdown +(`markdown`) for client-side rendering. + +```tsx +<FlatwaveMDComponent + frontmatter={frontmatter} + markdownHtml={compiledHtml} // SSG mode: pre-compiled HTML + locale="es" + className="prose" +/> +``` + +Key props: `frontmatter`, `markdownHtml`, `markdown`, `locale`, `className`, `style`, +`children: (rendered, fm) => ReactNode`. + +### FlatwaveMDPageComponent + +Full-page wrapper — delegates rendering to `FlatwaveMDComponent` and adds SEO head tags via +`react-helmet-async` (`<title>`, `<meta name="description">`, `<link rel="canonical">`, Open Graph). + +```tsx +<FlatwaveMDPageComponent + frontmatter={frontmatter} + markdownHtml={compiledHtml} + locale="es" + pageWrapper={Layout} // optional: custom layout component + loadingFallback={<Spinner />} // optional: shown while content loads +/> +``` -During `vite build`, the plugin generates: +### FlatwaveLanguageRouter -- locale-prefixed static HTML route files -- `route-manifest.json` -- `sitemap.xml` -- `robots.txt` -- a virtual module for content lookup +Convenience wrapper that composes `BrowserRouter` + `FlatwaveLanguageDetector` + `FlatwaveAppRoutes`. + +```tsx +<FlatwaveLanguageRouter + supportedLanguages={['es', 'pt']} + defaultLanguage="es" + routes={routes} // explicit: pass your route array + renderPage={(route, locale) => <FlatwaveMDPageComponent ... />} + layoutWrapper={MyLayout} + onLanguageChange={(lang) => i18n.changeLanguage(lang)} +/> +``` + +### FlatwaveLanguageDetector (standalone) + +Use inside your own `BrowserRouter` to add language detection without replacing your router setup. + +```tsx +<BrowserRouter> + <FlatwaveLanguageDetector supportedLanguages={['es', 'pt']} defaultLanguage="es"> + <MyAppRoutes /> + </FlatwaveLanguageDetector> +</BrowserRouter> +``` + +### FlatwaveLanguageSelector + +Renders a language switcher. Reads supported languages from `FlatwaveLanguageContext`. + +```tsx +<FlatwaveLanguageSelector + getLabel={(lang) => ({ es: 'Español', pt: 'Português' })[lang] || lang} + renderOption={(lang, label, isActive) => <button disabled={isActive}>{label}</button>} +/> +``` + +## React Hooks + +```ts +import { + useFlatwaveContent, // get one content entry + useFlatwaveRoutes, // get routes for a locale + useFlatwaveAlternatives, // get alternate-locale URLs for a content ID + useFlatwaveLanguage, // get current locale from context +} from '@kamansoft/vite-plugin-flatwave-react/react'; +``` + +## Advanced: Custom SSG Hooks + +Customise the build pipeline with hooks: + +```ts +flatwaveContent({ + // ... + ssg: { + hooks: { + // Transform Markdown before HTML compilation + transformMarkdown: async (md, ctx) => md + '\n\n---\n*Built with Flatwave*', + // Inject analytics into every generated page + transformHtml: async (html, ctx) => + html.replace('</body>', '<script>/* analytics */</script></body>'), + // Emit extra files (e.g. navigation JSON) + emitFiles: ({ routes }) => [ + { + fileName: 'navigation.json', + source: JSON.stringify(routes.map((r) => ({ url: r.path, title: r.metadata.title }))), + }, + ], + }, + }, +}); +``` + +## Advanced: Custom Render Strategy + +Override how each route is rendered to HTML: + +```ts +import { flatwaveContent, type RenderStrategy, type RenderContext } from '@kamansoft/vite-plugin-flatwave-react'; + +class MyStrategy implements RenderStrategy { + async render(ctx: RenderContext): Promise<string> { + return `<html><body><h1>${ctx.contentEntry.frontmatter.title}</h1></body></html>`; + } +} + +flatwaveContent({ ssg: { strategy: new MyStrategy() }, ... }) +``` ## Validation CLI ```bash -npx flatwave-validate --content-dir src/content --locales es,pt --default-locale es +npx flatwave-validate \ + --content-dir src/content \ + --locales es,pt \ + --default-locale es ``` -Use `--strict-missing` to fail when locale variants are missing. +Use `--strict-missing` to fail the build when a content file is missing its counterpart in another locale. ## License MIT © 2026 Flatwave contributors. - -## Example App Integration diff --git a/packages/vite-plugin-flatwave-react/dist/cli/validate.js b/packages/vite-plugin-flatwave-react/dist/cli/validate.js index f01f0f8..ba8331d 100755 --- a/packages/vite-plugin-flatwave-react/dist/cli/validate.js +++ b/packages/vite-plugin-flatwave-react/dist/cli/validate.js @@ -8,7 +8,6 @@ program .requiredOption('--content-dir <dir>', 'Markdown content directory, e.g. src/content') .requiredOption('--locales <locales>', 'Comma-separated locales, e.g. es,pt') .requiredOption('--default-locale <locale>', 'Default locale, e.g. es') - .option('--components-dir <dirs>', 'Comma-separated component directories', 'src/components,src/pages') .option('--strict-missing', 'Fail when locale variants are missing', false) .option('--no-validate-components', 'Disable component existence validation') .action(async (options) => { @@ -16,15 +15,10 @@ program .split(',') .map((locale) => locale.trim()) .filter(Boolean); - const componentsDir = options.componentsDir - .split(',') - .map((dir) => dir.trim()) - .filter(Boolean); const result = await validateContent({ contentDir: options.contentDir, locales, defaultLocale: options.defaultLocale, - componentsDir, strictMissingLocales: options.strictMissing, validateComponents: options.validateComponents, }); diff --git a/packages/vite-plugin-flatwave-react/dist/content/indexer.js b/packages/vite-plugin-flatwave-react/dist/content/indexer.js index 7420de9..043f700 100644 --- a/packages/vite-plugin-flatwave-react/dist/content/indexer.js +++ b/packages/vite-plugin-flatwave-react/dist/content/indexer.js @@ -13,7 +13,6 @@ export async function buildIndex(options) { slug: file.slug, path: routeForLocaleSlug(file.locale, file.slug), file: file.file, - component: file.frontmatter.component ? String(file.frontmatter.component) : undefined, public: file.frontmatter.public !== false && String(file.frontmatter.public ?? 'true').toLowerCase() !== 'false', attributes: { ...file.frontmatter }, diff --git a/packages/vite-plugin-flatwave-react/dist/content/routeBuilder.js b/packages/vite-plugin-flatwave-react/dist/content/routeBuilder.js index 0fbb231..3c887ec 100644 --- a/packages/vite-plugin-flatwave-react/dist/content/routeBuilder.js +++ b/packages/vite-plugin-flatwave-react/dist/content/routeBuilder.js @@ -22,7 +22,6 @@ export function buildContentIndex(entries) { locale: entry.locale, path: entry.route, contentId: entry.id, - component: entry.component, metadata: buildSeoMetadata(entry.frontmatter, entry.route, entry.locale), frontmatter: entry.frontmatter, alternatives, diff --git a/packages/vite-plugin-flatwave-react/dist/content/scanner.js b/packages/vite-plugin-flatwave-react/dist/content/scanner.js index 52abf3a..8a06027 100644 --- a/packages/vite-plugin-flatwave-react/dist/content/scanner.js +++ b/packages/vite-plugin-flatwave-react/dist/content/scanner.js @@ -53,7 +53,6 @@ export function buildContentEntry(parsed, alternatives) { slug: parsed.slug, path: route, file: parsed.file, - component: parsed.frontmatter.component ? String(parsed.frontmatter.component) : undefined, public: isPublicEntry(parsed.frontmatter), attributes, frontmatter: parsed.frontmatter, diff --git a/packages/vite-plugin-flatwave-react/dist/content/validator.d.ts b/packages/vite-plugin-flatwave-react/dist/content/validator.d.ts index 76ed923..977a36b 100644 --- a/packages/vite-plugin-flatwave-react/dist/content/validator.d.ts +++ b/packages/vite-plugin-flatwave-react/dist/content/validator.d.ts @@ -1,3 +1,3 @@ -export type { ValidationResult } from '../types.js'; import type { FlatwaveContentOptions, ValidationResult } from '../types'; +export type { ValidationResult } from '../types'; export declare function validateContent(options: FlatwaveContentOptions): Promise<ValidationResult>; diff --git a/packages/vite-plugin-flatwave-react/dist/content/validator.js b/packages/vite-plugin-flatwave-react/dist/content/validator.js index 5f92977..34f541c 100644 --- a/packages/vite-plugin-flatwave-react/dist/content/validator.js +++ b/packages/vite-plugin-flatwave-react/dist/content/validator.js @@ -1,17 +1,14 @@ -import { readdir } from 'node:fs/promises'; -import path from 'node:path'; import { routeForLocaleSlug, scanMarkdownFiles } from './scanner.js'; import { buildContentIndex } from './routeBuilder.js'; export async function validateContent(options) { const errors = []; const warnings = []; - const requiredFields = options.requiredFields ?? ['title', 'slug', 'id', 'component', 'public']; + const requiredFields = options.requiredFields ?? ['title', 'slug', 'id', 'public']; const files = await scanMarkdownFiles(options.contentDir, options.locales); await validateRequiredFields(files, requiredFields, errors); await validateDuplicateIds(files, errors); await validateDuplicateSlugs(files, errors); await validateMenuPositions(files, errors); - await validateComponents(files, options, errors); validateMissingLocales(files, options, warnings); const entries = files.map((file) => { const id = String(file.frontmatter.id || file.slug); @@ -22,7 +19,6 @@ export async function validateContent(options) { slug: file.slug, path: route, file: file.file, - component: file.frontmatter.component ? String(file.frontmatter.component) : undefined, public: file.frontmatter.public !== false && String(file.frontmatter.public ?? 'true').toLowerCase() !== 'false', attributes: file.frontmatter, @@ -101,45 +97,6 @@ async function validateMenuPositions(files, errors) { } } } -async function validateComponents(files, options, errors) { - if (options.validateComponents === false) - return; - const available = await discoverComponents(options.componentsDir); - for (const file of files) { - const component = file.frontmatter.component ? String(file.frontmatter.component) : undefined; - if (!component) - continue; - if (!available.has(component)) { - errors.push(`[${file.locale}] ${file.file}: Component '${component}' does not exist in ${formatComponentsDir(options.componentsDir)}.`); - } - } -} -async function discoverComponents(componentsDir) { - const dirs = Array.isArray(componentsDir) - ? componentsDir - : componentsDir - ? [componentsDir] - : ['src/components', 'src/pages']; - const components = new Set(); - for (const dir of dirs) { - const absolute = path.resolve(dir); - let files; - try { - files = (await readdir(absolute, { withFileTypes: true })); - } - catch { - continue; - } - for (const file of files) { - if (!file.isFile()) - continue; - if (!/\.(tsx?|jsx?)$/.test(file.name)) - continue; - components.add(file.name.replace(/\.[^.]+$/, '')); - } - } - return components; -} function validateMissingLocales(files, options, warnings) { const idsByLocale = new Map(); for (const file of files) { @@ -161,8 +118,3 @@ function validateMissingLocales(files, options, warnings) { } } } -function formatComponentsDir(componentsDir) { - if (!componentsDir) - return 'src/components or src/pages'; - return Array.isArray(componentsDir) ? componentsDir.join(', ') : componentsDir; -} diff --git a/packages/vite-plugin-flatwave-react/dist/index.js b/packages/vite-plugin-flatwave-react/dist/index.js index e65c997..247aaae 100644 --- a/packages/vite-plugin-flatwave-react/dist/index.js +++ b/packages/vite-plugin-flatwave-react/dist/index.js @@ -3,7 +3,6 @@ import { buildIndex } from './content/indexer.js'; import { validateContent } from './content/validator.js'; import { parseMarkdown } from './content/parser.js'; import { routeForLocaleSlug } from './content/scanner.js'; -import { runSsg } from './ssg/runSsg.js'; const VIRTUAL_ID = '\0virtual:flatwave/content'; const PUBLIC_VIRTUAL_ID = 'virtual:flatwave/content'; export function flatwaveContent(options) { @@ -74,6 +73,7 @@ export function flatwaveContent(options) { async generateBundle(_, bundle) { const html = findIndexHtml(bundle); const assets = extractAssets(html); + const { runSsg } = await import('./ssg/runSsg.js'); const outputFiles = await runSsg(index, normalizedOptions, assets); for (const file of outputFiles) { this.emitFile({ @@ -92,9 +92,8 @@ function normalizeOptions(options) { } return { ...options, - requiredFields: options.requiredFields ?? ['title', 'slug', 'id', 'component', 'public'], + requiredFields: options.requiredFields ?? ['title', 'slug', 'id', 'public'], validateComponents: options.validateComponents ?? true, - componentsDir: options.componentsDir, emitRouteManifest: options.emitRouteManifest ?? true, emitSitemap: options.emitSitemap ?? true, emitRobotsTxt: options.emitRobotsTxt ?? true, diff --git a/packages/vite-plugin-flatwave-react/dist/react/index.d.ts b/packages/vite-plugin-flatwave-react/dist/react/index.d.ts index aae6cb0..fd8cb8b 100644 --- a/packages/vite-plugin-flatwave-react/dist/react/index.d.ts +++ b/packages/vite-plugin-flatwave-react/dist/react/index.d.ts @@ -5,4 +5,12 @@ export declare function useFlatwaveRoutes(locale?: string): import("virtual:flat export declare function useFlatwaveAlternatives(id: string, currentLocale?: string): Record<string, string>; export declare function useFlatwaveLocales(): string[]; export declare function useFlatwaveLocale(locale?: string): string | undefined; +export type { FlatwaveMDComponentProps, FlatwaveMDPageProps, FlatwaveLanguageRouterProps, FlatwaveLanguageDetectorProps, FlatwaveAppRoutesProps, FlatwaveLanguageContextValue, FlatwaveFrontmatterWith, } from './types.js'; +export { FlatwaveLanguageContext, useFlatwaveLanguage } from './FlatwaveLanguageContext.js'; +export { FlatwaveMDComponent } from './FlatwaveMDComponent.js'; +export { FlatwaveMDPageComponent } from './FlatwaveMDPageComponent.js'; +export { FlatwaveLanguageRouter } from './FlatwaveLanguageRouter.js'; +export { FlatwaveLanguageDetector } from './FlatwaveLanguageDetector.js'; +export { FlatwaveAppRoutes } from './FlatwaveAppRoutes.js'; +export { FlatwaveLanguageSelector } from './FlatwaveLanguageSelector.js'; export { getAllContent, getAlternatives, getContent, getLocale, getLocales, getRoutes }; diff --git a/packages/vite-plugin-flatwave-react/dist/react/index.js b/packages/vite-plugin-flatwave-react/dist/react/index.js index 9c7f3f4..aeab796 100644 --- a/packages/vite-plugin-flatwave-react/dist/react/index.js +++ b/packages/vite-plugin-flatwave-react/dist/react/index.js @@ -1,5 +1,6 @@ import { useMemo } from 'react'; import { getAllContent, getAlternatives, getContent, getLocale, getLocales, getRoutes, } from 'virtual:flatwave/content'; +// React hooks export function useFlatwaveContent(id, locale) { return useMemo(() => getContent(id, locale), [id, locale]); } @@ -15,4 +16,14 @@ export function useFlatwaveLocales() { export function useFlatwaveLocale(locale) { return useMemo(() => getLocale(locale), [locale]); } +// Re-export FlatwaveLanguageContext and useFlatwaveLanguage hook +export { FlatwaveLanguageContext, useFlatwaveLanguage } from './FlatwaveLanguageContext.js'; +// Re-export component implementations +export { FlatwaveMDComponent } from './FlatwaveMDComponent.js'; +export { FlatwaveMDPageComponent } from './FlatwaveMDPageComponent.js'; +export { FlatwaveLanguageRouter } from './FlatwaveLanguageRouter.js'; +export { FlatwaveLanguageDetector } from './FlatwaveLanguageDetector.js'; +export { FlatwaveAppRoutes } from './FlatwaveAppRoutes.js'; +export { FlatwaveLanguageSelector } from './FlatwaveLanguageSelector.js'; +// Re-export virtual module utilities export { getAllContent, getAlternatives, getContent, getLocale, getLocales, getRoutes }; diff --git a/packages/vite-plugin-flatwave-react/dist/react/virtual.d.ts b/packages/vite-plugin-flatwave-react/dist/react/virtual.d.ts index 350d3c2..c8f7b67 100644 --- a/packages/vite-plugin-flatwave-react/dist/react/virtual.d.ts +++ b/packages/vite-plugin-flatwave-react/dist/react/virtual.d.ts @@ -1,26 +1,55 @@ declare module 'virtual:flatwave/content' { + export interface FlatwaveVirtualFrontmatter { + title?: string; + slug?: string; + id?: string; + public?: boolean | string; + description?: string; + canonical?: string; + image?: string; + robots?: string; + keywords?: string[]; + jsonLd?: unknown; + og?: Record<string, unknown>; + twitter?: Record<string, unknown>; + menu?: string; + menu_position?: number | string; + body?: string; + [key: string]: unknown; + } + export interface FlatwaveVirtualContent { id: string; locale: string; slug: string; path: string; file: string; - component?: string; public: boolean; attributes: Record<string, unknown>; - frontmatter: Record<string, unknown>; + frontmatter: FlatwaveVirtualFrontmatter; body: string; route: string; alternatives: Record<string, string>; } + export interface FlatwaveSeoMetadata { + title: string; + description?: string; + canonical?: string; + image?: string; + robots?: string; + keywords?: string[]; + jsonLd?: unknown; + og?: Record<string, string>; + twitter?: Record<string, string>; + } + export interface FlatwaveVirtualRoute { locale: string; path: string; contentId: string; - component?: string; - metadata: Record<string, unknown>; - frontmatter: Record<string, unknown>; + metadata: FlatwaveSeoMetadata; + frontmatter: FlatwaveVirtualFrontmatter; alternatives: Record<string, string>; } diff --git a/packages/vite-plugin-flatwave-react/dist/types.d.ts b/packages/vite-plugin-flatwave-react/dist/types.d.ts index 08ce82f..bad4463 100644 --- a/packages/vite-plugin-flatwave-react/dist/types.d.ts +++ b/packages/vite-plugin-flatwave-react/dist/types.d.ts @@ -23,6 +23,16 @@ export interface RenderHooks { transformHtml?: (html: string, context: unknown) => Promise<string> | string; afterRender?: (html: string, context: unknown) => Promise<void> | void; onError?: (error: Error, context: unknown) => Promise<string> | string; + emitFiles?: (context: EmitFilesContext) => Promise<SsgOutputFile[]> | SsgOutputFile[]; +} +export interface SsgOutputFile { + fileName: string; + source: string; +} +export interface EmitFilesContext { + routes: FlatwaveRoute[]; + contentIndex: FlatwaveContentIndex; + renderedFiles: SsgOutputFile[]; } export interface TemplateOverrides { indexHtml?: string; @@ -44,7 +54,6 @@ export interface FlatwaveContentOptions { strictMissingLocales?: boolean; requiredFields?: string[]; validateComponents?: boolean; - componentsDir?: string | string[]; emitRouteManifest?: boolean; emitSitemap?: boolean; emitRobotsTxt?: boolean; @@ -56,7 +65,6 @@ export interface FlatwaveFrontmatter extends Record<string, unknown> { title: string; slug: string; id: string; - component: string; public?: boolean | string; description?: string; canonical?: string; @@ -75,7 +83,6 @@ export interface FlatwaveContentEntry { slug: string; path: string; file: string; - component?: string; public: boolean; attributes: FlatwaveFrontmatter; frontmatter: FlatwaveFrontmatter; @@ -87,7 +94,6 @@ export interface FlatwaveRoute { locale: string; path: string; contentId: string; - component?: string; metadata: SeoMetadata; frontmatter: FlatwaveFrontmatter; alternatives: Record<string, string>; diff --git a/packages/vite-plugin-flatwave-react/package.json b/packages/vite-plugin-flatwave-react/package.json index f1d6ac2..57e267c 100644 --- a/packages/vite-plugin-flatwave-react/package.json +++ b/packages/vite-plugin-flatwave-react/package.json @@ -1,6 +1,6 @@ { "name": "@kamansoft/vite-plugin-flatwave-react", - "version": "1.0.0", + "version": "2.0.1", "description": "Vite content plugin for Markdown-driven, i18n-aware static React sites.", "type": "module", "main": "./dist/index.js", @@ -74,19 +74,23 @@ "access": "public" }, "peerDependencies": { - "vite": "^5.0.0 || ^6.0.0 || ^7.0.0", "react": ">=18.0.0", - "react-dom": ">=18.0.0" + "react-dom": ">=18.0.0", + "react-helmet-async": "^2.0.0", + "react-markdown": "^10.0.0", + "react-router-dom": "^6.0.0", + "vite": "^5.0.0 || ^6.0.0 || ^7.0.0" }, "dependencies": { "commander": "^13.1.0", "fast-glob": "^3.3.3", "gray-matter": "^4.0.3", + "react-helmet-async": "^2.0.0", + "rehype-raw": "^7.0.0", + "rehype-stringify": "^10.0.1", "remark": "^15.0.1", "remark-parse": "^11.0.0", "remark-rehype": "^11.1.0", - "rehype-stringify": "^10.0.1", - "rehype-raw": "^7.0.0", "unified": "^11.0.5" }, "devDependencies": { @@ -95,6 +99,8 @@ "@types/react-dom": "^18.3.1", "react": "^18.3.1", "react-dom": "^18.3.1", + "react-markdown": "^10.1.0", + "react-router-dom": "^7.18.0", "typescript": "^5.7.2", "vite": "^6.0.7" } diff --git a/packages/vite-plugin-flatwave-react/src/cli/validate.ts b/packages/vite-plugin-flatwave-react/src/cli/validate.ts index 5d77452..1505b22 100644 --- a/packages/vite-plugin-flatwave-react/src/cli/validate.ts +++ b/packages/vite-plugin-flatwave-react/src/cli/validate.ts @@ -10,11 +10,6 @@ program .requiredOption('--content-dir <dir>', 'Markdown content directory, e.g. src/content') .requiredOption('--locales <locales>', 'Comma-separated locales, e.g. es,pt') .requiredOption('--default-locale <locale>', 'Default locale, e.g. es') - .option( - '--components-dir <dirs>', - 'Comma-separated component directories', - 'src/components,src/pages' - ) .option('--strict-missing', 'Fail when locale variants are missing', false) .option('--no-validate-components', 'Disable component existence validation') .action( @@ -22,7 +17,6 @@ program contentDir: string; locales: string; defaultLocale: string; - componentsDir: string; strictMissing: boolean; validateComponents: boolean; }) => { @@ -30,16 +24,11 @@ program .split(',') .map((locale) => locale.trim()) .filter(Boolean); - const componentsDir = options.componentsDir - .split(',') - .map((dir) => dir.trim()) - .filter(Boolean); const result = await validateContent({ contentDir: options.contentDir, locales, defaultLocale: options.defaultLocale, - componentsDir, strictMissingLocales: options.strictMissing, validateComponents: options.validateComponents, }); diff --git a/packages/vite-plugin-flatwave-react/src/content/indexer.ts b/packages/vite-plugin-flatwave-react/src/content/indexer.ts index 0762f77..9470b0b 100644 --- a/packages/vite-plugin-flatwave-react/src/content/indexer.ts +++ b/packages/vite-plugin-flatwave-react/src/content/indexer.ts @@ -16,7 +16,6 @@ export async function buildIndex(options: FlatwaveContentOptions): Promise<Flatw slug: file.slug, path: routeForLocaleSlug(file.locale, file.slug), file: file.file, - component: file.frontmatter.component ? String(file.frontmatter.component) : undefined, public: file.frontmatter.public !== false && String(file.frontmatter.public ?? 'true').toLowerCase() !== 'false', diff --git a/packages/vite-plugin-flatwave-react/src/content/routeBuilder.ts b/packages/vite-plugin-flatwave-react/src/content/routeBuilder.ts index 596a171..899a5ad 100644 --- a/packages/vite-plugin-flatwave-react/src/content/routeBuilder.ts +++ b/packages/vite-plugin-flatwave-react/src/content/routeBuilder.ts @@ -37,7 +37,6 @@ export function buildContentIndex(entries: FlatwaveContentEntry[]): { locale: entry.locale, path: entry.route, contentId: entry.id, - component: entry.component, metadata: buildSeoMetadata(entry.frontmatter, entry.route, entry.locale), frontmatter: entry.frontmatter, alternatives, diff --git a/packages/vite-plugin-flatwave-react/src/content/scanner.ts b/packages/vite-plugin-flatwave-react/src/content/scanner.ts index beb88b2..c2c834d 100644 --- a/packages/vite-plugin-flatwave-react/src/content/scanner.ts +++ b/packages/vite-plugin-flatwave-react/src/content/scanner.ts @@ -77,7 +77,6 @@ export function buildContentEntry( slug: parsed.slug, path: route, file: parsed.file, - component: parsed.frontmatter.component ? String(parsed.frontmatter.component) : undefined, public: isPublicEntry(parsed.frontmatter), attributes, frontmatter: parsed.frontmatter, diff --git a/packages/vite-plugin-flatwave-react/src/content/validator.ts b/packages/vite-plugin-flatwave-react/src/content/validator.ts index b2e9d4d..6e2376b 100644 --- a/packages/vite-plugin-flatwave-react/src/content/validator.ts +++ b/packages/vite-plugin-flatwave-react/src/content/validator.ts @@ -1,21 +1,19 @@ -import { readdir } from 'node:fs/promises'; -export type { ValidationResult } from '../types.js'; -import path from 'node:path'; import type { FlatwaveContentEntry, FlatwaveContentOptions, ValidationResult } from '../types'; import { routeForLocaleSlug, scanMarkdownFiles } from './scanner.js'; import { buildContentIndex } from './routeBuilder.js'; +export type { ValidationResult } from '../types'; + export async function validateContent(options: FlatwaveContentOptions): Promise<ValidationResult> { const errors: string[] = []; const warnings: string[] = []; - const requiredFields = options.requiredFields ?? ['title', 'slug', 'id', 'component', 'public']; + const requiredFields = options.requiredFields ?? ['title', 'slug', 'id', 'public']; const files = await scanMarkdownFiles(options.contentDir, options.locales); await validateRequiredFields(files, requiredFields, errors); await validateDuplicateIds(files, errors); await validateDuplicateSlugs(files, errors); await validateMenuPositions(files, errors); - await validateComponents(files, options, errors); validateMissingLocales(files, options, warnings); const entries = files.map((file) => { @@ -27,7 +25,6 @@ export async function validateContent(options: FlatwaveContentOptions): Promise< slug: file.slug, path: route, file: file.file, - component: file.frontmatter.component ? String(file.frontmatter.component) : undefined, public: file.frontmatter.public !== false && String(file.frontmatter.public ?? 'true').toLowerCase() !== 'false', @@ -134,55 +131,6 @@ async function validateMenuPositions( } } -async function validateComponents( - files: Awaited<ReturnType<typeof scanMarkdownFiles>>, - options: FlatwaveContentOptions, - errors: string[] -): Promise<void> { - if (options.validateComponents === false) return; - - const available = await discoverComponents(options.componentsDir); - for (const file of files) { - const component = file.frontmatter.component ? String(file.frontmatter.component) : undefined; - if (!component) continue; - if (!available.has(component)) { - errors.push( - `[${file.locale}] ${file.file}: Component '${component}' does not exist in ${formatComponentsDir(options.componentsDir)}.` - ); - } - } -} - -async function discoverComponents(componentsDir?: string | string[]): Promise<Set<string>> { - const dirs = Array.isArray(componentsDir) - ? componentsDir - : componentsDir - ? [componentsDir] - : ['src/components', 'src/pages']; - const components = new Set<string>(); - - for (const dir of dirs) { - const absolute = path.resolve(dir); - let files: Array<{ isFile: () => boolean; name: string }>; - try { - files = (await readdir(absolute, { withFileTypes: true })) as Array<{ - isFile: () => boolean; - name: string; - }>; - } catch { - continue; - } - - for (const file of files) { - if (!file.isFile()) continue; - if (!/\.(tsx?|jsx?)$/.test(file.name)) continue; - components.add(file.name.replace(/\.[^.]+$/, '')); - } - } - - return components; -} - function validateMissingLocales( files: Awaited<ReturnType<typeof scanMarkdownFiles>>, options: FlatwaveContentOptions, @@ -208,8 +156,3 @@ function validateMissingLocales( } } } - -function formatComponentsDir(componentsDir?: string | string[]): string { - if (!componentsDir) return 'src/components or src/pages'; - return Array.isArray(componentsDir) ? componentsDir.join(', ') : componentsDir; -} diff --git a/packages/vite-plugin-flatwave-react/src/index.ts b/packages/vite-plugin-flatwave-react/src/index.ts index ffc1b34..1946da0 100644 --- a/packages/vite-plugin-flatwave-react/src/index.ts +++ b/packages/vite-plugin-flatwave-react/src/index.ts @@ -4,7 +4,6 @@ import { buildIndex } from './content/indexer.js'; import { validateContent } from './content/validator.js'; import { parseMarkdown } from './content/parser.js'; import { routeForLocaleSlug } from './content/scanner.js'; -import { runSsg } from './ssg/runSsg.js'; import type { FlatwaveContentIndex, FlatwaveContentOptions } from './types'; const VIRTUAL_ID = '\0virtual:flatwave/content'; @@ -81,6 +80,7 @@ export function flatwaveContent(options: FlatwaveContentOptions): Plugin[] { const html = findIndexHtml(bundle); const assets = extractAssets(html); + const { runSsg } = await import('./ssg/runSsg.js'); const outputFiles = await runSsg(index, normalizedOptions, assets); for (const file of outputFiles) { @@ -102,9 +102,8 @@ function normalizeOptions(options: FlatwaveContentOptions): FlatwaveContentOptio return { ...options, - requiredFields: options.requiredFields ?? ['title', 'slug', 'id', 'component', 'public'], + requiredFields: options.requiredFields ?? ['title', 'slug', 'id', 'public'], validateComponents: options.validateComponents ?? true, - componentsDir: options.componentsDir, emitRouteManifest: options.emitRouteManifest ?? true, emitSitemap: options.emitSitemap ?? true, emitRobotsTxt: options.emitRobotsTxt ?? true, diff --git a/packages/vite-plugin-flatwave-react/src/react/FlatwaveAppRoutes.tsx b/packages/vite-plugin-flatwave-react/src/react/FlatwaveAppRoutes.tsx new file mode 100644 index 0000000..aeeba1e --- /dev/null +++ b/packages/vite-plugin-flatwave-react/src/react/FlatwaveAppRoutes.tsx @@ -0,0 +1,54 @@ +import React from 'react'; +import * as ReactRouter from 'react-router-dom'; +import type { FlatwaveAppRoutesProps } from './types.js'; +import { FlatwaveLanguageContext } from './FlatwaveLanguageContext.js'; + +const Routes = ReactRouter.Routes; +const Route = ReactRouter.Route; + +export function FlatwaveAppRoutes({ + routes, + renderPage, + layoutWrapper, +}: FlatwaveAppRoutesProps): React.ReactElement { + const context = React.useContext(FlatwaveLanguageContext); + const locale = context?.locale || ''; + + // Group routes by locale + const localeRoutes = routes.filter((r) => r.locale === locale); + + return ( + <Routes> + {localeRoutes.map((route) => ( + <Route + key={route.path} + path={route.path} + element={ + layoutWrapper ? ( + <LayoutWrapper wrapper={layoutWrapper} locale={locale}> + {renderPage(route, locale)} + </LayoutWrapper> + ) : ( + renderPage(route, locale) + ) + } + /> + ))} + <Route path="*" element={null} /> + </Routes> + ); +} + +function LayoutWrapper({ + wrapper: Wrapper, + locale, + children, +}: { + wrapper: React.ComponentType<{ children: React.ReactNode; locale: string }>; + locale: string; + children: React.ReactNode; +}): React.ReactElement { + return <Wrapper locale={locale}>{children}</Wrapper>; +} + +export type { FlatwaveAppRoutesProps } from './types.js'; diff --git a/packages/vite-plugin-flatwave-react/src/react/FlatwaveLanguageContext.ts b/packages/vite-plugin-flatwave-react/src/react/FlatwaveLanguageContext.ts new file mode 100644 index 0000000..108c3ed --- /dev/null +++ b/packages/vite-plugin-flatwave-react/src/react/FlatwaveLanguageContext.ts @@ -0,0 +1,14 @@ +import React from 'react'; +import type { FlatwaveLanguageContextValue } from './types.js'; + +export const FlatwaveLanguageContext = React.createContext<FlatwaveLanguageContextValue>({ + locale: '', + supportedLanguages: [], + defaultLanguage: '', +}); + +export type { FlatwaveLanguageContextValue } from './types.js'; + +export function useFlatwaveLanguage() { + return React.useContext(FlatwaveLanguageContext); +} diff --git a/packages/vite-plugin-flatwave-react/src/react/FlatwaveLanguageDetector.tsx b/packages/vite-plugin-flatwave-react/src/react/FlatwaveLanguageDetector.tsx new file mode 100644 index 0000000..85de674 --- /dev/null +++ b/packages/vite-plugin-flatwave-react/src/react/FlatwaveLanguageDetector.tsx @@ -0,0 +1,62 @@ +import React from 'react'; +import * as ReactRouter from 'react-router-dom'; +import type { FlatwaveLanguageDetectorProps } from './types.js'; +import { FlatwaveLanguageContext } from './FlatwaveLanguageContext.js'; + +const useNavigate = ReactRouter.useNavigate; +const useLocation = ReactRouter.useLocation; + +export function FlatwaveLanguageDetector({ + supportedLanguages, + defaultLanguage, + onLanguageChange, + children, +}: FlatwaveLanguageDetectorProps): React.ReactElement | null { + const navigate = useNavigate(); + const location = useLocation(); + const [currentLocale, setCurrentLocale] = React.useState('' as string); + + React.useEffect(() => { + const currentPath = location.pathname; + const pathSegments = currentPath.split('/').filter(Boolean); + const firstSegment = pathSegments[0]; + + // Check if the first segment is a language code + const isLanguageInPath = supportedLanguages.includes(firstSegment); + + if (isLanguageInPath) { + // Language is already in the path + if (currentLocale !== firstSegment) { + setCurrentLocale(firstSegment); + onLanguageChange?.(firstSegment); + } + } else { + // No language in path, detect and redirect + const browserLang = navigator.language.split('-')[0]; + const targetLang = supportedLanguages.includes(browserLang) ? browserLang : defaultLanguage; + + // Navigate with language prefix + navigate(`/${targetLang}${currentPath}`, { replace: true }); + onLanguageChange?.(targetLang); + } + }, [ + location.pathname, + navigate, + supportedLanguages, + defaultLanguage, + onLanguageChange, + currentLocale, + ]); + + const contextValue = { + locale: currentLocale, + supportedLanguages, + defaultLanguage, + }; + + return ( + <FlatwaveLanguageContext.Provider value={contextValue}> + {children} + </FlatwaveLanguageContext.Provider> + ); +} diff --git a/packages/vite-plugin-flatwave-react/src/react/FlatwaveLanguageRouter.tsx b/packages/vite-plugin-flatwave-react/src/react/FlatwaveLanguageRouter.tsx new file mode 100644 index 0000000..6a5d559 --- /dev/null +++ b/packages/vite-plugin-flatwave-react/src/react/FlatwaveLanguageRouter.tsx @@ -0,0 +1,28 @@ +import React from 'react'; +import * as ReactRouter from 'react-router-dom'; +import type { FlatwaveLanguageRouterProps } from './types.js'; +import { FlatwaveLanguageDetector } from './FlatwaveLanguageDetector.js'; +import { FlatwaveAppRoutes } from './FlatwaveAppRoutes.js'; + +const BrowserRouter = ReactRouter.BrowserRouter; + +export function FlatwaveLanguageRouter({ + supportedLanguages, + defaultLanguage, + onLanguageChange, + routes, + renderPage, + layoutWrapper, +}: FlatwaveLanguageRouterProps): React.ReactElement { + return ( + <BrowserRouter> + <FlatwaveLanguageDetector + supportedLanguages={supportedLanguages} + defaultLanguage={defaultLanguage} + onLanguageChange={onLanguageChange} + > + <FlatwaveAppRoutes routes={routes} renderPage={renderPage} layoutWrapper={layoutWrapper} /> + </FlatwaveLanguageDetector> + </BrowserRouter> + ); +} diff --git a/packages/vite-plugin-flatwave-react/src/react/FlatwaveLanguageSelector.tsx b/packages/vite-plugin-flatwave-react/src/react/FlatwaveLanguageSelector.tsx new file mode 100644 index 0000000..f27b836 --- /dev/null +++ b/packages/vite-plugin-flatwave-react/src/react/FlatwaveLanguageSelector.tsx @@ -0,0 +1,70 @@ +import React from 'react'; +import * as ReactRouter from 'react-router-dom'; +import type { FlatwaveLanguageContextValue } from './types.js'; +import { FlatwaveLanguageContext } from './FlatwaveLanguageContext.js'; + +const useNavigate = ReactRouter.useNavigate; +const useLocation = ReactRouter.useLocation; + +export interface FlatwaveLanguageSelectorProps { + renderOption?: (lang: string, label: string, isActive: boolean) => React.ReactNode; + onSelect?: (lang: string) => void; + getLabel?: (lang: string) => string; + className?: string; + style?: React.CSSProperties; +} + +export function FlatwaveLanguageSelector({ + renderOption, + onSelect, + getLabel, + className, + style, +}: FlatwaveLanguageSelectorProps): React.ReactElement { + const navigate = useNavigate(); + const location = useLocation(); + const context = React.useContext(FlatwaveLanguageContext); + + const { locale, supportedLanguages } = context as FlatwaveLanguageContextValue; + + const handleSelect = (lang: string) => { + onSelect?.(lang); + + // Navigate to the selected language version of current path + const currentPath = location.pathname; + // Remove current language prefix + const pathWithoutLang = supportedLanguages.reduce( + (path, currentLang) => path.replace(`/${currentLang}`, '') || '/', + currentPath + ); + // Add new language prefix + navigate(`/${lang}${pathWithoutLang === '/' ? '' : pathWithoutLang}`, { replace: true }); + }; + + const defaultGetLabel = (lang: string) => lang; + const getLabelFn = getLabel || defaultGetLabel; + + if (renderOption) { + return ( + <div className={className} style={style}> + {supportedLanguages.map((lang) => renderOption(lang, getLabelFn(lang), locale === lang))} + </div> + ); + } + + // Default select element + return ( + <select + value={locale} + onChange={(e) => handleSelect(e.target.value)} + className={className} + style={style} + > + {supportedLanguages.map((lang) => ( + <option key={lang} value={lang}> + {getLabelFn(lang)} + </option> + ))} + </select> + ); +} diff --git a/packages/vite-plugin-flatwave-react/src/react/FlatwaveMDComponent.tsx b/packages/vite-plugin-flatwave-react/src/react/FlatwaveMDComponent.tsx new file mode 100644 index 0000000..0ec388c --- /dev/null +++ b/packages/vite-plugin-flatwave-react/src/react/FlatwaveMDComponent.tsx @@ -0,0 +1,62 @@ +import React from 'react'; +import * as ReactMarkdown from 'react-markdown'; +import type { FlatwaveMDComponentProps, FlatwaveLanguageContextValue } from './types.js'; +import { FlatwaveLanguageContext } from './FlatwaveLanguageContext.js'; + +const ReactMarkdownComponent = ReactMarkdown.default; + +function stripYamlFrontmatter(markdown: string): string { + return markdown.replace(/^---\s*\n[\s\S]*?\n---\s*\n?/, ''); +} + +export function FlatwaveMDComponent(props: FlatwaveMDComponentProps): React.ReactElement | null { + const { frontmatter, markdownHtml, markdown, locale, className, style, children } = props; + + let renderedContent: React.ReactNode = null; + + // Priority: markdownHtml > markdown + if (markdownHtml !== undefined) { + // SSG mode: use pre-compiled HTML + renderedContent = ( + <div dangerouslySetInnerHTML={{ __html: markdownHtml }} className={className} style={style} /> + ); + } else if (markdown !== undefined) { + // Client-side mode: render with react-markdown + const strippedMarkdown = stripYamlFrontmatter(markdown); + renderedContent = ( + <ReactMarkdownComponent + components={{ + p: ({ ...props }) => <p style={{ marginBottom: '1em' }} {...props} />, + }} + > + {strippedMarkdown} + </ReactMarkdownComponent> + ); + } + + // Provide locale context + const contextValue: FlatwaveLanguageContextValue = { + locale, + supportedLanguages: [], + defaultLanguage: '', + }; + + const wrappedContent = ( + <FlatwaveLanguageContext.Provider value={contextValue}> + {children ? children(renderedContent, frontmatter) : renderedContent} + </FlatwaveLanguageContext.Provider> + ); + + // Apply className/style to outer wrapper if no children + if (!children && (className || style)) { + return ( + <div className={className} style={style}> + {wrappedContent} + </div> + ); + } + + return wrappedContent; +} + +export type { FlatwaveMDComponentProps } from './types.js'; diff --git a/packages/vite-plugin-flatwave-react/src/react/FlatwaveMDPageComponent.tsx b/packages/vite-plugin-flatwave-react/src/react/FlatwaveMDPageComponent.tsx new file mode 100644 index 0000000..6b830ab --- /dev/null +++ b/packages/vite-plugin-flatwave-react/src/react/FlatwaveMDPageComponent.tsx @@ -0,0 +1,97 @@ +import React from 'react'; +import * as ReactHelmet from 'react-helmet-async'; +import type { FlatwaveMDPageProps } from './types.js'; +import { FlatwaveMDComponent } from './FlatwaveMDComponent.js'; + +const { Helmet, HelmetProvider } = (ReactHelmet as unknown as { default: typeof ReactHelmet }) + .default; + +export { HelmetProvider }; + +interface FrontmatterSeo { + title?: string; + description?: string; + canonical?: string; + image?: string; + robots?: string; + og?: { title?: string; description?: string }; +} + +export function FlatwaveMDPageComponent(props: FlatwaveMDPageProps): React.ReactElement | null { + const { + frontmatter, + markdownHtml, + markdown, + locale, + className, + style, + children, + pageWrapper, + loadingFallback, + } = props; + + // Handle missing content + if (markdownHtml === undefined && markdown === undefined) { + if (loadingFallback !== undefined) { + return <>{loadingFallback}</>; + } + return null; + } + + // Render page content + const pageContent = ( + <FlatwaveMDComponent + frontmatter={frontmatter} + markdownHtml={markdownHtml} + markdown={markdown} + locale={locale} + className={className} + style={style} + children={children} + /> + ); + + // SEO Head tags via react-helmet-async (only for client-side rendering when markdown is used) + // For SSG (markdownHtml provided), head tags are handled by renderHtmlHead in runSsg + const fm = frontmatter as FrontmatterSeo | undefined; + const title = typeof fm?.title === 'string' ? fm.title : undefined; + // Only render Helmet when in client-side mode (markdown provided, no markdownHtml) + const headTags = + markdown !== undefined && title ? ( + <Helmet> + <title>{title} + {typeof fm?.description === 'string' && ( + + )} + {typeof fm?.canonical === 'string' && } + {typeof fm?.og?.title === 'string' && } + {typeof fm?.og?.description === 'string' && ( + + )} + {typeof fm?.image === 'string' && } + {typeof fm?.robots === 'string' && } + + ) : null; + + const contentWithHead = ( + <> + {headTags} + {pageContent} + + ); + + // Apply layout wrapper + if (pageWrapper) { + const Wrapper = pageWrapper; + return ( + + {contentWithHead} + + ); + } + + // Default wrapper + return
{contentWithHead}
; +} + +export type { FlatwaveMDPageProps } from './types.js'; diff --git a/packages/vite-plugin-flatwave-react/src/react/index.ts b/packages/vite-plugin-flatwave-react/src/react/index.ts index 059f09c..bcadc0b 100644 --- a/packages/vite-plugin-flatwave-react/src/react/index.ts +++ b/packages/vite-plugin-flatwave-react/src/react/index.ts @@ -8,6 +8,7 @@ import { getRoutes, } from 'virtual:flatwave/content'; +// React hooks export function useFlatwaveContent(id: string, locale?: string) { return useMemo(() => getContent(id, locale), [id, locale]); } @@ -28,4 +29,27 @@ export function useFlatwaveLocale(locale?: string) { return useMemo(() => getLocale(locale), [locale]); } +// Re-export component props types +export type { + FlatwaveMDComponentProps, + FlatwaveMDPageProps, + FlatwaveLanguageRouterProps, + FlatwaveLanguageDetectorProps, + FlatwaveAppRoutesProps, + FlatwaveLanguageContextValue, + FlatwaveFrontmatterWith, +} from './types.js'; + +// Re-export FlatwaveLanguageContext and useFlatwaveLanguage hook +export { FlatwaveLanguageContext, useFlatwaveLanguage } from './FlatwaveLanguageContext.js'; + +// Re-export component implementations +export { FlatwaveMDComponent } from './FlatwaveMDComponent.js'; +export { FlatwaveMDPageComponent } from './FlatwaveMDPageComponent.js'; +export { FlatwaveLanguageRouter } from './FlatwaveLanguageRouter.js'; +export { FlatwaveLanguageDetector } from './FlatwaveLanguageDetector.js'; +export { FlatwaveAppRoutes } from './FlatwaveAppRoutes.js'; +export { FlatwaveLanguageSelector } from './FlatwaveLanguageSelector.js'; + +// Re-export virtual module utilities export { getAllContent, getAlternatives, getContent, getLocale, getLocales, getRoutes }; diff --git a/packages/vite-plugin-flatwave-react/src/react/types.ts b/packages/vite-plugin-flatwave-react/src/react/types.ts new file mode 100644 index 0000000..1169301 --- /dev/null +++ b/packages/vite-plugin-flatwave-react/src/react/types.ts @@ -0,0 +1,66 @@ +import type { FlatwaveFrontmatter, SeoMetadata } from '../types.js'; + +export interface FlatwaveMDComponentProps { + frontmatter: TFrontmatter; + markdownHtml?: string; + markdown?: string; + locale: string; + className?: string; + style?: React.CSSProperties; + children?: (rendered: React.ReactNode, frontmatter: TFrontmatter) => React.ReactNode; +} + +export interface FlatwaveMDPageProps< + TFrontmatter = FlatwaveFrontmatter, +> extends FlatwaveMDComponentProps { + pageWrapper?: React.ComponentType<{ + children: React.ReactNode; + frontmatter: TFrontmatter; + locale: string; + }>; + loadingFallback?: React.ReactNode; +} + +export interface FlatwaveLanguageContextValue { + locale: string; + supportedLanguages: string[]; + defaultLanguage: string; +} + +export interface FlatwaveVirtualRoute { + locale: string; + path: string; + contentId: string; + metadata: SeoMetadata; + frontmatter: Record; + alternatives: Record; +} + +export interface FlatwaveLanguageRouterProps { + supportedLanguages: string[]; + defaultLanguage: string; + onLanguageChange?: (lang: string) => void; + routes: FlatwaveVirtualRoute[]; + renderPage: (route: FlatwaveVirtualRoute, lang: string) => React.ReactNode; + dynamicRoute?: { + path: string; + renderPage: (params: { slug: string; lang: string }) => React.ReactNode; + }; + layoutWrapper?: React.ComponentType<{ children: React.ReactNode; locale: string }>; +} + +export interface FlatwaveLanguageDetectorProps { + supportedLanguages: string[]; + defaultLanguage: string; + onLanguageChange?: (lang: string) => void; + children: React.ReactNode; +} + +export interface FlatwaveAppRoutesProps { + routes: FlatwaveVirtualRoute[]; + renderPage: (route: FlatwaveVirtualRoute, lang: string) => React.ReactNode; + layoutWrapper?: React.ComponentType<{ children: React.ReactNode; locale: string }>; +} + +// Utility type for frontmatter extension +export type FlatwaveFrontmatterWith = FlatwaveFrontmatter & T; diff --git a/packages/vite-plugin-flatwave-react/src/ssg/DefaultRenderStrategy.test.tsx b/packages/vite-plugin-flatwave-react/src/ssg/DefaultRenderStrategy.test.tsx new file mode 100644 index 0000000..3fcef3c --- /dev/null +++ b/packages/vite-plugin-flatwave-react/src/ssg/DefaultRenderStrategy.test.tsx @@ -0,0 +1,89 @@ +import React from 'react'; +import { describe, it, expect } from 'vitest'; +import { renderToString } from 'react-dom/server'; +import * as ReactHelmet from 'react-helmet-async'; +import type { HelmetServerState } from 'react-helmet-async'; +import { FlatwaveMDPageComponent } from '../react/FlatwaveMDPageComponent.js'; + +const { HelmetProvider } = (ReactHelmet as unknown as { default: typeof ReactHelmet }).default; + +describe('DefaultRenderStrategy with FlatwaveMDPageComponent', () => { + it('renders FlatwaveMDPageComponent to string with main and markdown body', async () => { + const frontmatter = { + title: 'Test Page', + slug: 'test', + id: 'test', + public: true, + description: 'Test description', + canonical: '/test', + }; + + const markdownHtml = '

This is test content.

'; + const locale = 'en'; + + const helmetContext: { helmet?: HelmetServerState } = {}; + const html = renderToString( + + + + ); + + // Without markdown prop, Helmet is not rendered (head tags handled by SSG) + expect(html).toContain('
'); + expect(html).toContain('This is test content.'); + }); + + it('renders without title when frontmatter has no title', async () => { + const frontmatter = { + title: '', + slug: 'test', + id: 'test', + public: true, + }; + + const markdownHtml = '

No title page

'; + const locale = 'en'; + + const helmetContext: { helmet?: HelmetServerState } = {}; + const html = renderToString( + + + + ); + + expect(html).toContain('
'); + expect(html).toContain('No title page'); + }); + + it('renders loading fallback when no markdownHtml or markdown provided', async () => { + const frontmatter = { + title: 'Test Page', + slug: 'test', + id: 'test', + public: true, + }; + + const helmetContext: { helmet?: HelmetServerState } = {}; + const html = renderToString( + + Loading...} + /> + + ); + + expect(html).toContain('Loading...'); + }); +}); diff --git a/packages/vite-plugin-flatwave-react/src/ssg/DefaultRenderStrategy.tsx b/packages/vite-plugin-flatwave-react/src/ssg/DefaultRenderStrategy.tsx index e797cec..96b42ca 100644 --- a/packages/vite-plugin-flatwave-react/src/ssg/DefaultRenderStrategy.tsx +++ b/packages/vite-plugin-flatwave-react/src/ssg/DefaultRenderStrategy.tsx @@ -1,45 +1,32 @@ import { renderToString } from 'react-dom/server'; +import * as ReactHelmet from 'react-helmet-async'; +import type { HelmetServerState } from 'react-helmet-async'; import type { RenderStrategy, RenderContext } from './types.js'; +import { FlatwaveMDPageComponent } from '../react/FlatwaveMDPageComponent.js'; + +const { HelmetProvider } = (ReactHelmet as unknown as { default: typeof ReactHelmet }).default; export class DefaultRenderStrategy implements RenderStrategy { async render(context: RenderContext): Promise { - const { route, contentEntry, components, locale } = context; - - const componentModule = components.get(route.component || ''); - - // contentEntry.body is already compiled HTML (set by runSsg before calling render) - const compiledBody = contentEntry.body; + const { contentEntry, route } = context; - if (!componentModule) { - // Graceful degradation: component not found at build time is common when - // consuming projects haven't pre-built their components. Serve compiled - // markdown so the page still has meaningful content. - console.warn( - `[SSG] Component "${route.component}" not found for "${route.path}" — serving compiled markdown` - ); - return compiledBody; - } + const markdownHtml = contentEntry.body; + const frontmatter = contentEntry.frontmatter; + const locale = route.locale; - const Component = (componentModule as { default: React.ComponentType> }) - .default; - if (!Component) { - console.warn( - `[SSG] Component "${route.component}" has no default export for "${route.path}" — serving compiled markdown` + try { + const helmetContext: { helmet?: HelmetServerState } = {}; + const appHtml = renderToString( + + + ); - return compiledBody; - } - // contentEntry.body is already compiled HTML — runSsg pre-compiles via - // the transformMarkdown pipeline + compileMarkdownToHtml before calling render - const props = { - ...contentEntry.frontmatter, - markdownHtml: contentEntry.body, - locale, - route: route.path, - }; - - try { - const appHtml = renderToString(); + // Return only the body HTML - head tags are extracted via renderHtmlHead in runSsg return appHtml; } catch (error) { const message = error instanceof Error ? error.message : String(error); diff --git a/packages/vite-plugin-flatwave-react/src/ssg/RenderPipeline.ts b/packages/vite-plugin-flatwave-react/src/ssg/RenderPipeline.ts index 44f46b3..a6faee3 100644 --- a/packages/vite-plugin-flatwave-react/src/ssg/RenderPipeline.ts +++ b/packages/vite-plugin-flatwave-react/src/ssg/RenderPipeline.ts @@ -1,5 +1,5 @@ import type { RenderContext } from './types.js'; -import type { RenderHooks } from '../types.js'; +import type { RenderHooks, EmitFilesContext, SsgOutputFile } from '../types.js'; type HookPhase = keyof RenderHooks; @@ -8,6 +8,7 @@ type TransformMarkdownHook = NonNullable; type TransformHtmlHook = NonNullable; type AfterRenderHook = NonNullable; type OnErrorHook = NonNullable; +type EmitFilesHook = NonNullable; export class RenderPipeline { private beforeRenderHooks: BeforeRenderHook[] = []; @@ -15,6 +16,7 @@ export class RenderPipeline { private transformHtmlHooks: TransformHtmlHook[] = []; private afterRenderHooks: AfterRenderHook[] = []; private onErrorHooks: OnErrorHook[] = []; + private emitFilesHooks: EmitFilesHook[] = []; constructor(initialHooks: Partial = {}) { if (initialHooks.beforeRender) this.beforeRenderHooks.push(initialHooks.beforeRender); @@ -23,6 +25,7 @@ export class RenderPipeline { if (initialHooks.transformHtml) this.transformHtmlHooks.push(initialHooks.transformHtml); if (initialHooks.afterRender) this.afterRenderHooks.push(initialHooks.afterRender); if (initialHooks.onError) this.onErrorHooks.push(initialHooks.onError); + if (initialHooks.emitFiles) this.emitFilesHooks.push(initialHooks.emitFiles); } addHook(phase: HookPhase, hook: unknown): void { @@ -89,6 +92,21 @@ export class RenderPipeline { return `

Render error: ${error.message}

`; } + async executeEmitFiles(context: EmitFilesContext): Promise { + const results: SsgOutputFile[] = []; + for (const hook of this.emitFilesHooks) { + try { + const files = await hook(context); + if (Array.isArray(files)) { + results.push(...files); + } + } catch (error) { + console.error(`[RenderPipeline] emitFiles hook failed:`, error); + } + } + return results; + } + hasHooks(phase: HookPhase): boolean { const hooks = this.getHooks(phase); return hooks !== undefined && hooks.length > 0; @@ -106,6 +124,8 @@ export class RenderPipeline { return this.afterRenderHooks as unknown[]; case 'onError': return this.onErrorHooks as unknown[]; + case 'emitFiles': + return this.emitFilesHooks as unknown[]; } } } diff --git a/packages/vite-plugin-flatwave-react/src/ssg/index.ts b/packages/vite-plugin-flatwave-react/src/ssg/index.ts index e7fbfd3..72592ae 100644 --- a/packages/vite-plugin-flatwave-react/src/ssg/index.ts +++ b/packages/vite-plugin-flatwave-react/src/ssg/index.ts @@ -1,15 +1,13 @@ export type { RenderContext, - RenderHooks, TemplateOverrides, TemplateVariables, RenderStrategy, - RenderPipeline, } from './types.js'; +export type { RenderHooks } from '../types.js'; export { DefaultRenderStrategy } from './DefaultRenderStrategy.js'; -export { runSsg, type SsgOutputFile, renderSitemap, renderRobotsTxt } from './runSsg.js'; +export { runSsg, renderSitemap, renderRobotsTxt } from './runSsg.js'; export { resolveTemplate, renderTemplate } from './template.js'; -export { - compileMarkdownToHtml, - type MarkdownCompilerOptions, -} from '../content/markdownCompiler.js'; +export { compileMarkdownToHtml } from '../content/markdownCompiler.js'; +export type { MarkdownCompilerOptions } from '../content/markdownCompiler.js'; +export type { SsgOutputFile, EmitFilesContext } from '../types.js'; diff --git a/packages/vite-plugin-flatwave-react/src/ssg/runSsg.ts b/packages/vite-plugin-flatwave-react/src/ssg/runSsg.ts index bb9333f..5da9b9c 100644 --- a/packages/vite-plugin-flatwave-react/src/ssg/runSsg.ts +++ b/packages/vite-plugin-flatwave-react/src/ssg/runSsg.ts @@ -13,11 +13,7 @@ import { compileMarkdownToHtml, type MarkdownCompilerOptions, } from '../content/markdownCompiler.js'; - -export interface SsgOutputFile { - fileName: string; - source: string; -} +import type { SsgOutputFile } from '../types.js'; export function renderSitemap(routes: FlatwaveRoute[], hostname: string): string { const base = hostname.replace(/\/$/, ''); @@ -42,27 +38,6 @@ Sitemap: ${base}/sitemap.xml `; } -async function buildComponentsMap(routes: FlatwaveRoute[]): Promise> { - const components = new Map(); - const uniqueComponents = new Set(routes.map((r) => r.component).filter(Boolean)); - - for (const componentName of uniqueComponents) { - try { - const module = await import(`../react/${componentName}.js`); - components.set(componentName!, module); - } catch { - try { - const module = await import(`virtual:flatwave/components/${componentName}`); - components.set(componentName!, module); - } catch { - console.warn(`[SSG] Could not load component: ${componentName}`); - } - } - } - - return components; -} - function toCompilerOptions( opts?: SsgOptions['compileMarkdown'] ): MarkdownCompilerOptions | undefined { @@ -87,7 +62,7 @@ export async function runSsg( const strategy = ssgOptions.strategy ?? new DefaultRenderStrategy(); const pipeline = new RenderPipeline(ssgOptions.hooks); - const components = await buildComponentsMap(routes); + const components = new Map(); const concurrencyLimit = 4; const routeChunks: FlatwaveRoute[][] = []; @@ -205,5 +180,14 @@ export async function runSsg( }); } + // Call emitFiles hook after all routes are rendered + const emitFilesContext = { + routes, + contentIndex: index, + renderedFiles: outputFiles, + }; + const emittedFiles = await pipeline.executeEmitFiles(emitFilesContext); + outputFiles.push(...emittedFiles); + return outputFiles; } diff --git a/packages/vite-plugin-flatwave-react/src/types.ts b/packages/vite-plugin-flatwave-react/src/types.ts index da2a64d..dd87d6a 100644 --- a/packages/vite-plugin-flatwave-react/src/types.ts +++ b/packages/vite-plugin-flatwave-react/src/types.ts @@ -28,6 +28,18 @@ export interface RenderHooks { transformHtml?: (html: string, context: unknown) => Promise | string; afterRender?: (html: string, context: unknown) => Promise | void; onError?: (error: Error, context: unknown) => Promise | string; + emitFiles?: (context: EmitFilesContext) => Promise | SsgOutputFile[]; +} + +export interface SsgOutputFile { + fileName: string; + source: string; +} + +export interface EmitFilesContext { + routes: FlatwaveRoute[]; + contentIndex: FlatwaveContentIndex; + renderedFiles: SsgOutputFile[]; } export interface TemplateOverrides { @@ -52,7 +64,6 @@ export interface FlatwaveContentOptions { strictMissingLocales?: boolean; requiredFields?: string[]; validateComponents?: boolean; - componentsDir?: string | string[]; emitRouteManifest?: boolean; emitSitemap?: boolean; emitRobotsTxt?: boolean; @@ -65,7 +76,6 @@ export interface FlatwaveFrontmatter extends Record { title: string; slug: string; id: string; - component: string; public?: boolean | string; description?: string; canonical?: string; @@ -85,7 +95,6 @@ export interface FlatwaveContentEntry { slug: string; path: string; file: string; - component?: string; public: boolean; attributes: FlatwaveFrontmatter; frontmatter: FlatwaveFrontmatter; @@ -98,7 +107,6 @@ export interface FlatwaveRoute { locale: string; path: string; contentId: string; - component?: string; metadata: SeoMetadata; frontmatter: FlatwaveFrontmatter; alternatives: Record; diff --git a/packages/vite-plugin-flatwave-react/src/virtual.d.ts b/packages/vite-plugin-flatwave-react/src/virtual.d.ts index 350d3c2..c8f7b67 100644 --- a/packages/vite-plugin-flatwave-react/src/virtual.d.ts +++ b/packages/vite-plugin-flatwave-react/src/virtual.d.ts @@ -1,26 +1,55 @@ declare module 'virtual:flatwave/content' { + export interface FlatwaveVirtualFrontmatter { + title?: string; + slug?: string; + id?: string; + public?: boolean | string; + description?: string; + canonical?: string; + image?: string; + robots?: string; + keywords?: string[]; + jsonLd?: unknown; + og?: Record; + twitter?: Record; + menu?: string; + menu_position?: number | string; + body?: string; + [key: string]: unknown; + } + export interface FlatwaveVirtualContent { id: string; locale: string; slug: string; path: string; file: string; - component?: string; public: boolean; attributes: Record; - frontmatter: Record; + frontmatter: FlatwaveVirtualFrontmatter; body: string; route: string; alternatives: Record; } + export interface FlatwaveSeoMetadata { + title: string; + description?: string; + canonical?: string; + image?: string; + robots?: string; + keywords?: string[]; + jsonLd?: unknown; + og?: Record; + twitter?: Record; + } + export interface FlatwaveVirtualRoute { locale: string; path: string; contentId: string; - component?: string; - metadata: Record; - frontmatter: Record; + metadata: FlatwaveSeoMetadata; + frontmatter: FlatwaveVirtualFrontmatter; alternatives: Record; }