@astrojs/starlight 0.41.11 → 0.42.0

package/user-components/rehype-file-tree.ts

@@ -1,251 +0,0 @@
-import { AstroError } from 'astro/errors';
-import type { Element, ElementContent, Text } from 'hast';
-import { type Child, h, s } from 'hastscript';
-import { select } from 'hast-util-select';
-import { fromHtml } from 'hast-util-from-html';
-import { toString } from 'hast-util-to-string';
-import { rehype } from 'rehype';
-import { CONTINUE, SKIP, visit } from 'unist-util-visit';
-import { Icons, type StarlightIcon } from '../components-internals/Icons';
-import { definitions } from './file-tree-icons';
-
-declare module 'vfile' {
-	interface DataMap {
-		directoryLabel: string;
-	}
-}
-
-const folderIcon = makeSVGIcon(Icons['seti:folder']);
-const defaultFileIcon = makeSVGIcon(Icons['seti:default']);
-
-/**
- * Process the HTML for a file tree to create the necessary markup for each file and directory
- * including icons.
- * @param html Inner HTML passed to the `<FileTree>` component.
- * @param directoryLabel The localized label for a directory.
- * @returns The processed HTML for the file tree.
- */
-export function processFileTree(html: string, directoryLabel: string) {
-	const file = fileTreeProcessor.processSync({ data: { directoryLabel }, value: html });
-
-	return file.toString();
-}
-
-/** Rehype processor to extract file tree data and turn each entry into its associated markup. */
-const fileTreeProcessor = rehype()
-	.data('settings', { fragment: true })
-	.use(function fileTree() {
-		return (tree: Element, file) => {
-			const { directoryLabel } = file.data;
-
-			validateFileTree(tree);
-
-			visit(tree, 'element', (node) => {
-				// Strip nodes that only contain newlines.
-				node.children = node.children.filter(
-					(child) => child.type === 'comment' || child.type !== 'text' || !/^\n+$/.test(child.value)
-				);
-
-				// Skip over non-list items.
-				if (node.tagName !== 'li') return CONTINUE;
-
-				const [firstChild, ...otherChildren] = node.children;
-
-				// Keep track of comments associated with the current file or directory.
-				const comment: Child[] = [];
-
-				// Extract text comment that follows the file name, e.g. `README.md This is a comment`
-				if (firstChild?.type === 'text') {
-					const [filename, ...fragments] = firstChild.value.split(' ');
-					firstChild.value = filename || '';
-					const textComment = fragments.join(' ').trim();
-					if (textComment.length > 0) {
-						comment.push(fragments.join(' '));
-					}
-				}
-
-				// Comments may not always be entirely part of the first child text node,
-				// e.g. `README.md This is an __important__ comment` where the `__important__` and `comment`
-				// nodes would also be children of the list item node.
-				const subTreeIndex = otherChildren.findIndex(
-					(child) => child.type === 'element' && child.tagName === 'ul'
-				);
-				const commentNodes =
-					subTreeIndex > -1 ? otherChildren.slice(0, subTreeIndex) : [...otherChildren];
-				otherChildren.splice(0, subTreeIndex > -1 ? subTreeIndex : otherChildren.length);
-				comment.push(...commentNodes);
-
-				const firstChildTextContent = firstChild ? toString(firstChild) : '';
-
-				// Decide a node is a directory if it ends in a `/` or contains another list.
-				const isDirectory =
-					/\/\s*$/.test(firstChildTextContent) ||
-					otherChildren.some((child) => child.type === 'element' && child.tagName === 'ul');
-				// A placeholder is a node that only contains 3 dots or an ellipsis.
-				const isPlaceholder = /^\s*(\.{3}|…)\s*$/.test(firstChildTextContent);
-				// A node is highlighted if its first child is bold text, e.g. `**README.md**`.
-				const isHighlighted = firstChild?.type === 'element' && firstChild.tagName === 'strong';
-
-				// Create an icon for the file or directory (placeholder do not have icons).
-				const icon = h('span', isDirectory ? folderIcon : getFileIcon(firstChildTextContent));
-				if (isDirectory) {
-					// Add a screen reader only label for directories before the icon so that it is announced
-					// as such before reading the directory name.
-					icon.children.unshift(h('span', { class: 'sr-only' }, directoryLabel));
-				}
-
-				// Add classes and data attributes to the list item node.
-				node.properties.class = isDirectory ? 'directory' : 'file';
-				if (isPlaceholder) node.properties.class += ' empty';
-
-				// Create the tree entry node that contains the icon, file name and comment which will end up
-				// as the list item’s children.
-				const treeEntryChildren: Child[] = [
-					h('span', { class: isHighlighted ? 'highlight' : '' }, [
-						isPlaceholder ? null : icon,
-						firstChild,
-					]),
-				];
-
-				if (comment.length > 0) {
-					treeEntryChildren.push(makeText(' '), h('span', { class: 'comment' }, ...comment));
-				}
-
-				const treeEntry = h('span', { class: 'tree-entry' }, ...treeEntryChildren);
-
-				if (isDirectory) {
-					const hasContents = otherChildren.length > 0;
-
-					node.children = [
-						h('details', { open: hasContents }, [
-							h('summary', treeEntry),
-							...(hasContents ? otherChildren : [h('ul', h('li', '…'))]),
-						]),
-					];
-
-					// Continue down the tree.
-					return CONTINUE;
-				}
-
-				node.children = [treeEntry, ...otherChildren];
-
-				// Files can’t contain further files or directories, so skip iterating children.
-				return SKIP;
-			});
-		};
-	});
-
-/** Make a text node with the pass string as its contents. */
-function makeText(value = ''): Text {
-	return { type: 'text', value };
-}
-
-/** Make a node containing an SVG icon from the passed HTML string. */
-function makeSVGIcon(svgString: string) {
-	return s(
-		'svg',
-		{
-			width: 16,
-			height: 16,
-			class: 'tree-icon',
-			'aria-hidden': 'true',
-			viewBox: '0 0 24 24',
-		},
-		fromHtml(svgString, { fragment: true })
-	);
-}
-
-/** Return the icon for a file based on its file name. */
-function getFileIcon(fileName: string) {
-	const name = getFileIconName(fileName);
-	if (!name) return defaultFileIcon;
-	if (name in Icons) {
-		const path = Icons[name as StarlightIcon];
-		return makeSVGIcon(path);
-	}
-	return defaultFileIcon;
-}
-
-/** Return the icon name for a file based on its file name. */
-function getFileIconName(fileName: string) {
-	let icon: string | undefined = definitions.files[fileName];
-	if (icon) return icon;
-	icon = getFileIconTypeFromExtension(fileName);
-	if (icon) return icon;
-	for (const [partial, partialIcon] of Object.entries(definitions.partials)) {
-		if (fileName.includes(partial)) return partialIcon;
-	}
-	return icon;
-}
-
-/**
- * Get an icon from a file name based on its extension.
- * Note that an extension in Seti is everything after a dot, so `README.md` would be `.md` and
- * `name.with.dots` will try to look for an icon for `.with.dots` and then `.dots` if the first one
- * is not found.
- */
-function getFileIconTypeFromExtension(fileName: string) {
-	const firstDotIndex = fileName.indexOf('.');
-	if (firstDotIndex === -1) return;
-	let extension = fileName.slice(firstDotIndex);
-	while (extension !== '') {
-		const icon = definitions.extensions[extension];
-		if (icon) return icon;
-		const nextDotIndex = extension.indexOf('.', 1);
-		if (nextDotIndex === -1) return;
-		extension = extension.slice(nextDotIndex);
-	}
-	return;
-}
-
-/** Validate that the user provided HTML for a file tree is valid. */
-function validateFileTree(tree: Element) {
-	const rootElements = tree.children.filter(isElementNode);
-	const [rootElement] = rootElements;
-
-	if (rootElements.length === 0) {
-		throwFileTreeValidationError(
-			'The `<FileTree>` component expects its content to be a single unordered list but found no child elements.'
-		);
-	}
-
-	if (rootElements.length !== 1) {
-		throwFileTreeValidationError(
-			`The \`<FileTree>\` component expects its content to be a single unordered list but found multiple child elements: ${rootElements
-				.map((element) => `\`<${element.tagName}>\``)
-				.join(' - ')}.`
-		);
-	}
-
-	if (!rootElement || rootElement.tagName !== 'ul') {
-		throwFileTreeValidationError(
-			`The \`<FileTree>\` component expects its content to be an unordered list but found the following element: \`<${rootElement?.tagName}>\`.`
-		);
-	}
-
-	const listItemElement = select('li', rootElement);
-
-	if (!listItemElement) {
-		throwFileTreeValidationError(
-			'The `<FileTree>` component expects its content to be an unordered list with at least one list item.'
-		);
-	}
-}
-
-function isElementNode(node: ElementContent): node is Element {
-	return node.type === 'element';
-}
-
-/** Throw a validation error for a file tree linking to the documentation. */
-function throwFileTreeValidationError(message: string): never {
-	throw new AstroError(
-		message,
-		'To learn more about the `<FileTree>` component, see https://starlight.astro.build/components/file-tree/'
-	);
-}
-
-export interface Definitions {
-	files: Record<string, string>;
-	extensions: Record<string, string>;
-	partials: Record<string, string>;
-}

