✨ feat: enhance admin UI configuration and SSR handling

- Add support for number chip arrays and JSON editor in admin UI config. - Introduce pagebuilder block registry for Svelte components in admin previews. - Implement custom role names and a 3-layer cascade model for field-level permissions. - Add CORS configuration hierarchy for better API security. - Update project setup instructions for admin token and config management. - Improve SSR 404 signaling with proper context handling in NotFound component. - Refactor routing structure to separate NotFound page into its own route.
2026-05-12 23:20:31 +00:00
parent 60d5920132
commit 958b45272d
13 changed files with 573 additions and 197 deletions
@@ -108,6 +108,7 @@ fields:
 | ----------- | ---------------------- | --------------------------------------------- |
 | `string`    | Text input             | Use `inputProps.multiline: true` for textarea |
 | `number`    | Number input           |                                               |
+| `number[]`  | Number chip array      | Multiple numeric values                       |
 | `boolean`   | Toggle/checkbox        |                                               |
 | `date`      | Date picker            |                                               |
 | `object`    | Nested field group     | Requires `subFields`                          |
@@ -115,6 +116,7 @@ fields:
 | `string[]`  | Tag input              |                                               |
 | `file`      | File upload            |                                               |
 | `file[]`    | Multi-file upload      |                                               |
+| `any`       | JSON editor            | For mixed/arbitrary data                      |

 ### inputProps — widget customization

@@ -451,7 +453,79 @@ For complex nested objects, use `drillDown` to render them as a sub-page:

 ## Admin module (frontend/src/admin.ts)

-The `admin.ts` file exports custom Svelte components for injection into the tibi-admin UI. Components are rendered inside Shadow DOM to isolate styles.
+The `admin.ts` file exports the **pagebuilder block registry** and optional custom Svelte components for the tibi-admin UI. This is how the admin preview renders your Svelte blocks.
+
+### Pagebuilder block registry
+
+The current starter uses `createContentBlockDefinition()` to register each block type. This mounts real Svelte block components into Shadow DOM for admin previews:
+
+```typescript
+import { mount, unmount, type Component, type SvelteComponent } from "svelte"
+import BlockRenderer from "./blocks/BlockRenderer.svelte"
+
+// Creates a block definition that renders the same Svelte component
+// used in the public frontend. The block is mounted inside Shadow DOM
+// for style isolation.
+function createContentBlockDefinition(presentation: {
+    label: string
+    icon: string
+    color: string
+}) {
+    return {
+        css: [previewCssUrl],     // CSS files to inject into Shadow DOM
+        label: presentation.label,
+        icon: presentation.icon,
+        color: presentation.color,
+        previewStyles: {
+            "background-color": "white",
+        },
+        render(container, row, context) {
+            // Mount the Svelte component inside the admin preview
+            const target = document.createElement("div")
+            container.appendChild(target)
+
+            let mountedComponent = mount(BlockRenderer as Component<any>, {
+                target,
+                props: { blocks: [row], isAdminPreview: true },
+            })
+
+            return {
+                update(nextRow) {
+                    unmount(mountedComponent)
+                    target.innerHTML = ""
+                    mountedComponent = mount(BlockRenderer as Component<any>, {
+                        target,
+                        props: { blocks: [nextRow], isAdminPreview: true },
+                    })
+                },
+                destroy() {
+                    unmount(mountedComponent)
+                    target.remove()
+                },
+            }
+        },
+    }
+}
+
+const blockRegistry = {
+    hero: createContentBlockDefinition({ label: "Hero", icon: "image", color: "#1d4ed8" }),
+    richtext: createContentBlockDefinition({ label: "Richtext", icon: "article", color: "#7c3aed" }),
+    // ... add new blocks here
+}
+
+export { blockRegistry }
+```
+
+**Key points:**
+- Each registry entry wraps the Svelte `BlockRenderer` to render the block in the admin preview.
+- The `row` object is the block data (same shape as `ContentBlockEntry`).
+- Preview data may contain hydrated `_lookup.<fieldPath>` foreign key data and absolute file URLs — do not prepend `apiBase` or attempt re-fetching.
+- The `previewCssUrl` loads the project's `index.css` into Shadow DOM so block styles apply.
+- After adding blocks to the registry, run `yarn build` so `frontend/dist/admin.mjs` is regenerated.
+
+### Custom Svelte components (advanced)
+
+For custom dashboard widgets, preview components, or field widgets that require Svelte rendering inside the admin UI, use `getRenderedElement()`:

 ```typescript
 import type { SvelteComponent } from "svelte"
@@ -462,16 +536,14 @@ function getRenderedElement(
    nestedElements?: { tagName: string; className?: string }[]
 ) {
    // Creates a Shadow DOM container, mounts the Svelte component inside
-    // addCss: CSS files to inject into Shadow DOM
-    // nestedElements: wrapper elements inside Shadow DOM
 }

 export { getRenderedElement }
 ```

