@astrojs/starlight 0.0.3 → 0.0.4

package/CHANGELOG.md

@@ -1,5 +1,13 @@
 # @astrojs/starlight
 
+## 0.0.4
+
+### Patch Changes
+
+- [#40](https://github.com/withastro/starlight/pull/40) [`e22dd76`](https://github.com/withastro/starlight/commit/e22dd76136f9749bb5d43f96241385faccfc90a1) Thanks [@delucis](https://github.com/delucis)! - Generate sitemaps for Starlight sites
+
+- [#38](https://github.com/withastro/starlight/pull/38) [`623b577`](https://github.com/withastro/starlight/commit/623b577319b1dea2d6c42f1b680139fb858d85d6) Thanks [@delucis](https://github.com/delucis)! - Add tab components for use in MDX.
+
 ## 0.0.3
 
 ### Patch Changes

package/components/HeadSEO.astro

@@ -40,6 +40,8 @@ const description = data.description || config.description;
   href={import.meta.env.BASE_URL + 'favicon.svg'}
   type="image/svg+xml"
 />
+{/* Link to sitemap, but only when `site` is set. */}
+{Astro.site && <link rel="sitemap" href="/sitemap-index.xml" />}
 
 <!-- OpenGraph Tags -->
 <meta property="og:title" content={title} />

package/components.ts

@@ -0,0 +1,2 @@
+export { default as Tabs } from './user-components/Tabs.astro';
+export { default as TabItem } from './user-components/TabItem.astro';

package/index.ts

@@ -9,6 +9,7 @@ import { spawn } from 'node:child_process';
 import { dirname, relative } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { starlightAsides } from './integrations/asides';
+import { starlightSitemap } from './integrations/sitemap';
 import {
   StarlightUserConfig,
   StarlightConfig,
@@ -63,7 +64,7 @@ export default function StarlightIntegration(
     },
   };
 
-  return [Starlight, mdx()];
+  return [starlightSitemap(userConfig), Starlight, mdx()];
 }
 
 function resolveVirtualModuleId(id: string) {

package/integrations/sitemap.ts

@@ -0,0 +1,22 @@
+import sitemap, { SitemapOptions } from '@astrojs/sitemap';
+import type { StarlightConfig } from '../types';
+
+/**
+ * A wrapped version of the `@astrojs/sitemap` integration configured based
+ * on Starlight i18n config.
+ */
+export function starlightSitemap(opts: StarlightConfig) {
+  const sitemapConfig: SitemapOptions = {};
+  if (opts.isMultilingual) {
+    sitemapConfig.i18n = {
+      defaultLocale: opts.defaultLocale.locale! || 'root',
+      locales: Object.fromEntries(
+        Object.entries(opts.locales).map(([locale, config]) => [
+          locale,
+          config?.lang!,
+        ])
+      ),
+    };
+  }
+  return sitemap(sitemapConfig);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astrojs/starlight",
-  "version": "0.0.3",
+  "version": "0.0.4",
   "description": "Build beautiful, high-performance documentation websites with Astro",
   "keywords": [
     "docs",
@@ -20,6 +20,7 @@
   "type": "module",
   "exports": {
     ".": "./index.ts",
+    "./components": "./components.ts",
     "./schema": "./schema.ts",
     "./types": "./types.ts",
     "./index.astro": "./index.astro",
@@ -34,16 +35,19 @@
   },
   "dependencies": {
     "@astrojs/mdx": "^0.19.1",
+    "@astrojs/sitemap": "^1.3.1",
     "@pagefind/default-ui": "^0.12.0",
     "@types/mdast": "^3.0.11",
     "bcp-47": "^2.1.0",
     "execa": "^7.1.1",
     "hastscript": "^7.2.0",
     "pagefind": "^0.12.0",
+    "rehype": "^12.0.1",
     "remark-directive": "^2.0.1",
     "unified": "^10.1.2",
     "unist-util-remove": "^3.1.1",
-    "unist-util-visit": "^4.1.2"
+    "unist-util-visit": "^4.1.2",
+    "vfile": "^5.3.7"
   },
   "scripts": {}
 }

package/user-components/TabItem.astro

@@ -0,0 +1,17 @@
+---
+import { TabItemTagname } from './rehype-tabs';
+
+interface Props {
+  label: string;
+}
+
+const { label } = Astro.props;
+
+if (!label) {
+  throw new Error('Missing prop `label` on `<TabItem>` component.');
+}
+---
+
+<TabItemTagname data-label={label}>
+  <slot />
+</TabItemTagname>

package/user-components/Tabs.astro

@@ -0,0 +1,148 @@
+---
+import { processPanels } from './rehype-tabs';
+
+const panelHtml = await Astro.slots.render('default');
+const { html, panels } = processPanels(panelHtml);
+---
+
+<starlight-tabs>
+  {
+    panels && (
+      <div class="tablist-wrapper">
+        <ul role="tablist">
+          {panels.map(({ label, panelId, tabId }, idx) => (
+            <li role="presentation" class="tab">
+              <a
+                role="tab"
+                href={'#' + panelId}
+                id={tabId}
+                aria-selected={idx === 0 && 'true'}
+                tabindex={idx !== 0 ? -1 : 0}
+              >
+                {label}
+              </a>
+            </li>
+          ))}
+        </ul>
+      </div>
+    )
+  }
+  <Fragment set:html={html} />
+</starlight-tabs>
+
+<style>
+  starlight-tabs {
+    display: block;
+  }
+
+  .tablist-wrapper {
+    overflow-x: auto;
+  }
+
+  [role='tablist'] {
+    display: flex;
+    list-style: none;
+    border-bottom: 2px solid var(--sl-color-gray-5);
+    padding: 0;
+  }
+
+  [role='tablist'] .tab + .tab {
+    margin-top: 0;
+  }
+  .tab {
+    margin-bottom: -2px;
+  }
+  .tab > [role='tab'] {
+    display: block;
+    padding: 0 1.25rem;
+    text-decoration: none;
+    border-bottom: 2px solid var(--sl-color-gray-5);
+    color: var(--sl-color-gray-3);
+  }
+  .tab [role='tab'][aria-selected] {
+    color: var(--sl-color-white);
+    border-color: var(--sl-color-text-accent);
+    font-weight: 600;
+  }
+
+  .tablist-wrapper ~ :global([role='tabpanel']) {
+    margin-top: 1rem;
+  }
+</style>
+
+<script>
+  class StarlightTabs extends HTMLElement {
+    tabs: HTMLAnchorElement[];
+    panels: HTMLElement[];
+
+    constructor() {
+      super();
+      const tablist = this.querySelector<HTMLUListElement>('[role="tablist"]')!;
+      this.tabs = [
+        ...tablist.querySelectorAll<HTMLAnchorElement>('[role="tab"]'),
+      ];
+      this.panels = [
+        ...this.querySelectorAll<HTMLElement>('[role="tabpanel"]'),
+      ];
+
+      this.tabs.forEach((tab, i) => {
+        // Handle clicks for mouse users
+        tab.addEventListener('click', (e) => {
+          e.preventDefault();
+          const currentTab = tablist.querySelector('[aria-selected]');
+          if (e.currentTarget !== currentTab) {
+            this.switchTab(e.currentTarget as HTMLAnchorElement, i);
+          }
+        });
+
+        // Handle keyboard input
+        tab.addEventListener('keydown', (e) => {
+          const index = this.tabs.indexOf(e.currentTarget as any);
+          // Work out which key the user is pressing and
+          // Calculate the new tab's index where appropriate
+          const dir =
+            e.key === 'ArrowLeft'
+              ? index - 1
+              : e.key === 'ArrowRight'
+              ? index + 1
+              : e.key === 'ArrowDown'
+              ? 'down'
+              : null;
+          if (dir === null) return;
+          // If the down key is pressed, move focus to the open panel,
+          // otherwise switch to the adjacent tab
+          if (dir === 'down') {
+            e.preventDefault();
+            this.panels[i]?.focus();
+          } else if (this.tabs[dir]) {
+            e.preventDefault();
+            this.switchTab(this.tabs[dir], dir);
+          }
+        });
+      });
+    }
+
+    switchTab(newTab: HTMLAnchorElement | null | undefined, index: number) {
+      if (!newTab) return;
+
+      // Mark all tabs as unselected and hide all tab panels.
+      this.tabs.forEach((tab) => {
+        tab.removeAttribute('aria-selected');
+        tab.setAttribute('tabindex', '-1');
+      });
+      this.panels.forEach((oldPanel) => {
+        oldPanel.hidden = true;
+      });
+
+      // Show new panel and mark new tab as selected.
+      const newPanel = this.panels[index];
+      if (newPanel) newPanel.hidden = false;
+      // Restore active tab to the default tab order.
+      newTab.removeAttribute('tabindex');
+      newTab.setAttribute('aria-selected', 'true');
+      newTab.focus();
+    }
+  }
+
+  customElements.define('starlight-tabs', StarlightTabs);
+</script>

package/user-components/rehype-tabs.ts

@@ -0,0 +1,82 @@
+import { rehype } from 'rehype';
+import { CONTINUE, SKIP, visit } from 'unist-util-visit';
+
+interface Panel {
+  panelId: string;
+  tabId: string;
+  label: string;
+}
+
+declare module 'vfile' {
+  interface DataMap {
+    panels: Panel[];
+  }
+}
+
+export const TabItemTagname = 'starlight-tab-item';
+
+let count = 0;
+const getIDs = () => {
+  const id = count++;
+  return { panelId: 'tab-panel-' + id, tabId: 'tab-' + id };
+};
+
+/**
+ * Rehype processor to extract tab panel data and turn each
+ * `<starlight-tab-item>` into a `<section>` with the necessary
+ * attributes.
+ */
+const tabsProcessor = rehype()
+  .data('settings', { fragment: true })
+  .use(function tabs() {
+    return (tree, file) => {
+      file.data.panels = [];
+      let isFirst = true;
+      visit(tree, 'element', (node) => {
+        if (node.tagName !== TabItemTagname || !node.properties) {
+          return CONTINUE;
+        }
+
+        const { dataLabel } = node.properties;
+        const ids = getIDs();
+        file.data.panels?.push({
+          ...ids,
+          label: String(dataLabel),
+        });
+
+        // Remove `<TabItem>` props
+        delete node.properties.dataLabel;
+        // Turn into `<section>` with required attributes
+        node.tagName = 'section';
+        node.properties.id = ids.panelId;
+        node.properties['aria-labelledby'] = ids.tabId;
+        node.properties.role = 'tabpanel';
+        node.properties.tabindex = -1;
+        // Hide all panels except the first
+        // TODO: make initially visible tab configurable
+        if (isFirst) {
+          isFirst = false;
+        } else {
+          node.properties.hidden = true;
+        }
+
+        // Skip over the tab panel’s children.
+        return SKIP;
+      });
+    };
+  });
+
+/**
+ * Process tab panel items to extract data for the tab links and format
+ * each tab panel correctly.
+ * @param html Inner HTML passed to the `<Tabs>` component.
+ */
+export const processPanels = (html: string) => {
+  const file = tabsProcessor.processSync({ value: html });
+  return {
+    /** Data for each tab panel. */
+    panels: file.data.panels,
+    /** Processed HTML for the tab panels. */
+    html: file.toString(),
+  };
+};