Repository navigation
Show each port picker row's matched API, cut at its separators - #333
Merged
Merged
Conversation
…eparators why: On an API page the port picker named only the language and, for some rows, its differences; the matched API appeared only as `name (kind)` when a port had several. Design records 0030 and 0068 put the matched API on one line under each row, and record 0069 cuts a name that does not fit at its separators, keeping the right end, so a Java or Kotlin row reads `…kotlin.Pane.capture` rather than `io.github.libtmux.Pan…`. what: - page-port-links: every symbol exit carries `api`, the target's qualified name - PagePortSwitcher: the API line (mono, 0.75rem) leads a row's muted lines; a row's accessible name and title keep its label, or the full API name where it has none; such rows widen the panel to 32rem; the row's text fills the row so a name is measured against the room it has - lib/qualified-name.ts: abbreviateQualifiedName (separator-aware candidates scored for right-end context, owner and distinctness from the other rows; a call's arguments go first; a grapheme fallback) and fitQualifiedNames, measured with the label's font - documentation-navigation: fits the names on open and on resize - Tests: the cut rule on fixed-width cases, the row's API line and accessible name, the exit link's `api`; the workspace picker page inlines lib/qualified-name.ts
…e caution ink
why: The design system draws a picker row's differences ("3 overloads",
"on Server") in the caution ink at weight 500; the site drew them in
plain muted grey, and the hover rule for a row's small text would have
greyed them again.
what:
- documentation-picker.css: the differences line takes
--aside-caution-ink at 500, on hover too
- design-tokens test pins the rule
why: Design record 0071 asks for touch-target rows under pointer: coarse at every width. In the left-column and outline drawers, measured on a phone and a landscape phone, the sidebar head's up link (28px) and title (20px) and the outline's links (28px) were the only links under 44px. what: - The sidebar head's up link and title take the same hit-area pseudo element as the header's chips, so the head keeps its height - The outline drawer's links become touch-target-tall rows - design-tokens test pins both rules
why: The port picker shows an icon for all 23 ports, but the Programming-language artwork table credited 16. The Julia, Perl, Haskell, Clojure, Elixir, Erlang and PowerShell icons are Devicon copies with a local MIT notice and no row, so the page omitted their copyright holder and terms. what: - Add rows for Julia, Perl, Haskell, Clojure, Elixir, Erlang and PowerShell, each crediting the Devicon collection (copyright (c) 2015 konpa), linking its local LICENSE.txt and provenance.json - Take the credit text from each provenance record: the language marks belong to their respective projects, and no other terms are recorded, so none are added - Place each row after the nearest earlier port in port-families.ts order; existing rows keep their positions - Leave the modified-SVG sentence as is: only Scala, Common Lisp and Rust record modifications
why: Design record 0071 asks every row, tab, chip and button to be at least touch-target (2.75rem) tall under `pointer: coarse` at every width, through its hit area where the drawn control stays smaller. The header, sidebar head, outline drawer, pickers and API tree already do; the page content did not. Measured in Chromium with touch emulation, counting each control's tap height as the run of `elementFromPoint` hits from its centre, and leaving out links inside running text: page 1024x768 390x844 /reference/pane-pane-capture/ 95 -> 2 93 -> 0 /reference/pane-pane/ 165 -> 1 163 -> 0 /reference/ 465 -> 1 465 -> 0 /guides/capturing-output/ 47 -> 2 44 -> 1 / 96 -> 2 92 -> 1 Pages at 1280x800 with a mouse lay out identically before and after: every rule is inside `@media (pointer: coarse)`. what: - Hit areas (a `::before` or `::after` of `calc((100% - var(--touch-target)) / 2)` insets) for the member filter chips, the equivalents table's chips, the kind, modifier and source badge links, heading permalinks and `¶` anchors, the qualified-name copy button, the page-actions chip, the context bar's buttons, the release notice's dismiss and More, the footer icon links, the header's scheme switch, the port chips, the install bar's segments and facts link, the copy and pin buttons, the status badge toggle, and the replay's buttons and dots. - Badge and external-link hit areas use `::before`, because the shell draws an external link's mark in `::after`. The kind and modifier tabs drop `overflow: hidden` so the area is not clipped; the kind mark rounds its own corners instead. The replay track grows to the touch target so it does not clip its dots' areas. - Real `min-height` for list-like rows: breadcrumbs, footer links, the page-end up row and related lists, member names, guide, definition and tmux-usage links, the equivalents table's cell links, summaries, the member search input, section search, product tabs, the example toolbar's labels, and the Core showcase options and links. - The code frame's copy button grows from 2.5rem to the touch target with its icon kept at the same size. - Chip rows get a row gap that keeps one row's hit areas off the next. - One test in design-tokens.test.ts pins the rules and that each sits under a coarse media query. Not covered: the sidebar head's up link (its title link sits 8px below it, so it gets 31.5px; the head would have to grow), the Core player's step dots (20px to 24px apart down the program's margin), and links inside running text (WCAG 2.5.8 inline exemption). The API tree's group labels read as 20px in the probe, but their 44px row forwards a tap to the link.
why: #210 found that build_shell() reuses one cached shell for builds that differ only in LIBTMUX_DOCS_SITE or LIBTMUX_DOCS_ROOT. The cache key omitted both, yet the Astro build receives them: the origin sets canonical URLs and the sitemap, the root sets where links resolve. A second build with a different origin or root silently returned the first build's output. what: - Add site_origin and LIBTMUX_DOCS_ROOT to the build_shell cache key. The root defaults to "/" exactly as the build invocation does. - Leave the measurement items in the issue alone. The script has no test for its cache key, and sourcing it runs a whole assembly. Verified by extracting the real build_shell() and driving it with a stub renderer that writes the origin and root it receives. Four calls (default, new origin, new root, default again) gave miss, hit, hit, hit before the change, and miss, miss, miss, hit after: differing builds now miss, and an identical repeat still hits.
why: #188 reported that any change to libtmux-powershell's Directory.Packages.props turns that port's docs build red. validateNavigationDependency threw when the file's sha256 differed from the pin in ports.ts, so a routine LibTmux package bump could not pass its own docs job, and the fix had to land here first. The guard exists so borrowed .NET navigation is reviewed when the declaration changes. Deriving the LibTmux version from the declaration would keep that without a pin, but the port's API model records only the file's digest, not its contents, so the version is not available here without a change to the port's exporter. Keeping the pin and warning keeps the review prompt and stops blocking a build the port cannot fix from its own repository. what: - Warn once per changed digest, naming the new sha256, the pinned version and revision still in effect, and what to record in ports.ts. Under GitHub Actions the warning is a ::warning annotation, as in verify-destinations.mjs, so it shows on the run summary. - Throw clearly when the declaration is missing from the native provenance or its sha256 is not a 64-digit hex digest. - Keep throwing when the .NET model this repository ships differs from the pinned package version or source revision: that is this repository's own data, not the port's declaration. - Replace the changed-declaration assertion in the existing test with a test that a changed digest warns once and does not throw, and that a missing or malformed one still throws. Verified in site/: api-dependency-navigation and five neighbouring api-tree, sidebar, glossary and search suites pass; the new test fails against the previous implementation; oxlint reports no findings in api-tree.ts; astro check reports 0 errors.
tony
force-pushed
the
feat/picker-api-lines
branch
from
November 18, 2026 23:09
c52cb99 to
e20fca8
Compare
…Server.Panes why: #259. The PowerShell landing page and Core overview on libtmux.org print `Snapshot.Panes` five times, and the player says `Get-TmuxSnapshot` returned a `Snapshot`. The cmdlet declares `[OutputType(typeof(Server))]` and the library has no `Snapshot` type, so `$snapshot.Panes` reads `LibTmux.Server.Panes`. The C# recipe already names this step `Server.Panes`. The wrong label also needed an exemption in the Core player's links test, which hid the broken link. what: - scripts/lib/core-recipes/powershell.mjs: the `snapshot` step's type is `Server`, and the `pane-lookup` step's label is `Server.Panes`. - site/src/data/core-recordings/powershell.json: recorded again with `scripts/gen-core-recording.mjs --port powershell` against libtmux-powershell at 2c30121 (the recorded revision), tmux 3.8a and PowerShell 7.4.20. The program hash is unchanged. The type and label are the only semantic changes. The other lines are per-run values: the library's version-probe and field-separator nonces, server pids and start times, and the order of two control-mode lines (`%exit` and `%client-detached`). - site/test/core-apis.test.ts: drop the `Snapshot.Panes` exemption, so every PowerShell step label must link into the API models. The test fails against the old recording. Source: https://github.com/libtmux/libtmux-powershell/blob/2c30121b7733bf772d17140231a49332e5a470ab/src/LibTmux.PowerShell/GetTmuxSnapshotCommand.cs#L7-L8
…x tree why: #168. The Sphinx tree under /en/py/latest/api/ still advertised the legacy host. Probed 2026-10-18, /api/libtmux.pane/ carried og:url https://libtmux.git-pull.com/api/libtmux.pane/ and no rel="canonical", and api/sitemap.xml listed only libtmux.git-pull.com URLs. Redirecting the legacy host to pages whose own signals name it undoes the redirect. The cause is upstream's conf.py, which the build passed through unchanged. It sets docs_url to the legacy host; gp-sphinx 0.1.0a39 derives ogp_site_url, site_url (sitemap, llms.txt) from it; and gp-furo emits a canonical only when html_baseurl is set, which nothing set. what: - version-bookkeeping.sh: add sphinx_url_settings, which builds the four settings with canonicalUrl from versions.ts. html_baseurl and ogp_canonical_url (canonical link, og:url) name the port's default version, as an Astro page does; site_url and ogp_site_url (sitemap, llms.txt, images) name the version being built - build-site.sh: pass them to sphinx-build as -D, so conf.py stays untouched, and fail the reference build if they cannot be computed - build-site.sh: key the reference cache on origin, root and default version, which now change the output - Seo.astro: name the libtmux.org Python home, under the port's default version, as the structured-data url instead of libtmux.git-pull.com; sameAs keeps the legacy host as an alias of the same project - versions.test.ts: assert the four settings for the default version and for a non-default build Verified with a Sphinx build of the libtmux docs at gp-sphinx 0.1.0a39: pages carry canonical and og:url under https://libtmux.org/en/py/latest/api/, and sitemap.xml, llms.txt and docs.json name no legacy host. Tagged versions follow versions.ts and canonicalise to the default version; whether that default is latest is #167.
tony
added a commit
that referenced
this pull request
Nov 19, 2026
) why: #333 landed on main as a626ef8 while this branch was in review. The design owner asked for design-tokens.test.ts to run against this branch merged onto that main before it merges, and the docs test should run on the combined tree. what: - Take main at a626ef8: port picker rows show the API they matched, and touch screens get 44px tap targets - No conflicts; the tree equals git merge-tree of main and this branch
This branch was successfully deployed
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
On an API page, each port picker row now names the API it goes to, and a name too long for its row is cut at its separators, keeping the end that names the API: a Kotlin row reads
…kotlin.Pane.capture, SwiftServer.capture(…).Why
Until now the picker named only the language and, on some rows, what differs; the matched API showed only as
name (kind)when a port had several. Design records 0030 and 0068 (libtmux/design) put the matched API on one line under each row, and record 0069 cuts a name that does not fit at its separators rather than at its end, where the method name is.What changes
page-port-links.ts: every symbol exit carriesapi, the target symbol's qualified name.PagePortSwitcher.astro: the API line leads a row's muted lines in mono at 0.75rem; the row's accessible name and title keep its label, or the full API name where it has none; rows with an API line widen the panel to 32rem; the row's text fills the row so a name is measured against the room it has.qualified-name.ts:abbreviateQualifiedNamecuts at.,::,#,/and:, never inside a component, keeps brackets, backticks and arity whole, prefers the right end, keeps an owner such asio.github.libtmuxwhole or drops it, prefers a form no other row shares, and drops a call's arguments before its owner;fitQualifiedNamesmeasures with the label's own font.documentation-navigation.ts: fits the names when a picker opens and on resize.documentation-picker.css: a row's differences take the caution ink at weight 500, on hover too, as the design system draws them; they were plain muted grey.global.css: on touch screens the left-column drawer's head links take a 44px hit area without growing the head, and the outline drawer's links become 44px rows (design record 0071). The drawers were already full-height side sheets with the scrim and scroll lock; these links were the only ones under 44px on a phone and a landscape phone.pointer: coarse; desktop geometry is unchanged.third-party-notices.md: rows for the Julia, Perl, Haskell, Clojure, Elixir, Erlang and PowerShell icons (Devicon, MIT), so all 23 icons the picker shows are credited.api-tree.ts: a changedDirectory.Packages.propsin libtmux-powershell warns (a::warningannotation in Actions) and keeps the pinned .NET navigation, instead of failing the port's docs build. A missing or malformed declaration still fails. Fixes A PowerShell dependency bump fails its docs build untilports.tsis updated #188.build-site.sh: the shell cache key includes the site origin andLIBTMUX_DOCS_ROOT, so builds that differ only in those no longer share a cached shell. Refs Reduce repeated docs builds, S3 uploads, and retained output #210 (its measurement items stay open).powershell.mjsandpowershell.json: the PowerShell Core player saysGet-TmuxSnapshotreturns aServerand labels the lookupServer.Panes, as the cmdlet's[OutputType(typeof(Server))]declares; the recording was made again andcore-apis.test.tsdrops itsSnapshot.Panesexemption, so every PowerShell step label must link into the API model. Fixes PowerShell Core recipe typesGet-TmuxSnapshotasSnapshot, notServer#259.version-bookkeeping.shandbuild-site.sh: the Python Sphinx tree under/en/py/latest/api/names libtmux.org in its canonical link,og:url, sitemap andllms.txt, throughsphinx-build -Dsettings with upstream'sconf.pyuntouched; the reference cache is keyed on origin, root and default version.Seo.astronames the libtmux.org Python home as the structured-dataurl, keeping the legacy host insameAs. Fixes Point the Python Sphinx tree's canonical,og:urland sitemap at libtmux.org #168.Verification
LIBTMUX_DOCS_PORT=rs,pane.Pane.capture, 1280px): rows have 182px for the name. Python, Ruby, Lua, TypeScript, Go, C++, Clojure, C# and Erlang show their names whole; Java…libtmux.Pane.capture, Kotlin…kotlin.Pane.capture, Scala…scaladsl.Pane.capture, SwiftServer.capture(…), OCaml…Client.capture_text, Perl…Server::capture_pane, RakuLibTmux…PaneRef.capture, F#LibTmux…Pane.capture; each row's title and accessible name carry the full name.vitest: qualified-name, documentation-picker-interaction, page-port-links, api-equivalents, complete-examples, design-tokens, chrome-context, header-links-interaction and the workspace picker outer suite: 470 passed.pnpm lintin site passes.vitestafter the rebase onto Show the new Session, Window and Pane directories on perl, raku, erlang and ocaml #331: design-tokens, qualified-name, api-dependency-navigation, documentation-picker-interaction, versions and core-apis: 198 passed. A Sphinx build of the libtmux docs at gp-sphinx 0.1.0a39 carries canonical andog:urlunderhttps://libtmux.org/en/py/latest/api/, and itssitemap.xml,llms.txtanddocs.jsonname no legacy host.