docs: page partials, client-side scripts, test files (#215)

# Changes

Adds missing docs on:

- Page partials
- Client-side scripts
- Component testing

# Associated issue

Resolves #71

# How to test

Review updated documentation.

# Checklist

- [x] I have performed a self-review of my own code
- [x] I have made sure that my PR is easy to review (not too big,
includes comments)
- [x] I have made updated relevant documentation files (in project
README, docs/, etc)
- ~~I have added a decision log entry if the change affects the
architecture or changes a significant technology~~
- [ ] I have notified a reviewer

<!-- Please strike through and check off all items that do not apply
(rather than removing them) -->

README.md

@@ -11,7 +11,6 @@
 - Provide functional interactivity without a JS framework (React, Vue, Svelte, etc)*.
 - Provide functional interactivity without specific styling ("unstyled")*.
 - Provide a fully accessible and highly performant baseline for every project.
-- Utilise testing to ensure quality and prevent regressions.
 
 \* We'll leave the choice for a JS framework and strategy for styling to developers using Head Start for their project.
 

docs/blocks-and-components.md

@@ -13,17 +13,23 @@ src/
 │   ├── Blocks.d.ts
 │   └── SomeContentBlock/
 │       ├── SomeContentBlock.astro
-│       └── SomeContentBlock.fragment.graphql
+│       ├── SomeContentBlock.fragment.graphql
+│       ├── SomeContentBlock.client.ts
+│       └── SomeContentBlock.test.ts
+│       
 └── components/
     └── SomeUiComponent/
-        └── SomeUiComponent.astro
+        ├── SomeUiComponent.astro
+│       ├── SomeContentBlock.client.ts
+│       └── SomeContentBlock.test.ts
 ```
 
 - [Components](https://docs.astro.build/en/core-concepts/astro-components/) are the UI elements the website is composed of. This can be Astro and framework specific components.
 - Blocks are a specific set of components which have a complementary content [Block](https://www.datocms.com/docs/content-modelling/blocks) in DatoCMS and therefore have a paired GraphQL Fragment file.
+- Optionally blocks and components have a complementary `*.client.ts` file for client-side scripts and a `*.test.ts` file for related unit tests.
 
 > [!NOTE]
-> You can use `npm run create:block` and `npm run:component` to quickly scaffold a new block or component with their associated files.
+> You can use `npm run create:block` and `npm run create:component` to quickly scaffold a new block or component with their associated files.
 
 See [CMS Data Loading](./cms-data-loading.md) for documentation on the use of GraphQL Fragment files.
 
@@ -107,3 +113,33 @@ export type AnyBlock =
   | SomeContentBlockFragment // and add it here (order A to Z)
   | TextBlockFragment;
 ```
+
+## Client-side scripts
+
+Astro supports [client-side scripts inside components](https://docs.astro.build/en/guides/client-side-scripts/#client-side-scripts). Head Start uses the convention to include these as external scripts for better TypeScript intellisense and linting. To distinguish server-side files (most in Astro) from client-side scripts we use a `.client.ts` extension. So blocks and components can include these as `<script src="./SomeComponent.client.ts"></script>`.
+
+## Testing components
+
+[Head Start provides a testing setup](./testing.md). This includes helpers to make component testing easier. Astro renders components to string. The `renderToFragment` helper allows you to test components as document fragments providing most familiar DOM methods like `.querySelector` and `.getAttribute`:
+
+```ts
+// SomeComponent.test.ts
+import { describe, expect, test } from 'vitest';
+import { renderToFragment } from '@lib/renderer';
+import SomeComponent, { type Props } from './SomeComponent.astro';
+
+describe('Some Component', () => {
+  const fragment = await renderToFragment<Props>(SomeComponent, {
+    someProp: 'some value',
+  });
+
+  test('uses some prop as attribute', () => {
+    const value = fragment.querySelector('.someSelector')?.getAttribute('some-attribute');
+    expect(value).toBe('some value');
+  });
+
+  // Add more tests here
+});
+```
+
+Note: test files must use the `.test.ts` extension to run.

docs/project-structure.md

@@ -24,6 +24,8 @@ Inside of this project, you'll see the following folders and files:
 │   │   └── SomeUiComponent.astro
 │   ├── layouts/
 │   │   └── Default.astro
+│   ├── lib/
+│   │   └── some-helper-function.ts
 │   └── pages/
 │       ├── api/
 |       |   └── some-dynamic-endpoint.ts
@@ -41,6 +43,7 @@ Inside of this project, you'll see the following folders and files:
   - `components/` - [Components](https://docs.astro.build/en/core-concepts/astro-components/) are the elements the website is composed of. This can be Astro and framework specific components.
   - `blocks/` - Blocks are a specific set of components which have a complementary content [Block](https://www.datocms.com/docs/content-modelling/blocks) in DatoCMS and therefore have a paired GraphQL fragment file.
   - `layouts/` - [Layouts](https://docs.astro.build/en/core-concepts/layouts/) are Astro components used to provide a reusable UI structure, such as a page template.
+  - `lib/` - Shared logic and utility helpers, like `datocms`, `i18n` and `routing`.
   - `assets/icons/` - SVG icons, can be used with `<Icon name={ basename }>` (See [`src/components/Icon/`](../src/components/Icon/)).
 - `public/` is for any static assets, like fonts and favicons, that should be available on the website as-is.
 - `config/` bundles all our configuration files (like DatoCMS migrations), so the project root doesn't become too cluttered.

docs/routing.md

@@ -34,6 +34,10 @@ Head Start leverages [Astro's Custom 404 Error page](https://docs.astro.build/en
 
 Astro supports [API routes](https://docs.astro.build/en/core-concepts/endpoints/#server-endpoints-api-routes) (server endpoints), which can be any route in `src/pages/`. Head Start uses a convention to place all API routes in `src/pages/api/`. This way it's clear where all API routes live, they have a logical URL prefix in the browser (`/api/`) and [API routes not found](../src/pages/api/[...notFound].ts) can be caught and respond with a 404 JSON response, rather than an HTML response.
 
+## Partial page routes
+
+Astro supports [Page Partials](https://docs.astro.build/en/basics/astro-pages/#page-partials) to fetch and use in conjuction with client-side scripts. As a convention Head Start uses a `.partial.astro` for these routes. An example is the [`search/results.partial.astro` route](../src/pages/[locale]/search/results.partial.astro).
+
 ## Redirects
 
 Head Start supports redirect rules which are editable and [sortable](https://www.datocms.com/docs/content-modelling/record-ordering) in the CMS. Head Start uses [`regexparam`](https://github.com/lukeed/regexparam) to handle redirect rules with static paths, (optional) parameters and (optional) wildcards. Examples:
@@ -43,3 +47,7 @@ Head Start supports redirect rules which are editable and [sortable](https://www
 - from `/path-with-wildcard/*` to `/new-path-with-wildcard/*` (or `/new-path-with-wildcard/:splat`)
 
 \* See [decision entry on redirects](./decision-log/2024-09-24-redirects-middleware.md) for motivation.
+
+## Cloudflare runtime
+
+Routes have access 

docs/upgrading.md

@@ -11,7 +11,7 @@ Did you start your project using Head Start as its template? You can still apply
 
 Since Head Start doesn't have formal versioning, the best changelog is the [list of changes (commits) on the `main` branch](https://github.com/voorhoede/head-start/commits/main/) on GitHub or from the command line in the repository (`git log main --oneline`):
 
-```bash
+```shell
 6790dba feature: upgrade Astro to v5 beta (#189)
 39298c5 feature: Remove background image when image is loaded (#185)
 822a3a2 test: Link Node, no trailing whitespace (#186)
@@ -30,13 +30,13 @@ Head Start uses a squash-and-merge strategy for pull requests. So the list shoul
 
 If you only need a single change, you can use a commit's patch file. For example if you select the commit ["feature: upgrade Astro to v5 beta" (`a622bd`)](https://github.com/voorhoede/head-start/commit/a622bd), you can add `.patch` to the URL to get its patch file: [`https://github.com/voorhoede/head-start/commit/a622bd.patch`](https://github.com/voorhoede/head-start/commit/a622bd.patch). Then you can apply the patch to your project from its repository:
 
-```bash
+```shell
 curl https://github.com/voorhoede/head-start/commit/a622bd.patch | git am
 ```
 
 Alternatively you can add Head Start as a secondary remote to your project's repository and use cherry picking to apply the change:
 
-```bash
+```shell
 git remote add head-start git@github.com:voorhoede/head-start.git
 git remote update
 
@@ -50,7 +50,7 @@ That's it. The original commit for the change is now applied to your project.
 
 If you want to apply a range of changes from Head Start to your own project, applying patches as described above is not an option. Instead you can use cherry picking for an entire range. For example when you want to apply all the changes made to Head Start after you've used it as a template for your own project. Note the commit SHA of the first and the last change of your range. Then add Head Start as a secondary remote to your project's repository and use cherry picking to apply the range of changes:
 
-```bash
+```shell
 git remote add head-start git@github.com:voorhoede/head-start.git
 git remote update
 
@@ -60,7 +60,7 @@ git cherry-pick --strategy recursive --strategy-option theirs 035a205^..a622bd
 
 If you encounter any merge conflicts along the way, resolve them as you normally do, then continue the cherry picking process:
 
-```bash
+```shell
 git cherry-pick --continue
 ```