@communitiesuk/svelte-component-library 0.1.17 → 0.2.0-alpha.2

package/README.md

@@ -1,69 +1,92 @@
-# Quick Start Installation
+# MHCLG Svelte Component Library
 
-Because this package is currently privately published to the GitHub npm package registry, you'll need to log in to the package registry before you can install the package. To log in you'll need your GitHub username and a personal access token with the correct permissions.
+A comprehensive component library for government digital services, built with Svelte 5 and following GOV.UK Design System principles.
 
-## 1. To get your personal access token on GitHub, follow these steps:
+## Prerequisites
 
-1.  **Log in to GitHub**: Go to your GitHub account.
-2.  **Navigate to Developer Settings**:
-    *   Click on your profile photo in the upper-right corner of the page.
-    *   Select Settings.
-    *   In the left sidebar, click Developer settings.
-3.  **Access Personal Access Tokens**:
-    *   Under the Personal access tokens section in the sidebar, click either Tokens (classic) or Fine-grained tokens, depending on your preference.
-4.  **Generate a New Token**:
-    *   Click Generate new token (for classic tokens, select Generate new token (classic)).
-    *   Provide a descriptive name in the "Note" field.
-    *   Set an expiration date if needed.
-    *   Choose the required scopes or permissions for the token. For installing the package, we will need "write:packages" (Upload packages to GitHub Package Registry), "read:packages" (Download packages from GitHub Package Registry) and "repo".
+This component library is designed for use with:
 
-5.  **Generate and Save the Token**:
-    *   Click Generate token.
-    *   Optionally, copy the new token to your clipboard for immediate use. Make sure to save it securely, as you won’t be able to view it again.
+- **SvelteKit projects** - The components are built for SvelteKit applications
 
-## 2. Next, you will need to add the GitHub registry path to the npm config file `.npmrc` so that npm knows to look for the package we want to authenticate for within the GitHub registry rather than the npm website.
+- **Svelte 5** - Components use the latest Svelte 5 syntax and runes
 
-1.  Add this line to the `.npmrc` file: `@communitiesuk:registry=https://npm.pkg.github.com`
+## Documentation and Examples
 
