docs(quick-261007-p4y): toggle sizing and settings controller links
This commit is contained in:
Jakub Zych
@@ -0,0 +1,155 @@
|
||||
---
|
||||
phase: quick-261007-p4y
|
||||
plan: 01
|
||||
status: complete
|
||||
subsystem: admin, cabana, pact, sm-translate-plugin
|
||||
tags: [admin-spa, settings, pact, cabana, translate, parity]
|
||||
requires: []
|
||||
provides:
|
||||
- "pact.SettingsItem.Controller: a settings entry that links to an admin controller"
|
||||
- "cabana link compile/validation, metadata filtering (Allows + canOpen), singleton-endpoint 404s"
|
||||
- "SPA settingsPath / settingsLinkFor; Settings-aware rail, breadcrumbs and page title"
|
||||
- "translate plugin: Locales on the Settings page instead of the main navigation"
|
||||
affects: [sm-grzybyfunkcjonalne-app, sm-summercmsio-app]
|
||||
tech-stack:
|
||||
added: []
|
||||
patterns:
|
||||
- "Settings entries share one code namespace across singleton and link entries"
|
||||
- "Registry.Setting hides link entries so protectSetting answers 404 with no http.go change"
|
||||
key-files:
|
||||
created:
|
||||
- modules/cabana/settings_link_test.go
|
||||
- modules/cabana/example_settings_test.go
|
||||
- ../sm-translate-plugin/admin_settings.go
|
||||
modified:
|
||||
- admin/src/components/form/fields/SwitchField.vue
|
||||
- modules/pact/capabilities.go
|
||||
- modules/cabana/settings.go
|
||||
- modules/cabana/registry.go
|
||||
- modules/cabana/navigation.go
|
||||
- modules/cabana/contracts.go
|
||||
- modules/cabana/example_test.go
|
||||
- admin/openapi/admin.json
|
||||
- admin/src/api/schema.d.ts
|
||||
- admin/tests/fixtures/settings.json
|
||||
- admin/src/state/useSettings.ts
|
||||
- admin/src/views/SettingsIndexView.vue
|
||||
- admin/src/components/shell/PluginRail.vue
|
||||
- admin/src/components/shell/Breadcrumbs.vue
|
||||
- admin/src/app/pageTitle.ts
|
||||
- modules/pact/README.md
|
||||
- modules/cabana/README.md
|
||||
- docs/backend/settings.md
|
||||
- docs/setup/coming-from-wintercms.md
|
||||
- modules/boardwalk/dist/
|
||||
- ../sm-translate-plugin/admin.go
|
||||
- ../sm-translate-plugin/plugin_test.go
|
||||
- ../sm-translate-plugin/locales_admin_test.go
|
||||
- ../sm-translate-plugin/README.md
|
||||
deleted:
|
||||
- ../sm-translate-plugin/admin_navigation.go
|
||||
decisions:
|
||||
- "A settings link entry rejects Model as well as Form/NewModel, so the SPA never sees a misleading model string"
|
||||
- "Translate's settings category follows the PHP reference (golem15.translate::lang.plugin.name); no core System category constant added"
|
||||
- "The docs Go example for the link entry lives in its own file (example_settings_test.go) because example_controller_test.go is embedded whole in admin-controllers.md"
|
||||
metrics:
|
||||
duration: "13 min"
|
||||
completed: 2026-10-07
|
||||
estimate:
|
||||
tokens: 140000
|
||||
tasks: 3
|
||||
actuals:
|
||||
tokens: 15600
|
||||
tasks: 3
|
||||
commits: 3
|
||||
plan_head_before: a586357a346a66111d37bd8c1d564c769a412715
|
||||
plan_head_after: 0b09acdb0cca4955a2dcba2e9a2708a06b032104
|
||||
---
|
||||
|
||||
# Quick 261007-p4y: Toggle proportions and Settings controller links Summary
|
||||
|
||||
The admin switch now has pixel-based proportions: a 44x26 track and a 20px knob. Settings entries can now link to an admin controller through an additive `pact.SettingsItem.Controller` field, covered from start-up validation through to the Settings page. The translate plugin now lists Locales on the Settings page, under the Translate category, as WinterCMS did.
|
||||
|
||||
## Commits
|
||||
|
||||
summercms.go (3 commits, measured `git rev-list --count a586357..HEAD` = 3):
|
||||
|
||||
| Task | Commit | Message |
|
||||
|------|--------|---------|
|
||||
| 1 | b040ee3 | fix(admin): size the switch toggle in pixels at the 14px root |
|
||||
| 2A | 4a9b089 | feat(cabana): settings entries that link to an admin controller |
|
||||
| 2B | 0b09acd | feat(admin): open controller-link settings entries from the settings index |
|
||||
|
||||
sm-translate-plugin (separate repo, 1 commit):
|
||||
|
||||
| Task | Commit | Message |
|
||||
|------|--------|---------|
|
||||
| 3 | bde3f1a | feat(settings): open Locales from the Settings page |
|
||||
|
||||
No commit has a co-author trailer. No commit touches `.planning`. Nothing was pushed.
|
||||
|
||||
## What was built
|
||||
|
||||
- **Switch:** `w-[44px]` and `size-[20px]` give 3 + 20 + 18 + 3 = 44, with a symmetric inset. Dist was rebuilt and committed on its own.
|
||||
- **pact:** `SettingsItem.Controller` is a new additive field placed before `Form`. Keyed literals in other code compile unchanged, and a grep of the meta repo found no unkeyed ones.
|
||||
- **cabana:**
|
||||
- `compileSettingLink` rejects a link that also sets Form, NewModel or Model.
|
||||
- The link branch in `compileContributions` skips the AdminFS requirement.
|
||||
- After every plugin is collected, start-up fails on an unknown controller with `cabana: setting <code> references unknown controller <id>`.
|
||||
- `Registry.Setting` hides link entries, so all three singleton endpoints answer 404.
|
||||
- `SettingsEntry.Controller` is serialised as `json:"controller"` and is always present.
|
||||
- Metadata lists a link entry only when the principal passes `Allows(item.Permissions)` and `canOpen(controller)`.
|
||||
- **OpenAPI:** `controller` is a required string on `cabana.SettingsEntry` in admin.json and schema.d.ts. The settings fixture entries now carry `"controller": ""`.
|
||||
- **SPA:**
|
||||
- Index cards link through `settingsPath`.
|
||||
- The rail marks Settings current on a linked controller that has no navigation entry. A linked controller that does have a navigation entry keeps its plugin highlighted.
|
||||
- Breadcrumbs on such a page read `Ustawienia > <label> [> record]`.
|
||||
- The page title falls back to the entry label.
|
||||
- **Translate:** `Plugin.Settings()` returns the single locales link entry, with values taken from the PHP registerSettings reference. `admin_navigation.go` is removed, and `HasNavigation` is replaced by `HasSettings` in the assertion block.
|
||||
|
||||
## TDD evidence
|
||||
|
||||
- Go RED: `settings_link_test.go` failed to build (`unknown field Controller in struct literal of type pact.SettingsItem`). After the change it passes: 4 tests plus 9 subtests.
|
||||
- SPA RED: 6 new cases failed across useSettings, Settings, PluginRail, Breadcrumbs and pageTitle. After the change it passes: all 1083 tests in 74 files.
|
||||
- Translate RED: the build failed (`p.Settings undefined`). After the change it passes, and the harness test ran against Postgres via testcontainers.
|
||||
|
||||
## Verification
|
||||
|
||||
- summercms.go: `go vet ./...` and `go test ./... -count=1` pass. So do `scripts/check-admin-openapi.sh --check`, `scripts/check-admin-dist.sh`, `go test ./cmd/summer -run TestDocsTree`, `npm --prefix admin run typecheck` and `npm --prefix admin test`.
|
||||
- sm-translate-plugin: `gofmt -l .` is clean, and `go vet ./...` and `go test ./... -count=1` pass.
|
||||
- Both working trees are clean, apart from the orchestrator-owned `.planning/quick/...` directory.
|
||||
|
||||
## Deviations from Plan
|
||||
|
||||
### Auto-fixed Issues
|
||||
|
||||
**1. [Rule 3 - Blocking] The docs snippet needed a `src=` reference and a shorter description**
|
||||
- **Found during:** Task 2, commit A
|
||||
- **Issue:** TestDocsTree rejects a Go fence without `src=` and a frontmatter description over 160 characters. Adding the example to `example_controller_test.go` changed a whole-file snippet in `docs/backend/admin-controllers.md`.
|
||||
- **Fix:** I added `modules/cabana/example_settings_test.go`, which holds `LinkedBlogPlugin` and a `docs:start settings-link` region. `TestDocsSettingsLink` in `example_test.go` activates the plugin through `cabana.Activate`, which proves the link compiles end to end. The settings.md description is shortened.
|
||||
- **Commit:** 4a9b089
|
||||
|
||||
**2. [Process] The admin-behaviour paragraph moved to commit B**
|
||||
- The settings.md paragraph about the rail and breadcrumbs went into the SPA commit (0b09acd) rather than commit A, so each commit's docs match its code.
|
||||
|
||||
**3. [Test fixture choice] Rail, breadcrumb and title tests use `acme.lang.locales`**
|
||||
- The plan suggested `acme.demo.locales`, but `acme.demo` is in the navigation fixture, which would make the plugin highlight win. These tests use a plugin that is absent from navigation, `acme.lang.locales`. The path tests in useSettings still use `acme.demo.locales`.
|
||||
|
||||
## Follow-ups
|
||||
|
||||
- Consuming apps (sm-grzybyfunkcjonalne-app, sm-summercmsio-app) must bump their translate submodule to bde3f1a or later. They also need a framework tag that includes `pact.SettingsItem.Controller` (4a9b089 or later). Neither bump is done here, because it was out of scope.
|
||||
- The PHP plugin also registers a `messages` settings link. There is no Messages admin controller in the Go port yet, so only `locales` is registered.
|
||||
|
||||
## Known Stubs
|
||||
|
||||
None.
|
||||
|
||||
## Threat Flags
|
||||
|
||||
None. All new surface is covered by the plan's threat register: T-01 has the metadata filter tests, T-02 the 404 tests, T-03 the compile validation tests, and T-04 the settingsPath fallback test.
|
||||
|
||||
## Self-Check: PASSED
|
||||
|
||||
- FOUND: modules/cabana/settings_link_test.go, modules/cabana/example_settings_test.go, ../sm-translate-plugin/admin_settings.go
|
||||
- MISSING (intended): ../sm-translate-plugin/admin_navigation.go
|
||||
- FOUND commits: b040ee3, 4a9b089, 0b09acd (summercms.go); bde3f1a (sm-translate-plugin)
|
||||
Reference in New Issue
Block a user