tibi-svelte-starter/.agents/skills/admin-ui-config/SKILL.md

name, description

name	description
admin-ui-config	Configure the admin UI for collections — meta labels, preview/viewHint, field widgets, inputProps, sidebar layout, choices, foreign references, and image handling. Use when setting up or customizing collection admin views.

admin-ui-config

When to use this skill

Use this skill when:

• Configuring how a collection appears in the tibi-admin UI
• Configuring collection preview and default list presentation
• Configuring field widgets (dropdowns, media pickers, richtext, etc.)
• Organizing fields into sidebar groups or sections
• Setting up foreign key references between collections
• Customizing the admin module (frontend/src/admin.ts)

Reference source

The canonical type definitions are in tibi-admin-nova/types/admin.d.ts. Always consult this file for the full API. This skill provides a practical summary.

Treat this skill as Nova-first. Use current Nova concepts such as preview, singleton: { enabled }, drillDown, dependsOn, containerProps.layout, pagebuilder, viewHint, subNavigation, and AI media assist.

---

Collection meta configuration

The meta key in a collection YAML controls how the collection appears in the admin sidebar and collection/list UI.

name: mycollection
meta:
    label: { de: "Produkte", en: "Products" } # Sidebar label (i18n)
    muiIcon: shopping_cart # Material UI icon name
    group: shop # Group in admin sidebar
    singleton:
        enabled: false
    hide: false # Set to true to hide the collection for non-admin users
    preview:
        label: name
        secondary: price

Preview

Use meta.preview as the universal entry representation for Nova lists, breadcrumbs, foreign-key widgets, and search result previews:

preview: name

preview:
  label: name
  secondary: slug
  badge: status

preview:
  eval: "`${$this.firstName} ${$this.lastName}`"

List presentation

For current Nova, use meta.viewHint plus meta.preview for collection/list presentation.

meta:
    viewHint: table
    preview:
        label: name
        secondary: slug
        badge: status
        table:
            - name
            - source: status
              label: Status
            - source: author.name
              label: Author
        select:
            - author.name

• meta.viewHint controls the preferred collection presentation (table, cards, media, or navigation object where supported).
• preview.table defines explicit list columns for Nova.
• preview.select can reduce lookup work for preview table columns.
• meta.subNavigation defines filtered entry tabs in the sidebar.

---

Field configuration

Each field in the fields array can have a meta section controlling its admin UI behavior.

Basic field with meta

fields:
    - name: name
      type: string
      meta:
          label: { de: "Name", en: "Name" }
          helperText: { de: "Anzeigename", en: "Display name" }
          position: main # "main" (default) or "sidebar"

Field types

YAML type	Admin widget (default)	Notes
string	Text input	Use inputProps.multiline: true for textarea
number	Number input
boolean	Toggle/checkbox
date	Date picker
object	Nested field group	Requires subFields
object[]	Repeatable group	Requires subFields, drag-to-reorder
string[]	Tag input
file	File upload
file[]	Multi-file upload

inputProps — widget customization

inputProps passes props directly to the field widget:

# Multiline text (textarea)
- name: description
  type: string
  meta:
      label: { de: "Beschreibung", en: "Description" }
      inputProps:
          multiline: true
          rows: 5

# Number with min/max
- name: price
  type: number
  meta:
      inputProps:
          min: 0
          max: 99999
          step: 0.01

# Placeholder text
- name: email
  type: string
  meta:
      inputProps:
          placeholder: "name@example.com"

Widget override

Override the default widget with meta.widget:

- name: content
  type: string
  meta:
      widget: richtext # Rich text editor (HTML)

- name: heroImage
  type: file
  meta:
      widget: image # Image-focused file widget

- name: relatedPages
  type: string[]
  meta:
      widget: foreignKeyChipArray

Common widget types: text, checkbox, select, chipArray, checkboxArray, date, datetime, file, image, richtext, json, foreignKey, foreignKeyChipArray, pagebuilder, containerLessObject, containerLessObjectArray.

Important current widgets/features to consider when designing a real website backoffice:

• pagebuilder for CMS-driven block/page authoring
• foreignKeyChipArray for many-reference editing
• image plus imageEditor / downscale for image-heavy workflows
• drillDown editing for complex nested arrays

