From d634e22d47c8cef6054acf9f8b90c7461e409985 Mon Sep 17 00:00:00 2001 From: Will Manning Date: Wed, 4 Nov 2026 14:04:51 -0500 Subject: [PATCH 1/9] Explorer: copy design system v120 Function names in code take the gold syntax-function colour, and the copy drops rules the Explorer does not draw (FilterChip, FileMap, DetailStrip, vx-page, vx-band, vx-split, vx-lede, vx-stat). Signed-off-by: Will Manning --- vortex-web/src/styles/vortex-tokens.css | 7 +-- vortex-web/src/styles/vortex.css | 76 ++----------------------- 2 files changed, 7 insertions(+), 76 deletions(-) diff --git a/vortex-web/src/styles/vortex-tokens.css b/vortex-web/src/styles/vortex-tokens.css index 6f736e2a23e..938a6a91e4f 100644 --- a/vortex-web/src/styles/vortex-tokens.css +++ b/vortex-web/src/styles/vortex-tokens.css @@ -1,7 +1,7 @@ /* Vortex design system tokens, copied by tools/site-styles.mjs. Edit the system, then run tools/site-styles.mjs; do not edit here. Made by: node tools/site-styles.mjs --sections base,site,tables,app,focus --base - sha256 a837268db37ce246591addb34264a88e9290b620a84c894fdf8b4b191280b76f */ + sha256 8dc23dccb215c58c2ff3a26443eb2e86ca16e776835bcce4661ec2d9eef81240 */ :root, [data-theme="dark"] { --white: #ffffff; --grey-50: #fcfcf9; @@ -44,7 +44,7 @@ --warn-ink: var(--orange); --syntax-plain: var(--grey-300); --syntax-keyword: var(--blue-soft); - --syntax-function: #c9a8f5; + --syntax-function: #f4df9a; --syntax-type: #6fcfd6; --syntax-string: #f2a0c2; --syntax-comment: var(--grey-450); @@ -172,7 +172,6 @@ --radius-card: 6px; --radius-full: 999px; --page-max: 1440px; - --content-max: 1344px; --measure: 54ch; --page-pad: 48px; --gutter: 24px; @@ -195,9 +194,7 @@ .vx-h3 { font-family: var(--font-display); font-size: 28px; line-height: 1.15; font-weight: 500; letter-spacing: -0.02em; } .vx-h4 { font-family: var(--font-display); font-size: 22px; line-height: 1.2; font-weight: 600; letter-spacing: -0.02em; } .vx-h5 { font-family: var(--font-display); font-size: 18px; line-height: 1.25; font-weight: 600; letter-spacing: -0.01em; } -.vx-stat { font-family: var(--font-display); font-size: 30px; line-height: 1; font-weight: 500; letter-spacing: -0.02em; } .vx-reading { font-family: var(--font-sans); font-size: 17px; line-height: 1.7; font-weight: 400; letter-spacing: 0; } -.vx-lede { font-family: var(--font-sans); font-size: 18px; line-height: 1.5; font-weight: 300; letter-spacing: -0.005em; } .vx-body { font-family: var(--font-sans); font-size: 16px; line-height: 1.6; font-weight: 400; letter-spacing: 0; } .vx-small { font-family: var(--font-sans); font-size: 14px; line-height: 1.5; font-weight: 400; letter-spacing: 0; } .vx-caption { font-family: var(--font-sans); font-size: 12.5px; line-height: 1.4; font-weight: 400; letter-spacing: 0; } diff --git a/vortex-web/src/styles/vortex.css b/vortex-web/src/styles/vortex.css index ff6fac6e4e3..178cc281065 100644 --- a/vortex-web/src/styles/vortex.css +++ b/vortex-web/src/styles/vortex.css @@ -1,7 +1,7 @@ /* Vortex design system components (sections: base, site, tables, app, focus), copied by tools/site-styles.mjs. Edit the system, then run tools/site-styles.mjs; do not edit here. Made by: node tools/site-styles.mjs --sections base,site,tables,app,focus --base - sha256 b4802f5118685e56475939eed3023f73d2de0096e7da25b39e2126b3e1c9180b */ + sha256 f72dcbd5bd26d786f0f151e872964fb81a282c42d4b796fa04da0dd2da9692bd */ /* ------------------------------------------------------------------ base */ /* Every component sizes with border-box, so it draws the same under a site's reset or none. */ @@ -69,7 +69,6 @@ main[tabindex="-1"]:focus { user-select: all; overflow-wrap: anywhere; } -.vx-stat, .vx-num { font-variant-numeric: tabular-nums; } @@ -119,31 +118,16 @@ main[tabindex="-1"]:focus { /* Headings take ink, so a page never has to say so. It sits in base, which every site copies. :where() keeps it at no specificity, so any component that colours its own headings wins. */ -:where(.vx-display, .vx-display-mono, .vx-h1, .vx-h2, .vx-h3, .vx-h4, .vx-h5, .vx-stat) { color: var(--ink); } +:where(.vx-display, .vx-display-mono, .vx-h1, .vx-h2, .vx-h3, .vx-h4, .vx-h5) { color: var(--ink); } -/* An encoding chain: mono steps on raised, joined by arrows. A post and DetailStrip +/* An encoding chain: mono steps on raised, joined by arrows. A post and the Explorer both draw it, so it sits in base, which every site copies. */ .vx-chain { display: flex; flex-wrap: wrap; align-items: center; gap: var(--space-8); font: 400 12.5px/1 var(--font-mono); color: var(--ink-body); } .vx-chain-step { padding: var(--space-4) var(--space-8); background: var(--raised); border: 1px solid var(--edge); border-radius: var(--radius-control); } .vx-chain-arrow { color: var(--ink-muted); } /* ------------------------------------------------------------------ site */ -/* Page: the frame and the bands a page is built from. .vx-page holds the header, a main and the - footer in a column, so the footer sits at the bottom of a short page. A .vx-band is one slice of - the page, at page-max with page-pad on both sides, as the header and footer are. */ -.vx-page { min-height: 100dvh; display: flex; flex-direction: column; } -.vx-page > main { flex: 1 0 auto; } -.vx-band { width: 100%; max-width: var(--page-max); margin-inline: auto; padding: var(--space-80) var(--page-pad); } -.vx-band.is-compact { padding-block: var(--space-48); } -@media (min-width: 761px) { - .vx-band { padding-block: var(--space-152); } - .vx-band.is-compact { padding-block: var(--space-120); } -} -/* A page head: an Eyebrow, the heading and a lede, at the reading measure. */ -.vx-page-head { display: grid; justify-items: start; gap: var(--space-18); max-width: 840px; } -.vx-page-head > * { margin: 0; } -.vx-page-head > .vx-lede { color: var(--ink-body); } /* The frame: the terminal's dashed rule, 1px wide, 12px on and 4px off, in ink-body. The header draws it below itself and the footer above itself, on the side that faces the page, and a .vx-frame box draws it on all four, over the ground, so it can sit on the ASCII mark. Inside a @@ -160,11 +144,6 @@ main[tabindex="-1"]:focus { background-position: left top, left bottom, left top, right top; } .vx-frame .vx-tabs-list { border-bottom: 0; background: var(--vx-dash-x) left bottom / 16px 1px repeat-x; } -/* Two columns on the 24px gutter. They stack at 760px. */ -.vx-split { display: grid; grid-template-columns: repeat(2, minmax(0, 1fr)); gap: var(--gutter); align-items: start; } -@media (max-width: 760px) { - .vx-split { grid-template-columns: minmax(0, 1fr); } -} .vx-btn { display: inline-flex; align-items: center; @@ -621,29 +600,6 @@ html:has(.vx-header.has-tools) { scroll-padding-top: calc(var(--space-64) + var( .vx-table.is-data tr.is-spacer td { height: auto; padding: 0; border: 0; } /* ------------------------------------------------------------------ app: Explorer */ -/* Chips filter a view. A pressed chip is a selected item: an accent-soft wash and an accent-ink border, which holds 3:1. */ -.vx-chips { display: flex; flex-wrap: wrap; align-items: center; gap: var(--space-8); } -.vx-chip { - appearance: none; - display: inline-flex; - align-items: center; - height: var(--control-sm); - margin: 0; - padding: 0 var(--space-12); - background: var(--raised); - border: 1px solid var(--edge); - border-radius: var(--radius-control); - font: 400 12.5px/1 var(--font-sans); - color: var(--ink-body); - cursor: pointer; - transition: border-color var(--vx-motion), color var(--vx-motion), background-color var(--vx-motion); -} -.vx-chip:hover { border-color: var(--ink); color: var(--ink); } -.vx-chip[aria-pressed="true"] { background: var(--accent-soft); border-color: var(--accent-ink); color: var(--ink); } -/* After the pressed rule, so a press shows on a chip that is already on. */ -.vx-chip:active { background: var(--edge); } -.vx-chip.is-all { font-weight: 500; } - .vx-tree { padding: var(--space-8) 0; font: 400 12.5px/1 var(--font-mono); } .vx-tree-node { display: grid; @@ -676,18 +632,8 @@ html:has(.vx-header.has-tools) { scroll-padding-top: calc(var(--space-64) + var( .vx-tree-toggle.is-leaf { visibility: hidden; } .vx-tree-node:hover .vx-tree-toggle { fill: var(--ink); } -/* A selected segment carries an accent ring, and the others step back. */ -.vx-filemap { display: grid; gap: var(--space-8); } -.vx-filemap-bar { display: flex; height: 34px; border: 1px solid var(--edge); border-radius: var(--radius-control); overflow: hidden; } -.vx-filemap-bar > button { all: unset; box-sizing: border-box; display: block; height: 100%; border-right: 1px solid var(--surface); background: var(--vx-dt-fill); box-shadow: inset 0 0 0 1px var(--vx-dt-edge); cursor: pointer; transition: opacity var(--vx-motion); } -.vx-filemap-bar > button[aria-pressed="true"] { box-shadow: inset 0 0 0 2px var(--accent); } -.vx-filemap-bar:has(> [aria-pressed="true"]) > button:not([aria-pressed="true"]) { opacity: 0.4; } -.vx-filemap-axis { display: flex; justify-content: space-between; } -.vx-filemap-legend { display: flex; flex-wrap: wrap; gap: var(--space-8) var(--space-16); font: 400 12.5px/1.3 var(--font-sans); color: var(--ink-muted); } -.vx-filemap-swatch { display: inline-block; width: 10px; height: 10px; margin-right: var(--space-8); vertical-align: -1px; background: var(--vx-dt, var(--chart-muted)); } - /* Dtype colours: one per dtype family (components/lib/dtype.js names the family), shared by the - tree's dots, the file map, and every Explorer view. Five families take chart-2 to chart-6, never + tree's dots and every Explorer view. Five families take chart-2 to chart-6, never Blue. A list or struct is muted, because its children carry their own colours. The dtype's name always shows beside its colour, so the colour is never the only cue. */ .vx-dt-int { --vx-dt: var(--chart-5); } @@ -732,18 +678,6 @@ html:has(.vx-header.has-tools) { scroll-padding-top: calc(var(--space-64) + var( .vx-facts dt { margin: 0; } .vx-facts dd { margin: 0; color: var(--ink); font: 400 13px/1.4 var(--font-mono); font-variant-numeric: tabular-nums; overflow-wrap: anywhere; } -/* The detail strip measures its own width, so it lays out the same in any column. */ -.vx-detail { container-type: inline-size; overflow: hidden; } -.vx-detail-head { display: flex; flex-wrap: wrap; align-items: baseline; gap: var(--space-12); padding: var(--space-12) var(--space-16); border-bottom: 1px solid var(--line); } -.vx-detail-name { color: var(--ink); } -.vx-detail-cells { display: grid; grid-template-columns: minmax(0, 1fr) minmax(0, 0.8fr) minmax(0, 1.6fr); gap: 1px; background: var(--line); } -.vx-detail-cell { display: grid; gap: var(--space-8); align-content: start; padding: var(--space-12) var(--space-16); background: var(--surface); } -.vx-detail-value { color: var(--ink); } -@container (max-width: 520px) { - .vx-detail-cells { grid-template-columns: repeat(2, minmax(0, 1fr)); } - .vx-detail-cell:last-child { grid-column: 1 / -1; } -} - .vx-status-line { display: flex; flex-wrap: wrap; gap: var(--space-8) var(--space-20); padding: var(--space-8) var(--space-20); border-top: 1px solid var(--line); } .vx-status-item { display: inline-flex; align-items: center; gap: var(--space-8); } .vx-status-item::before { content: ""; width: 6px; height: 6px; border-radius: var(--radius-full); background: var(--status-idle); } @@ -757,4 +691,4 @@ html:has(.vx-header.has-tools) { scroll-padding-top: calc(var(--space-64) + var( segments inside a clipped container draw it inside their edge. */ :is(a, button, input, select, textarea, summary, [tabindex]):focus-visible, .vx-docs-toggle:focus-visible ~ .vx-docs-header .vx-docs-menu { outline: 2px solid var(--focus-ring); outline-offset: 2px; } -:is(.vx-docs-nav a, .vx-docs-nav summary, .vx-docs-toc a, .vx-docs-fold a, .vx-post-row, .vx-tree-node, .vx-filemap-bar > button, .vx-tabs-list button, .vx-switch button, .vx-theme-switch button, .vx-table-wrap :is(a, button), .vx-docs-main table.docutils a):focus-visible { outline-offset: -2px; } +:is(.vx-docs-nav a, .vx-docs-nav summary, .vx-docs-toc a, .vx-docs-fold a, .vx-post-row, .vx-tree-node, .vx-tabs-list button, .vx-switch button, .vx-theme-switch button, .vx-table-wrap :is(a, button), .vx-docs-main table.docutils a):focus-visible { outline-offset: -2px; } From b04aedda5296d9c4e145c0dd34d563b702399520 Mon Sep 17 00:00:00 2001 From: Will Manning Date: Wed, 4 Nov 2026 15:45:24 -0500 Subject: [PATCH 2/9] Docs: draw the shared header, footer, and 404 The docs now draw the header every Vortex surface shares: the wordmark, the links to Docs, Bench, Explorer, Blog, and Slack, the search, the theme switch, and GitHub. The footer is the shared one, with the LF logo. A theme chosen on any vortex.dev surface holds here too. An address that matches no page gets the shared 404 page, with a 404 status. Titles read " | Vortex". The CSP now allows the docs' own font, which it blocked before. Signed-off-by: Will Manning --- .github/vercel-cli/pages-html-routes.py | 6 + LICENSES/LicenseRef-Third-Party.txt | 6 + REUSE.toml | 8 + docs/_ext/vortex_theme.py | 17 +- docs/_static/lf_white.svg | 42 ++ docs/_static/vortex-header.js | 21 + docs/_static/vortex-theme-bootstrap.js | 5 + docs/_static/vortex-theme.js | 164 ++++++++ docs/_theme/vortex/404.html | 25 ++ docs/_theme/vortex/layout.html | 85 ++-- docs/_theme/vortex/system/vortex-tokens.css | 22 +- docs/_theme/vortex/system/vortex.css | 438 ++++++++++++++++++-- docs/_theme/vortex/vortex.css | 19 +- docs/conf.py | 2 + docs/vercel-output-config.json | 4 +- 15 files changed, 783 insertions(+), 81 deletions(-) create mode 100644 LICENSES/LicenseRef-Third-Party.txt create mode 100755 docs/_static/lf_white.svg create mode 100644 docs/_static/vortex-header.js create mode 100644 docs/_static/vortex-theme-bootstrap.js create mode 100644 docs/_static/vortex-theme.js create mode 100644 docs/_theme/vortex/404.html diff --git a/.github/vercel-cli/pages-html-routes.py b/.github/vercel-cli/pages-html-routes.py index c4952910308..5851b99cb6d 100644 --- a/.github/vercel-cli/pages-html-routes.py +++ b/.github/vercel-cli/pages-html-routes.py @@ -44,6 +44,12 @@ def html_routes(static: Path) -> list[dict]: # Only reached when no file or directory matched. redirect(r"^/(.+)/$", "/$1", 307), {"src": r"^/(.+)$", "dest": "/$1.html", "check": True}, + # An address that matches no file gets the build's 404 page, with a 404 status. + *( + [{"handle": "error"}, {"src": "^/.*$", "dest": "/404.html", "status": 404}] + if (static / "404.html").is_file() + else [] + ), ] diff --git a/LICENSES/LicenseRef-Third-Party.txt b/LICENSES/LicenseRef-Third-Party.txt new file mode 100644 index 00000000000..e5f7ba5df2f --- /dev/null +++ b/LICENSES/LicenseRef-Third-Party.txt @@ -0,0 +1,6 @@ +Files marked LicenseRef-Third-Party are not licensed by the Vortex project. + +The Apache-2.0 and CC-BY-4.0 grants that cover the rest of this repository do not apply to +them. Copyright in each file belongs to the holder named in its SPDX-FileCopyrightText entry +in REUSE.toml, and any trademarks it shows belong to their owners. For permission to reuse +one of these files, contact its holder. diff --git a/REUSE.toml b/REUSE.toml index b371aaf2d67..fe06a93fc2b 100644 --- a/REUSE.toml +++ b/REUSE.toml @@ -21,6 +21,14 @@ precedence = "override" SPDX-FileCopyrightText = "2024 The Geist Project Authors (https://github.com/vercel/geist-font.git)" SPDX-License-Identifier = "OFL-1.1" +# The Linux Foundation's logo, in the footer of the docs and the Explorer, belongs to the Linux +# Foundation. +[[annotations]] +path = ["docs/_static/lf_white.svg", "vortex-web/public/lf_white.svg"] +precedence = "override" +SPDX-FileCopyrightText = "The Linux Foundation" +SPDX-License-Identifier = "LicenseRef-Third-Party" + # BtrBlocks diagram is licensed under CC-BY-4.0. [[annotations]] path = "vortex-btrblocks/decision-tree.*" diff --git a/docs/_ext/vortex_theme.py b/docs/_ext/vortex_theme.py index 0694c4977ba..5a0161c738c 100644 --- a/docs/_ext/vortex_theme.py +++ b/docs/_ext/vortex_theme.py @@ -4,7 +4,8 @@ and fail the build if a copy of the system was edited by hand 2. Load only one CSS and no JS per page except search page 3. Rewrite TOC into detail/summary with regex so it loads without JS -4. Minify CSS +4. Make the 404 page's relative URLs root-relative, since it is served at any address +5. Minify CSS """ from __future__ import annotations @@ -102,9 +103,23 @@ def _toc(app: Sphinx, pagename: str, templatename: str, context: dict[str, Any], context["vortex_globaltoc"] = html +# The 404 page is served at whatever address missed, so its relative links and assets would resolve +# against that address. Every relative URL in it becomes root-relative. +_RELATIVE_URL = re.compile(r'((?:href|src)=")(?![a-z][a-z0-9+.-]*:|/|#)') + + +def _root_relative_404(app: Sphinx, exception: Exception | None) -> None: + if exception is not None or app.builder.format != "html": + return + page = Path(app.outdir) / "404.html" + if page.exists(): + page.write_text(_RELATIVE_URL.sub(r"\1/", page.read_text())) + + def setup(app: Sphinx) -> dict[str, Any]: _GEN_STATIC.mkdir(parents=True, exist_ok=True) app.connect("builder-inited", _css) app.connect("html-page-context", _filter_assets) app.connect("html-page-context", _toc) + app.connect("build-finished", _root_relative_404) return {"parallel_read_safe": True, "parallel_write_safe": True} diff --git a/docs/_static/lf_white.svg b/docs/_static/lf_white.svg new file mode 100755 index 00000000000..316c64c84c4 --- /dev/null +++ b/docs/_static/lf_white.svg @@ -0,0 +1,42 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + diff --git a/docs/_static/vortex-header.js b/docs/_static/vortex-header.js new file mode 100644 index 00000000000..dced92c1c53 --- /dev/null +++ b/docs/_static/vortex-header.js @@ -0,0 +1,21 @@ +// SPDX-License-Identifier: Apache-2.0 +// SPDX-FileCopyrightText: Copyright the Vortex contributors + +// The shared header's scripts (the design system's Header and ThemeSwitch): every theme switch on +// the page, and the Menu, which closes on Escape (focus goes back to its button) and on a click +// outside it. Without scripts the Menu still opens and closes, and the theme follows the OS. +import { mountThemeSwitch } from "./vortex-theme.js"; + +for (const el of document.querySelectorAll(".vx-theme-switch")) mountThemeSwitch(el); + +const menu = document.querySelector(".vx-header-menu"); +if (menu) { + document.addEventListener("keydown", (e) => { + if (e.key !== "Escape" || !menu.open) return; + menu.open = false; + menu.querySelector("summary")?.focus(); + }); + document.addEventListener("pointerdown", (e) => { + if (menu.open && !menu.contains(e.target)) menu.open = false; + }); +} diff --git a/docs/_static/vortex-theme-bootstrap.js b/docs/_static/vortex-theme-bootstrap.js new file mode 100644 index 00000000000..12e9d12ffa4 --- /dev/null +++ b/docs/_static/vortex-theme-bootstrap.js @@ -0,0 +1,5 @@ +// SPDX-License-Identifier: Apache-2.0 +// SPDX-FileCopyrightText: Copyright the Vortex contributors +// The design system's THEME_BOOTSTRAP (components/lib/theme.js), as a file, because the docs' CSP +// allows only scripts from their own origin. Load it in , before the stylesheets. +(function(){var r=document.documentElement,c="system",v=null,t=null,ok=!t;if(t){var p=location.pathname;for(var i=0;i. The choice itself also lands on , so the switch +// can show it pressed before its script runs. +// +// A site whose other pages are Dark only passes `themeable`, a list of path prefixes: "/blog" +// covers /blog and every page under it. Pages outside the list stay Dark whatever the choice. +// It is a list and not a function because the bootstrap carries it into an inline script as data. +const KEY = "vx-theme"; +const CHOICES = ["light", "dark", "system"]; +const PLAIN_PATH = /^\/[\w.~\/-]*$/; +const DEFAULT = "system"; +const YEAR = 31536000; +const COOKIE = /(?:^|;\s*)vx-theme=([^;]*)/; + +// "/blog/" and "/blog" are one prefix. "/" stays "/". +const trim = (prefix) => (prefix.length > 1 ? prefix.replace(/\/+$/, "") : prefix); + +/** Whether `path` takes the reader's theme. With no list, every path does. */ +export function isThemeable(path, themeable) { + if (!themeable) return true; + return themeable.map(trim).some((p) => path === p || path.startsWith(p === "/" ? "/" : `${p}/`)); +} + +/** + * The no-flash snippet for a site where only `themeable` paths follow the choice (every path when + * it is left out). Paste it into an inline classic {%- for css in css_files %} {{ css_tag(css) }} {%- endfor %} + {%- block scripts %} {%- for js in script_files %} {{ js_tag(js) }} @@ -50,29 +55,34 @@ {{ _('Skip to content') }} - -
- - - - - Vortex - - {{ _('Docs') }} - - - + +{#- The shared header (the design system's Header): the wordmark, the surfaces' links with Docs + current, the search and the sidebar's button in the docs' tools, then the theme switch, GitHub, + and the Menu. #} +{%- macro nav_links() %} +{{ _('Docs') }}{{ _('Bench') }}{{ _('Explorer') }}{{ _('Blog') }}Slack +{%- endmacro %} +{%- macro theme_switch() %} +
+{%- endmacro %} +
+
VortexVortex
+ +
+ + + +
+
+ {{ theme_switch() }} + vortex-data/vortex +
+ {{ _('Menu') }} + +
+
+{%- block frame %}
-