From bb93525719475eb6256306d220d86ab8941fef76 Mon Sep 17 00:00:00 2001 From: Jay Fletcher <5743488+jayjfletcher@users.noreply.github.com> Date: Thu, 29 Oct 2026 16:39:07 -0400 Subject: [PATCH 01/32] 2026-10-29-2037-screen-extensions-registry: shaped --- .../meta.yml | 5 ++ .../references.md | 46 ++++++++++++ .../shape.md | 75 +++++++++++++++++++ 3 files changed, 126 insertions(+) create mode 100644 docs/agent/specs/2026-10-29-2037-screen-extensions-registry/meta.yml create mode 100644 docs/agent/specs/2026-10-29-2037-screen-extensions-registry/references.md create mode 100644 docs/agent/specs/2026-10-29-2037-screen-extensions-registry/shape.md diff --git a/docs/agent/specs/2026-10-29-2037-screen-extensions-registry/meta.yml b/docs/agent/specs/2026-10-29-2037-screen-extensions-registry/meta.yml new file mode 100644 index 0000000..bb44199 --- /dev/null +++ b/docs/agent/specs/2026-10-29-2037-screen-extensions-registry/meta.yml @@ -0,0 +1,5 @@ +id: 2026-10-29-2037-screen-extensions-registry +title: 'Screen extensions registry' +status: shaping +created: '2026-10-29 20:37' +standards: {} diff --git a/docs/agent/specs/2026-10-29-2037-screen-extensions-registry/references.md b/docs/agent/specs/2026-10-29-2037-screen-extensions-registry/references.md new file mode 100644 index 0000000..109701d --- /dev/null +++ b/docs/agent/specs/2026-10-29-2037-screen-extensions-registry/references.md @@ -0,0 +1,46 @@ +# References + +## Roster registered tabs (the pattern to generalise) + +- **Location:** + - `Roster/src/Atrium/Tabs.php`, `TabDefinition.php` and `TabVisibility.php` + - `Roster/resources/views/ui/partials/tabs.blade.php` and `registered-tab.blade.php` + - spec `Roster/docs/agent/specs/2026-10-23-2015-dynamic-tabs-orgs-users/`, which includes D-005 to D-024 and the post-mortem +- **Relevance:** the behaviour to lift into Atrium as-is. +- **Borrow:** + - key regex `^[a-z0-9][a-z0-9._-]*$` + - reserved keys taken from a public constant + - clone on register + - `public private(set)` properties, with closures kept private + - default deny and `public()` + - a `scoped()` memo keyed by screen, record and tab + - throwing `authorize` closures reported once per request + - only the open tab's resolver runs + - spread order `[...$data, ...$host]` + - a single `data` prop for components + - unknown icons fall back via `Icons::has()` + - the README section, checked by a docs test + +## Atrium widget and plugin registries + +- **Location:** `Atrium/src/Domains/Widgets/Services/WidgetRegistry.php` and `WidgetDefinition`; `Atrium/src/Domains/Plugins/Services/PluginRegistry.php`. +- **Relevance:** existing Atrium registries with per-request availability (`WidgetRegistry::available(Request)`). +- **Borrow:** registry naming, provider wiring and how availability is filtered per request. + +## Atrium themes + +- **Location:** `Atrium/src/Domains/Themes/` (`Theme`, `ThemeRegistry`, `ThemesServiceProvider`, which defines `atrium`, `harbor`, `sunset`, `forest`, `midnight` and `ledger`), plus `resources/css/atrium.css` tokens. +- **Relevance:** dynamic tabs must work in every theme and in both the `sidebar` and `top` layouts. +- **Borrow:** token-only styling. The existing `x-atrium::tabs` (Alpine, client-side) and `tab-panel` components are related but not the same: screen tabs are server-side `?tab=` links. + +## Existing tab bars that will move onto the registry + +- Roster organization: `Roster/resources/views/ui/organizations/show.blade.php` and `OrganizationUiController` +- Roster user: `users/show.blade.php` and `UserUiController` +- Roster team: `teams/show.blade.php` and `TeamUiController` +- Roster SSO connection: `sso/show.blade.php` and `SsoUiController` (moves to Guardian) + +## Audit trail component (capability target for Keen) + +- **Location:** `Atrium/resources/views/components/audit-trail.blade.php` (props `source`, `subject`, `scope`, `action`, `limit`, `title`). +- **Relevance:** the audited-subject declaration must carry what this component needs (package key, subject or scope, and an optional action prefix). diff --git a/docs/agent/specs/2026-10-29-2037-screen-extensions-registry/shape.md b/docs/agent/specs/2026-10-29-2037-screen-extensions-registry/shape.md new file mode 100644 index 0000000..4a81dd9 --- /dev/null +++ b/docs/agent/specs/2026-10-29-2037-screen-extensions-registry/shape.md @@ -0,0 +1,75 @@ +# Screen extensions registry — Shaping Notes + +## Scope + +Make "register it from your own package" the one standard way to add tabs and sections to any Atrium screen, replacing every place where a host package checks whether another package is installed and renders that package's UI itself. + +This is a change to Atrium. It generalises Roster's `Atrium\Tabs` / `TabDefinition` / `TabVisibility` (Roster PR #5, spec `2026-10-23-2015-dynamic-tabs-orgs-users`) into Atrium so that every package's screens can be extended the same way. + +In scope: + +- **Registry.** One Atrium registry (working name `ScreenExtensions`), a singleton, populated from providers' `boot()`. It supports: + - **Tabs** on a screen's tab bar. + - **Sections:** named slots on a screen (a card or panel area, a table-row slot), each holding a list of registered sections. + - Screens are identified by a **string key**, `{package}.{screen}` (`roster.organization`, `roster.user`, `roster.team`, `roster.sso-connection`, `showroom.product`, `showroom.transfers`, …), so a registering package never imports the host's classes. +- **Definitions.** Tab and section definitions keep Roster's proven behaviour: + - fluent definitions (`label`, `icon`, `view` / `component`, `resolve`, `permission`, `authorize`, `public`) + - key validation, reserved built-in keys and clone-on-register + - default-deny visibility + - a per-request `scoped()` visibility memo + - a host's own screen authorization running before any registered code + - a resolver running only for the open tab or rendered section + - Roster's variables winning over resolver data + - throwing `authorize` closures counted as a denial and reported once per request + - `flush()` for tests only +- **Permission checks.** Atrium can't know each host's permission model. A host screen supplies its own access check, and Roster's `ScreenAccess::allows()` is one such check. +- **Screen declarations.** A host screen declares: + - its key + - its record, which may be absent for list or index screens + - its built-in tab keys, which are reserved + - its section slots + - an optional **audited subject**: the package key plus the subject record, a scope record, or package-wide. Keen's History section uses this (see the Keen spec). +- **Shared rendering components.** + - `x-atrium::screen-tabs`: a tab bar built from a screen's built-in and visible registered tabs, as `?tab=` links with `aria-current="page"`. + - `x-atrium::screen-sections`: renders a slot's visible sections in registration order. + - Both replace Roster's `roster::ui.partials.tabs` and `registered-tab` partials. +- **Themes.** Dynamic tabs and sections must render correctly in every built-in theme and both layouts: + - themes: `atrium`, `harbor`, `sunset`, `forest`, `midnight`, `ledger` + - layouts: `sidebar` and `top` + - The `top` layout already shows the current section's pages as a tab row under the topbar. A screen's tab bar must not collide with that row, and must stay usable (scrolling or wrapping) when many tabs are registered. + - Browser tests cover every theme in both layouts. + - Theme authors get a documented contract: the components only use design tokens, so a new theme needs no tab-specific work. + +## Decisions + +- D-001: the registry lives in Atrium. Roster's `Tabs` / `TabDefinition` / `TabVisibility` are deleted, not kept as wrappers. Roster moves onto Atrium's registry in its own spec. This is a breaking change, accepted because nothing is on Packagist yet. (User, 2026-10-29.) +- D-002: screens are identified by string keys `{package}.{screen}`, and a registering package never imports host classes. Registering for a screen whose package isn't installed is harmless, because that tab or section simply never renders. Registering packages therefore need no `class_exists()` checks. +- D-003: Keen's audit trail is added by capability. Screens declare an audited subject, and Keen registers one section that attaches to any screen that declares one. The registry therefore needs a "for every screen declaring X" registration form, alongside the per-screen-key form. (User, 2026-10-29.) +- D-004: every theme and both layouts must handle dynamic tabs, enforced by browser tests across all themes and layouts. (User, 2026-10-29.) +- D-005: this replaces section A of the cross-package audit (tabs and sections gated on another package). Section B is out of scope: nav items, whole pages, `historyNavItem()`, the history page and `atrium.keen.*` route checks. + +## Context + +- **References:** see `references.md`. +- **Order:** this spec is first. Every other spec in this initiative depends on it: + - Roster: adopt the registry + - Guardian + - Keen: History section + - Cortex + - Impex + - Showroom, Polycart, PennantPlus +- **Product:** Atrium is the shared dashboard for the Refactor Circus suite. Making it the extension point for screens means packages own their own UI wherever it appears. +- **Visuals:** none provided. The bar keeps the look of the existing Roster organization tab bar (`x-atrium::icon-button` items). + +## Standards + +- architecture/public-api: the registry, definitions and screen declaration become Atrium's public API for every package. +- architecture/container-bindings: the singleton registry plus the `scoped()` per-request visibility memo (Octane-safe). +- architecture/dependencies: hosts and registrants link only through string keys, with no `class_exists()` checks between packages. +- architecture/domain-modules: where the registry sits in Atrium's domains (likely a new `Screens` domain beside `Widgets` and `Plugins`). +- atrium/components: the new `screen-tabs` / `screen-sections` components, using design tokens only and safelisted utilities. +- atrium/domains: Atrium domain conventions. +- data/value-objects: immutable-from-outside definitions (`public private(set)`, clone on register). +- http/authorization: the host's screen authorization comes first, visibility is deny-by-default, and a hidden `?tab=` answers 403. +- testing/test-layers: unit tests for the registry and definitions, feature tests for rendering, and browser tests for every theme and layout. +- testing/arch-tests: new classes are final and use strict types. From 9329466287bac9026957ef5a1b07f98ced57e09e Mon Sep 17 00:00:00 2001 From: Jay Fletcher <5743488+jayjfletcher@users.noreply.github.com> Date: Thu, 29 Oct 2026 16:49:06 -0400 Subject: [PATCH 02/32] 2026-10-29-2037-screen-extensions-registry: shaping decisions --- .../specs/2026-10-29-2037-screen-extensions-registry/shape.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/docs/agent/specs/2026-10-29-2037-screen-extensions-registry/shape.md b/docs/agent/specs/2026-10-29-2037-screen-extensions-registry/shape.md index 4a81dd9..2de887d 100644 --- a/docs/agent/specs/2026-10-29-2037-screen-extensions-registry/shape.md +++ b/docs/agent/specs/2026-10-29-2037-screen-extensions-registry/shape.md @@ -47,6 +47,9 @@ In scope: - D-003: Keen's audit trail is added by capability. Screens declare an audited subject, and Keen registers one section that attaches to any screen that declares one. The registry therefore needs a "for every screen declaring X" registration form, alongside the per-screen-key form. (User, 2026-10-29.) - D-004: every theme and both layouts must handle dynamic tabs, enforced by browser tests across all themes and layouts. (User, 2026-10-29.) - D-005: this replaces section A of the cross-package audit (tabs and sections gated on another package). Section B is out of scope: nav items, whole pages, `historyNavItem()`, the history page and `atrium.keen.*` route checks. +- D-006: the registry supports per-row section slots: a slot rendered once per table row, with that row's record as the section's record, the resolver and `authorize` running per row, and the visibility memo keyed by row record. Impex's run link on `showroom.transfers` needs this. (User, 2026-10-29.) +- D-007: `x-atrium::audit-trail` moves out of Atrium into Keen (Keen spec). `x-atrium::audit.entries` stays in Atrium, because Atrium's own history page (`resources/views/history/show.blade.php:17`) renders it. (User, 2026-10-29.) +- D-008: keys registered on another package's screen are vendor-prefixed (`guardian.sso`, `keen.activity`, `cortex.mcp`), so they never clash with a host's reserved built-in keys while both exist. The README recommends `vendor.key`, and these first-party registrations follow it. ## Context From a5e3df3a2e2f9b5131bf1e41e162644f5b040cdc Mon Sep 17 00:00:00 2001 From: Jay Fletcher <5743488+jayjfletcher@users.noreply.github.com> Date: Thu, 29 Oct 2026 16:50:46 -0400 Subject: [PATCH 03/32] 2026-10-29-2037-screen-extensions-registry: spec written --- .../meta.yml | 7 +- .../spec.md | 173 ++++++++++++++++++ .../standards.md | 14 ++ 3 files changed, 192 insertions(+), 2 deletions(-) create mode 100644 docs/agent/specs/2026-10-29-2037-screen-extensions-registry/spec.md create mode 100644 docs/agent/specs/2026-10-29-2037-screen-extensions-registry/standards.md diff --git a/docs/agent/specs/2026-10-29-2037-screen-extensions-registry/meta.yml b/docs/agent/specs/2026-10-29-2037-screen-extensions-registry/meta.yml index bb44199..5ce9998 100644 --- a/docs/agent/specs/2026-10-29-2037-screen-extensions-registry/meta.yml +++ b/docs/agent/specs/2026-10-29-2037-screen-extensions-registry/meta.yml @@ -1,5 +1,8 @@ id: 2026-10-29-2037-screen-extensions-registry title: 'Screen extensions registry' -status: shaping +status: written created: '2026-10-29 20:37' -standards: {} +standards: + refactor-circus/standards: + version: dev-main + reference: a5b675396232 diff --git a/docs/agent/specs/2026-10-29-2037-screen-extensions-registry/spec.md b/docs/agent/specs/2026-10-29-2037-screen-extensions-registry/spec.md new file mode 100644 index 0000000..4cbafb9 --- /dev/null +++ b/docs/agent/specs/2026-10-29-2037-screen-extensions-registry/spec.md @@ -0,0 +1,173 @@ +# Screen extensions registry + +## Goal + +Any package can add tabs and sections to any Atrium screen by registering them from its own `boot()`. Host screens declare where those extensions may go and stop checking whether other packages are installed. Tabs and sections render the same way in every Atrium theme and layout. + +## Acceptance criteria + +### Registry and definitions + +1. `RefactorCircus\Atrium\Domains\Screens\Services\ScreenExtensions` is bound as a singleton (`app(ScreenExtensions::class) === app(ScreenExtensions::class)`) and is reachable as `Atrium::screens()`. It supports these registration methods: + - `tab(string $screen, TabDefinition)` + - `section(string $screen, string $slot, SectionDefinition)` + - `audited(SectionDefinition)` + + Each returns the registry, for chaining. A registration for a screen key that no installed package declares is stored and never renders, with no error. A unit test registers for `missing.screen` and asserts that nothing throws and that a declared screen with another key is unaffected. +2. `TabDefinition::make($key)` and `SectionDefinition::make($key)` live in `Domains\Screens\Data`. + - **Fluent setters:** both have `label()`, `icon()` (tabs only), `view()` / `component()` (setting one clears the other), `resolve(Closure)`, `permission(string)`, `authorize(Closure)` and `public()`. + - **Readable state:** `key`, `label`, `icon`, `view`, `component`, `permission` and `public` are `public private(set)`. `label` defaults to the key, a tab's `icon` defaults to `squares-2x2`, and `public` defaults to `false`. + - **Private closures:** `resolver` and `authorize` are private, and reading either from outside throws `Error`. + + Unit tests cover the view/component exclusivity and assert that writing any property throws `Error`. +3. **Registration validation.** + - Keys must match `^[a-z0-9][a-z0-9._-]*$`, or construction throws `InvalidArgumentException`. Tests cover an accepted `acme.billing`, and reject uppercase, a space, a slash and an empty key. + - Registration also throws `InvalidArgumentException` for: + - a duplicate key on the same screen (for tabs) or the same screen and slot (for sections), with a message naming the key and the screen + - a definition with neither a view nor a component + - a screen key that doesn't match `^[a-z0-9-]+\.[a-z0-9.-]+$` (`{package}.{screen}`) + - The registry stores a clone, so later fluent calls on the caller's instance change nothing. A test mutates the original after registering it and asserts that the registered copy is unchanged. + - Keys are cast with `(string)` wherever they are read back. A test registers the keys `123` and `007` and asserts that `?tab=007` reaches the view as the string `'007'`. +4. `ScreenExtensions::flush()` forgets everything and is documented as for tests only; nothing can be unregistered at runtime. Atrium's `TestCase` and the published testing helper call it in `beforeEach` and `afterEach`. A unit test registers a tab, a section and an audited section, calls `flush()`, and asserts that all three listings are empty. + +### Screen declarations + +5. A host renders a screen by building `Screen::make(string $key)` (`Domains\Screens\Data\Screen`). Its setters are: + - `record(?Model)` + - `tabs(array $builtIn)`, where each built-in entry gives its key, label and icon, in order + - `defaultTab(string)` + - `slots(string ...$names)` + - `rowSlots(string ...$names)` + - `access(Closure(string $permission, Request, ?Model $record): bool)` + - `audits(string $package, ?Model $subject = null, ?Model $scope = null, ?string $action = null, string $slot = 'history')` + + It then passes the screen to `ScreenExtensions::resolve(Screen, Request): ResolvedScreen`. + - **Reserved tab keys:** registering a tab whose key is one of the screen's built-in keys renders nothing, and resolving reports it once per request through `report()` with an `InvalidArgumentException` naming the key and the screen. The registry can't know a screen's built-ins at `boot()`, so the clash is caught at resolve time. Tested. + - **Permission checks:** a definition's `permission()` is checked only through the screen's `access` closure. A screen without one treats every `permission()` tab or section as hidden. Tested. +6. `ResolvedScreen` exposes: + - `tabs` (visible tabs in order: the built-ins as given, then registered tabs in registration order) + - `openTab` (string) + - `openRegisteredTab` (`?TabDefinition`) + - `sections(string $slot): list` (visible, in registration order) + - `rowSections(string $slot, Model $row): list` + - `data(TabDefinition|SectionDefinition, ?Model $record = null): array` (the resolver's output, computed on first call and memoized for the request) + + Resolving reads `?tab=` only as a string; `?tab[]=x` counts as absent. The open tab is chosen this way: + - **Absent or unknown key:** `defaultTab`, or the first built-in if none is set, with a 200. Registered tabs are never the default. + - **Visible registered tab:** that tab. + - **Registered tab the viewer can't see:** a 403 HTTP exception. +7. **Visibility.** + - A tab or section is visible only when: + - its `permission()` passes the screen's `access` closure + - its `authorize(fn (Request, ?Model $record): bool)` returns `true` + - both pass, when it has both + - with neither, only after `public()` + - A throwing `authorize` closure counts as a denial and is reported once per request per screen and key. + - Results are memoized per request in `ScreenVisibility`, bound with `scoped()` and keyed by screen, record key, slot and extension key. Results never live on the registry or the definitions. + - Tests cover, for both tabs and sections: permission only, closure only, `public()`, neither (hidden), both passing, one failing, and a throwing closure (reported exactly once, closure called exactly once, screen returns 200). Two sequential requests with `app()->forgetScopedInstances()` between them and different viewers each evaluate visibility afresh. +8. **Order of evaluation.** + - Hosts call `resolve()` only after their own screen authorization. The README states this, and a test-host screen denied with a 403 asserts that no `authorize` closure or resolver runs (both counted). + - Resolvers run only when `data()` is called: for the open registered tab, and for each section the component renders. A counting resolver on a hidden tab, an unopened tab, a hidden section and a section in a slot the view doesn't render is never called. + - On the component path, resolver data reaches the view as a single `data` prop. On the view path it is spread first, with the host's variables (`screen`, the record under `record`, and `tab`) spread over it, so the host's variables win. A test returns `screen`, `record` and `tab` from a resolver and asserts that the host's values win. + +### Per-row slots + +9. A `rowSlots()` slot renders once per row: ``. + - Inside a row slot, the section's `authorize` closure and resolver receive that row's model, and visibility is memoized per row key. + - A feature test renders a three-row table with a section whose `authorize` admits only the second row, and asserts: + - the section markup appears exactly once, in that row + - `authorize` was called three times and the resolver once + - a second render of the same rows in the same request makes no further calls + - A section registered on a row slot and rendered without `:row` throws `InvalidArgumentException`; so does a normal slot rendered with `:row`. Tested. + +### Audited screens (capability) + +10. `audited(SectionDefinition)` registers a section for every screen that calls `audits(...)`. It renders in the slot the screen named (default `history`) and is visible only when that screen declares an audited subject. + - The section's resolver and view receive an `AuditedSubject` value (`package`, `subject`, `scope`, `action`) instead of the record. + - A screen without `audits()` never renders it, and its `authorize` and resolver are never called. Tested with counting closures. + - A screen that declares `audits()` but doesn't render the named slot also doesn't call them. Tested. + +### Rendering components + +11. `x-atrium::screen-tabs :screen="$resolved"` renders a `