vault backup: 2026-05-15 15:27:55

wiki/_master-index.md

@@ -35,7 +35,7 @@ This 3-hop pattern works for hundreds of articles without vector search.
 | [[wiki/reports/_index\|reports/]] | Weekly and monthly summaries — generate: `uv run python scripts/report-generator.py --weekly` | 1 |
 | [[wiki/infrastructure/_index\|infrastructure/]] | Server inventory: all 10 SSH hosts — optical, optical-dev, optical-prod, baic, librechat, modocmms, box-cli, aimpress, pve | 12 |
 | [[wiki/testing/_index\|testing/]] | Web app testing: functional, performance, security, UI types; TDD/BDD/Agile methodologies; Selenium/Cypress/Playwright/JMeter/OWASP ZAP tools | 1 |
-| [[wiki/payloadcms/_index\|payloadcms/]] | Full Payload CMS reference — getting started, config, database (Postgres/MongoDB/SQLite), all 22 field types, access control, hooks, authentication (cookies, JWT, API keys, custom strategies, token data), admin UI, custom components, Lexical rich text, live preview, versions/drafts, Local/REST/GraphQL APIs, queries, plugins, jobs queue, upload, ecommerce, production deploy, TypeScript, migration guides, i18n, localization | 69 |
+| [[wiki/payloadcms/_index\|payloadcms/]] | Full Payload CMS reference — getting started, config, database (Postgres/MongoDB/SQLite), all 22 field types, access control, hooks, authentication (cookies, JWT, API keys, custom strategies, token data), admin UI, custom components, Lexical rich text, live preview, versions/drafts, Local/REST/GraphQL APIs, queries, plugins, jobs queue, upload, ecommerce, production deploy, TypeScript, migration guides, i18n, localization | 70 |
 
 | [[wiki/shared-patterns/_index\|shared-patterns/]] | Oliver Agency standard library patterns: httpx, structlog, pydantic-settings, alembic — reuse before writing from scratch | 4 |
 | [[wiki/mistakes/_index\|mistakes/]] | Anti-patterns extracted from sessions — per-stack running lists (fastapi, react, docker, postgres, general) — injected at session start | 5 |

wiki/payloadcms/_index.md

@@ -70,3 +70,4 @@
 | [[wiki/payloadcms/fields-collapsible\|Collapsible Field]] | Presentational-only layout field — groups nested fields under a collapsible header; no DB column; supports dynamic label via `({ data, path })` | raw/fields__collapsible.md | 2026-05-15 |
 | [[wiki/payloadcms/fields-date\|Date Field]] | Date picker field — ISO 8601 storage, pickerAppearance modes, timezone support with separate `_tz` column, custom UTC offsets, GraphQL enum names | raw/fields__date.md | 2026-05-15 |
 | [[wiki/payloadcms/fields-email\|Email Field]] | Email field with built-in format validation — unique index, saveToJWT, index, placeholder, autoComplete, custom components | raw/fields__email.md | 2026-05-15 |
+| [[wiki/payloadcms/fields-group\|Group Field]] | Nest fields under a shared property (named) or visually group without nesting (presentational); `localized` covers all nested fields at once | raw/fields__group.md | 2026-05-15 |

wiki/payloadcms/fields-group.md

@@ -0,0 +1,114 @@
+---
+title: "Group Field"
+aliases: [payload-group-field, group-field]
+tags: [payloadcms, fields, group, nested, admin-ui]
+sources: [raw/fields__group.md]
+created: 2026-05-15
+updated: 2026-05-15
+---
+
+The **Group field** nests multiple fields under a shared property name in the database and groups them visually in the Admin Panel.
+
+## Basic Config
+
+```ts
+import type { Field } from 'payload'
+
+export const MyGroupField: Field = {
+  name: 'pageMeta',       // → nested object key in DB
+  type: 'group',
+  fields: [               // required — fields nested inside
+    { name: 'title', type: 'text' },
+    { name: 'description', type: 'textarea' },
+  ],
+}
+```
+
+## Config Options
+
+| Option | Required | Description |
+|--------|----------|-------------|
+| `name` | — | Property name in DB (omit for presentational-only) |
+| `fields` | ✅ | Array of fields nested inside this group |
+| `label` | | Heading in Admin Panel; defaults to field name |
+| `interfaceName` | | Creates reusable TS interface + GraphQL type |
+| `localized` | | One flag localizes **all** nested fields at once |
+| `defaultValue` | | Object with defaults for all nested fields |
+| `saveToJWT` | | Include group data in JWT (top-level groups only) |
+| `hidden` | | Hidden from API + Admin UI, still stored in DB |
+| `virtual` | | Not stored in DB at all |
+| `validate` | | Custom validation function |
+| `hooks` | | Field lifecycle hooks |
+| `access` | | Field-level access control |
+| `typescriptSchema` | | Override generated TS type with JSON schema |
+| `custom` | | Plugin extension point |
+
+## Named vs Presentational Groups
+
+### Named group — creates nested object in data
+
+```ts
+{
+  name: 'pageMeta',    // → { pageMeta: { title, description } }
+  label: 'Page Meta',
+  type: 'group',
+  fields: [ ... ],
+}
+```
+
+### Presentational group — no nesting, visual grouping only
+
+Omit `name`, keep `label`:
+
+```ts
+{
+  label: 'Page Meta',  // visual section heading only
+  type: 'group',       // no name → no nested object
+  fields: [ ... ],
+}
+```
+
+Fields appear at the parent document level, not nested.
+
+## Admin Options
+
+```ts
+admin: {
+  hideGutter: true,  // hides the vertical gutter line (useful inside Array/Block)
+}
+```
+
+Inherits all base [[wiki/payloadcms/fields-basic|Field Admin options]].
+
+## Localization
+
+Setting `localized: true` on the group localizes **all** nested fields without marking each individually — one flag covers everything inside.
+
+Requires [[wiki/payloadcms/localization|localization enabled]] in the base config.
+
+## interfaceName — Reusable TypeScript Interface
+
+```ts
+{
+  name: 'pageMeta',
+  type: 'group',
+  interfaceName: 'Meta',   // generates: interface Meta { title: string; description: string }
+  fields: [ ... ],
+}
+```
+
+See [[wiki/payloadcms/typescript|TypeScript]] for `generate:types` CLI.
+
+## Key Takeaways
+
+- **Named group** → nested object in DB (`{ pageMeta: { title, description } }`)
+- **Presentational group** (no `name`) → fields remain flat in DB, grouped visually only
+- `localized: true` on group = all nested fields localized at once
+- `interfaceName` creates a reusable TS interface + GraphQL type for the group shape
+- `hideGutter: true` cleans up nested group appearance inside Array/Block fields
+- Group fields can contain any field type including other groups
+
+## Sources
+
+- [Payload CMS Docs — Group Field](https://payloadcms.com/docs/fields/group)
+- Raw: `raw/fields__group.md`