Add support for synced tabs (#640)

Co-authored-by: Chris Swithinbank <357379+delucis@users.noreply.github.com> Co-authored-by: Sarah Rainsberger <5098874+sarah11918@users.noreply.github.com> Co-authored-by: Chris Swithinbank <swithinbank@gmail.com>
withastro · Apr 30, 2024 · 7dc503e · 7dc503e
1 parent 61493e5
commit 7dc503e
Show file tree

Hide file tree

Showing 25 changed files with 627 additions and 247 deletions.
diff --git a/.changeset/config.json b/.changeset/config.json
@@ -9,7 +9,7 @@
   "access": "public",
   "baseBranch": "main",
   "updateInternalDependencies": "patch",
-  "ignore": ["starlight-docs", "@example/*", "starlight-file-icons-generator"],
+  "ignore": ["starlight-docs", "@example/*", "starlight-file-icons-generator", "@e2e/*"],
   "___experimentalUnsafeOptions_WILL_CHANGE_IN_PATCH": {
     "onlyUpdatePeerDependentsWhenOutOfRange": true
   }

diff --git a/.changeset/eight-pens-end.md b/.changeset/eight-pens-end.md
@@ -0,0 +1,5 @@
+---
+'@astrojs/starlight': minor
+---
+
+Adds support for syncing multiple sets of tabs on the same page.
diff --git a/.changeset/slimy-swans-teach.md b/.changeset/slimy-swans-teach.md
@@ -0,0 +1,13 @@
+---
+'@astrojs/starlight': minor
+---
+
+Updates the default `line-height` from `1.8` to `1.75`. This change avoids having a line height with a fractional part which can cause scripts accessing dimensions involving the line height to get an inconsistent rounded value in various browsers.
+
+If you want to preserve the previous `line-height`, you can add the following custom CSS to your site:
+
+```css
+:root {
+  --sl-line-height: 1.8;
+}
+```
diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
@@ -30,6 +30,20 @@ jobs:
       - name: Test packages
         run: pnpm -r test:coverage
 
+  e2e-test:
+    name: Run E2E tests
+    runs-on: ubuntu-20.04
+    steps:
+      - uses: actions/checkout@v4
+      - uses: pnpm/action-setup@v3
+      - uses: actions/setup-node@v4
+        with:
+          node-version: ${{ env.NODE_VERSION }}
+          cache: 'pnpm'
+      - run: pnpm i
+      - name: Test packages
+        run: pnpm -r test:e2e
+
   pa11y:
     name: Check for accessibility issues
     runs-on: ubuntu-20.04

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -187,6 +187,36 @@ pnpm test:coverage
 
 This will print a table to your terminal and also generate an HTML report you can load in a web browser by opening [`packages/starlight/__coverage__/index.html`](./packages/starlight/__coverage__/index.html).
 
+### End-to-end (E2E) tests
+
+Starlight also includes E2E tests in [`packages/starlight/__e2e__/`](./packages/starlight/__e2e__/), which are run using [Playwright][playwright].
+
+To run these tests, move into the Starlight package and then run `pnpm test:e2e`:
+
+```sh
+cd packages/starlight
+pnpm test:e2e
+```
+
+#### Test fixtures
+
+Each subdirectory of `packages/starlight/__e2e__/fixtures` should contain the basic files needed to run Starlight (`package.json`, `astro.config.mjs`, a content collection configuration in `src/content/config.ts` and some content to render in `src/content/docs/`).
+
+The `testFactory()` helper can be used in a test file to define the fixture which will be built and loaded in a preview server during a set of tests.
+
+```ts
+// packages/starlight/__e2e__/feature.test.ts
+import { testFactory } from './test-utils';
+
+const test = await testFactory('./fixtures/basics/');
+```
+
+This allows you to run tests against different combinations of Astro and Starlight configuration options for various content.
+
+#### When to add E2E tests?
+
+E2E are most useful for testing what happens on a page after it has been loaded by a browser. They run slower than unit tests so they should be used sparingly when unit tests aren’t sufficient.
+
 ## Translations
 
 Translations help make Starlight accessible to more people.
@@ -254,6 +284,7 @@ To add a language, you will need its BCP-47 tag and a label. See [“Adding a ne
 [gfi]: https://github.com/withastro/starlight/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22+
 [api-docs]: https://docs.astro.build/en/reference/integrations-reference/
 [vitest]: https://vitest.dev/
+[playwright]: https://playwright.dev/
 
 ## Showcase
 

diff --git a/docs/src/content/docs/getting-started.mdx b/docs/src/content/docs/getting-started.mdx
@@ -15,7 +15,7 @@ See the [manual setup instructions](/manual-setup/) to add Starlight to an exist
 
 Create a new Astro + Starlight project by running the following command in your terminal:
 
-<Tabs>
+<Tabs syncKey="pkg">
 <TabItem label="npm">
 
 ```sh
@@ -52,7 +52,7 @@ When working locally, [Astro’s development server](https://docs.astro.build/en
 
 Inside your project directory, run the following command to start the development server:
 
-<Tabs>
+<Tabs syncKey="pkg">
 <TabItem label="npm">
 
 ```sh
@@ -103,7 +103,7 @@ Be sure to update Starlight regularly!
 
 Starlight is an Astro integration. You can update it and other Astro packages by running the following command in your terminal:
 
-<Tabs>
+<Tabs syncKey="pkg">
 <TabItem label="npm">
 
 ```sh

diff --git a/docs/src/content/docs/guides/components.mdx b/docs/src/content/docs/guides/components.mdx
@@ -87,6 +87,50 @@ The code above generates the following tabs on the page:
 	</TabItem>
 </Tabs>
 
+#### Synced tabs
+
+Keep multiple tab groups synchronized by adding the `syncKey` attribute.
+
+All `<Tabs>` on a page with the same `syncKey` value will display the same active label. This allows your reader to choose once (e.g. their operating system or package manager), and see their choice reflected throughout the page.
+
+To synchronize related tabs, add an identical `syncKey` property to each `<Tabs>` component and ensure that they all use the same `<TabItem>` labels:
+
+```mdx 'syncKey="constellations"'
+# src/content/docs/example.mdx
+
+import { Tabs, TabItem } from '@astrojs/starlight/components';
+
+_Some stars:_
+
+<Tabs syncKey="constellations">
+	<TabItem label="Orion">Bellatrix, Rigel, Betelgeuse</TabItem>
+	<TabItem label="Gemini">Pollux, Castor A, Castor B</TabItem>
+</Tabs>
+
+_Some exoplanets:_
+
+<Tabs syncKey="constellations">
+	<TabItem label="Orion">HD 34445 b, Gliese 179 b, Wasp-82 b</TabItem>
+	<TabItem label="Gemini">Pollux b, HAT-P-24b, HD 50554 b</TabItem>
+</Tabs>
+```
+
+The code above generates the following on the page:
+
+_Some stars:_
+
+<Tabs syncKey="constellations">
+	<TabItem label="Orion">Bellatrix, Rigel, Betelgeuse</TabItem>
+	<TabItem label="Gemini">Pollux, Castor A, Castor B</TabItem>
+</Tabs>
+
+_Some exoplanets:_
+
+<Tabs syncKey="constellations">
+	<TabItem label="Orion">HD 34445 b, Gliese 179 b, Wasp-82 b</TabItem>
+	<TabItem label="Gemini">Pollux b, HAT-P-24b, HD 50554 b</TabItem>
+</Tabs>
+
 ### Cards
 
 import { Card, CardGrid } from '@astrojs/starlight/components';

diff --git a/docs/src/content/docs/guides/css-and-tailwind.mdx b/docs/src/content/docs/guides/css-and-tailwind.mdx
@@ -63,7 +63,7 @@ The Starlight Tailwind plugin applies the following configuration:
 
 Start a new Starlight project with Tailwind CSS pre-configured using `create astro`:
 
-<Tabs>
+<Tabs syncKey="pkg">
 <TabItem label="npm">
 
 ```sh
@@ -95,7 +95,7 @@ If you already have a Starlight site and want to add Tailwind CSS, follow these
 
 1.  Add Astro’s Tailwind integration:
 
-    <Tabs>
+    <Tabs syncKey="pkg">
 
     <TabItem label="npm">
 
@@ -125,7 +125,7 @@ If you already have a Starlight site and want to add Tailwind CSS, follow these
 
 2.  Install the Starlight Tailwind plugin:
 
-    <Tabs>
+    <Tabs syncKey="pkg">
 
     <TabItem label="npm">
 

diff --git a/docs/src/content/docs/guides/customization.mdx b/docs/src/content/docs/guides/customization.mdx
@@ -130,7 +130,7 @@ You can customize — or even disable — the table of contents globally in the
 
 By default, `<h2>` and `<h3>` headings are included in the table of contents. Change which headings levels to include site-wide using the `minHeadingLevel` and `maxHeadingLevel` options in your [global `tableOfContents`](/reference/configuration/#tableofcontents). Override these defaults on an individual page by adding the corresponding [frontmatter `tableOfContents`](/reference/frontmatter/#tableofcontents) properties:
 
-<Tabs>
+<Tabs syncKey="config-type">
   <TabItem label="Frontmatter">
 
 ```md {4-6}
@@ -164,7 +164,7 @@ defineConfig({
 
 Disable the table of contents entirely by setting the `tableOfContents` option to `false`:
 
-<Tabs>
+<Tabs syncKey="config-type">
   <TabItem label="Frontmatter">
 
 ```md {4}

diff --git a/package.json b/package.json
@@ -29,7 +29,7 @@
     {
       "name": "/_astro/*.js",
       "path": "examples/basics/dist/_astro/*.js",
-      "limit": "22.5 kB"
+      "limit": "23 kB"
     },
     {
       "name": "/_astro/*.css",

diff --git a/packages/starlight/__e2e__/.gitignore b/packages/starlight/__e2e__/.gitignore
@@ -0,0 +1,3 @@
+# generated types
+.astro/
+dist/
diff --git a/packages/starlight/__e2e__/fixtures/basics/astro.config.mjs b/packages/starlight/__e2e__/fixtures/basics/astro.config.mjs
@@ -0,0 +1,10 @@
+import starlight from '@astrojs/starlight';
+import { defineConfig } from 'astro/config';
+
+export default defineConfig({
+	integrations: [
+		starlight({
+			title: 'Basics',
+		}),
+	],
+});
diff --git a/packages/starlight/__e2e__/fixtures/basics/package.json b/packages/starlight/__e2e__/fixtures/basics/package.json
@@ -0,0 +1,9 @@
+{
+  "name": "@e2e/basics",
+  "version": "0.0.0",
+  "private": true,
+  "dependencies": {
+    "@astrojs/starlight": "workspace:*",
+    "astro": "^4.3.5"
+  }
+}
diff --git a/packages/starlight/__e2e__/fixtures/basics/src/content/config.ts b/packages/starlight/__e2e__/fixtures/basics/src/content/config.ts
@@ -0,0 +1,6 @@
+import { defineCollection } from 'astro:content';
+import { docsSchema } from '@astrojs/starlight/schema';
+
+export const collections = {
+	docs: defineCollection({ schema: docsSchema() }),
+};