package/user-components/rehype-steps.ts

@@ -1,85 +0,0 @@
-import { AstroError } from 'astro/errors';
-import type { Element, Root } from 'hast';
-import { rehype } from 'rehype';
-import rehypeFormat from 'rehype-format';
-import type { VFile } from 'vfile';
-
-const prettyPrintProcessor = rehype().data('settings', { fragment: true }).use(rehypeFormat);
-const prettyPrintHtml = (html: string) =>
-	prettyPrintProcessor.processSync({ value: html }).toString();
-
-const stepsProcessor = rehype()
-	.data('settings', { fragment: true })
-	.use(function steps() {
-		return (tree: Root, vfile: VFile) => {
-			const rootElements = tree.children.filter(
-				(item): item is Element =>
-					item.type === 'element' &&
-					// Since Astro 5.16.9, `<script>` elements from nested child elements can end up hoisted
-					// into the `<Steps>` slot due to our use of `Astro.slots.render()`. We can safely ignore
-					// these, so we filter them out here.
-					// TODO: we may be able to remove this in the future if the upstream issue is fixed.
-					// See: https://github.com/withastro/astro/issues/15627
-					item.tagName !== 'script'
-			);
-			const [rootElement] = rootElements;
-
-			if (!rootElement) {
-				throw new StepsError(
-					'The `<Steps>` component expects its content to be a single ordered list (`<ol>`) but found no child elements.'
-				);
-			} else if (rootElements.length > 1) {
-				throw new StepsError(
-					'The `<Steps>` component expects its content to be a single ordered list (`<ol>`) but found multiple child elements: ' +
-						rootElements.map((element: Element) => `\`<${element.tagName}>\``).join(', ') +
-						'.',
-					vfile.value.toString()
-				);
-			} else if (rootElement.tagName !== 'ol') {
-				throw new StepsError(
-					'The `<Steps>` component expects its content to be a single ordered list (`<ol>`) but found the following element: ' +
-						`\`<${rootElement.tagName}>\`.`,
-					vfile.value.toString()
-				);
-			}
-
-			// Ensure `role="list"` is set on the ordered list.
-			// We use `list-style: none` in the styles for this component and need to ensure the list
-			// retains its semantics in Safari, which will remove them otherwise.
-			rootElement.properties.role = 'list';
-			// Add the required CSS class name, preserving existing classes if present.
-			if (!Array.isArray(rootElement.properties.className)) {
-				rootElement.properties.className = ['sl-steps'];
-			} else {
-				rootElement.properties.className.push('sl-steps');
-			}
-
-			// Add the `start` attribute as a CSS custom property so we can use it as the starting index
-			// of the steps custom counter.
-			if (typeof rootElement.properties.start === 'number') {
-				const styles = [`--sl-steps-start: ${rootElement.properties.start - 1}`];
-				if (rootElement.properties.style) styles.push(String(rootElement.properties.style));
-				rootElement.properties.style = styles.join(';');
-			}
-		};
-	});
-
-/**
- * Process steps children: validates the HTML and adds `role="list"` to the ordered list.
- * @param html Inner HTML passed to the `<Steps>` component.
- */
-export const processSteps = (html: string | undefined) => {
-	const file = stepsProcessor.processSync({ value: html });
-	return { html: file.toString() };
-};
-
-class StepsError extends AstroError {
-	constructor(message: string, html?: string) {
-		let hint =
-			'To learn more about the `<Steps>` component, see https://starlight.astro.build/components/steps/';
-		if (html) {
-			hint += '\n\nFull HTML passed to `<Steps>`:\n' + prettyPrintHtml(html);
-		}
-		super(message, hint);
-	}
-}