-Build with `yarn build`. The output includes the admin module and is loaded by tibi-admin-nova as a custom module.
+### Build

-**Use case:** Custom dashboard widgets, preview components, or field widgets that require Svelte rendering inside the admin UI.
+Run `yarn build`. The admin module (`frontend/src/admin.ts`) is compiled into `frontend/dist/admin.mjs` as part of the esbuild build pipeline (the same build produces both `index.mjs` for the SPA and `admin.mjs` for the admin module). tibi-admin-nova loads this module from the project's asset path (`/_/assets/dist/admin.mjs`). The `ADMIN_ASSET_VERSION` from `config.yml.env` is appended as a query parameter for cache busting: `admin.mjs?v=${ADMIN_ASSET_VERSION}`.

 ---

@@ -513,7 +585,7 @@ permissions:
            get: true
            post: true
            put: true
-            delete: true
+            delete: false # usually false for real editorial workflows

 fields:
    - name: active
@@ -583,6 +655,33 @@ fields:

 ---

+## Indexes and search
+
+For production collections with many entries, consider adding indexes in the YAML:
+
+```yaml
+name: products
+indexes:
+    - name: price_sort
+      key: [price]
+    - name: category_active
+      key: [category, -active]  # -prefix for descending
+    - name: slug_unique
+      key: [slug]
+      unique: true
+```
+
+Search configurations can be added for advanced text/vector search:
+
+```yaml
+search:
+    - name: default
+      mode: text
+      fields: [name, description]
+```
+
+See `tibi-server/docs/04-collections.md` (sections on indexes and search config) for full reference.
+
 ## Common pitfalls

 - **`meta.label` supports both strings and i18n objects** — Use i18n objects only when the collection or field label must be localized.
@@ -49,6 +49,20 @@ At minimum, reason about permissions on these levels:

 Do not flatten all of this into one vague notion of “editor access”.

+**Custom role names:** Permission set keys in collection/action YAML are arbitrary strings. You can define any role name (e.g. `editor`, `reviewer`, `publisher`, `seo-manager`) and assign users with matching permissions. Combined with org/team membership (see `tibi-server/docs/18-orgs-teams.md`), this enables fine-grained editorial workflows beyond the built-in `public` and `user` roles.
+
+### The 3-layer cascade model
+
+Field-level permissions follow a strict 3-layer cascade:
+
+1. **Collection-Level** (`collection.readonlyFields`, `collection.hiddenFields`): Base set applied to all permission sets.
+2. **PermissionSet-Level** (`permissions.<role>.readonlyFields`, `permissions.<role>.hiddenFields`): Adds to or removes from the collection-level set. Prefix a field with `-` to negate (e.g. `-createdBy` removes it from the effective set).
+3. **Field-Definition Override** (`field.readonly`, `field.hidden`): Absolute override — `true` forces the field into the set, `false` forces it out regardless of upper layers.
+
+**Important:** Field-definition `readonly`/`hidden` also supports **eval expressions** (JS) for per-document dynamic evaluation. Eval rules are evaluated in a separate phase after the static cascade (Phase 1 = static cascade, Phase 2 = per-document eval). Admin role (role=0) bypasses all field-level restrictions.
+
+See `tibi-server/docs/17-field-level-permissions.md` for the full reference with examples and eval expression context variables (`$`, `$this`, `$auth`, `$method`, `$project`, `$namespace`).
+
 ## Collection-level workflow design

 Before implementing permissions, define who does what.
@@ -124,6 +124,25 @@ Think in terms of:

 Do not rely on frontend hiding or convention where server-side permissions should be explicit.

