72faa38472
- Replace view-only row buttons with clickable rows (recordUrl)\n- Update action-surface contract slot to InspectAffordance + validator support\n- Add golden guard tests + contract doc\n- Update SpecKit constitution/templates to include inspection affordance rule
82 lines
2.7 KiB
Markdown
82 lines
2.7 KiB
Markdown
# Data Model — Action Surface Contract
|
|
|
|
This feature introduces a small, explicit model for declaring and validating action surfaces.
|
|
|
|
## Entities
|
|
|
|
### ActionSurfaceDeclaration
|
|
|
|
Represents the contract declaration attached to a Filament component.
|
|
|
|
**Fields**:
|
|
- `version` (int): schema version for forward compatibility (start at `1`).
|
|
- `componentType` (enum): `Resource | Page | RelationManager`.
|
|
- `className` (string): fully qualified class name (filled by validator when reporting).
|
|
- `panelScope` (enum): `Tenant | Admin` (filled by validator based on discovery context).
|
|
- `profile` (enum): contract profile (see below).
|
|
- `slots` (map<ActionSurfaceSlot, SlotRequirement>): required and optional slots for this component.
|
|
- `exemptions` (list<ActionSurfaceExemption>): explicit exemptions with reason.
|
|
- `defaults` (ActionSurfaceDefaults): shared UX defaults (e.g., `moreGroupLabel`).
|
|
|
|
### ActionSurfaceSlot (enum)
|
|
|
|
Discrete UI locations that may contain actions.
|
|
|
|
Proposed baseline slots:
|
|
- `ListHeader`
|
|
- `ListRowPrimary`
|
|
- `ListRowMoreMenu`
|
|
- `ListBulkMoreGroup`
|
|
- `ListEmptyState`
|
|
- `DetailHeader`
|
|
|
|
(Profiles determine which slots are required.)
|
|
|
|
### SlotRequirement
|
|
|
|
Requirement status for a single slot.
|
|
|
|
**Fields**:
|
|
- `status` (enum): `Satisfied | Exempt`.
|
|
- `details` (optional string): freeform explanation or expected actions.
|
|
- `requiresTypedConfirmation` (bool, default false): indicates the actions in this slot require typed confirmation.
|
|
|
|
### ActionSurfaceExemption
|
|
|
|
Represents a justified opt-out for a required slot.
|
|
|
|
**Fields**:
|
|
- `slot` (ActionSurfaceSlot)
|
|
- `reason` (string, required, non-empty)
|
|
- `trackingRef` (optional string)
|
|
|
|
### ActionSurfaceDefaults
|
|
|
|
Shared defaults enforced/checked by CI.
|
|
|
|
**Fields**:
|
|
- `moreGroupLabel` (string, required): must be `More`.
|
|
- `exportIsDefaultBulkActionForReadOnly` (bool): default expectation for ReadOnly + RunLog profiles.
|
|
|
|
## Profiles (enum)
|
|
|
|
Profiles map component archetypes to required slots.
|
|
|
|
Proposed profiles (initial set):
|
|
- `CrudListAndEdit`: list + edit page exists.
|
|
- `CrudListAndView`: list + view page exists.
|
|
- `ListOnlyReadOnly`: list-only, no edit/view.
|
|
- `RunLog`: operational log list (read-only, expects Export bulk action by default).
|
|
|
|
## Validation rules (CI)
|
|
|
|
For each in-scope class:
|
|
- Must define an action surface declaration.
|
|
- Must select a profile.
|
|
- For every slot required by that profile:
|
|
- slot must be present with `Satisfied`, OR
|
|
- slot must be marked `Exempt` and there must be a matching exemption with non-empty reason.
|
|
- Defaults must include `moreGroupLabel = "More"`.
|
|
|
|
Note: The validator is intentionally declarative; it validates the presence and completeness of the declaration (and exemptions), not the exact runtime Filament action configuration.
|