Skip to content

feat: add JS level system for component preview notices #393

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
alexluckett merged 6 commits into from
May 13, 2026
Merged

feat: add JS level system for component preview notices #393

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
6 commits
Select commit Hold shift + click to select a range
d1d28c0
feat: add JS level system for component preview notices
alexluckett May 12, 2026
3900a16
fi image url
alexluckett May 12, 2026
8698901
add notice about map question pattern
alexluckett May 12, 2026
2396088
add link for map location pattern
alexluckett May 13, 2026
f70fd98
jsdoc types
alexluckett May 13, 2026
a4e86da
fix test
alexluckett May 13, 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
4 changes: 2 additions & 2 deletions docs/assets/css/docusaurus.scss
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -69,7 +69,7 @@
margin-bottom: 0;
}

.app-map-placeholder {
.app-preview-placeholder {
margin-top: 20px;
margin-bottom: 20px;
padding: 40px 20px;
Expand All @@ -86,7 +86,7 @@
}

.govuk-template--rebranded .app-masthead .govuk-grid-column-one-third-from-desktop {
background-image: url("../../../static/assets/images/form-input-screenshot.png");
background-image: url("/forms-engine-plugin/assets/images/form-input-screenshot.png");
background-repeat: no-repeat;
background-position: center bottom;
background-size: 220px;
Expand Down
1 change: 0 additions & 1 deletion docusaurus.config.cjs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -78,7 +78,6 @@ const config = {
text: 'Features',
href: '/features',
sidebar: [
{ text: 'Overview', href: '/features' },
{ text: 'Components', href: '/features/components' },
{ text: 'Page Types', href: '/features/pages' },
{
Expand Down
83 changes: 72 additions & 11 deletions scripts/component-preview-fixtures.js
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -26,6 +26,7 @@ const sampleList = {
/** @type {Partial<Record<ComponentType, Fixture>>} */
export const fixtures = {
[ComponentType.TextField]: {
jsLevel: 3,
def: {
type: ComponentType.TextField,
name: 'full-name',
Expand All @@ -38,6 +39,7 @@ export const fixtures = {
payload: {}
},
[ComponentType.EmailAddressField]: {
jsLevel: 3,
def: {
type: ComponentType.EmailAddressField,
name: 'email',
Expand All @@ -48,6 +50,7 @@ export const fixtures = {
payload: {}
},
[ComponentType.MultilineTextField]: {
jsLevel: 3,
def: {
type: ComponentType.MultilineTextField,
name: 'description',
Expand All @@ -60,6 +63,7 @@ export const fixtures = {
payload: {}
},
[ComponentType.NumberField]: {
jsLevel: 3,
def: {
type: ComponentType.NumberField,
name: 'age',
Expand All @@ -71,6 +75,7 @@ export const fixtures = {
payload: {}
},
[ComponentType.TelephoneNumberField]: {
jsLevel: 3,
def: {
type: ComponentType.TelephoneNumberField,
name: 'phone',
Expand All @@ -81,6 +86,7 @@ export const fixtures = {
payload: {}
},
[ComponentType.MonthYearField]: {
jsLevel: 3,
def: {
type: ComponentType.MonthYearField,
name: 'start-date',
Expand All @@ -92,6 +98,7 @@ export const fixtures = {
payload: {}
},
[ComponentType.DatePartsField]: {
jsLevel: 3,
def: {
type: ComponentType.DatePartsField,
name: 'dob',
Expand All @@ -103,6 +110,7 @@ export const fixtures = {
payload: {}
},
[ComponentType.UkAddressField]: {
jsLevel: 3,
variants: [
{
label: 'With postcode lookup',
Expand All @@ -129,6 +137,7 @@ export const fixtures = {
]
},
[ComponentType.YesNoField]: {
jsLevel: 3,
def: {
type: ComponentType.YesNoField,
name: 'agree',
Expand All @@ -139,6 +148,7 @@ export const fixtures = {
payload: {}
},
[ComponentType.RadiosField]: {
jsLevel: 3,
def: {
type: ComponentType.RadiosField,
name: 'colour',
Expand All @@ -150,6 +160,7 @@ export const fixtures = {
payload: {}
},
[ComponentType.CheckboxesField]: {
jsLevel: 3,
def: {
type: ComponentType.CheckboxesField,
name: 'colours',
Expand All @@ -161,6 +172,7 @@ export const fixtures = {
payload: {}
},
[ComponentType.SelectField]: {
jsLevel: 3,
def: {
type: ComponentType.SelectField,
name: 'country',
Expand All @@ -172,6 +184,9 @@ export const fixtures = {
payload: {}
},
[ComponentType.AutocompleteField]: {
jsLevel: 2,
jsNotice:
'This component is progressively enhanced. Without JavaScript it renders as a standard &lt;select&gt; dropdown that works fully. With JavaScript enabled it becomes a searchable autocomplete.',
def: {
type: ComponentType.AutocompleteField,
name: 'country',
Expand All @@ -183,6 +198,7 @@ export const fixtures = {
payload: {}
},
[ComponentType.DeclarationField]: {
jsLevel: 3,
def: {
type: ComponentType.DeclarationField,
name: 'declaration',
Expand All @@ -196,6 +212,9 @@ export const fixtures = {
// FileUploadField acts as a file manager for files already in session state.
// Actual uploading is handled by CDP via FileUploadPageController.
[ComponentType.FileUploadField]: {
jsLevel: 2,
jsNotice:
'This component is progressively enhanced. File uploads work without JavaScript using standard form submission. With JavaScript enabled, users get real-time upload progress.',
variants: [
{
label: 'No files uploaded',
Expand Down Expand Up @@ -260,6 +279,7 @@ export const fixtures = {
]
},
[ComponentType.Html]: {
jsLevel: 3,
def: {
type: ComponentType.Html,
name: 'info',
Expand All @@ -271,6 +291,7 @@ export const fixtures = {
payload: {}
},
[ComponentType.InsetText]: {
jsLevel: 3,
def: {
type: ComponentType.InsetText,
name: 'notice',
Expand All @@ -282,6 +303,7 @@ export const fixtures = {
payload: {}
},
[ComponentType.Details]: {
jsLevel: 3,
def: {
type: ComponentType.Details,
name: 'help',
Expand All @@ -293,6 +315,7 @@ export const fixtures = {
payload: {}
},
[ComponentType.Markdown]: {
jsLevel: 3,
def: {
type: ComponentType.Markdown,
name: 'guidance',
Expand All @@ -304,6 +327,7 @@ export const fixtures = {
payload: {}
},
[ComponentType.List]: {
jsLevel: 3,
def: {
type: ComponentType.List,
name: 'steps',
Expand All @@ -315,6 +339,7 @@ export const fixtures = {
payload: {}
},
[ComponentType.HiddenField]: {
jsLevel: 3,
def: {
type: ComponentType.HiddenField,
name: 'ref',
Expand All @@ -325,6 +350,10 @@ export const fixtures = {
payload: {}
},
[ComponentType.LatLongField]: {
jsLevel: 2,
jsNotice:
'This component is progressively enhanced. The coordinate fields work without JavaScript. With JavaScript enabled, an interactive map lets users click to set their location.',
previewSuffix: 'Map appears here with JavaScript enabled',
def: {
type: ComponentType.LatLongField,
name: 'location',
Expand All @@ -333,10 +362,13 @@ export const fixtures = {
schema: {}
},
model: null,
payload: {},
mapPlaceholder: true
payload: {}
},
[ComponentType.EastingNorthingField]: {
jsLevel: 2,
jsNotice:
'This component is progressively enhanced. The coordinate fields work without JavaScript. With JavaScript enabled, an interactive map lets users click to set their location.',
previewSuffix: 'Map appears here with JavaScript enabled',
def: {
type: ComponentType.EastingNorthingField,
name: 'location',
Expand All @@ -345,43 +377,53 @@ export const fixtures = {
schema: {}
},
model: null,
payload: {},
mapPlaceholder: true
payload: {}
},
[ComponentType.OsGridRefField]: {
jsLevel: 2,
jsNotice:
'This component is progressively enhanced. The OS grid reference field works without JavaScript. With JavaScript enabled, an interactive map lets users click to set their location.',
previewSuffix: 'Map appears here with JavaScript enabled',
def: {
type: ComponentType.OsGridRefField,
name: 'location',
title: 'Enter an OS grid reference',
options: {}
},
model: null,
payload: {},
mapPlaceholder: true
payload: {}
},
[ComponentType.NationalGridFieldNumberField]: {
jsLevel: 2,
jsNotice:
'This component is progressively enhanced. The national grid reference field works without JavaScript. With JavaScript enabled, an interactive map lets users click to set their location.',
previewSuffix: 'Map appears here with JavaScript enabled',
def: {
type: ComponentType.NationalGridFieldNumberField,
name: 'location',
title: 'Enter a national grid reference',
options: {}
},
model: null,
payload: {},
mapPlaceholder: true
payload: {}
},
[ComponentType.GeospatialField]: {
jsLevel: 1,
jsNotice: [
'A multiline text input that accepts raw GeoJSON is available as a fallback when JavaScript is unavailable, but this is not a recommended user journey. This component has a hard client-side JavaScript requirement. If JavaScript availability is a concern, use a progressively enhanced component instead.',
'We recommend using the <a className="govuk-link" href="https://submit-form-to-defra.service.gov.uk/form/preview/draft/geospatial-pattern/site-information">map question pattern</a> when asking users to select or draw locations on a map. This pattern provides alternatives so users who cannot use maps are not excluded.'
],
def: {
type: ComponentType.GeospatialField,
name: 'location',
title: 'Enter a location',
options: {}
},
model: null,
payload: {},
mapPlaceholder: true
payload: {}
},
[ComponentType.PaymentField]: {
jsLevel: 3,
variants: [
{
label: 'Before payment',
Expand Down Expand Up @@ -432,5 +474,24 @@ export const fixtures = {
* @typedef {import('~/src/server/plugins/engine/types.js').FormPayload} FormPayload
* @typedef {{ def: ComponentDef, model: Partial<FormModel>|null, payload: FormPayload }} FixtureRender
* @typedef {{ label: string } & FixtureRender} FixtureVariant
* @typedef {{ mapPlaceholder?: boolean } & (FixtureRender | { variants: FixtureVariant[] })} Fixture
* @typedef {{ jsLevel: 1|2|3, jsNotice?: string | string[], previewSuffix?: string } & (FixtureRender | { variants: FixtureVariant[] })} Fixture
*
* jsLevel describes the component's JavaScript dependency:
* 1 — hard JS requirement, cannot be statically rendered (e.g. map). Docs show a jsNotice only.
* 2 — progressively enhanced, works without JS but degrades. Docs show a jsNotice + static preview.
* 3 — no meaningful JS dependency beyond what GOV.UK Frontend already provides. Docs show a static preview only.
*
* jsNotice — HTML/JSX string or array of strings explaining the JS dependency (required for levels 1
* and 2). Each string is wrapped in a <p className="govuk-body">. Use <a className="govuk-link">
* for links. previewSuffix is plain text (markdown context).
*
* previewSuffix — optional text appended below the static preview as a placeholder, used to
* indicate where a JS-rendered element (e.g. a map) would appear in a live environment.
*
* def — the component definition passed to the form engine to render the preview.
* model — partial FormModel state; null if no model context is needed.
* payload — form submission payload used to pre-populate the component.
*
* variants — alternative to a single render: an array of labelled def/model/payload sets,
* each rendered as a separate tab in the preview.
*/
Loading
Loading