package/user-components/rehype-tabs.ts

@@ -1,121 +0,0 @@
-import type { Element } from 'hast';
-import { select } from 'hast-util-select';
-import { rehype } from 'rehype';
-import { CONTINUE, SKIP, visit } from 'unist-util-visit';
-import { VFile } from 'vfile';
-import type { StarlightIcon } from '../components-internals/Icons';
-
-interface Panel {
-	panelId: string;
-	tabId: string;
-	label: string;
-	icon?: StarlightIcon;
-}
-
-declare module 'vfile' {
-	interface DataMap {
-		panels: Panel[];
-		index: number;
-	}
-}
-
-export const TabItemTagname = 'starlight-tab-item';
-
-// https://github.com/adobe/react-spectrum/blob/99ca82e87ba2d7fdd54f5b49326fd242320b4b51/packages/%40react-aria/focus/src/FocusScope.tsx#L256-L275
-const focusableElementSelectors = [
-	'input:not([disabled]):not([type=hidden])',
-	'select:not([disabled])',
-	'textarea:not([disabled])',
-	'button:not([disabled])',
-	'a[href]',
-	'area[href]',
-	'summary',
-	'iframe',
-	'object',
-	'embed',
-	'audio[controls]',
-	'video[controls]',
-	'[contenteditable]',
-	'[tabindex]:not([disabled])',
-]
-	.map((selector) => `${selector}:not([hidden]):not([tabindex="-1"])`)
-	.join(',');
-
-/**
- * Rehype processor to extract tab panel data and turn each
- * `<starlight-tab-item>` into a `<div>` with the necessary
- * attributes.
- */
-const tabsProcessor = rehype()
-	.data('settings', { fragment: true })
-	.use(function tabs() {
-		return (tree: Element, file) => {
-			file.data.panels = [];
-			let isFirst = true;
-			let count = 0;
-			const getIDs = () => {
-				const id = count++;
-				return {
-					panelId: `tab-panel-${file.data.index}-${id}`,
-					tabId: `tab-${file.data.index}-${id}`,
-				};
-			};
-			visit(tree, 'element', (node) => {
-				if (node.tagName !== TabItemTagname || !node.properties) {
-					return CONTINUE;
-				}
-
-				const { dataLabel, dataIcon } = node.properties;
-				const ids = getIDs();
-				const panel: Panel = {
-					...ids,
-					label: String(dataLabel),
-				};
-				if (dataIcon) panel.icon = String(dataIcon) as StarlightIcon;
-				file.data.panels?.push(panel);
-
-				// Remove `<TabItem>` props
-				delete node.properties.dataLabel;
-				delete node.properties.dataIcon;
-				// Turn into `<div>` with required attributes
-				node.tagName = 'div';
-				node.properties.id = ids.panelId;
-				node.properties['aria-labelledby'] = ids.tabId;
-				node.properties.role = 'tabpanel';
-
-				const focusableChild = select(focusableElementSelectors, node);
-				// If the panel does not contain any focusable elements, include it in
-				// the tab sequence of the page.
-				if (!focusableChild) {
-					node.properties.tabindex = 0;
-				}
-
-				// 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.
- * @param index The index of the `<Tabs>` component on the page.
- */
-export const processPanels = (html: string, index: number) => {
-	const file = tabsProcessor.processSync(new VFile({ value: html, data: { index } }));
-	return {
-		/** Data for each tab panel. */
-		panels: file.data.panels,
-		/** Processed HTML for the tab panels. */
-		html: file.toString(),
-	};
-};

package/utils/base.ts

@@ -1,15 +0,0 @@
-import { stripLeadingSlash, stripTrailingSlash } from './path';
-
-const base = stripTrailingSlash(import.meta.env.BASE_URL);
-
-/** Get the a root-relative URL path with the site’s `base` prefixed. */
-export function pathWithBase(path: string) {
-	path = stripLeadingSlash(path);
-	return path ? base + '/' + path : base + '/';
-}
-
-/** Get the a root-relative file URL path with the site’s `base` prefixed. */
-export function fileWithBase(path: string) {
-	path = stripLeadingSlash(path);
-	return path ? base + '/' + path : base;
-}

package/utils/canonical.ts

@@ -1,19 +0,0 @@
-import type { AstroConfig } from 'astro';
-import { ensureTrailingSlash, stripTrailingSlash } from './path';
-
-export interface FormatCanonicalOptions {
-	format: AstroConfig['build']['format'];
-	trailingSlash: AstroConfig['trailingSlash'];
-}
-
-const canonicalTrailingSlashStrategies = {
-	always: ensureTrailingSlash,
-	never: stripTrailingSlash,
-	ignore: ensureTrailingSlash,
-};
-
-/** Format a canonical link based on the project config. */
-export function formatCanonical(href: string, opts: FormatCanonicalOptions) {
-	if (opts.format === 'file') return href;
-	return canonicalTrailingSlashStrategies[opts.trailingSlash](href);
-}

package/utils/collection-fs.ts

@@ -1,20 +0,0 @@
-import { resolve } from 'node:path';
-import { fileURLToPath } from 'node:url';
-import { getCollectionUrl, type StarlightCollection } from './collection';
-
-/**
- * @see {@link file://./collection.ts} for more context about this file.
- *
- * Below are various functions to easily get paths to collections used in Starlight that rely on
- * Node.js builtins. They exist in a separate file from {@link file://./collection.ts} to avoid
- * potentially importing Node.js builtins in the final bundle.
- */
-
-export function resolveCollectionPath(collection: StarlightCollection, srcDir: URL) {
-	return resolve(fileURLToPath(srcDir), `content/${collection}`);
-}
-
-export function getCollectionPosixPath(collection: StarlightCollection, srcDir: URL) {
-	// Return POSIX path with leading slash even on Windows, e.g. `/C:/project/src/content/docs/`.
-	return fileURLToPath(getCollectionUrl(collection, srcDir), { windows: false });
-}

package/utils/createPathFormatter.ts

@@ -1,60 +0,0 @@
-import type { AstroConfig } from 'astro';
-import { fileWithBase, pathWithBase } from './base';
-import {
-	ensureHtmlExtension,
-	ensureTrailingSlash,
-	stripHtmlExtension,
-	stripTrailingSlash,
-} from './path';
-
-interface FormatPathOptions {
-	format?: AstroConfig['build']['format'];
-	trailingSlash?: AstroConfig['trailingSlash'];
-}
-
-const defaultFormatStrategy = {
-	addBase: pathWithBase,
-	handleExtension: (href: string) => stripHtmlExtension(href),
-};
-
-const formatStrategies = {
-	file: {
-		addBase: fileWithBase,
-		handleExtension: (href: string) => ensureHtmlExtension(href),
-	},
-	directory: defaultFormatStrategy,
-	preserve: defaultFormatStrategy,
-};
-
-const trailingSlashStrategies = {
-	always: ensureTrailingSlash,
-	never: stripTrailingSlash,
-	ignore: (href: string) => href,
-};
-
-/** Format a path based on the project config. */
-function formatPath(
-	href: string,
-	{ format = 'directory', trailingSlash = 'ignore' }: FormatPathOptions
-) {
-	const formatStrategy = formatStrategies[format];
-	const trailingSlashStrategy = trailingSlashStrategies[trailingSlash];
-
-	// Handle extension
-	href = formatStrategy.handleExtension(href);
-
-	// Add base
-	href = formatStrategy.addBase(href);
-
-	// Skip trailing slash handling for `build.format: 'file'`
-	if (format === 'file') return href;
-
-	// Handle trailing slash
-	href = href === '/' ? href : trailingSlashStrategy(href);
-
-	return href;
-}
-
-export function createPathFormatter(opts: FormatPathOptions) {
-	return (href: string) => formatPath(href, opts);
-}