Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
13 changes: 13 additions & 0 deletions src/frontend/astro.config.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,7 @@ import { aspireVersionPlaceholdersIntegration } from './config/aspire-version-pl
import { remarkAspireVersionPlaceholders } from './config/remark-aspire-version-placeholders.mjs';
import { remarkTypeScriptFirstAppHostTabs } from './config/remark-typescript-first-apphost-tabs.mjs';
import { remarkMermaid } from './config/remark-mermaid.mjs';
import { starlightIconSprite } from './config/starlight-icon-sprite.mjs';
import catppuccin from '@catppuccin/starlight';
import lunaria from './config/lunaria-starlight.mjs';
import mdx from '@astrojs/mdx';
Expand Down Expand Up @@ -66,6 +67,15 @@ export default defineConfig({
cacheDir: './node_modules/.astro',
...(outDir ? { outDir } : {}),
vite: {
plugins: [starlightIconSprite()],
build: {
// Astro inlines processed <script>s (and Vite inlines `?url` scripts as data: URLs) when
// they're under this limit. Shared scripts are repeated on every one of ~38k pages, so
// always emit JavaScript (and the shared icon sprite) as cacheable /_astro/ files; other
// assets keep Vite's default.
assetsInlineLimit: (filePath) =>
/\.[cm]?[jt]s(?:\?|$)|\.sprite\.svg(?:\?|$)/.test(filePath) ? false : undefined,
},
define: {
// Resolve filesystem-backed redirects before prerender modules are bundled.
__ASPIRE_REDIRECT_PATHS__: JSON.stringify(Object.keys(redirects)),
Expand Down Expand Up @@ -249,6 +259,9 @@ export default defineConfig({
],
build: {
concurrency: buildConcurrency,
// Every docs page shares the same component stylesheets, so ship them as cached files
// instead of re-inlining the same ~13-18 KB of CSS into each of the ~38k pages.
inlineStylesheets: 'never',
},
experimental: {
parallelPrerender: { workers: prerenderWorkers },
Expand Down
30 changes: 30 additions & 0 deletions src/frontend/config/starlight-icon-sprite.mjs
Original file line number Diff line number Diff line change
@@ -0,0 +1,30 @@
import { realpathSync } from 'node:fs';
import { fileURLToPath } from 'node:url';
import { normalizePath } from 'vite';

const resolveReal = (url) => normalizePath(realpathSync(fileURLToPath(url)));

/**
* Redirects every import of Starlight's `<Icon>` component, including Starlight's own internal
* imports and plugin components, to `src/components/starlight/Icon.astro`, which serves common
* icons from a shared SVG sprite instead of inlining their paths into every page. The wrapper
* itself still imports the original component for icons outside the sprite.
*/
export function starlightIconSprite() {
const wrapper = resolveReal(new URL('../src/components/starlight/Icon.astro', import.meta.url));
const original = resolveReal(
new URL('../node_modules/@astrojs/starlight/user-components/Icon.astro', import.meta.url)
);

return {
name: 'aspire:starlight-icon-sprite',
enforce: 'pre',
async resolveId(source, importer, options) {
if (!importer || !source.endsWith('Icon.astro')) return null;
if (normalizePath(importer.split('?')[0]) === wrapper) return null;
const resolved = await this.resolve(source, importer, { ...options, skipSelf: true });
if (!resolved || normalizePath(resolved.id.split('?')[0]) !== original) return null;
return wrapper;
},
};
}
10 changes: 10 additions & 0 deletions src/frontend/eslint.config.mjs
Original file line number Diff line number Diff line change
Expand Up @@ -53,6 +53,16 @@ export default [
files: ['tests/e2e/**/*.ts'],
...tseslint.configs.disableTypeChecked,
},
// Classic browser scripts loaded verbatim with `<script is:inline src>` (see Head.astro).
{
files: ['src/scripts/**/*.inline.js'],
languageOptions: {
sourceType: 'script',
globals: {
...globals.browser,
},
},
},
{
files: ['tests/unit/**/*.ts', 'tests/typecheck/**/*.ts'],
rules: {
Expand Down
1 change: 1 addition & 0 deletions src/frontend/package.json
Original file line number Diff line number Diff line change
Expand Up @@ -19,6 +19,7 @@
"compute-skill-digests": "node ./scripts/compute-skill-digests.mjs",
"verify-skill-digests": "node ./scripts/compute-skill-digests.mjs --check",
"twoslash-types": "tsx ./scripts/generate-twoslash-types.ts",
"icon-sprite": "tsx ./scripts/generate-icon-sprite.ts",
"dev": "bun run git-env && bun run check-data && bun run compute-skill-digests && astro dev",
"dev:host": "bun run git-env && bun run check-data && bun run compute-skill-digests && astro dev --host",
"start": "bun run git-env && bun run check-data && bun run compute-skill-digests && astro dev",
Expand Down
51 changes: 50 additions & 1 deletion src/frontend/patches/@astrojs__starlight@0.41.3.patch
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
diff --git a/components/Search.astro b/components/Search.astro
index d8c80d826995d6c8ce598aa618ddf7ea575ecadc..ec1f9b15f677f0c7ae98160eef1c9dc714330421 100644
index d8c80d826995d6c8ce598aa618ddf7ea575ecadc..0a35ace9530404d2469ae11ed87688766d75e8bd 100644
--- a/components/Search.astro
+++ b/components/Search.astro
@@ -59,7 +59,7 @@ if (project.trailingSlash === 'never') dataAttributes['data-strip-trailing-slash
Expand Down Expand Up @@ -112,3 +112,52 @@ index d8c80d826995d6c8ce598aa618ddf7ea575ecadc..ec1f9b15f677f0c7ae98160eef1c9dc7
}
}
customElements.define('site-search', SiteSearch);
diff --git a/components/SidebarSublist.astro b/components/SidebarSublist.astro
index 457ab20fd3583f521bd756cd2acb5cc57643d60b..b6c81a9520418c03b14e3053c46edc9541556e03 100644
--- a/components/SidebarSublist.astro
+++ b/components/SidebarSublist.astro
@@ -1,7 +1,6 @@
---
import { flattenSidebar } from '../utils/navigation';
import type { SidebarEntry } from '../utils/routing/types';
-import Icon from '../user-components/Icon.astro';
import Badge from '../user-components/Badge.astro';
import SidebarRestorePoint from './SidebarRestorePoint.astro';

@@ -48,7 +47,7 @@ const { sublist, nested } = Astro.props;
/>
)}
</span>
- <Icon name="right-caret" class="caret" size="1.25rem" />
+ <span class="caret" aria-hidden="true" />
</summary>
<SidebarRestorePoint />
<Astro.self sublist={entry.entries} nested />
@@ -101,7 +100,14 @@ const { sublist, nested } = Astro.props;
display: none;
}

+ /* Masked from shared CSS instead of an inline SVG repeated for every sidebar group. */
.caret {
+ display: block;
+ width: 1.25rem;
+ height: 1.25rem;
+ background-color: currentColor;
+ -webkit-mask: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24'%3E%3Cpath d='m14.83 11.29-4.24-4.24a1 1 0 1 0-1.42 1.41L12.71 12l-3.54 3.54a1 1 0 0 0 0 1.41 1 1 0 0 0 .71.29 1 1 0 0 0 .71-.29l4.24-4.24a1.002 1.002 0 0 0 0-1.42Z'/%3E%3C/svg%3E") center / contain no-repeat;
+ mask: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24'%3E%3Cpath d='m14.83 11.29-4.24-4.24a1 1 0 1 0-1.42 1.41L12.71 12l-3.54 3.54a1 1 0 0 0 0 1.41 1 1 0 0 0 .71.29 1 1 0 0 0 .71-.29l4.24-4.24a1.002 1.002 0 0 0 0-1.42Z'/%3E%3C/svg%3E") center / contain no-repeat;
transition: transform 0.2s ease-in-out;
flex-shrink: 0;
}
@@ -111,6 +117,12 @@ const { sublist, nested } = Astro.props;
[open] > summary .caret {
transform: rotateZ(90deg);
}
+ @media (forced-colors: active) {
+ .caret {
+ forced-color-adjust: none;
+ background-color: CanvasText;
+ }
+ }

a {
display: block;
4 changes: 2 additions & 2 deletions src/frontend/patches/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ regenerated (`bun patch <package>`, edit, then `bun patch --commit <directory>`)

| Patch | Why |
| --- | --- |
| `@astrojs__starlight@0.41.3.patch` | Starlight search must initialize and dispose per element across `ClientRouter` swaps, not only on `DOMContentLoaded` ([#1673](https://github.com/microsoft/aspire.dev/issues/1673)). |
| `@astrojs__starlight@0.41.3.patch` | Starlight search must initialize and dispose per element across `ClientRouter` swaps, not only on `DOMContentLoaded` ([#1673](https://github.com/microsoft/aspire.dev/issues/1673)). The sidebar group caret is drawn with a CSS mask from the shared stylesheet instead of an inline SVG repeated for every group (hundreds per API reference page). |
| `astro@7.4.1.patch` | Imported SVGs are callable components that can't be structured-cloned, so the parallel prerender worker keeps only their image metadata before posting results. |
| `starlight-page-actions@0.7.0.patch` | Keeps accessible actions across page swaps, allows readable heading markup, and points Markdown actions on untranslated locale pages to the default-locale Markdown. |
| `starlight-page-actions@0.7.0.patch` | Keeps accessible actions across page swaps, allows readable heading markup, and points Markdown actions on untranslated locale pages to the default-locale Markdown. The dropdown's external-link icon is a CSS mask instead of an inline SVG per item. |
| `starlight-plugin-icons@1.1.6.patch` | Temporary network-resilience fix for `getMaterialIconsData`: falls back to the vendored `.starlight-icons` cache when the icon-data fetch fails. Remove once [Rettend/starlight-plugin-icons#9](https://github.com/Rettend/starlight-plugin-icons/pull/9) is merged and released. |
43 changes: 36 additions & 7 deletions src/frontend/patches/starlight-page-actions@0.7.0.patch
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
diff --git a/components/Dropdown.astro b/components/Dropdown.astro
index 5a44e3674908f7a311a4934da878d60e82a4402a..c8be207ec007f0c7f677d5f4a21632fe04644ab5 100644
index 5a44e3674908f7a311a4934da878d60e82a4402a..af151ca27a7a090ca20c93e7e1bd49dc57c3e9e1 100644
--- a/components/Dropdown.astro
+++ b/components/Dropdown.astro
@@ -19,13 +19,13 @@ const { label, options, id } = Astro.props;
Expand All @@ -19,6 +19,15 @@ index 5a44e3674908f7a311a4934da878d60e82a4402a..c8be207ec007f0c7f677d5f4a21632fe
{
options.map((option) => {
const OptionIcon = option.icon;
@@ -40,7 +40,7 @@ const dropdownId = id ? `dropdown-${id}` : "dropdown-0";
/>
)}
<span>{option.label}</span>
- <Icon name="external" size="1rem" class="external-icon" />
+ <i class="external-icon" aria-hidden="true" />
</a>
);
})
@@ -53,8 +53,8 @@ const dropdownId = id ? `dropdown-${id}` : "dropdown-0";
position: relative;
}
Expand All @@ -44,7 +53,27 @@ index 5a44e3674908f7a311a4934da878d60e82a4402a..c8be207ec007f0c7f677d5f4a21632fe
display: block;
}

@@ -159,7 +162,7 @@ const dropdownId = id ? `dropdown-${id}` : "dropdown-0";
@@ -154,12 +157,27 @@ const dropdownId = id ? `dropdown-${id}` : "dropdown-0";
transform: scale(1.6);
}

+ /* Masked from shared CSS instead of an inline SVG repeated for every menu item. */
.dropdown-item .external-icon {
+ display: block;
+ width: 1rem;
+ height: 1rem;
+ flex: 0 0 1rem;
margin-left: auto;
+ background-color: currentColor;
+ -webkit-mask: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24'%3E%3Cpath d='M19.33 10.18a1 1 0 0 1-.77 0 1 1 0 0 1-.62-.93l.01-1.83-8.2 8.2a1 1 0 0 1-1.41-1.42l8.2-8.2H14.7a1 1 0 0 1 0-2h4.25a1 1 0 0 1 1 1v4.25a1 1 0 0 1-.62.93Z'/%3E%3Cpath d='M11 4a1 1 0 1 1 0 2H7a1 1 0 0 0-1 1v10a1 1 0 0 0 1 1h10a1 1 0 0 0 1-1v-4a1 1 0 1 1 2 0v4a3 3 0 0 1-3 3H7a3 3 0 0 1-3-3V7a3 3 0 0 1 3-3h4Z'/%3E%3C/svg%3E") center / contain no-repeat;
+ mask: url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24'%3E%3Cpath d='M19.33 10.18a1 1 0 0 1-.77 0 1 1 0 0 1-.62-.93l.01-1.83-8.2 8.2a1 1 0 0 1-1.41-1.42l8.2-8.2H14.7a1 1 0 0 1 0-2h4.25a1 1 0 0 1 1 1v4.25a1 1 0 0 1-.62.93Z'/%3E%3Cpath d='M11 4a1 1 0 1 1 0 2H7a1 1 0 0 0-1 1v10a1 1 0 0 0 1 1h10a1 1 0 0 0 1-1v-4a1 1 0 1 1 2 0v4a3 3 0 0 1-3 3H7a3 3 0 0 1-3-3V7a3 3 0 0 1 3-3h4Z'/%3E%3C/svg%3E") center / contain no-repeat;
+ }
+
+ @media (forced-colors: active) {
+ .dropdown-item .external-icon {
+ forced-color-adjust: none;
+ background-color: LinkText;
+ }
}

@media (min-width: 425px) {
Expand All @@ -53,7 +82,7 @@ index 5a44e3674908f7a311a4934da878d60e82a4402a..c8be207ec007f0c7f677d5f4a21632fe
right: 0;
left: auto;
width: 236px;
@@ -168,34 +171,66 @@ const dropdownId = id ? `dropdown-${id}` : "dropdown-0";
@@ -168,34 +186,66 @@ const dropdownId = id ? `dropdown-${id}` : "dropdown-0";
</style>

<script>
Expand All @@ -75,6 +104,10 @@ index 5a44e3674908f7a311a4934da878d60e82a4402a..c8be207ec007f0c7f677d5f4a21632fe
- ?.classList.remove("show")
- );
- dropdownMenu.classList.toggle("show");
- });
-
- document.addEventListener("click", () => {
- dropdownMenu?.classList.remove("show");
+ let listeners: AbortController | undefined;
+
+ function initializeDropdowns() {
Expand Down Expand Up @@ -130,10 +163,6 @@ index 5a44e3674908f7a311a4934da878d60e82a4402a..c8be207ec007f0c7f677d5f4a21632fe
+ }, { signal });
});

- document.addEventListener("click", () => {
- dropdownMenu?.classList.remove("show");
- });
-
- dropdownMenu?.addEventListener("click", (e) => {
- e.stopPropagation();
- });
Expand Down
11 changes: 11 additions & 0 deletions src/frontend/scripts/generate-icon-sprite.ts
Original file line number Diff line number Diff line change
@@ -0,0 +1,11 @@
/**
* Regenerates `src/assets/icons/starlight-icons.sprite.svg` from Starlight's icon set for the
* names listed in `src/utils/icon-sprite.ts`. Run with `bun run icon-sprite`.
*/
import { writeFile } from 'node:fs/promises';
import { Icons } from '../node_modules/@astrojs/starlight/components-internals/Icons';
import { renderIconSprite } from '../src/utils/icon-sprite';

const output = new URL('../src/assets/icons/starlight-icons.sprite.svg', import.meta.url);
await writeFile(output, renderIconSprite(Icons));
console.log(`Wrote ${output.pathname}`);
1 change: 1 addition & 0 deletions src/frontend/src/assets/icons/starlight-icons.sprite.svg
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
69 changes: 7 additions & 62 deletions src/frontend/src/components/OsAwareTabs.astro
Original file line number Diff line number Diff line change
Expand Up @@ -17,67 +17,12 @@ const { syncKey = 'terminal' } = Astro.props;
</TabItem>
</Tabs>

{syncKey && <script is:inline define:vars={{ syncKey }}>
(function() {
// Check if localStorage is available
if (typeof localStorage === 'undefined') return;
{syncKey && <span hidden data-os-aware-tabs-sync-key={syncKey} />}

function activateTabByLabel(starlightTabs, label) {
const tabs = Array.from(starlightTabs.querySelectorAll('[role="tab"]'));
const panels = Array.from(starlightTabs.querySelectorAll(':scope > [role="tabpanel"]'));
const tabIndex = tabs.findIndex((tab) => tab.textContent?.trim() === label);
<script>
// Bundled once per site instead of an inline script per component instance.
import { initOsAwareTabs } from '@scripts/os-aware-tabs';

if (tabIndex < 0) return;

tabs.forEach((tab, index) => {
if (!(tab instanceof HTMLElement)) return;
const isSelected = index === tabIndex;
tab.setAttribute('aria-selected', isSelected ? 'true' : 'false');
tab.setAttribute('tabindex', isSelected ? '0' : '-1');
});

panels.forEach((panel, index) => {
if (!(panel instanceof HTMLElement)) return;
if (index === tabIndex) {
panel.removeAttribute('hidden');
}
else {
panel.setAttribute('hidden', 'true');
}
});
}

const storageKey = `starlight-synced-tabs__${syncKey}`;
const existingPreference = localStorage.getItem(storageKey);

// Only set default if user hasn't made a choice yet
if (existingPreference) return;

// Detect OS using multiple methods for reliability
// Check userAgentData.platform first (modern), then navigator.platform, then userAgent
let isWindows = false;

// Check modern API first
const platform = navigator.userAgentData?.platform;
if (platform) {
isWindows = /windows/i.test(platform);
}
// Fallback to legacy APIs
else if (typeof navigator.platform === 'string') {
isWindows = /^Win/i.test(navigator.platform);
}
else if (typeof navigator.userAgent === 'string') {
isWindows = /Win(dows|32|64)/i.test(navigator.userAgent);
}

// Set default tab based on OS
// Windows users get PowerShell, everyone else gets Bash
const defaultTab = isWindows ? 'PowerShell' : 'Bash';

localStorage.setItem(storageKey, defaultTab);

document
.querySelectorAll(`starlight-tabs[data-sync-key="${syncKey}"]`)
.forEach((starlightTabs) => activateTabByLabel(starlightTabs, defaultTab));
})();
</script>}
initOsAwareTabs();
document.addEventListener('astro:page-load', initOsAwareTabs);
</script>
Loading
Loading