diff --git a/AGENTS.md b/AGENTS.md index 06efb11..fb2fdc0 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -14,13 +14,14 @@ This repository is a Laravel package. Keep the package focused, idiomatic, and e These are recorded in full in the global standards and under `docs/agent/standards/`; the short form: -- **Code lives in domain modules.** `src/Domains/{Domain}/` (`Access`, `Dashboard`, `History`, `Navigation`, `Plugins`, `Search`, `Settings`, `Themes`, `Widgets`), namespace `RefactorCircus\Atrium\Domains\{Domain}`, each with a `{Domain}ServiceProvider` registered by `Domains\DomainServiceProvider`. Models are `{Entity}Model` in `Models/`; value objects in `Data/`; registries in `Services/`. Package-wide base classes, contracts and `Support/` stay at the top level. A moved model keeps its old class name as a morph alias. See `architecture/domain-modules` (global standard) and `docs/agent/standards/atrium/domains.md`. +- **Code lives in domain modules.** `src/Domains/{Domain}/` (`Access`, `Dashboard`, `Navigation`, `Plugins`, `Screens`, `Search`, `Settings`, `Themes`, `Widgets`), namespace `RefactorCircus\Atrium\Domains\{Domain}`, each with a `{Domain}ServiceProvider` registered by `Domains\DomainServiceProvider`. Models are `{Entity}Model` in `Models/`; value objects in `Data/`; registries in `Services/`. Package-wide base classes, contracts and `Support/` stay at the top level. A moved model keeps its old class name as a morph alias. See `architecture/domain-modules` (global standard) and `docs/agent/standards/atrium/domains.md`. - **Actions own mutating logic.** Extend `RefactorCircus\Keystone\Actions\Action`, implement a `protected handle()` with a concrete return type, and let callers use `execute()`. Action input is a `final readonly` `{Action}Data` in the domain's `Data/` (on `RefactorCircus\Keystone\Data\Data`), never an array: fields are promoted constructor properties (camelCase of the input keys; `T|Missing = new Missing` for partial updates), `rules()` lives on the Data, and the starting event carries it. Requests' `rules()` return `XData::rules()` and `persist()` builds with `XData::fromValidated($this->validated())` - never `XData::from()` in a request; untrusted input elsewhere uses `XData::from()`, which validates, and code that vouches for its values uses `new XData(...)`. Nested input is nested Data (`#[ListOf(WidgetPlacementData::class)]`), checked by the parent's rules under its key (`widgets.*.widget_key`). `tests/ArchTest.php` checks this with Keystone's `Testing\Arch`, along with the event pair on every action, writes only inside a transaction, and a `{Entity}{Hook}Event` for every model hook. `handle()` dispatches a starting `{Subject}{Verb-ing}ActionEvent` with the input, runs the work in a private `perform()` wrapped in `DB::transaction()`, then dispatches the finished `{Subject}{Verb-ed}ActionEvent` with the result. - **Requests own validation, authorization, and the call into an action.** Extend `RefactorCircus\Atrium\Http\Requests\Request` and implement `persist()`. Controllers only `return $request->persist();` and never contain database calls. - **Events are final classes using `Dispatchable` and `SerializesModels`.** Action events live in the domain's `Events/` and implement `RefactorCircus\Keystone\Contracts\ActionStartingEvent` or `ActionFinishedEvent` (after commit); every action has one of each. Model events live beside them, are named `{Entity}{Hook}Event`, implement `RefactorCircus\Keystone\Contracts\ModelLifecycleEvent`, and are mapped by the `RefactorCircus\Keystone\Models\Concerns\DispatchesModelEvents` trait every model uses. - **Shared runtime lives in `refactor-circus/keystone`.** The `Action` and `Request` bases, event contracts, `DispatchesModelEvents`, the package registry and the audit seams come from Keystone, which every package in the suite requires. Atrium registers itself as the `atrium` package from `AtriumServiceProvider::definition()`. - **Tables are configurable.** Models resolve their table with `getTable()` from `Support\Tables` (`atrium.tables`, on Keystone's `Database\Tables`), and the migrations use the same keys, never literal `atrium_*` names. `tests/ArchTest.php` checks with `Arch::literalTableNames()`, and that every model has a policy in `atrium.policies` with `Arch::modelsWithoutPolicies()`; `tests/Modes/RenamedTables` reruns dashboard flows with every table renamed. - **Requests authorize through policies.** `authorize()` calls `$this->allows()` / `allowsEach()`: `viewAny`/`create` on the model class, `view`/`update`/`delete` on the instance. Every model has a policy; policies extend `Domains\Dashboard\Policies\Policy`, are registered from `atrium.policies` by `registerPolicies()`, and child-model policies defer to the dashboard through the Gate with Keystone's `Policy::allowsOn()`. +- **Screens declare themselves.** Every Atrium page with a controller view builds `Domains\Screens\Data\Screen::standard()` with its key, record and kind, resolves it with `ScreenExtensions::resolve()` after its own authorization, and renders `x-atrium::screen-tabs`, `x-atrium::screen-tab-panel` and the sections of every slot it declares. Other packages add tabs and sections through `Atrium::screens()` from `boot()`. Atrium knows no other suite package: it requires only Keystone and has no audit concept (the history screen and audit components live in Keen). - Do not require a feature-flag package such as Pennant; gating is the host application's concern. Pennant is a dev dependency only, for `Domains\Themes\Features\ThemeSwitcherFeature`, which only Pennant resolves. Feature-flag management lives in `refactor-circus/pennantplus`, which plugs into Atrium like any other package. ## PHP Conventions diff --git a/CHANGELOG.md b/CHANGELOG.md index fdd5af0..82720cb 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,18 +7,27 @@ - Moved to the Refactor Circus organisation: the package is now `refactor-circus/atrium` with the PHP namespace `RefactorCircus\Atrium` (it was `jayi/atrium` and `JayI\Atrium`). Update `composer.json` requirements and `use` statements. Old class names are not kept as aliases, so stored values written under them - polymorphic `*_type` columns, audit subjects, Pennant feature names - need updating to the new names. - Actions take Data objects, not arrays: `CreateDashboardAction` takes a `CreateDashboardData`, `UpdateDashboardAction` an `UpdateDashboardData` (fields left out stay as they are), and `SaveDashboardLayoutAction` a `SaveDashboardLayoutData` whose `widgets` are `WidgetPlacementData` objects (`Domains\Dashboard\Data`). The requests' validation rules live on the Data, and the starting events carry it: `DashboardCreatingActionEvent::$data` and `DashboardUpdatingActionEvent::$data` are Data objects, and `DashboardLayoutSavingActionEvent` carries `$data` (its `widgets`) in place of `$widgets`. - `Domains\Dashboard\Policies\Policy::allowsOnDashboard()` is gone: policies defer to the parent dashboard with refactor-circus/keystone's `Policy::allowsOn()`, which takes the same arguments. +- **History moved to Keen.** Atrium has no audit concept any more: the history screen, its components and its nav item now live in [refactor-circus/keen](https://github.com/Refactor-Circus/Keen), which adds a History nav item for every package that audits. Install Keen to keep them, and merge Atrium, Keen and the packages that used them together, since the removal breaks anything still calling them. Removed from Atrium: + - the `atrium.history.show` route (`GET {path}/history/{package}`), which now answers 404; + - the `History` domain: `RefactorCircus\Atrium\Domains\History\HistoryServiceProvider` (no longer registered by `Domains\DomainServiceProvider`) and `RefactorCircus\Atrium\Domains\History\Http\Controllers\HistoryController`; + - the `atrium::history.show` view (`resources/views/history/show.blade.php`); + - the `x-atrium::audit-trail` component, `x-atrium::audit.entries`, `x-atrium::audit.changes` and the rest of `resources/views/components/audit/`, with their `@source` lines in `resources/css/atrium.css`; + - `RefactorCircus\Atrium\Domains\Plugins\Support\Plugin::historyNavItem()`: stop calling it from a plugin's `navigation()`; Keen adds the links; + - the 24 `atrium::atrium.audit_*` translation keys (`audit_history`, `audit_empty`, `audit_when`, `audit_action`, `audit_subject`, `audit_actor`, `audit_surface`, `audit_source_app`, `audit_none`, `audit_system`, `audit_no_changes`, `audit_field`, `audit_before`, `audit_after`, `audit_view_all`, `audit_log`, `audit_log_for`, `audit_action_hint`, `audit_subject_type`, `audit_subject_id`, `audit_filter`, `audit_clear`, `audit_newest`, `audit_older`): a view or a published `lang/vendor/atrium` file that still uses them should take Keen's strings instead. ### Added +- **Screen extensions**: any package can add tabs and sections to any screen that declares itself, registered from its `boot()` with `Atrium::screens()` (`Domains\Screens\Services\ScreenExtensions`, a singleton) for one screen (`{package}.{screen}`), every screen of a package (`{package}.*`) or every screen (`*`). Definitions are `Domains\Screens\Data\TabDefinition` and `SectionDefinition`, visible only through a `permission()` the screen's `access` closure grants, an `authorize()` closure or `public()`; their `authorize` and `resolve` closures receive the `Screen` last. Hosts declare a screen per request with `Screen::standard()` (the `header.actions`, `before`, `after` slots, plus `aside` or the row slot `row.actions`), resolve it with `ScreenExtensions::resolve()` into a `ResolvedScreen`, and render it with the new `x-atrium::screen-tabs`, `x-atrium::screen-sections` and `x-atrium::screen-tab-panel` components. Answers and data are memoized per request in the `scoped()` `ScreenVisibility`; a failing section is reported once and renders nothing. A same-key duplicate on one target throws in `local` and `testing` and is reported and skipped elsewhere; across targets the most specific wins. See the README's "Screen extensions". +- `Screen::reserve(string ...$keys)` reserves tab keys a host does not render, such as built-in tabs the viewer may not open: a registered tab with a reserved key is skipped and reported like one using a built-in key, and `?tab=` naming one opens the default tab. +- Atrium's own pages declare themselves as screens: `atrium.dashboard`, `atrium.named-dashboard`, `atrium.dashboard-widget`, `atrium.settings` (with `row.actions` per settings panel, as a `Domains\Settings\Data\SettingsPanelRow`) and `atrium.settings-panel`. With nothing registered they render as before. +- `RefactorCircus\Atrium\Testing\ResetsScreenExtensions`, a test case trait that snapshots the screen extensions after boot and restores them after each test (`ScreenExtensions::snapshot()` and `restore()`). + - **Lazy widgets**: `WidgetDefinition::lazy()` renders a placeholder with the dashboard and fetches the widget's body afterwards from the new `atrium.dashboards.widgets.show` route (`GET {path}/dashboards/{dashboard}/widgets/{widget}`), which answers whoever may see the dashboard. Widgets stay eager unless marked lazy. - **Configurable table names**: both tables are named under the new `atrium.tables` config key (`dashboards`, `dashboard_widgets`) and read by the migrations and models through `Support\Tables` (on refactor-circus/keystone's `Database\Tables`). Rename them before migrating; keys a published config leaves out keep their default. -- A package's audit log link, history page and `` panels show only while the package audits (refactor-circus/keystone's `Package::audits()`: Keen installed and its `{key}.audit.enabled` on), not merely while an audit log is installed. - Four more themes - **Sunset**, **Forest**, **Midnight** and **Ledger** - and theme layouts: `Theme::layout('top')` (or `'layout' => 'top'` in config) lays the shell out with sections across a bar under the topbar and the current section's pages as tabs beneath, as Ledger does. - A two-level sidebar: a rail of sections (the app's own pages, then one icon per group) and a docked panel with the current section's pages. Clicking a section shows its pages without leaving the page, and hovering previews them. `NavGroup` gains `icon()` and `sort()` for its place in the rail. `Atrium::navigationSections()` lists the rail's entries. -- A per-package audit log page at `atrium.history.show` (`/atrium/history/{package}`), with filters and paging, and `Plugin::historyNavItem()` to link it from a plugin's sidebar group. History panels link to it. - Themes: a second built-in theme, **Harbor**, beside the default **Atrium**; themes from `atrium.themes.available` and `Atrium::theme()`; and a theme switcher beside the light/dark toggle, shown behind the `atrium.themes.switcher_feature` feature (Atrium's own `Domains\Themes\Features\ThemeSwitcherFeature` by default, a Pennant feature that is on until turned off, globally or per user, once a feature resolver such as refactor-circus/pennantplus is registered). - Shared components so the packages of the suite need no markup or styles of their own: `description-list`, `chip`, `search-input`, `flash`, `banner`, `guest`, `form.combobox`, `form.actions`, a `bare` mode for form controls, and `prefix`/`suffix` slots on `form.input`. -- History components that read the audit log through refactor-circus/keystone's `AuditTrail`: `audit-trail`, `audit.entries` and `audit.changes`. `audit-trail` renders nothing until an audit log (refactor-circus/keen) is installed. - `Plugin::featuresFromConfig()`, `RefactorCircus\Atrium\Support\ScreenAccess` and the `AuthorizesScreens` controller trait, so a package's plugin and screens stop copying the same feature loading and policy checks. - A safelist of layout utilities in the compiled stylesheet, and `RefactorCircus\Atrium\Testing\AtriumStyles` for checking a package's views use only Atrium's styles. @@ -30,7 +39,6 @@ - A page beneath a navigation item now counts as that item's: an item on a resource's `*.index` route stays active on its `*.show` and `*.edit` pages, and a URL item on the paths beneath it. The sidebar's panel and Ledger's tabs no longer disappear on a record's own page. - Ledger's top bar no longer has a hover menu as well as its row of tabs. - Form controls no longer render an `id` twice when one is passed. -- `audit-trail` shows a package's history only to those its history endpoint would answer. - `form.input` and `form.select` no longer use `null` as an array offset when no `wrapper` is passed, which PHP 8.5 deprecates. ### Changed diff --git a/README.md b/README.md index a9dbd19..9e60863 100644 --- a/README.md +++ b/README.md @@ -84,22 +84,6 @@ class BillingPlugin extends Plugin - `RefactorCircus\Atrium\Support\ScreenAccess::allows('billing', 'refund', $invoice)` asks a package's policies exactly as its JSON API and MCP tools do, honouring its `authorization` switch. Use it to hide controls. - The `RefactorCircus\Atrium\Http\Controllers\Concerns\AuthorizesScreens` trait gives a screen controller `$this->authorizeScreen('refund', $invoice)`, which answers 403 the same way for the package the controller belongs to. -### A package's own audit log - -With an audit log installed ([refactor-circus/keen](https://github.com/Refactor-Circus/Keen)), every package has its own log at `/atrium/history/{package}`: its entries, newest first, filtered by action or record. Add a link to it in your plugin's sidebar group: - -```php -public function navigation(): array -{ - return [ - // ... - $this->historyNavItem('billing')->group('Billing')->sort(90), - ]; -} -``` - -The link and the page show only while an audit log is installed and the user may read the package's history, as its history endpoint decides. `` panels link to the same page. - ### Registering the plugin Packages declare their plugin in `composer.json` and Atrium discovers it on install: @@ -124,6 +108,192 @@ Host applications stay in control. Add plugin classes to `plugins` in `config/at Discovered plugins are cached in `bootstrap/cache/atrium-plugins.php`, as Laravel caches its package manifest, so a request does not read Composer's `installed.json`. `package:discover` (which Composer runs after every install and update) and `optimize` rebuild it, `atrium:discover` rebuilds it by hand, and `optimize:clear` (or `atrium:clear-discovered`) removes it. Without the file, plugins are read from the installed packages on every boot, as before. +## Screen extensions + +Any package can add tabs and sections to any screen that declares itself, without the screen knowing the package exists. A screen declares only generic facts: its key (`{package}.{screen}`), its record, its kind, its built-in tabs and its slots. Atrium declares its own pages: `atrium.dashboard` (`/`), `atrium.named-dashboard` (`d/{slug}`), `atrium.dashboard-widget`, `atrium.settings` and `atrium.settings-panel`. + +### Registering tabs and sections + +Register from a service provider's `boot()`, and only there. The registry lasts for the process and nothing can be unregistered, so a registration made during a request would leak into the next one. Each registration is copied, so changing your definition afterwards changes nothing. + +```php +use Illuminate\Database\Eloquent\Model; +use Illuminate\Http\Request; +use RefactorCircus\Atrium\Domains\Screens\Data\Screen; +use RefactorCircus\Atrium\Domains\Screens\Data\SectionDefinition; +use RefactorCircus\Atrium\Domains\Screens\Data\TabDefinition; +use RefactorCircus\Atrium\Facades\Atrium; + +public function boot(): void +{ + Atrium::screens() + // A tab on one screen, opened with ?tab=acme.invoices. + ->tab('crm.customer', TabDefinition::make('acme.invoices') + ->label('Invoices') + ->icon('banknotes') + ->view('acme::screens.invoices') + ->permission('acme.invoices.view') + ->resolve(fn (?Model $record, Screen $screen): array => [ + 'invoices' => Invoice::forCustomer($record)->latest()->get(), + ])) + + // A section in one slot of one screen. + ->section('crm.customer', 'aside', SectionDefinition::make('acme.balance') + ->component('acme::balance') + ->authorize(fn (Request $request, ?Model $record, Screen $screen): bool => $request->user()?->can('view', $record) === true) + ->resolve(fn (?Model $record, Screen $screen): array => ['balance' => Balance::of($record)])) + + // A row section: rendered once per row of a list screen, with the row as $record. + ->section('crm.customers', 'row.actions', SectionDefinition::make('acme.row-balance') + ->view('acme::screens.row-balance') + ->authorize(fn (Request $request, ?Model $record, Screen $screen): bool => $record instanceof Customer)) + + // A wildcard section: every screen that declares the slot. Return early. + ->section('*', 'aside', SectionDefinition::make('acme.notes') + ->view('acme::screens.notes') + ->authorize(fn (Request $request, ?Model $record, Screen $screen): bool => $screen->kind === Screen::DETAIL + && $record !== null + && $request->user()?->can('acme.notes', $record) === true)); +} +``` + +- **Targets.** An exact screen key (`crm.customer`), every screen of one package (`{package}.*`, such as `crm.*`), or every screen (`*`). A `*` tab joins every declared screen; a `*` section joins every screen declaring its slot. A section on a slot the screen does not declare never renders and its closures never run, and a registration for a screen no installed package declares is kept and never renders, with no error. +- **Keys.** Prefix every key with your vendor, as `vendor.key` (`acme.invoices`). Keys go into `?tab=`, `data-testid` and URLs, and match `^[a-z0-9][a-z0-9._-]*$`. A registered tab may not reuse a built-in tab key (`overview` included): it is skipped and reported. +- **Rendering.** Give each tab or section a `view()` or a `component()` (setting one clears the other). A view receives the resolver's data with the host's `screen` (the `Screen`), `record` and `tab` (the open tab's key) over it, so the host's values win. A component receives the resolver's data as one `data` prop. +- **Who sees it.** Extensions are hidden by default. One shows only when its `permission()` passes the screen's `access` closure, its `authorize()` closure returns `true`, both pass when it has both, or it is `public()`. A screen without an `access` closure hides every `permission()` extension. An `authorize()` that throws counts as a denial and is reported once per request. + +### Closures and evaluation order + +Every closure receives the `Screen` last: + +```php +->authorize(fn (Request $request, ?Model $record, Screen $screen): bool => ...) +->resolve(fn (?Model $record, Screen $screen): array => [...]) +``` + +`$record` is the screen's record (null on screens without one), or the row inside a row slot. + +1. The host authorizes the request itself. Nothing of yours runs on a page the viewer may not open. +2. The host resolves the screen. Each registered tab's visibility is checked, then each section's when its slot renders, once per row in a row slot. +3. Resolvers run only for what renders: the open registered tab and each visible section in a rendered slot. Answers and data are remembered for the request, per screen, slot, extension and record. + +Wildcard and row-slot closures run on every matching screen or row, so keep them cheap: return early on `$screen->key` or `$screen->kind` before any query. + +### Opening tabs + +A tab opens through `?tab={key}`. An absent or unknown key opens the host's default tab with a 200. A registered tab the viewer cannot see answers 403. That 403-versus-200 difference reveals which tab keys exist, which is accepted: never put anything secret in a key. + +The tab bar shows only when two or more tabs are visible. A screen with no built-in tabs gets one, `overview`, holding the page. Registered tabs follow the built-in ones (exact registrations first, then wildcard ones, each in registration order) and are never the default. Built-in labels come from the host; Atrium translates nothing. + +A host that leaves out a built-in tab the viewer may not open still reserves its key with `$screen->reserve('salaries')`: a registered tab using a reserved key is skipped and reported, as for a built-in key, so it shows to no one. Reserved keys never render, and `?tab=` naming one opens the default tab with a 200. They match the same key pattern; an invalid one throws. + +### What renders around an open registered tab + +The tab's panel replaces the host's page content. `header.actions` always renders; `before`, `after`, `aside` and row slots render only while a built-in tab is open. + +A section renders into a buffer: one whose resolver or view throws renders nothing, is reported once per request, and the page still answers 200. An open registered tab's panel that throws fails the page (500), as the page itself would. + +The tab bar and the sections use only Atrium's design tokens and safelisted utilities, so they look the same in every theme and layout, and a theme sets nothing for them. Keep your views to the same contract and check them with `AtriumStyles` (see [Package styles](#package-styles)). + +A section renders inside the host's page, but it writes through your own routes and your own authorization: forms in it post to your routes, and your requests authorize them. The host only decided who may open the page. + +### Duplicates + +- **The same key twice on one target** (the same target string, and for sections the same slot): registration throws `InvalidArgumentException` naming the key and the target in the `local` and `testing` environments. In production, and any other environment, it reports the exception once through `report()`, skips the later registration and keeps the first, rather than taking down every route and command from `boot()`. +- **The same key on one screen through different targets**: the more specific target wins: the exact key, then `{package}.*`, then `*`. Each less specific duplicate is skipped and reported once per request. + +### Declaring a screen + +A host declares a screen per request with `Screen::standard()`, which gives the standard slots: `header.actions`, `before` and `after`, plus `aside` on a `detail` screen or the row slot `row.actions` on a `list` screen. Add more with `slots()` and `rowSlots()`. Resolve it only after your own authorization: + +```php +use Illuminate\Database\Eloquent\Model; +use Illuminate\Http\Request; +use Illuminate\Support\Facades\Gate; +use RefactorCircus\Atrium\Domains\Screens\Data\Screen; +use RefactorCircus\Atrium\Domains\Screens\Services\ScreenExtensions; + +public function show(Request $request, Invoice $invoice, ScreenExtensions $screens): View +{ + $this->authorizeScreen('view', $invoice); + + $screen = Screen::standard('acme.invoice', Screen::DETAIL) + ->record($invoice) + ->tabs([ + ['key' => 'details', 'label' => __('Details'), 'icon' => 'document-text'], + ['key' => 'payments', 'label' => __('Payments'), 'icon' => 'banknotes'], + ]) + ->access(fn (string $permission, Request $request, ?Model $record): bool => Gate::forUser($request->user()) + ->allows($permission, $record ? [$record] : [])); + + return view('acme::invoices.show', [ + 'invoice' => $invoice, + 'resolved' => $screens->resolve($screen, $request), + ]); +} +``` + +```blade + + @if ($resolved->sections('header.actions') !== []) + + + + @endif + + + + +@if ($resolved->openRegisteredTab !== null) + +@else + + + {{-- Your page, for the built-in tab $resolved->openTab. --}} + + + +@endif +``` + +On a list screen, render the row slot inside each row: ``. + +### Packages know nothing of each other + +Atrium requires only [Keystone](https://github.com/Refactor-Circus/Keystone) among the suite's packages; every other suite package is a `suggest`, never a requirement, and a package's Atrium UI loads only when Atrium is installed. So a package's code never names another package's screens. It ships editable defaults in its own config instead, and the application changes or empties the list: + +```php +// config/acme.php +'atrium' => [ + 'screens' => [ + // The target screen => 'tab', or the slot to add a section to. + 'crm.customer' => 'tab', + 'crm.contact' => 'aside', + ], +], +``` + +```php +// AcmeServiceProvider::boot(); Atrium is suggested, so it may be missing. +if (class_exists(Atrium::class)) { + foreach (config('acme.atrium.screens', []) as $target => $slot) { + $slot === 'tab' + ? Atrium::screens()->tab($target, $this->invoicesTab()) + : Atrium::screens()->section($target, $slot, $this->balanceSection()); + } +} +``` + +A default takes effect only when its target screen exists: a registration for a screen nobody declares never renders. + +### Testing + +Registrations made in a test would otherwise outlive it. Use `RefactorCircus\Atrium\Testing\ResetsScreenExtensions` on your test case: it snapshots the registry once the application has booted, keeping every provider's `boot()` registrations, and restores the snapshot after each test. + +```php +uses(TestCase::class, ResetsScreenExtensions::class)->in('Feature'); +``` + ## Managing Pennant feature flags The Feature flags page moved to [refactor-circus/pennantplus](https://github.com/Refactor-Circus/PennantPlus), which registers it as an Atrium plugin when both are installed. @@ -170,7 +340,7 @@ Available components: **Forms**: `form.input` (with `prefix` and `suffix` slots), `form.textarea`, `form.select`, `form.checkbox`, `form.radio`, `form.file`, `form.combobox`, `form.actions`. Pass `bare` to an input, textarea, select or checkbox for the control alone, such as in a table cell. -**History**: `audit-trail` (a package's or one record's history, from the installed audit log), `audit.entries`, `audit.changes` +**Screens**: `screen-tabs`, `screen-sections` and `screen-tab-panel`, which render a declared screen's extensions (see [Screen extensions](#screen-extensions)) ### Screen conventions @@ -540,6 +710,7 @@ The code is organised into domain modules under `src/Domains/{Domain}`, namespac | `Dashboard` | `Models\DashboardModel` and `Models\DashboardWidgetModel`, their policies, actions, events, requests and controllers, and `Services\DashboardManager` | | `Navigation` | `Data\NavItem`, `Data\NavGroup` and `Services\NavigationRegistry` | | `Plugins` | The `Contracts\Plugin` contract, the `Support\Plugin` base class, `Services\PluginRegistry`, Composer discovery and the plugin commands | +| `Screens` | `Data\Screen`, `Data\TabDefinition`, `Data\SectionDefinition` and `Data\ResolvedScreen`, `Services\ScreenExtensions` (the registry behind `Atrium::screens()`) and `Services\ScreenVisibility` | | `Search` | `Data\SearchSource`, `Data\SearchResult`, `Services\SearchRegistry` and the search endpoint | | `Settings` | `Data\SettingsPanel`, `Services\SettingsRegistry` and the settings pages | | `Widgets` | `Data\WidgetDefinition` and `Services\WidgetRegistry` | diff --git a/config/atrium.php b/config/atrium.php index 648439d..81e7298 100644 --- a/config/atrium.php +++ b/config/atrium.php @@ -102,12 +102,11 @@ |-------------------------------------------------------------------------- | | Atrium keeps no audit log of its own. With refactor-circus/keen - | installed, Keen records every dashboard change Atrium makes, and - | Atrium shows each package's history while that package audits. + | installed, Keen records every dashboard change Atrium makes and shows + | each package's history. | | enabled: Set to false to keep Atrium's own dashboard changes out of the - | audit log even while Keen is installed. Other packages' history - | follows their own `audit.enabled`. + | audit log even while Keen is installed. | */ diff --git a/docs/agent/specs/2026-10-29-2037-screen-extensions-registry/brief.md b/docs/agent/specs/2026-10-29-2037-screen-extensions-registry/brief.md new file mode 100644 index 0000000..58010b1 --- /dev/null +++ b/docs/agent/specs/2026-10-29-2037-screen-extensions-registry/brief.md @@ -0,0 +1,36 @@ +Risk: high + +## What changed +- New `Domains/Screens`: + - the `ScreenExtensions` registry, a singleton reached through `Atrium::screens()` + - `TabDefinition` and `SectionDefinition` + - `Screen`, with `standard()` slots: `header.actions`, `before`, `after`, `aside`, and the row slot `row.actions` + - `ResolvedScreen` + - the per-request memo `ScreenVisibility` + - wildcard targets `*` and `{package}.*` + - the `x-atrium::screen-tabs`, `screen-tab-panel` and `screen-sections` components + - the `Testing\ResetsScreenExtensions` trait +- All five Atrium pages declare themselves with a tab bar, the standard slots and a Gate `access()` check: the dashboard, the named dashboard, widget detail, the settings index (with a `row.actions` slot on each panel row) and the settings panel. +- Removed and moved to Keen (D-014, D-016): + - the History domain, the `history/{package}` route and `HistoryController` + - `x-atrium::audit-trail` and `x-atrium::audit.*` + - `Plugin::historyNavItem()` +- Added a README and Boost "Screen extensions" section, a CHANGELOG upgrade note, and a browser matrix over 6 themes, 2 layouts and light/dark. + +## Why +This makes "register it from your own package" the only way to add tabs and sections to any screen, so host packages stop checking whether other packages are installed (D-017: no package knows another; integrations go through config). It generalises Roster's registered tabs (Roster PR #5). + +## Look at +- `src/Domains/Screens/Services/ScreenExtensions.php`: registration, the duplicate rules by environment (D-022), and exact/`pkg.*`/`*` precedence (D-023, D-028). +- `src/Domains/Screens/Services/ScreenVisibility.php`: the per-request memo keyed by morph class plus key or the model itself. Visibility answers must never leak across viewers. +- `resources/views/components/screen-sections.blade.php`: failure isolation. It snapshots and restores the view factory's state so that a throwing section can't break the page (D-015). +- `src/Domains/Settings/Data/SettingsPanelRow.php`: the unsaved stand-in that carries each settings panel row (D-031, D-033). + +## Tested +- `composer test`: phpstan 0 errors, pint, 100% type coverage, pest 589/589. +- `composer test:browser`: 46/46, including the 24 theme × layout × mode cases. The gate didn't run this suite; I ran it by hand after the job escalated. +- `npm run build:css`: `public/atrium.css` is unchanged, so the committed file is current. + +## Risks +- Breaking: the history page, the audit components and `historyNavItem()` are gone. Every host that uses them breaks until its own spec lands (see Breaks). Merge as a group: Atrium, Keen, then the hosts (D-009). +- Wildcard and row-slot closures run on every matching screen or row, so a slow registrant slows every page. The README tells registrants to return early. diff --git a/docs/agent/specs/2026-10-29-2037-screen-extensions-registry/build.md b/docs/agent/specs/2026-10-29-2037-screen-extensions-registry/build.md new file mode 100644 index 0000000..9f5f0e0 --- /dev/null +++ b/docs/agent/specs/2026-10-29-2037-screen-extensions-registry/build.md @@ -0,0 +1,264 @@ +# Build: Screen extensions registry + +## Group 1 (salvaged) + +**Found.** No index lock and no merge or rebase in progress. The previous build agent left every group 1 file in the worktree, uncommitted: the `Domains/Screens` domain (`ScreensServiceProvider`, `DefinesExtension`, `TabDefinition`, `SectionDefinition`, `Screen`, `ResolvedScreen`, `ScreenExtensions`, `ScreenVisibility`), `Testing\ResetsScreenExtensions`, the edits to `DomainServiceProvider`, `Atrium`, the facade and `tests/TestCase.php`, and all seven test files. It had ticked 1.1 to 1.3 in `tasks.md` but committed nothing and wrote no build note. `tests/Pest.php` needed no change and is untouched. + +**Checked.** Read every file against criteria 1 to 8 and 11 and task 1.1's list: singleton and `Atrium::screens()`; setters, defaults, `Error` on writes and closure reads, view/component exclusivity, trailing `Screen`; key, slot and target validation with every D-026 reject; clone on register; `123`/`007` as strings through `?tab=`; duplicates per environment (local/testing throw, production reports once and keeps the first); cross-target precedence in all three pairings for tabs and sections; `snapshot()`/`restore()`/`flush()` and the trait's two-test behaviour; `Screen::make`/`standard()`; tab ordering, reserved keys (exact and `*`), `?tab=` string-only, unknown key 200, hidden key 403; the visibility matrix, throwing `authorize` reported and called once, memo by morph class plus key or the unsaved model itself, `forgetScopedInstances()` between viewers; `*` and `test.*` matching. All present. `php -l` passes on all 20 files. The suite was not run here; the gate runs it. + +**Committed.** The 20 group 1 files listed above, plus 1.1 and 1.2 ticked in `tasks.md` and this note. + +**Left.** +- 1.3 (`vendor/bin/pest` green) is unticked: there is no record that the previous agent ran the suite. +- Two related edits by the previous agent sit outside the group's file list and are left uncommitted in the worktree: `phpstan.neon.dist` adds `tests/TestCase.php` to the analysed paths, so PHPStan analyses the published `ResetsScreenExtensions` trait through its one user instead of reporting it unused; and `docs/agent/standards-feedback.md` records `Screen::kind()` taking a string (with `Screen::DETAIL`/`Screen::LIST`) rather than an enum, because the spec fixes `kind('detail'|'list')` and `standard(string $key, string $kind)`. `composer analyse` likely needs the `phpstan.neon.dist` change. +- `AGENTS.md` and the group 5 bullet reformat in `tasks.md` are not group 1 changes and are left as found. + +## Group 1 + +Retry to finish 1.3. Nothing had run the group's tests before this, so this pass ran them. + +**Files.** `tests/Feature/Screens/VisibilityTest.php` (fixed); also `phpstan.neon.dist` and `docs/agent/standards-feedback.md`, which are outside the group's file list (see Deviations). + +**Tests.** `vendor/bin/pest tests/Unit/Screens tests/Feature/Screens` first failed 4 of 172 tests, all in `VisibilityTest`: "hides an extension whose authorize closure throws" and "evaluates afresh for another viewer", for both the tab and the section case. The bug was in the tests, not in `ScreenVisibility`. Each test registered its counting closure inside an arrow function (`fn ($d) => $d->authorize(function () use (&$calls) { ... })`). An arrow function captures `$calls` by value, so the counter the inner closure incremented was the arrow function's copy and the test always saw 0. Both registrations are now plain closures that capture `use (&$calls)` / `use (&$asked, &$resolved)`. After the fix, all 172 pass (392 assertions). `pint --test` passes on every group 1 file, and `phpstan analyse` passes with 0 errors. The full suite was not run here; the gate runs it. + +**Deviations.** +- `phpstan.neon.dist` adds `tests/TestCase.php` to the analysed paths, and this group needs it. Without it, PHPStan reports `trait.unused` on the published `Testing\ResetsScreenExtensions` trait (checked against a copy of the config without that path) and `composer analyse` fails. With it, PHPStan analyses the trait through its one user. +- `docs/agent/standards-feedback.md` records the `data/value-objects` deviation: `Screen::kind()` takes a string, with `Screen::DETAIL`/`Screen::LIST` constants, instead of an enum, because the spec fixes `kind('detail'|'list')` and `Screen::standard(string $key, string $kind)`. + +## Group 4 + +Built in the `--g4` worktree on `ring-master/2026-10-29-2037-screen-extensions-registry--g4`. + +**Files.** +- Added `tests/Feature/HistoryRemovedTest.php`: `GET /atrium/history/billing` is 404 even with an auditing package and an installed audit trail, and `atrium.history.show` is not a route; `HistoryController` and `HistoryServiceProvider` don't load, and `src/Domains/History`, `history/show`, `audit-trail` and `components/audit/` don't exist; `method_exists(Plugin::class, 'historyNavItem')` is false; no `@source` line in `atrium.css` names `audit` or `history/`. +- Deleted `src/Domains/History/` (provider, `routes.php`, `HistoryController`), `resources/views/history/show.blade.php`, `resources/views/components/audit-trail.blade.php`, `resources/views/components/audit/` (`entries`, `changes`), `tests/Feature/HistoryPageTest.php` and `tests/Feature/AuditComponentsTest.php`. +- Edited `resources/css/atrium.css` (dropped the four `@source` lines) and `src/Domains/Plugins/Support/Plugin.php` (removed `historyNavItem()` and its now unused imports). + +**Tests.** The new test was written before the deletions. The suite was not run here; the gate runs it. + +**Deviations.** These files are outside the group's list: +- `src/Domains/DomainServiceProvider.php`: dropped `HistoryServiceProvider`, as task 4.2 says. +- `tests/Feature/DomainLayoutTest.php`: dropped `HistoryServiceProvider` from its provider dataset. Without this the test can't load the class. +- `lang/en/atrium.php`: removed the 24 `audit_*` keys. Only the deleted views and `historyNavItem()` used them. Keen ships its own. +- `config/atrium.php`: in the `audit` comment, the claim that Atrium shows each package's history now says Keen does it. +- `docs/agent/standards/atrium/components.md`: dropped `audit-trail`, `audit.entries` and `audit.changes` from the generic pieces. + +**Left for group 6** (it owns these files): `README.md` lines 96, 101 and 173 (`historyNavItem`, `x-atrium::audit-trail`, the History components list); `History` in `CLAUDE.md`, in `docs/agent/standards/atrium/domains.md` and in that standard's description in `docs/agent/standards.index.yml`; rebuilding `public/atrium.css`; the `CHANGELOG.md` upgrade note. The Boost skill had no references. + +## Group 2 + +Built in the `--g2` worktree on `ring-master/2026-10-29-2037-screen-extensions-registry--g2` (commit `667f2d8`). + +**Files.** +- Components: `resources/views/components/screen-tabs.blade.php` (a `flex ... overflow-x-auto` `