90 lines
4.8 KiB
Markdown
90 lines
4.8 KiB
Markdown
# Slice 2a: Request Reference Usability
|
|
|
|
## Status
|
|
|
|
Complete - automated validation, proportional manual acceptance, and explicit final sign-off passed
|
|
|
|
## Objective
|
|
|
|
Make REST request-template authoring easier to discover and visually map while
|
|
preserving the existing canonical template format and guided insertion workflow.
|
|
|
|
## Compatible Reference Suggestions
|
|
|
|
- [x] Make template-capable request fields aware of compatible component and
|
|
declared-variable references.
|
|
- [x] Offer suggestions when a user begins entering a template, including after
|
|
typing `{{`, without requiring exact template syntax from memory.
|
|
- [x] Apply suggestions to endpoint URLs, header values, query-parameter values,
|
|
and request body templates where the existing runtime supports references.
|
|
- [x] Insert the canonical executed forms
|
|
`{{components.<componentName>.value}}` and `{{variables.<variableName>}}`.
|
|
|
|
- [x] Filter suggestions to references supported by the selected field and
|
|
current project configuration.
|
|
- [x] Preserve free-form template editing and the existing **Request value
|
|
reference** controls.
|
|
|
|
## Header Name Suggestions
|
|
|
|
- [x] Offer a pulldown of common HTTP header names, including **Accept** and
|
|
**Content-Type**, when authoring REST Action headers.
|
|
- [x] Keep free-form custom header-name entry available for backend-agnostic,
|
|
vendor-specific, and less common headers.
|
|
- [x] Preserve the existing canonical header object and runtime behavior.
|
|
|
|
## Source and Destination Alignment
|
|
|
|
- [x] Reorder the **Request value reference** controls so request destinations
|
|
align vertically with request keys and value sources align vertically with
|
|
request values.
|
|
- [x] Present the controls in this order: request destination, component or
|
|
variable source, then **Insert reference**.
|
|
- [x] Preserve the source and destination terminology and existing insertion
|
|
behavior.
|
|
- [x] Manually verify the alignment remains clear for URL, header, query, and body
|
|
destinations at supported viewport widths.
|
|
|
|
## Acceptance Criteria
|
|
|
|
- [x] Typing `{{` in a supported request field offers compatible component and
|
|
declared-variable suggestions.
|
|
- [x] Choosing a suggestion inserts valid canonical template syntax without
|
|
preventing subsequent free-form editing.
|
|
- [x] Unsupported or ambiguous references are not offered.
|
|
- [x] Header-name authoring suggests common HTTP headers while still accepting
|
|
arbitrary custom names.
|
|
- [x] A destination such as `Query: environment` is vertically aligned with the
|
|
`environment` request key below it.
|
|
- [x] A source such as `Component: environment` is vertically aligned with the
|
|
resulting `{{components.environment.value}}` request value below it.
|
|
- [x] Existing request-template execution and canonical/runtime-state separation
|
|
continue to pass automated and manual regression checks.
|
|
|
|
## Boundaries
|
|
|
|
- This work improves authoring only; it does not add new runtime template
|
|
destinations, expression syntax, transforms, or orchestration.
|
|
- Path-parameter reference insertion remains excluded until its runtime contract
|
|
is deliberately unified.
|
|
- Authentication and secret references remain owned by Slice 3.
|
|
|
|
## Automated Validation
|
|
|
|
- Focused request-authoring coverage: 4 suites / 23 tests passed.
|
|
- Complete frontend coverage: 21 suites / 507 tests passed, 0 snapshots.
|
|
- Frontend production build passed under the documented Node 20/npm 10 toolchain.
|
|
- Backend and schema validation were not rerun because Slice 2a changes only frontend authoring behavior and preserves the canonical document shape.
|
|
|
|
## Manual Acceptance
|
|
|
|
Proportional manual acceptance passed on 2026-08-01 in an isolated Chromium browser against project `Slice 2 Final` (`#12`) at `http://localhost:3000/`. The normal viewport was 1440 x 1100 and the responsive viewport was 700 x 1000. The saved project was not updated.
|
|
|
|
- Contextual component and variable suggestions passed across URL, header-value, query-value, and body-template fields.
|
|
- Duplicate `hostname` component names were withheld from contextual and guided suggestions while `Variable: statusText` remained available; `hostname` and `hostnameSecondary` became eligible after uniqueness was restored.
|
|
- Common header suggestions included `Accept` and `Content-Type`; `X-Custom-Vendor-Header` was preserved exactly with value `test` in the canonical `headers` object.
|
|
- Guided controls appeared as **Request destination**, **Value source**, and **Insert reference**, aligned semantically at 1440 x 1100 and stacked clearly without overlap at 700 x 1000.
|
|
- Header/query insertion replaced existing values, URL/body insertion appended, path parameters remained excluded, free-form editing remained available, and canonical JSON remained free of mapping and runtime state.
|
|
|
|
This evidence is manual acceptance, separate from the automated validation above. The user granted explicit final Slice 2a sign-off on 2026-08-01.
|