Choices — dropdowns/selects

Static choices:

- name: type
  type: string
  meta:
      label: { de: "Typ", en: "Type" }
      choices:
          - id: page
            name: { de: "Seite", en: "Page" }
          - id: blog
            name: { de: "Blog", en: "Blog" }
          - id: product
            name: { de: "Produkt", en: "Product" }

Dynamic choices from API:

- name: category
  type: string
  meta:
      choices:
          endpoint: categories # Collection name
          mapping:
              id: id
              name: name

Foreign references

Link to entries in another collection:

- name: author
  type: string
  meta:
      label: { de: "Autor", en: "Author" }
      foreign:
          collection: users
          id: id
          sort: name
          projection: name,email
          render:
              label: name
              secondary: email
          createDefaults:
              role: author

Use foreign.id: id for the outward FK field identity. Only Mongo-style filters/query conditions use _id. Use foreign.render or target-collection meta.preview so references stay readable. Bare IDs are not acceptable authoring UX for a serious website project.

Image fields

- name: image
  type: file
  meta:
      widget: image
      downscale: # Auto-resize on upload
          maxWidth: 1920
          maxHeight: 1080
          quality: 0.85
      imageEditor: true # Enable crop/rotate editor

---

Layout: position, sections, sidebar

Sidebar placement

- name: active
  type: boolean
  meta:
      position: sidebar # Moves field to sidebar

- name: publishDate
  type: date
  meta:
      position: "sidebar:publishing" # Sidebar with group key

Sidebar groups (ordered)

Define sidebar group order in collection meta:

meta:
    sidebar:
        - group: publishing
          label: { de: "Veröffentlichung", en: "Publishing" }
        - group: seo
          label: { de: "SEO", en: "SEO" }
        - group: settings
          label: { de: "Einstellungen", en: "Settings" }

Sections in main area

- name: seoTitle
  type: string
  meta:
      section: SEO # Groups fields under a section header

- name: seoDescription
  type: string
  meta:
      section: SEO

Grid layout (columns)

Use containerProps for multi-column layout:

- name: firstName
  type: string
  meta:
      containerProps:
          layout:
              size: col-6 # Half width (12-column grid)

- name: lastName
  type: string
  meta:
      containerProps:
          layout:
              size: col-6

containerProps.layout is one of the most important Nova ergonomics features. Use it aggressively to avoid long, single-column forms.

Recommended pattern for real projects:

• sidebar for publication, SEO, flags, relations, admin-only metadata
• main area for editorial content
• 2-column or 3-column layout for short related fields
• section headings for repeated conceptual groups

---

Nested objects and arrays

Object (nested group)

- name: address
  type: object
  meta:
      label: { de: "Adresse", en: "Address" }
  subFields:
      - name: street
        type: string
      - name: city
        type: string
      - name: zip
        type: string

Object array (repeatable blocks)

- name: blocks
  type: object[]
  meta:
      label: { de: "Inhaltsblöcke", en: "Content Blocks" }
      widget: pagebuilder
      preview: { eval: "`${$this.type}: ${$this.headline || ''}`" }
      drillDown: true
  subFields:
      - name: type
        type: string
        meta:
            choices:
                - id: hero
                  name: Hero
                - id: richtext
                  name: Richtext
      - name: headline
        type: string
      - name: hide
        type: boolean

The preview eval determines what's shown in the collapsed state of each array item.

Drill-down arrays

For complex object[] data, prefer drillDown: true over dense inline editing. This is especially important for:

• nested content blocks
• FAQs / accordions
• team members with nested metadata
• pricing tables / feature matrices

Pagebuilder fields

Nova supports pagebuilder configuration at both collection and field level.

Typical pattern:

meta:
    pagebuilder:
        blockTypeField: type
        defaultViewport: desktop
        blockRegistry:
            file: /_/assets/dist/admin.mjs

fields:
    - name: blocks
      type: object[]
      meta:
          widget: pagebuilder
          pagebuilder:
              blockTypeField: type

Use pagebuilder when editors work with heterogeneous content blocks. Use plain object[] only when the structure is uniform and simple.

