Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
34 commits
Select commit Hold shift + click to select a range
bb93525
2026-10-29-2037-screen-extensions-registry: shaped
jayjfletcher Oct 29, 2026
9329466
2026-10-29-2037-screen-extensions-registry: shaping decisions
jayjfletcher Oct 29, 2026
a5e3df3
2026-10-29-2037-screen-extensions-registry: spec written
jayjfletcher Oct 29, 2026
e80b53d
2026-10-29-2037-screen-extensions-registry: every screen declares slo…
jayjfletcher Oct 29, 2026
1094eeb
2026-10-29-2037-screen-extensions-registry: decisions D-009 to D-019
jayjfletcher Oct 29, 2026
13b02ba
2026-10-29-2037-screen-extensions-registry: rewritten in place per D-…
jayjfletcher Oct 29, 2026
33d83cd
2026-10-29-2037-screen-extensions-registry: approved
jayjfletcher Oct 29, 2026
f2895a0
2026-10-29-2037-screen-extensions-registry: tasks
jayjfletcher Oct 29, 2026
b261929
2026-10-29-2037-screen-extensions-registry: building
jayjfletcher Oct 29, 2026
73e5d22
2026-10-29-2037-screen-extensions-registry: group 1 Registry, definit…
jayjfletcher Oct 29, 2026
a3174ce
2026-10-29-2037-screen-extensions-registry: group 1 Registry, definit…
jayjfletcher Oct 29, 2026
d3c2cab
2026-10-29-2037-screen-extensions-registry: group 4 Remove history fr…
jayjfletcher Oct 30, 2026
667f2d8
2026-10-29-2037-screen-extensions-registry: group 2 Rendering compone…
jayjfletcher Oct 30, 2026
c2335fe
2026-10-29-2037-screen-extensions-registry: D-030; groups 1, 2, 4 built
jayjfletcher Oct 30, 2026
253fc72
2026-10-29-2037-screen-extensions-registry: integrate group 2
jayjfletcher Oct 30, 2026
7afc9a2
2026-10-29-2037-screen-extensions-registry: integrate group 4
jayjfletcher Oct 30, 2026
1509834
2026-10-29-2037-screen-extensions-registry: building (run 2)
jayjfletcher Oct 30, 2026
b933023
2026-10-29-2037-screen-extensions-registry: group 3 Declare Atrium's …
jayjfletcher Oct 30, 2026
381aa40
2026-10-29-2037-screen-extensions-registry: D-031, D-032
jayjfletcher Oct 30, 2026
8f04d47
2026-10-29-2037-screen-extensions-registry: building (run 3)
jayjfletcher Oct 30, 2026
869d92c
2026-10-29-2037-screen-extensions-registry: group 3 Declare Atrium's …
jayjfletcher Oct 30, 2026
941c3c4
2026-10-29-2037-screen-extensions-registry: D-033
jayjfletcher Oct 30, 2026
a403788
2026-10-29-2037-screen-extensions-registry: group 3 Declare Atrium's …
jayjfletcher Oct 30, 2026
2064a03
2026-10-29-2037-screen-extensions-registry: group 3 Declare Atrium's …
jayjfletcher Oct 30, 2026
fb8ad25
2026-10-29-2037-screen-extensions-registry: group 5 Browser theme and…
jayjfletcher Oct 30, 2026
a2357c0
2026-10-29-2037-screen-extensions-registry: group 5 Browser theme and…
jayjfletcher Oct 30, 2026
6877adc
2026-10-29-2037-screen-extensions-registry: group 6 Documentation, ar…
jayjfletcher Oct 30, 2026
8da9f70
2026-10-29-2037-screen-extensions-registry: group 6 Documentation, ar…
jayjfletcher Oct 30, 2026
0f89502
2026-10-29-2037-screen-extensions-registry: rework round 1
jayjfletcher Oct 30, 2026
b13b1ab
2026-10-29-2037-screen-extensions-registry: rework round 2
jayjfletcher Oct 30, 2026
34775b9
2026-10-29-2037-screen-extensions-registry: approved as is
jayjfletcher Oct 30, 2026
1eb49a2
2026-10-29-2037-screen-extensions-registry: in review: PR #16
jayjfletcher Oct 30, 2026
797d3e3
Add Screen::reserve() for keys the viewer may not open
jayjfletcher Oct 30, 2026
0542685
2026-10-29-2037-screen-extensions-registry: D-034 Screen::reserve
jayjfletcher Oct 30, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 2 additions & 1 deletion AGENTS.md
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down
16 changes: 12 additions & 4 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -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 `<x-atrium::audit-trail>` 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.

Expand All @@ -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
Expand Down
Loading
Loading