Merge branch 'main-check-merge'

Author: ajhillman-ddj

.github/workflows/npm-publish-github-packages.yml

@@ -0,0 +1,36 @@
+# This workflow will run tests using node and then publish a package to GitHub Packages when a release is created
+# For more information see: https://docs.github.com/en/actions/publishing-packages/publishing-nodejs-packages
+
+name: Node.js Package
+
+on:
+  release:
+    types: [created]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+      - run: npm ci
+      # - run: npm test
+
+  publish-gpr:
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          registry-url: https://npm.pkg.github.com/
+      - run: npm ci
+      - run: npm publish
+        env:
+          NODE_AUTH_TOKEN: ${{secrets.GITHUB_TOKEN}}

.gitignore

@@ -20,3 +20,6 @@ Thumbs.db
 # Vite
 vite.config.js.timestamp-*
 vite.config.ts.timestamp-*
+
+*.mdc
+.github/*.md

.npmrc

@@ -1 +1,3 @@
 engine-strict=true
+@communitiesuk:registry=https://npm.pkg.github.com
+//npm.pkg.github.com/:_authToken=${NODE_AUTH_TOKEN}

README.md

@@ -1,3 +1,133 @@
+# Quick Start Installation
+
+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.
+
+## 1. To get your personal access token on GitHub, follow these steps:
+
+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".
+
+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.
+
+## 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.
+
+1.  Add this line to the `.npmrc` file: `@communitiesuk:registry=https://npm.pkg.github.com`
+
+## 3. Now we can log in:
+
+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.
+
+> Username: USERNAME
+> Password: TOKEN
+
+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)
+
+## 4. Now you are logged in, you can install the package:
+
+1.  Enter the npm install command for this package, using the latest version. The package should start installing.
+
+To import a component from the newly installed package, you can add an import statement in the following structure to your Svelte page file:
+
+```javascript
+import { InternalHeader, NotificationBanner, WarningText, SearchAutocomplete, Accordion} from "@communitiesuk/svelte-component-library";
+```
+
+See the documentation app for examples of how to use the imported components.
+
+2. To make sure govuk styles are applied correctly add this script tag to the app.html body tag section:
+
+```javascript
+<script>
+    document.body.className +=
+        " js-enabled" +
+        ("noModule" in HTMLScriptElement.prototype
+        ? " govuk-frontend-supported"
+        : "");
+</script>
+```
+# 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.
+
+## 1. Commit Your Changes
+
+Before versioning, ensure all your code changes are committed to Git:
+
+```bash
+git add .
+git commit -m "Your descriptive commit message"
+```
+
+Make sure you are on your main development branch you want to release (e.g., `main`).
+
+## 2. Bump the Package Version
+
+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
+    ```
+
+## 3. Push Changes and Tags
+
+Push the commit and the new tag created by `npm version` to your remote Git repository (e.g., GitHub):
+
+```bash
+git push && git push --tags
+```
+
+*   `git push`: Pushes the version commit.
+*   `git push --tags`: Pushes the newly created version tag.
+
+## 4. Publishing (Automatic via GitHub Actions)
+
+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.
+
+Click on "create new release" from the repo homepage.
+
+Choose the target branch that you want to release (e.g. main).
+
+Choose the tag version pushed to GitHub in a previous step.
+
+Click generate release notes, and add any additional write-up to describe the changes in this release.
+
+Amend the release title to something appropriate, including the version number in the title.
+
+Click "Set as pre-release" given the package is not stable yet.
+
+Click the publish release button.
+
+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.
+
 # create-svelte
 
 Everything you need to build a Svelte library, powered by [`create-svelte`](https://github.com/sveltejs/kit/tree/main/packages/create-svelte).
@@ -49,10 +179,10 @@ You can preview the production build with `npm run preview`.
 
 ## 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/)).
+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
-```
+```

docs/ResponsiveDesign.md

@@ -0,0 +1,88 @@
+# Introduction
+
+Plain HTML will work on any screen. Therefore, failure to display content properly on different screen sizes is generally caused by CSS.[^1]
+
+[^1]:[Responsive columns without media queries](https://medium.com/@hayavuk/responsive-columns-without-media-queries-1dd92dc0f5e6)
+
+# Breakpoints and media queries
+
+> Breakpoints should be content-based, not device based - *Kaloyan Kosev*[^1]
+
+> Start with the small screen first, then expand until it looks like s\*\*t. Time for a breakpoint! – *Stephen Hay*[^3]
+
+You don't want everything to scale proportionally. On larger screens, images can become very large, forcing other content off the screen[^4]. 
+
+It's common to use viewport width in media queries, but there are a large range of media features that can be detected (color, color index, aspect ratio, device aspect ratio, width, device width, height, device height, orientation, monochrome, resolution, scan, pixel-density, and more)[^3].
+
+There are several reasons not to use device pixel dimensions as breakpoints. One is that new devices are likely to have different dimensions, making the older ones abritrary[^3].  
+
+Sometimes a design needs to change significantly when the available space (or other parameter) renders it unsuitable. Other times, it might only be necessary to change one aspect. This is known as a minor breakpoint or a tweakpoint [^3]. 
+
+Developers are warned that highly complex media queries pose a danger: they can be difficult to manage long-term [^3].
+
+Older advice on the internet suggests that pixel-based media queries didn't function as expected when a user zoomed in. This issue is now outdated. However, it's still recommended to use em-based media queries because they will still function when a browser's font size isn't the default 16px [^1]
+
+It's recommended that lines of text aren't too short or long, ideally 45-90 characters. It's possible to achieve this with different font sizes by specifying font size and element width as a proportion of viewport width, and scaling them at the same rate [^3].
+
+Progressive enhancement is...
+Min-width is better suited to progressive enhancement than max-width, because styles are overridden at smaller screens, not larger ones[^5]
+
+[^1] [Journey to highly effective and maintainable CSS media queries](https://notes.devlabs.bg/journey-to-highly-effective-and-maintainable-css-media-queries-876e5b92f918)
+
+[^2] [7 habits of highly effective media queries](https://bradfrost.com/blog/post/7-habits-of-highly-effective-media-queries/)
+
+[^3] [Responsive web design](https://practicaltypography.com/responsive-web-design.html)
+
+[^4] [Responsive web design](https://alistapart.com/article/responsive-web-design/)
+
+[^5] [Avoiding common mistakes with CSS media queries](https://blog.pixelfreestudio.com/avoiding-common-mistakes-with-css-media-queries/)
+
+# Units
+
+Units are used to define the size of elements on a screen. Using appropriate units is important for ensuring designs scale properly on different screen sizes. 
+
+rem units are defined by the font size of the root element (16px by default).
+em units are defined by the font size of the parent element.
+
+Font sizes should be set using rem units; values in pixels won't scale properly if the browser's font size changes. By default, 1rem = 16px, so 1.5rem = 24px.
+
+Margins and padding should be set using em units. 
+
+When defining CSS width and height values, percentages are recommended (as a proportion of the parent element).
+
+Properties that don't need to be responsive (e.g. border-width) can be set using pixels.
+
+From: [Why CSS units matter to your responsive website designs](https://pieces.app/blog/css-units-responsive-website-designs)
+
+See also: [whatunit.com](https://whatunit.com/)
+
+# Interaction
+
+Touch targets should be large enough (Apple recomends 44x44 pixels[^1]) and should be sufficient spaced apart [^2]
+
+[^1] [A Hands-On Guide to Mobile-First Design](https://www.uxpin.com/studio/blog/a-hands-on-guide-to-mobile-first-design/)
+[^2] [Common Mobile Design Mistake on Your Website](https://conroycreativecounsel.com/avoid-these-common-mobile-design-mistakes-on-your-website/)
+
+# Progressive Enhancement
+
+# Common Pitfalls of Mobile-First
+
+> Porting an unchanged UI to a different platform hurts UX. - *NN Group*[^3]
+
+A one-size-fits-all approach might be appealing, but it's possible to focus on smaller screens *at the expense of* larger screens. Desktops are more 'robust' - they can handle more complexity.
+
+This involves dailing to 'flesh out' a design for screens that can handle it [^1]. This is known as 'mobile everything'[^2] or 'mobile-only'[^3]. 
+
+Consider a hamburger icon to find the links to toggle between views. On mobile, there might be insufficient space, but not so on desktop. Displaying these links permanently would reduce clicks from one to two [^2]. Futhermore, interactive elements like a hamburger icon might be easily noticed on a mobile screen, but overlooked on a large desktop screen [^3].
+
+Other examples include hiding functionality in drawers, using icons instead of/without text, and breaking content into several screens [^2].
+
+Research has found that navigation isn't used as frequently when it's hidden within a menu [^3].
+
+Some argue that the importance of consistency across devices is overestimated [^1].
+The context is different on different devices, so the interfaces should be adapted to suit the context [^1].
+Input differs across devices too, so design should be modified accordingly. Phones are typically used in portrait mode, and thumbs will be able to respond to functionality near the bottom. Tablets are often used with both hands, so there's greater scope for where interactive elements are placed. Desktop users have more fine-grained control, due to using a mouse or trackpad. Desktop users might expect key functionality to be positioned towards the top of the screen [^1].
+
+[^1] [Why is mobile-first design failing](https://jamesarcher.co/170/mobile-first-why-are-we-getting-it-wrong)
+[^3] [Mobile-first not mobile-only](https://www.nngroup.com/articles/mobile-first-not-mobile-only/)
+[^2] [Mobile first, desktop worst](https://blog.prototypr.io/mobile-first-desktop-worst-f900909ae9e2)