+## CORS configuration
+
+CORS follows a 3-level hierarchy. Configure it in `api/config.yml` under `cors:` for project-wide settings, or in individual collection/action YAML for per-endpoint overrides:
+
+| Level | Configuration location | Scope |
+|-------|----------------------|-------|
+| Server | tibi-server `config.yml` | Global default |
+| Project | `api/config.yml` → `cors:` | Per project |
+| Collection/Action | Collection or action YAML → `cors:` | Per endpoint |
+
+Each level can `merge: true` (append to parent) or `merge: false` (replace entirely).
+
+For a project that serves a browser-based SPA to end users on its own domain and serves API/tibiadmin on separate subdomains, the default (no explicit CORS config) is usually correct since the SPA makes same-origin API calls via the BrowserSync/production reverse proxy. Add explicit CORS only when:
+- the API is called from external origins (e.g. third-party integrations)
+- the admin UI is served on a different origin than the API
+- an action endpoint needs to support cross-origin form submissions
+
+See `tibi-server/docs/02-configuration.md` (section "CORS Configuration Hierarchy") for details.
+
 ## Secure implementation patterns

 ### Public form endpoint
@@ -53,12 +53,19 @@ sed -i "s/__PROJECT_NAME__/$PROJECT/g" .env
 sed -i "s/__TIBI_NAMESPACE__/$NAMESPACE/g" .env api/config.yml frontend/.htaccess
 ```

-Also update the starter-derived values that are not placeholder tokens anymore, especially `STAGING_PATH`, `STAGING_URL`, `CODING_URL`, `api/hooks/config-client.js`, and starter metadata in `package.json`.
+Also update the starter-derived values that are not placeholder tokens anymore, especially `STAGING_PATH`, `STAGING_URL`, `CODING_URL`, `CODING_TIBIADMIN_URL`, `api/hooks/config-client.js`, and starter metadata in `package.json`.

-**Verify each replacement:**
+**Important:** The file `api/hooks/config-client.js` contains a **separate** placeholder `__PROJECT__` (not `__PROJECT_NAME__`):

 ```sh
-grep -n '__PROJECT_NAME__\|__TIBI_NAMESPACE__' .env api/config.yml frontend/.htaccess
+# api/hooks/config-client.js has: const originURL = "https://__PROJECT__.code.testversion.online"
+sed -i "s/__PROJECT__/$PROJECT/g" api/hooks/config-client.js
+```
+
+**Verify all placeholders:**
+
+```sh
+grep -n '__PROJECT_NAME__\|__TIBI_NAMESPACE__\|__PROJECT__\|__ORG__' .env api/config.yml frontend/.htaccess api/hooks/config-client.js
 # Expected: no output (all placeholders replaced)
 ```

@@ -83,7 +90,9 @@ The page title is set dynamically via `<svelte:head>` in `frontend/src/App.svelt

 Also verify that SSR still renders meaningful page content and not just the shell after the rewrite.

-## Step 4 — Admin token
+## Step 4 — Admin token and config.yml.env
+
+**How config.yml.env works:** The file `api/config.yml.env` is **not** a standard `.env` file. It is an env-file that the tibi-server reads from the same directory as `config.yml`. The server resolves `${ADMIN_TOKEN}` and `${ADMIN_ASSET_VERSION}` variables in the YAML config from this file. This is separate from the project-root `.env` which serves Docker Compose and the Makefile.

 `api/config.yml.env` ships with a default `ADMIN_TOKEN`. For production projects, generate a secure one:

@@ -95,6 +104,8 @@ This updates only `ADMIN_TOKEN` and keeps the other env keys in the file intact.

 **Verify:** `cat api/config.yml.env` shows a 40-character hex token while preserving entries such as `ADMIN_ASSET_VERSION`.

+**Note:** The `ADMIN_ASSET_VERSION` in the same file is used for cache-busting the admin bundle (`frontend/dist/admin.mjs`). It is auto-generated on build — but if missing, the admin bundle may not load correctly.
+
 ## Step 5 — Install, upgrade, and start

 ```sh
@@ -106,6 +117,8 @@ make docker-start   # Start stack in foreground (CTRL-C to stop)

 Do not blindly run a full dependency upgrade as part of project bootstrap unless the task explicitly includes dependency maintenance. First get the starter running as-is, then upgrade intentionally and validate.

+**Important:** After changing `.env` or `api/config.yml.env`, you must run `make docker-down && make docker-up` for the changes to take effect. Docker Compose reads `.env` at startup time; tibi-server reads `config.yml.env` at reload. A simple `make docker-restart-frontend` is not sufficient for environment variable changes.
+
 **Verify containers are running:**

 ```sh
