x-govuk · frankieroberto · Dec 8, 2023 · Dec 1, 2023 · Dec 1, 2023 · Dec 1, 2023
diff --git a/README.md b/README.md
@@ -1,129 +1,3 @@
 # GOV.UK Prototype Components · [![test](https://github.com/x-govuk/govuk-prototype-components/actions/workflows/test.yml/badge.svg)](https://github.com/x-govuk/govuk-prototype-components/actions/workflows/test.yml)
 
-GOV.UK Prototype Components contains the code you need to use common or experimental components that are not yet in the GOV.UK Design System.
-
-These components are currently experimental and more research is needed to validate them.
-
-| Component | Description |
-| - | - |
-| [xGovukAutocomplete](https://x-govuk.github.io/govuk-prototype-components/autocomplete/) | Implements the [Accessible autocomplete pattern](https://github.com/alphagov/accessible-autocomplete) to enhance a fixed list of options provided by a `<select>` element. |
-| [xGovukMasthead](https://x-govuk.github.io/govuk-prototype-components/masthead/) | Implements the masthead component [used on many GOV.UK product pages](https://github.com/alphagov/product-page-example). |
-| [xGovukPrimaryNavigation](https://x-govuk.github.io/govuk-prototype-components/primary-navigation/) | Implements the primary navigation component used on the GOV.UK Design System website. |
-| [xGovukRelatedNavigation](https://x-govuk.github.io/govuk-prototype-components/related-navigation/) | Implements [related navigation component](https://components.publishing.service.gov.uk/component-guide/related_navigation) found in the `govuk_publishing_components` gem. |
-| [xGovukSubNavigation](https://x-govuk.github.io/govuk-prototype-components/sub-navigation/) | Implements the sub navigation component used on the GOV.UK Design System website. |
-
-Two JavaScript-only modules are also provided:
-
-| Module | Description |
-| - | - |
-| [Edge](https://x-govuk.github.io/govuk-prototype-components/edge/) | Define the edges of your prototype for research. |
-| [Warn on unsaved changes](https://x-govuk.github.io/govuk-prototype-components/warn-on-unsaved-changes/) | Warn users if they try to leave a page without saving changes to a form. |
-
-> [!NOTE]\
-> Prior to v1.0.0, this project included a collection of decorated form components. These can now be found in the [`govuk-decorated-components`](https://github.com/x-govuk/govuk-decorated-components) package.
-
-## Requirements
-
-Node.js v18 or later.
-
-## Installation
-
-```shell
-npm install @x-govuk/govuk-prototype-components
-```
-
-## Usage with the GOV.UK Prototype Kit
-
-GOV.UK Prototype Components are designed to work with the GOV.UK Prototype Kit.
-
-If you are using v13 or later of the kit, the components will be immediately available once you have installed the package, and can be [managed alongside other plugins in your prototype](https://prototype-kit.service.gov.uk/docs/install-and-use-plugins).
-
-## Advanced usage
-
-If you are using an earlier version of the GOV.UK Prototype Kit, or only want to install selected components, you can do so by following the instructions below.
-
-### CSS
-
-To import all the Sass rules from GOV.UK Prototype Components, add the following to your Sass file:
-
-```scss
-@import "node_modules/@x-govuk/govuk-prototype-components/x-govuk/all";
-```
-
-You can also import Sass rules for an individual component. For example, to import styles for the masthead component, add the following to your Sass file:
-
-```scss
-@import "node_modules/@x-govuk/govuk-prototype-components/x-govuk/components/masthead/masthead";
-```
-
-### JavaScript
-
-To import the JavaScript for the GOV.UK Prototype Components, you can either:
-
-* add the GOV.UK Prototype Components JavaScript file to your HTML
-* import the JavaScript using a bundler like [Webpack](https://webpack.js.org/)
-
-#### Add the JavaScript file to your HTML
-
-If you decide to add the JavaScript to your HTML, first either:
-
-* set up your routing so that requests for the JavaScript file are served from `node_modules/@x-govuk/govuk-prototype-components/x-govuk/all.js`
-* copy the `node_modules/@x-govuk/govuk-prototype-components/x-govuk/all.js` file into your application
-
-Then import the JavaScript file before the closing `</body>` tag of your HTML page or page template, and run the `initAll` function to initialise all the components.
-
-```html
-<body>
-  ...
-  <script src="<YOUR-APP>/<YOUR-JS-FILE>.js"></script>
-  <script>
-    window.GOVUKPrototypeComponents.initAll()
-  </script>
-</body>
-```
-
-#### Import JavaScript using ES modules
-
-If you decide to import using a bundler, use `import` to import all GOV.UK Prototype Components, then run the `initAll` function to initialise them:
-
-```js
-import { initAll } from '@x-govuk/govuk-prototype-components'
-
-initAll()
-```
-
-You can also import the JavaScript for an individual component. For example, to import the autocomplete component, add the following to your JavaScript file:
-
-```js
-import { Autocomplete } from '@x-govuk/govuk-prototype-components'
-
-const myAutocomplete = document.querySelector('#my-autocomplete')
-new Autocomplete(myAutocomplete).init()
-```
-
-#### Import JavaScript using Common JS
-
-If you’re using a bundler that uses CommonJS (like [Browserify](http://browserify.org/)), use `require`:
-
-```js
-const GOVUKPrototypeComponents = require('@x-govuk/govuk-prototype-components')
-
-GOVUKPrototypeComponents.initAll()
-```
-
-It is not possible to import individual components using CommonJS.
-
-## Contribute
-
-The project repository is public and anyone can contribute.
-
-[View this project on GitHub](https://github.com/x-govuk/govuk-prototype-components).
-
-## Releasing a new version
-
-`npm run release`
-
-This command will ask you what version you want to use. It will then publish a new version on NPM, create and push a new git tag and then generate release notes ready for posting on GitHub.
-
-> ![NOTE]
-> Releasing a new version requires permission to publish packages to the `@x-govuk` organisation.
+See [GOV.UK Prototype Components documentation](https://x-govuk.github.io/govuk-prototype-components/).
diff --git a/docs/_components/example/_example.scss b/docs/_components/example/_example.scss
@@ -0,0 +1,25 @@
+.app-example__frame {
+  background: govuk-colour("white");
+  border: 0;
+  border-right: 1px solid $govuk-border-colour;
+  display: block;
+  max-width: 100%;
+  width: 100%;
+}
+
+.app-example__new-window {
+  @include govuk-font($size: 16);
+}
+
+.app-example__tabs {
+  .govuk-tabs__panel#preview {
+    padding: 0;
+    padding-right: 1px;
+  }
+}
+
+.app-example__toolbar {
+  background: $govuk-body-background-colour;
+  border-top: 1px solid $govuk-border-colour;
+  padding: govuk-spacing(2);
+}
diff --git a/docs/_components/example/macro.njk b/docs/_components/example/macro.njk
@@ -0,0 +1,3 @@
+{% macro appExample(params) %}
+  {%- include "./template.njk" -%}
+{% endmacro %}
diff --git a/docs/_components/example/template.njk b/docs/_components/example/template.njk
@@ -0,0 +1,32 @@
+{% from "govuk/components/tabs/macro.njk" import govukTabs %}
+
+{%- set nunjucksHtml %}
+
+```js
+{{ getNunjucksCode(params.component) }}
+```
+{% endset %}
+
+{%- set previewHtml -%}
+<iframe class="app-example__frame" data-module="app-example-frame" src="/examples/{{ params.component }}"></iframe>
+<p class="app-example__toolbar">
+  <a class="app-example__new-window" href="/examples/{{ params.component }}" target="_blank">Open this example in a new tab</a>
+</p>
+{%- endset %}
+
+{{ govukTabs({
+  classes: "app-example__tabs",
+  items: [{
+    label: "Preview",
+    id: "preview",
+    panel: {
+      html: previewHtml
+    }
+  }, {
+    label: "Nunjucks",
+    id: "nunjucks",
+    panel: {
+      html: nunjucksHtml
+    }
+  }]
+}) }}
diff --git a/docs/_layouts/example.njk b/docs/_layouts/example.njk
@@ -0,0 +1,18 @@
+{% extends "layouts/base.njk" %}
+{% from "x-govuk/components/autocomplete/macro.njk" import xGovukAutocomplete %}
+
+{% block header %}{% endblock %}
+
+{% block content %}
+  {{ content }}
+{% endblock %}
+
+{% block scripts %}
+  <script src="/assets/iframeResizer.contentWindow.js"></script>
+  <script src="/assets/x-govuk/all.js"></script>
+  <script>
+    window.GOVUKPrototypeComponents.initAll()
+  </script>
+{% endblock %}
+
+{% block footer %}{% endblock %}
diff --git a/docs/_layouts/product.njk b/docs/_layouts/product.njk
@@ -0,0 +1 @@
+{% extends "layouts/product.njk" %}
diff --git a/docs/_layouts/sub-navigation.njk b/docs/_layouts/sub-navigation.njk
@@ -0,0 +1,8 @@
+{% extends "layouts/sub-navigation.njk" %}
+
+{% block scripts %}
+  <script src="/assets/iframeResizer.js"></script>
+  <script>
+    iFrameResize({ log: true }, `[data-module="app-example-frame"]`)
+  </script>
+{% endblock %}
diff --git a/x-govuk/components/autocomplete/README.md → docs/autocomplete.md b/x-govuk/components/autocomplete/README.md → docs/autocomplete.md
@@ -1,52 +1,18 @@
-# Autocomplete
+---
+title: Autocomplete
+layout: sub-navigation
+order: 1
+---
 
 The autocomplete component implements the [Accessible autocomplete pattern](https://github.com/alphagov/accessible-autocomplete) to enhance a fixed list of options provided by a `<select>` element.
 
 This component may be useful if you want users to pick from a number of options. Unlike an autosuggest component, this component will only allow users to choose from a predetermined list of options.
 
-## Example usage
-
-```njk
-{{ xGovukAutocomplete({
-  id: "country",
-  name: "country",
-  allowEmpty: false,
-  label: {
-    classes: "govuk-label--l",
-    isPageHeading: true,
-    text: "Pick a country"
-  },
-  items: [
-    { text: "Austria" },
-    { text: "Belgium" },
-    { text: "Bulgaria" },
-    { text: "Croatia" },
-    { text: "Republic of Cyprus" },
-    { text: "Czech Republic" },
-    { text: "Denmark" },
-    { text: "Estonia" },
-    { text: "Finland" },
-    { text: "France" },
-    { text: "Germany" },
-    { text: "Greece" },
-    { text: "Hungary" },
-    { text: "Ireland" },
-    { text: "Italy" },
-    { text: "Latvia" },
-    { text: "Lithuania" },
-    { text: "Luxembourg" },
-    { text: "Malta" },
-    { text: "Netherlands" },
-    { text: "Poland" },
-    { text: "Portugal" },
-    { text: "Romania" },
-    { text: "Slovakia" },
-    { text: "Slovenia" },
-    { text: "Spain" },
-    { text: "Sweden" }
-  ]
+{% from "example/macro.njk" import appExample %}
+
+{{ appExample({
+  component: "autocomplete"
 }) }}
-```
 
 ## Component options
 

diff --git a/x-govuk/components/edge/README.md → docs/edge.md b/x-govuk/components/edge/README.md → docs/edge.md
@@ -1,4 +1,8 @@
-# Edge
+---
+title: Edge
+layout: sub-navigation
+order: 2
+---
 
 A javascript component to make it easy to define the edges of your prototype for research.
 

diff --git a/docs/examples/autocomplete.njk b/docs/examples/autocomplete.njk
@@ -0,0 +1,46 @@
+---
+title: Autocomplete example
+layout: example.njk
+eleventyExcludeFromCollections: true
+---
+{% from "x-govuk/components/autocomplete/macro.njk" import xGovukAutocomplete %}
+
+{{ xGovukAutocomplete({
+  id: "country",
+  name: "country",
+  allowEmpty: false,
+  label: {
+    classes: "govuk-label--l",
+    isPageHeading: true,
+    text: "Pick a country"
+  },
+  items: [
+    { text: "Austria" },
+    { text: "Belgium" },
+    { text: "Bulgaria" },
+    { text: "Croatia" },
+    { text: "Republic of Cyprus" },
+    { text: "Czech Republic" },
+    { text: "Denmark" },
+    { text: "Estonia" },
+    { text: "Finland" },
+    { text: "France" },
+    { text: "Germany" },
+    { text: "Greece" },
+    { text: "Hungary" },
+    { text: "Ireland" },
+    { text: "Italy" },
+    { text: "Latvia" },
+    { text: "Lithuania" },
+    { text: "Luxembourg" },
+    { text: "Malta" },
+    { text: "Netherlands" },
+    { text: "Poland" },
+    { text: "Portugal" },
+    { text: "Romania" },
+    { text: "Slovakia" },
+    { text: "Slovenia" },
+    { text: "Spain" },
+    { text: "Sweden" }
+  ]
+}) }}
diff --git a/docs/examples/masthead.njk b/docs/examples/masthead.njk
@@ -0,0 +1,28 @@
+---
+title: Masthead example
+layout: example.njk
+eleventyExcludeFromCollections: true
+---
+{% from "x-govuk/components/masthead/macro.njk" import xGovukMasthead %}
+
+{{ xGovukMasthead({
+  classes: "x-govuk-masthead--large",
+  phaseBanner: {
+    text: "This is a new service"
+  },
+  breadcrumbs: {
+    items: [{
+      href: "/",
+      text: "Home"
+    }]
+  },
+  title: {
+    text: "Design your service using GOV.UK styles, components and patterns"
+  },
+  description: {
+    text: "Use this design system to make your service consistent with GOV.UK. Learn from the research and experience of other service teams and avoid repeating work that’s already been done."
+  },
+  startButton: {
+    href: "/get-started/"
+  }
+}) }}
diff --git a/docs/examples/primary-navigation.njk b/docs/examples/primary-navigation.njk
@@ -0,0 +1,17 @@
+---
+title: Primary navigation
+layout: example.njk
+eleventyExcludeFromCollections: true
+---
+{% from "x-govuk/components/primary-navigation/macro.njk" import xGovukPrimaryNavigation %}
+
+{{ xGovukPrimaryNavigation({
+  visuallyHiddenTitle: "Navigation",
+  items: [{
+    text: "About this project",
+    href: "#"
+  }, {
+    text: "Contact us",
+    href: "#"
+  }]
+}) }}