-## 3. Now we can log in:
+Visit our [component library documentation](https://communitiesuk.github.io/mhclg_svelte_component_library/) for:
 
-1.  Enter the following command into the terminal:
-    ```bash
-    npm login --scope=@communitiesuk --auth-type=legacy --registry=https://npm.pkg.github.com
-    ```
-2.  Enter your GitHub username, followed by the PAT token we obtained in the previous step as the password. When copying the token into the terminal, it may not be visible. Press the "Enter" key regardless and it should submit.
+- Interactive component examples
+- API documentation
+- Usage patterns and best practices
+- Installation guides
 
-> Username: USERNAME
-> Password: TOKEN
+## Quick Start Installation
 
-More information about the GitHub npm registry can be found here: [https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-npm-registry](https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-npm-registry)
+The package is publicly available on npm:
 
-## 4. Now you are logged in, you can install the package:
+```bash
+npm install @communitiesuk/svelte-component-library@latest
+```
+
+## Usage
+
+### GOV.UK Frontend Styles
+
+To ensure GOV.UK styles are applied correctly, add this script tag to your `app.html` file in the body section:
+
+```html
+<script>
+  document.body.className +=
+    " js-enabled" +
+    ("noModule" in HTMLScriptElement.prototype
+      ? " govuk-frontend-supported"
+      : "");
+</script>
+```
 
-1.  Enter the npm install command for this package, using the latest version. The package should start installing.
+This is required because the GOV.UK Frontend CSS checks the document body for JavaScript availability to progressively enhance components.
 
-To import a component from the newly installed package, you can add an import statement in the following structure to your Svelte page file:
+### GOV.UK Rebranded Styles (Optional)
+
+To use the refreshed GOV.UK brand (launched June 2025), add the `govuk-template--rebranded` class to your `app.html` body element:
+
+```html
+<body class="govuk-template--rebranded">
+  <!-- Your app content -->
+</body>
+```
+
+**When to use rebrand:**
+
+- **Global CSS styles**: The `govuk-template--rebranded` class on `<body>` automatically applies rebranded styles to all components
+- **Component markup**: Some components (like Footer and Header) have a `rebrand` prop that controls whether they show additional rebranded markup elements (like the crown logo). The rebrand prop is set to true by default on all relavent componets - you can specify false should you want to keep the old markup and assets.
+- **Assets**: Rebranded components will use updated assets (logos, icons) from the `/assets/rebrand/` folder
+
+**Example with rebranded Footer:**
 
 ```javascript
-import { InternalHeader, NotificationBanner, WarningText, SearchAutocomplete, Accordion} from "@communitiesuk/svelte-component-library";
+import { Footer } from "@communitiesuk/svelte-component-library";
+
+// Use rebrand=true to show the crown logo at top of footer
+<Footer rebrand={true} />;
 ```
 
-See the documentation app for examples of how to use the imported components.
+### Importing Components
 
-2. To make sure govuk styles are applied correctly add this script tag to the app.html body tag section:
+Import components directly from the package:
 
 ```javascript
-<script>
-    document.body.className +=
-        " js-enabled" +
-        ("noModule" in HTMLScriptElement.prototype
-        ? " govuk-frontend-supported"
-        : "");
-</script>
+import {
+  InternalHeader,
+  NotificationBanner,
+  WarningText,
+  SearchAutocomplete,
+  Accordion,
+} from "@communitiesuk/svelte-component-library";
 ```
+
 # Releasing a new version of the Svelte Component Library
 
-This guide outlines the steps to bump the version of your package, tag the release in Git, and push it to prepare for publishing.
+This guide outlines the steps to bump the version of your package, tag the release in Git, and publish to npm.
 
 ## 1. Commit Your Changes
 
@@ -80,75 +103,80 @@ Make sure you are on your main development branch you want to release (e.g., `ma
 
 Use the `npm version` command to update `package.json` and `package-lock.json`, create a commit, and create an annotated Git tag. Choose **one** of the following based on [Semantic Versioning (SemVer)](https://semver.org/):
 
-*   **Patch Release (Bug fixes, tiny changes - e.g., 0.1.8 -> 0.1.9):**
-    ```bash
-    npm version patch
-    ```
-*   **Minor Release (New features, backward-compatible - e.g., 0.1.8 -> 0.2.0):**
-    ```bash
-    npm version minor
-    ```
-*   **Major Release (Breaking changes - e.g., 0.1.8 -> 1.0.0):**
-    ```bash
-    npm version major
-    ```
-*   **Specific Version:**
-    ```bash
-    npm version <new-version> # Replace <new-version> with the desired version, e.g., 1.2.3
-    ```
+- **Patch Release (Bug fixes, tiny changes - e.g., 1.0.0 → 1.0.1):**
 
-## 3. Push Changes and Tags
+  ```bash
+  npm version patch
+  ```
 
-Push the commit and the new tag created by `npm version` to your remote Git repository (e.g., GitHub):
+- **Minor Release (New features, backwards compatible - e.g., 1.0.0 → 1.1.0):**
 
-```bash
-git push && git push --tags
-```
+  ```bash
+  npm version minor
+  ```
 
-*   `git push`: Pushes the version commit.
-*   `git push --tags`: Pushes the newly created version tag.
+- **Major Release (Breaking changes - e.g., 1.0.0 → 2.0.0):**
+  ```bash
+  npm version major
+  ```
 
-## 4. Publishing (Automatic via GitHub Actions)
+This command will:
 
-Now the tag has been pushed, we can create a release on GitHub to trigger the GitHub Actions workflow defined in `.github/workflows/npm-publish-github-packages.yml`, which will handle the actual `npm publish` step to GitHub Packages.
+- Update the version number in `package.json` and `package-lock.json`
+- Create a new commit with the version bump
+- Create a Git tag with the new version number
 
-Click on "create new release" from the repo homepage.
+## 3. Push Changes and Tags
 
-Choose the target branch that you want to release (e.g. main).
+Push the commit and the new tag created by `npm version` to the remote Git repository (e.g., GitHub):
 
-Choose the tag version pushed to GitHub in a previous step.
+```bash
+git push && git push --tags
+```
 
-Click generate release notes, and add any additional write-up to describe the changes in this release.
+- `git push`: Pushes the version commit.
+- `git push --tags`: Pushes the newly created version tag.
 
-Amend the release title to something appropriate, including the version number in the title.
+## 4. Create a GitHub Release
 
-Click "Set as pre-release" given the package is not stable yet.
+1. Go to the GitHub repository
+2. Click on "Releases" in the right sidebar
+3. Click "Create a new release"
+4. Select the tag you just created (e.g., `v1.0.1`)
+5. Add a release title and description
+6. Click "Publish release"
 
-Click the publish release button.
+## 5. Automatic Publishing
 
-If you now go to the "Actions" tab in the repo's horizontal nav bar, you'll see the publish workflow being triggered. Once complete, the package will be uploaded and the new version can be installed.
+Once you create the GitHub release, If you now go to the "Actions" tab in the repo's horizontal nav bar, you'll see the publish workflow being triggered. The GitHub Actions workflow (`.github/workflows/npm-publish.yml`) will automatically:
 
-# create-svelte
+- Build the package
+- Publish it to npm public registry
+- Make it available for installation via `npm install @communitiesuk/svelte-component-library`
 
-Everything you need to build a Svelte library, powered by [`create-svelte`](https://github.com/sveltejs/kit/tree/main/packages/create-svelte).
+## 6. Verify the Release
 
-Read more about creating a library [in the docs](https://svelte.dev/docs/kit/packaging).
+After the GitHub Action completes, verify that your package was published successfully:
 
-## Creating a project
+1. Check the [npm package page](https://www.npmjs.com/package/@communitiesuk/svelte-component-library)
+2. Try installing the new version in a test project:
+   ```bash
+   npm install @communitiesuk/svelte-component-library@latest
+   ```
 
-If you're seeing this, you've probably already done this step. Congrats!
+## Notes
 
-```bash
-# create a new project in the current directory
-npx sv create
+- Only create releases from the "main" branch to ensure stability
+- Always test changes thoroughly before creating a release
+- Consider creating pre-release versions for testing: `npm version prerelease --preid=alpha`
 
-# create a new project in my-app
-npx sv create my-app
-```
+# Developing and Building Commands
+
+This project is built with [`create-svelte`](https://github.com/sveltejs/kit/tree/main/packages/create-svelte). Read more about creating a library [in the docs](https://svelte.dev/docs/kit/packaging).
 
 ## Developing
 
-Once you've created a project and installed dependencies with `npm install` (or `pnpm install` or `yarn`), start a development server:
+Start a development server:
 
 ```bash
 npm run dev
@@ -176,13 +204,3 @@ npm run build
 You can preview the production build with `npm run preview`.
 
 > To deploy your app, you may need to install an [adapter](https://svelte.dev/docs/kit/adapters) for your target environment.
-
-## Publishing
-
-Go into the `package.json` and give your package the desired name through the `"name"` option. Also, consider adding a `"license"` field and point it to a `LICENSE` file which you can create from a template (one popular option is the [MIT license](https://opensource.org/license/mit/)).
-
-To publish your library to [npm](https://www.npmjs.com):
-
-```bash
-npm publish
-```

package/dist/assets/css/base.css

@@ -0,0 +1,9 @@
+@layer base {
+  .link-to-other-page {
+    @apply underline underline-offset-4;
+  }
+
+  .g-top-level-container {
+    @apply w-full lg:w-3/4 max-w-3xl mx-auto my-10 px-5;
+  }
+}

package/dist/assets/css/code-block.css

@@ -0,0 +1,116 @@
+/* Code block styles */
+.code-block {
+  background: var(--sk-bg-2);
+  border: 1px solid var(--sk-border);
+  border-radius: var(--sk-border-radius);
+  margin: 0px;
+  position: relative;
+}
+
+.code-block pre {
+  box-sizing: border-box;
+  color: var(--shiki-color-text);
+  border-radius: var(--sk-border-radius);
+  width: 100%;
+  margin: 0;
+  padding: 0.2rem 0.3rem;
+  position: relative;
+  overflow-x: auto;
+  white-space: pre-wrap; /* Wraps long lines */
+  word-break: break-word; /* Prevents breaking words unnecessarily */
+  overflow-x: auto;
+}
+
+.code-block pre code {
+  background: 0 0;
+  width: 100%;
+  margin: 0;
+  padding: 0;
+  display: block;
+  top: 0;
+}
+
+.code-block .controls {
+  --height: 3.6rem;
+  height: var(--height);
+  z-index: 2;
+  box-sizing: border-box;
+  justify-content: end;
+  align-items: center;
+  gap: 0.5rem;
+  padding: 0.3rem 0.5rem;
+  display: flex;
+  position: absolute;
+  top: 0;
+  right: 0;
+}
+
+.code-block .controls:has(.filename) {
+  background: var(--sk-bg-3);
+  padding-left: 1rem;
+  position: relative;
+}
+
+.code-block .controls:not(:has(.filename)) {
+  background: inherit;
+}
+
+.code-block .controls .filename {
+  content: attr(data-file);
+  font: var(--sk-font-ui-small);
+  color: var(--sk-fg-3);
+  text-overflow: ellipsis;
+  white-space: nowrap;
+  flex: 1;
+  display: block;
+  position: relative;
+  top: 0.1rem;
+  overflow: hidden;
+}
+
+.code-block .controls .filename:after {
+  content: attr(data-ext);
+}
+
+.controls .copy-to-clipboard {
+  height: calc(var(--height) - 1rem);
+  aspect-ratio: 1;
+  border-radius: var(--sk-border-radius);
+  position: relative;
+}
+
+.code-block .controls .copy-to-clipboard[disabled] {
+  opacity: 1;
+}
+
+.code-block .controls .copy-to-clipboard:before,
+.code-block .controls .copy-to-clipboard:after {
+  content: "";
+  background: 50%/1.6rem 1.6rem no-repeat;
+  width: 100%;
+  height: 100%;
+  transition: opacity 0.2s 0.6s;
+  display: block;
+  position: absolute;
+  top: 0;
+  left: 0;
+}
+
+.code-block .controls .copy-to-clipboard:before {
+  background-image: url("data:image/svg+xml,%3csvg%20xmlns='http://www.w3.org/2000/svg'%20viewBox='0%200%2024%2024'%3e%3crect%20width='11.2'%20height='14'%20x='7.9'%20y='3'%20rx='1.5'%20ry='1.5'%20style='fill:none;stroke:%23000000e0;stroke-miterlimit:10;stroke-width:1.5px'/%3e%3cpath%20d='M4%207v12.5c0%20.8.7%201.5%201.5%201.5h10'%20style='fill:none;stroke:%23000000e0;stroke-miterlimit:10;stroke-width:1.5px;stroke-linecap:round'/%3e%3c/svg%3e");
+}
+
+.code-block .controls .copy-to-clipboard:after {
+  opacity: 0;
+  background-image: url("data:image/svg+xml,%3csvg%20height='24'%20viewBox='0%200%2024%2024'%20width='24'%20xmlns='http://www.w3.org/2000/svg'%3e%3cpath%20d='m21%207-12%2012-5.5-5.5%201.41-1.41%204.09%204.08%2010.59-10.58z'%20fill='%23000000e0'/%3e%3c/svg%3e");
+}
+
+.code-block .controls .copy-to-clipboard:active:before {
+  opacity: 0;
+  transition: none;
+}
+
+.code-block .controls .copy-to-clipboard:active:after {
+  opacity: 1;
+  transition: none;
+}

package/dist/assets/css/components.css

@@ -0,0 +1,47 @@
+@layer components {
+  [data-role="details-container"]
+    [data-role="component-information-array-container"] {
+    @apply flex flex-col gap-6;
+  }
+
+  [data-role="details-container"]
+    [data-role="component-information-detail-grid-container"] {
+    @apply grid grid-cols-[120px_auto] gap-x-6;
+  }
+
+  [data-role="details-container"]
+    [data-role="component-information-detail-grid-container"] {
+    dt {
+      @apply break-words hyphens-auto;
+    }
+  }
+
+  [data-role="details-container"]
+    [data-role="component-information-detail-grid-container"]
+    dd
+    p:first-of-type {
+    @apply mt-0;
+  }
+
+  [data-role="details-container"]
+    [data-role="component-information-detail-grid-container"]
+    dd
+    p:last-of-type {
+    @apply mb-0;
+  }
+
+  [data-role="examples-section"] {
+    @apply max-w-screen-lg my-0;
+  }
+  [data-role="demo-section"] {
+    @apply max-w-screen-lg mx-auto my-0;
+  }
+
+  [data-role="component-container"] {
+    @apply grid place-items-center;
+  }
+}
+
+[role="tabpanel"] {
+  @apply my-2 mx-0 p-0;
+}

package/dist/assets/css/fonts.css

@@ -0,0 +1,19 @@
+@font-face {
+  font-family: "GDS Transport";
+  font-style: normal;
+  font-weight: normal;
+  src:
+    url("/fonts/light-94a07e06a1-v2.woff2") format("woff2"),
+    url("/fonts/light-f591b13f7d-v2.woff") format("woff");
+  font-display: fallback;
+}
+
+@font-face {
+  font-family: "GDS Transport";
+  font-style: normal;
+  font-weight: bold;
+  src:
+    url("/fonts/bold-b542beb274-v2.woff2") format("woff2"),
+    url("/fonts/bold-affa96571d-v2.woff") format("woff");
+  font-display: fallback;
+}

package/dist/assets/css/govuk-additional.css

@@ -0,0 +1,142 @@
+:root {
+    /* Font families */
+    --sk-font-family-ui: "Fira Sans", -apple-system, sans-serif;
+    --sk-font-family-body: "GDS Transport", Georgia, serif;
+    --sk-font-family-heading: "DM Serif Display", Georgia, serif;
+    --sk-font-family-mono: "Fira Mono", monospace;
+  
+    /* Font sizes and line heights */
+    --sk-font-size-body: 1.8rem;
+    --sk-line-height-body: calc(1.5 * var(--sk-font-size-body));
+  
+    /* Colors */
+    --sk-fg-1: #141414;
+    --sk-fg-2: #262626;
+    --sk-fg-3: #666;
+    --sk-fg-4: gray;
+    --sk-fg-accent: #d43008;
+    --sk-bg-1: #fff;
+    --sk-bg-2: #fdfdfd;
+    --sk-bg-3: #fafafa;
+    --sk-bg-4: #f2f2f2;
+    --sk-border: #ebebeb;
+    --sk-scrollbar: #0000004d;
+    --sk-bg-selection: #42b4ff4d;
+  
+    /* Borders and spacing */
+    --sk-border-radius: .4rem;
+    --sk-page-padding-side: 1.6rem;
+  }
+  
+  /* Base styles */
+  * {
+   
+    scrollbar-width: thin;
+    scrollbar-color: var(--sk-scrollbar) transparent;
+  }
+  
+  ::selection {
+    background: var(--sk-bg-selection);
+}
+
+/* GDS Example frame styles */
+.app-example-wrapper {
+    margin-top: 20px;
+    margin-bottom: 20px;
+    border: 1px solid #b1b4b6;
+    border-top-width: 1px;
+    border-right-width: 1px;
+    border-bottom-width: 1px;
+    border-left-width: 1px;
+    border-top-style: solid;
+    border-right-style: solid;
+    border-bottom-style: solid;
+    border-left-style: solid;
+    border-top-color: rgb(177, 180, 182);
+    border-right-color: rgb(177, 180, 182);
+    border-bottom-color: rgb(177, 180, 182);
+    border-left-color: rgb(177, 180, 182);
+    border-image-source: initial;
+    border-image-slice: initial;
+    border-image-width: initial;
+    border-image-outset: initial;
+    border-image-repeat: initial;
+    /* border-top: 0; */
+    border-top-width: 1px;
+    /* border-top-style: initial;
+    border-top-color: initial; */
+  }
+  
+  .app-example {
+    position: relative;
+    font-size: 16px;
+    line-height: 1.25;
+    border-top: 1px solid #b1b4b6;
+    background: url("data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAoAAAAKCAYAAACNMs+9AAAAJUlEQVQoU2P88ePHfwY0wMHBwYguxjgUFKI7GsTH5m4M3w1ChQAZTSeO0/AZpgAAAABJRU5ErkJggg==") repeat;
+  }
+  
+  .app-example--tabs {
+    margin-bottom: 0;
+  }
+  
+  .app-example__toolbar {
+    padding: 10px;
+    border-bottom: 1px solid #b1b4b6;
+    background: #ffffff;
+  }
+  
+  .app-example__frame {
+    display: block;
+    width: 100%;
+    max-width: 100%;
+    border: 0;
+    border-right: 1px solid #b1b4b6;
+    background: #ffffff;
+  }
+  
+  /* Frame sizes */
+  .app-example__frame,
+  .app-example__frame--xs {
+    height: 150px;
+  }
+  
+  .app-example__frame--s {
+    height: 250px;
+  }
+  
+  .app-example__frame--m {
+    height: 350px;
+  }
+  
+  .app-example__frame--l {
+    height: 450px;
+  }
+  
+  .app-example__frame--xl {
+    height: 650px;
+  }
+  
+  .app-example__frame--resizable {
+    min-width: 230px;
+    min-height: 50px;
+    overflow: auto;
+    transform: translate3d(0, 0, 0);
+  }
+  
+  @media (min-width: 40.0625em) {
+    .app-example__frame--resizable {
+      resize: both;
+    }
+  }
+  
+  .app-example__code {
+    position: relative;
+  }
+  
+  /* Responsive margin utilities */
+  @media (min-width: 40.0625em) {
+    .app-example-wrapper {
+      margin-top: 40px;
+      margin-bottom: 40px;
+    }
+}