@@ -135,12 +148,10 @@ For frontend development without a running tibi-server backend:
 ```sh
 # Set in .env:
 MOCK=1
-# Then restart:
-make docker-up
+# Then full restart (env change requires docker-down first):
+make docker-down && make docker-up
 ```

-Mock data lives in `frontend/mocking/` as JSON files. Missing endpoints return 404.
-
 **When to use mock mode:** Early UI prototyping, frontend-only work, CI environments without a database.

 ## Step 8 — Remove demo content
@@ -215,6 +226,22 @@ For tibi-server specifically, decide early whether the site also needs:
 - field-level permissions
 - AI/LLM integration for admin/editor workflows

+## SSR debugging: manual project reload
+
+After changing collection YAML files, hook code, or `config.js` (SSR route validation), you may need to trigger a project reload for tibi-server to pick up the changes. Hook files auto-reload, but structural changes (new collections, config changes) require explicit reload:
+
+```bash
+curl -X POST "$CODING_URL/api/v1/_/$TIBI_NAMESPACE/_/admin/reload" \
+  -H "Token: $ADMIN_TOKEN"
+```
+
+The starter's `api/config.yml` has `allowReload: true` for the admin token by default. Response `{"message": "ok"}` confirms the reload.
+
+Use this when:
+- A new collection was added to `api/config.yml` but the API doesn't see it
+- Hook files changed but the server hasn't picked them up
+- SSR route validation (`api/hooks/config.js`) was updated and the old behavior persists
+
 ## Step 11 — Functional verification for a real website project

 After the first project shaping pass, verify more than just TypeScript:
@@ -150,6 +150,41 @@ If this mapping is wrong, SSR may appear to work for root pages while returning
 - This means SSR is not just HTML prerendering; it also primes client-side data access.
 - If HTML renders but `window.__SSR_CACHE__` is missing, the SSR pipeline is incomplete.

+## SSR 404 signaling
+
+When a page is not found during SSR, the framework returns the 404 page but with HTTP status **200** unless a 404 signal is set. The SSR hook (`get_read.js`) checks `context.is404` after rendering:
+
+```js
+// get_read.js, after app.default.render()
+if (context.is404) {
+    status = 404
+}
+```
+
+The signal is set from `NotFound.svelte` — when this component is rendered during SSR, it sets the flag directly. This keeps the 404 logic in the component that owns it:
+
+```ts
+// NotFound.svelte — top-level script, runs during render:
+if (typeof window === "undefined") {
+    // @ts-ignore - context is the goja global in SSR runtime
+    context.is404 = true
+}
+```
+
+**Why this works:**
+- The `tibi-types` package declares `var context: HookContext` as a global (available because goja provides it during SSR).
+- During SSR, `loadContent()` runs synchronously (goja transforms `async`/`await`).
+- By the time `render(App)` returns in `ssr.ts`, `context.is404` is already `true`.
+- `get_read.js` reads it, returns HTTP 404, and the rendered 404 page HTML is sent with the correct status.
+- Caching is automatically skipped for 404 responses.
+
+**Verification:** Test with a non-existent URL:
+
+```bash
+curl -w "\nHTTP Status: %{http_code}\n" "http://tibiserver:8080/api/v1/_/<namespace>/ssr?url=/de/nicht-existierend"
+# Expected: HTTP 404, body contains the 404 page HTML
+```
+
 ## What an LLM should inspect first when changing SSR

 1. `api/hooks/ssr/get_read.js` to understand cache lookup, route validation, and template injection.
@@ -115,6 +115,12 @@ Use:
 - `singleton`
 - foreign previews

+**I18n field config:** When modeling multilingual content, decide early whether to use:
+- **Field-level i18n** — object fields whose subField names match language codes (`de`, `en`, etc.) are auto-detected and rendered with language tabs in Nova. Configured via `api.meta.i18n` in `config.yml` or per-collection `meta.i18n`.
+- **Entry-level i18n** — each entry represents one language, linked by a shared `translationGroup` UUID. The `I18nEntryConfig` type (from `tibi-admin-nova/types/admin.d.ts`) defines `languageField`, `groupField`, and `copyFields`/`clearFields` for translation cloning behavior.
+
+See `tibi-admin-nova/types/admin.d.ts` interfaces `I18nFieldConfig` and `I18nEntryConfig` for the full API.
+
 Do not treat admin config as optional polish. It is part of the solution architecture.

 ### 6. Actions and workflows