dependsOn

Use dependsOn to show only fields relevant to the selected block or mode:

- name: image
  type: file
  meta:
      dependsOn:
          eval: $parent.type == 'hero'

This is critical for keeping pagebuilder schemas usable.

AI-aware media and admin features

Current Nova types support AI-related admin capabilities, especially around media workflows. When appropriate for a project:

• use AI-assisted alt/caption generation for image-heavy collections
• prefer explicit target fields for generated metadata
• keep AI assist opt-in and editorially reviewable

Use AI only where it improves authoring quality; do not force it into every collection.

Field-level permissions and authoring safety

Current tibi-server supports readonlyFields, hiddenFields, and eval-based field visibility/readonly rules.

Reflect these server rules in admin design:

• do not put critical computed fields front-and-center if editors may not be allowed to modify them
• use dependsOn, hidden, and readonly semantics deliberately
• remember that server-side permissions are authoritative even if the UI looks editable

Drill-down

For complex nested objects, use drillDown to render them as a sub-page:

- name: variants
  type: object[]
  meta:
      drillDown: true # Opens as sub-page instead of inline

---

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.

import type { SvelteComponent } from "svelte"

function getRenderedElement(
    component: typeof SvelteComponent,
    options?: { props: { [key: string]: any }; addCss?: string[] },
    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.

Use case: Custom dashboard widgets, preview components, or field widgets that require Svelte rendering inside the admin UI.

---

Complete collection example

name: products
meta:
    label: { de: "Produkte", en: "Products" }
    muiIcon: inventory_2
    group: shop
    viewHint: table
    defaultSort:
        field: insertTime
        order: DESC
    preview:
        label: name
        secondary: sku
        badge: active
        table:
            - name
            - sku
            - source: price
              label: { de: "Preis", en: "Price" }
            - source: category
              label: { de: "Kategorie", en: "Category" }
    sidebar:
        - group: publishing
          label: { de: "Veröffentlichung", en: "Publishing" }
        - group: seo
          label: { de: "SEO", en: "SEO" }

permissions:
    public:
        methods:
            get: true
    user:
        methods:
            get: true
            post: true
            put: true
            delete: true

fields:
    - name: active
      type: boolean
      meta:
          label: { de: "Aktiv", en: "Active" }
          position: "sidebar:publishing"
    - name: name
      type: string
      meta:
          label: { de: "Name", en: "Name" }
    - name: sku
      type: string
      meta:
          label: { de: "Artikelnummer", en: "SKU" }
          containerProps:
              layout:
                  size: col-6
    - name: price
      type: number
      meta:
          label: { de: "Preis", en: "Price" }
          inputProps:
              min: 0
              step: 0.01
          containerProps:
              layout:
                  size: col-6
    - name: category
      type: string
      meta:
          label: { de: "Kategorie", en: "Category" }
          choices:
              - id: electronics
                name: { de: "Elektronik", en: "Electronics" }
              - id: clothing
                name: { de: "Kleidung", en: "Clothing" }
    - name: description
      type: string
      meta:
          label: { de: "Beschreibung", en: "Description" }
          inputProps:
              multiline: true
              rows: 4
    - name: image
      type: file
      meta:
          label: { de: "Produktbild", en: "Product Image" }
          widget: image
          downscale:
              maxWidth: 1200
              quality: 0.85
    - name: seoTitle
      type: string
      meta:
          label: { de: "SEO Titel", en: "SEO Title" }
          position: "sidebar:seo"
    - name: seoDescription
      type: string
      meta:
          label: { de: "SEO Beschreibung", en: "SEO Description" }
          position: "sidebar:seo"
          inputProps:
              multiline: true
              rows: 3

---

Common pitfalls

• meta.label supports both strings and i18n objects — Use i18n objects only when the collection or field label must be localized.
• choices.id must match stored value — The id in choices is what gets saved to the database.
• inputProps depends on widget — Not all props work with all widgets. Check tibi-admin-nova source if unsure.
• position: sidebar without group — Fields go to an ungrouped area. Use position: "sidebar:GroupName" for grouping.
• type: object[] needs subFields — Forgetting subFields renders an empty repeater.