release: promote beta 1.0.0 to main (stable)

.github/CODEOWNERS

@@ -0,0 +1,36 @@
+# CODEOWNERS — auto-request reviewers based on path domain.
+# Last-match-wins; broad rules first, specific overrides below.
+# Created 2026-05-03 from the OR-abstraction audit follow-up.
+
+# Default: every named codeowner reviews unmatched paths.
+*                       @rubenvdlinde @rjzondervan @Rem-Dam @remko48 @WilcoLouwerse @bbrands02 @SudoThijn
+
+# Backend (PHP) — services, controllers, mappers, db, migration, etc.
+lib/                    @bbrands02 @rjzondervan @WilcoLouwerse
+appinfo/                @bbrands02 @rjzondervan @WilcoLouwerse
+**/*.php                @bbrands02 @rjzondervan @WilcoLouwerse
+phpcs.xml               @bbrands02 @rjzondervan @WilcoLouwerse
+phpmd.xml               @bbrands02 @rjzondervan @WilcoLouwerse
+phpstan.neon            @bbrands02 @rjzondervan @WilcoLouwerse
+phpstan-baseline.neon   @bbrands02 @rjzondervan @WilcoLouwerse
+phpmd.baseline.xml      @bbrands02 @rjzondervan @WilcoLouwerse
+composer.json           @bbrands02 @rjzondervan @WilcoLouwerse
+composer.lock           @bbrands02 @rjzondervan @WilcoLouwerse
+
+# Frontend (Vue / TS / JS) — components, stores, pages, build config.
+src/                    @SudoThijn @remko48
+**/*.vue                @SudoThijn @remko48
+**/*.ts                 @SudoThijn @remko48
+**/*.js                 @SudoThijn @remko48
+package.json            @SudoThijn @remko48
+package-lock.json       @SudoThijn @remko48
+jest.config.js          @SudoThijn @remko48
+playwright.config.ts    @SudoThijn @remko48
+webpack.config.js       @SudoThijn @remko48
+babel.config.js         @SudoThijn @remko48
+
+# Specs / docs / ADRs / openspec.
+openspec/               @rubenvdlinde @Rem-Dam
+docs/                   @rubenvdlinde @Rem-Dam
+**/*.md                 @rubenvdlinde @Rem-Dam
+README.md               @rubenvdlinde @Rem-Dam

.github/workflows/branch-protection.yml

@@ -5,5 +5,5 @@ on:
     branches: [main, beta]
 
 jobs:
-  check:
+  branch-protection:
     uses: ConductionNL/.github/.github/workflows/branch-protection.yml@main

.github/workflows/documentation-beta.yml

@@ -0,0 +1,40 @@
+name: Documentation (Beta)
+
+on:
+  push:
+    branches:
+      - beta
+
+jobs:
+  deploy-beta:
+    name: Deploy Beta Styleguide
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Setup Node.js 20
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+
+      - name: Install and build component styleguide
+        timeout-minutes: 10
+        run: |
+          cd styleguide
+          npm ci
+          npm run build
+
+      - name: Deploy styleguide to /beta/ on GitHub Pages
+        uses: peaceiris/actions-gh-pages@v3
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./styleguide/build
+          publish_branch: gh-pages
+          destination_dir: beta/styleguide
+          user_name: 'github-actions[bot]'
+          user_email: 'github-actions[bot]@users.noreply.github.com'
+          keep_files: true

.github/workflows/documentation-dev.yml

@@ -0,0 +1,41 @@
+name: Documentation (Dev)
+
+on:
+  push:
+    branches:
+      - development
+
+jobs:
+  deploy-dev:
+    name: Deploy Dev Styleguide
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Setup Node.js 20
+        uses: actions/setup-node@v4
+        with:
+          node-version: '20'
+
+      - name: Install and build component styleguide
+        timeout-minutes: 10
+        run: |
+          cd styleguide
+          npm ci
+          npm run build
+
+      - name: Deploy styleguide to /dev/ on GitHub Pages
+        uses: peaceiris/actions-gh-pages@v3
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./styleguide/build
+
+          publish_branch: gh-pages
+          destination_dir: dev/styleguide
+          user_name: 'github-actions[bot]'
+          user_email: 'github-actions[bot]@users.noreply.github.com'
+          keep_files: true

.github/workflows/documentation.yml

@@ -26,6 +26,13 @@ jobs:
         with:
           node-version: '20'
 
+      - name: Install and build component styleguide
+        timeout-minutes: 10
+        run: |
+          cd styleguide
+          npm ci
+          npm run build
+
       - name: Clear build cache and install dependencies
         timeout-minutes: 3
         run: |
@@ -43,6 +50,12 @@ jobs:
             exit 1
           fi
 
+      - name: Copy styleguide into Docusaurus build
+        run: |
+          mkdir -p docusaurus/build/styleguide
+          cp -r styleguide/build/. docusaurus/build/styleguide/
+
+
       - name: Create .nojekyll file
         run: |
           cd docusaurus/build
@@ -58,7 +71,7 @@ jobs:
           user_email: 'github-actions[bot]@users.noreply.github.com'
           force_orphan: false
           allow_empty_commit: true
-          keep_files: false
+          keep_files: true
 
       - name: Verify deployment
         run: |

.github/workflows/release.yml

@@ -1,5 +1,21 @@
 name: Release
 
+# Auto-publish @conduction/nextcloud-vue to npm via semantic-release.
+#
+# Authentication: npm Trusted Publisher (OIDC). The runner mints a
+# short-lived ID token via `id-token: write`, the npm plugin exchanges it
+# at the registry for a one-shot publish credential, and provenance is
+# attested via NPM_CONFIG_PROVENANCE=true. There is no NPM_TOKEN secret
+# to rotate.
+#
+# Trust config on npmjs.com expects this workflow at the path
+# `.github/workflows/release.yml` in `ConductionNL/nextcloud-vue`. If you
+# rename or move this file, update the npm Trusted Publisher config.
+#
+# Node 24 is the floor: semantic-release@24 requires Node ^22.14 || ≥24.10
+# and the Trusted Publisher publish path uses npm CLI's own OIDC support,
+# which lands in npm 11.x (bundled with Node 24).
+
 on:
   push:
     branches: [main, beta]
@@ -17,7 +33,7 @@ jobs:
       - uses: actions/checkout@v4
       - uses: actions/setup-node@v4
         with:
-          node-version: 20
+          node-version: 24
           cache: 'npm'
       - run: npm ci
       - run: npm run lint
@@ -27,6 +43,13 @@ jobs:
     name: Release
     needs: quality
     runs-on: ubuntu-latest
+    permissions:
+      contents: write       # @semantic-release/git pushes the chore(release) bump back to beta/main
+      issues: write
+      pull-requests: write
+      id-token: write       # npm Trusted Publisher (OIDC) + provenance attestation
+    env:
+      NPM_CONFIG_PROVENANCE: 'true'
     steps:
       - uses: actions/checkout@v4
         with:
@@ -35,13 +58,13 @@ jobs:
 
       - uses: actions/setup-node@v4
         with:
-          node-version: 20
+          node-version: 24
           cache: 'npm'
+          registry-url: 'https://registry.npmjs.org'
 
       - run: npm ci
 
       - name: Release
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          NPM_TOKEN: ${{ secrets.NPM_TOKEN }}
         run: npx semantic-release

.gitignore

@@ -6,3 +6,7 @@ dist/
 # Docusaurus build output
 docusaurus/build
 .docusaurus
+
+# Styleguide build output
+styleguide/build
+.styleguide

.vscode/settings.json

@@ -28,4 +28,7 @@
     "[php]": {
         "editor.defaultFormatter": "DEVSENSE.phptools-vscode"
     },
+    "[markdown]": {
+        "editor.defaultFormatter": "esbenp.prettier-vscode"
+    },
 }

CLAUDE.md

@@ -18,14 +18,23 @@ import { useObjectStore } from '@conduction/nextcloud-vue'
 import '@conduction/nextcloud-vue/src/css/index.css'
 ```
 
+Consumer apps MUST also call `registerTranslations()` once in `main.js` (alongside `registerIcons({})`) **before** `new Vue().$mount(...)` — without it, library-rendered strings stay in English even when the user's Nextcloud language is Dutch. See [docs/getting-started.md](docs/getting-started.md#register-library-translations-required).
+
 ### Available Components
 
 **Layout & Pages**
-- `CnIndexPage` — Top-level schema-driven index page (table/cards, pagination, mass actions, dialogs)
-- `CnDetailPage` — Generic detail/overview page with stats table and flexible content slots (simpler alternative to CnIndexPage)
+- `CnIndexPage` — Top-level schema-driven index page (table/cards, pagination, mass actions, dialogs). Overridable via `#header` and `#actions` slots.
+- `CnDetailPage` — Generic detail/overview page with stats table and flexible content slots. Overridable via `#header` and `#actions` slots.
 - `CnPageHeader` — Page header with icon, title, description
 - `CnActionsBar` — Action bar with add button, mass actions, view toggle, search
 
+**Manifest Renderer (JSON-driven app shell)**
+- `CnAppRoot` — Top-level app wrapper. Orchestrates loading → dependency-check → shell phases. Provides `cnManifest`, `cnCustomComponents`, `cnTranslate` to descendants. Slots: `#loading`, `#dependency-missing`, `#menu`, `#header-actions`, `#sidebar`, `#footer` — each independently overridable. Use this when adopting the full manifest pattern; lower tiers (just `useAppManifest`, or `+ CnPageRenderer`, or `+ CnAppNav`) are also supported.
+- `CnAppNav` — Manifest-driven `NcAppNavigation`. Reads `manifest.menu[]`; sorts by `order`; filters by `permission`; one level of `children[]`. Accepts `manifest`, `translate`, `permissions` as props (with inject fallback) for standalone use.
+- `CnPageRenderer` — Type dispatcher mounted inside `<router-view>`. Matches `$route.name === page.id`, dispatches by `page.type` (`index | detail | dashboard | custom`) using `defineAsyncComponent` for tree-shaking. Forwards `page.config` as props; resolves `page.headerComponent` / `page.actionsComponent` against the customComponents registry.
+- `CnAppLoading` — Default loading screen (logo slot + NcLoadingIcon + message). Used by CnAppRoot's `#loading` phase.
+- `CnDependencyMissing` — Default dependency-missing screen (lists missing apps with install/enable links). Used by CnAppRoot's `#dependency-missing` phase.
+
 **Data Display**
 - `CnDetailGrid` — Data-driven label-value grid with grid and horizontal layout modes
 - `CnDataTable` — Sortable data table with selection, loading, empty states
@@ -92,6 +101,7 @@ import '@conduction/nextcloud-vue/src/css/index.css'
 - `buildQueryString(params)` — Build URL query string from params object
 - `parseResponseError(response)` — Extract error message from API response
 - `networkError()` / `genericError()` — Standard error message helpers
+- `validateManifest(manifest)` — Validate an app manifest against the JSON Schema. Returns `{ valid, errors }`. Use at build time or in test fixtures; the same validator runs at runtime inside `useAppManifest`.
 
 ### Available Store
 - `useObjectStore` — Generic Pinia store for OpenRegister objects (CRUD, pagination, search, caching)
@@ -103,6 +113,8 @@ import '@conduction/nextcloud-vue/src/css/index.css'
 - `useFileSelection(options)` — File upload/drop handling
 - `useDashboardView(options)` — Dashboard state: widget defs, layout, NC widget loading, add/remove/persist
 - `useContextMenu()` — Right-click context menu positioning and state (cursor CSS vars, open/close, action helpers)
+- `useAppManifest(appId, bundledManifest, options?)` — Load + validate the app manifest. Returns `{ manifest, isLoading, validationErrors }`. Synchronous bundled load + async backend-merge stub (silent fallback on 4xx / network errors); validates via `validateManifest`. Pass `options.endpoint` or `options.fetcher` to override the backend URL or inject a mock.
+- `useAppStatus(appId)` — Check whether a Nextcloud app is installed and enabled via `@nextcloud/capabilities`. Returns `{ installed, enabled, loading }`. Cached per appId for the page lifetime. CnAppRoot calls this once per `manifest.dependencies` entry to drive the dependency-check phase.
 
 ### CnIndexPage Dialog Override System
 
@@ -113,7 +125,7 @@ CnIndexPage has built-in single-object dialogs (Delete, Copy, Form) that are **o
    - `#copy-dialog="{ item, close }"` — Replace copy dialog
    - `#form-dialog="{ item, schema, close }"` — Replace create/edit dialog (use CnFormDialog or CnAdvancedFormDialog)
 2. **Form content override** — `#form-fields` replaces the form inside the built-in CnFormDialog
-3. **Per-field override** — `#field-{key}` inside CnFormDialog replaces a single field
+3. **Per-field override** — `#field-{key}` inside CnFormDialog replaces a single field. For JSON / code-editor fields this slot is rarely needed: set `widget: 'json'` (structured value, parses on input) or `widget: 'code'` (raw string + `field.language` for highlighting) on the schema property and CnFormDialog renders `CnJsonViewer` automatically.
 4. **Per-field option rendering** — `#field-{key}-option` and `#field-{key}-selected-option` customize dropdown option display for select/multiselect/tags fields
 
 Key events emitted by CnIndexPage:
@@ -175,6 +187,34 @@ const DEFAULT_LAYOUT = [
 </CnDashboardPage>
 ```
 
+### JSON Manifest Renderer
+
+Apps can declare their entire shell — routes, navigation, page configuration, dependencies — in a single `src/manifest.json`. The library reads it and renders the app. Adoption is incremental (four tiers from "just `useAppManifest`" to "full `CnAppRoot` shell"); a custom menu component can replace the default `CnAppNav` via the `#menu` slot.
+
+Minimal manifest:
+
+```json
+{
+  "$schema": "https://raw.githubusercontent.com/ConductionNL/nextcloud-vue/main/src/schemas/app-manifest.schema.json",
+  "version": "1.0.0",
+  "dependencies": ["openregister"],
+  "menu": [
+    { "id": "decisions", "label": "myapp.menu.decisions", "icon": "icon-checkmark", "route": "decisions-index", "order": 10 }
+  ],
+  "pages": [
+    { "id": "decisions-index", "route": "/decisions", "type": "index", "title": "myapp.decisions.title",
+      "config": { "register": "decisions", "schema": "decision", "columns": ["title", "status"] } },
+    { "id": "decisions-detail", "route": "/decisions/:id", "type": "detail", "title": "myapp.decisions.detail",
+      "config": { "register": "decisions", "schema": "decision" } },
+    { "id": "settings", "route": "/settings", "type": "custom", "title": "myapp.settings.title", "component": "SettingsPage" }
+  ]
+}
+```
+
+`page.id` is also the vue-router route name; CnPageRenderer matches by `$route.name === page.id`. The `type` enum is closed (`index | detail | dashboard | custom`) — bespoke pages use `type: "custom"` with a registry component.
+
+See `examples/manifest-demo/manifest.json` for a fuller reference and `docs/migrating-to-manifest.md` for tier-by-tier adoption guidance.
+
 ## Rules for Modifying Components
 
 1. **NEVER break existing prop interfaces** — new props MUST have defaults
@@ -184,7 +224,7 @@ const DEFAULT_LAYOUT = [
 5. **Run `npm test` before submitting changes**
 6. **CSS class prefix**: All classes use `cn-` prefix to avoid collisions
 7. **Theming**: Use Nextcloud CSS variables only (`var(--color-primary-element)`, `var(--color-border)`, etc.). Do NOT reference `--nldesign-*` variables — the nldesign app overrides Nextcloud's own variables, so theming works automatically.
-8. **Translation**: Components accept pre-translated strings via props with English defaults. Never import `t()` from a specific app.
+8. **Always update docs when you add, rename, or remove a prop, event, or slot** — edit `docs/components/cn-<component>.md` in the same change. The CI `check:docs` step (run via `npm run check:docs`) verifies both that a doc file exists AND that every SFC prop and named slot appears in it. Run it locally before committing to catch gaps.
 
 ## Adding New Components
 
@@ -268,3 +308,13 @@ scripts/
 
 This library is used by: OpenRegister, OpenCatalogi, Procest, Pipelinq, MyDash.
 Changes here affect all of them. Test carefully.
+
+Every consumer's `main.js` must include:
+
+```js
+import { registerIcons, registerTranslations } from '@conduction/nextcloud-vue'
+registerIcons({ /* app-specific icons */ })
+registerTranslations()
+```
+
+`registerTranslations()` is a required bootstrap call — without it, the library falls back to English regardless of the user's Nextcloud language.