Skip to content

Grow related chips with wrapped names, and pin five finished P0 items - #182

Merged
tony merged 7 commits into
mainfrom
p0-chip-wrap-and-closers
Oct 24, 2026
Merged

tony merged 7 commits into
mainfrom
p0-chip-wrap-and-closers

Conversation

@tony

@tony tony commented Oct 24, 2026

Copy link
Copy Markdown
Contributor

Fixes the crushed "Related APIs" chips on reference pages (reported on Scala Server), and pins five finished P0 items with tests that fail when they regress.

what

  • Chips grow with their name: kind-marks.css gives a related chip a min-height instead of a fixed height, keeps the kind mark one line tall at the first line, and aligns the name's first line with the mark. word-break.ts adds a break opportunity before #, so a member name such as Server#list_sessions can wrap there.
  • Browser check: checkChipGrowth in check-badge-centring.mjs measures the Related APIs chips on the Scala Server, Session, Window, Pane and Client pages. Each chip must hold every line of its name, grow when it wraps, keep its mark one line tall in the corner, and stay clear of its neighbour and inside the column. It runs in check-dev.mjs --badge-centring, with controls for a fixed height, a stretched mark, a lost first-line offset and an overlap.
  • P0 10: ProseText.astro marks the # of a linked member reference with the port-themed separator, by the rule ApiDoc already uses; the pattern lives in api-labels.ts, and a test fails if the two copies drift.
  • P0 22: kind-badge-order.outer.test.ts loads every stylesheet that paints a kind mark in twelve orders in Chromium and requires identical painted colours in light, dark and system dark.
  • P0 3: footer-external-links.test.ts requires the footer's GitHub link to stay icon-only, named GitHub, and outside the external-link glyph selector.
  • P0 12: inline-reference-appearance.test.ts requires one dotted currentColor underline per link, with the code-frame and prose offset and thickness tokens, and no underline on the code inside.
  • P0 2: breadcrumb-font.test.ts requires the breadcrumb trail to stay in the sans face across the root shell and native outlets.

why

A related chip had a fixed one-line height, so a wrapped name overflowed and only its last line showed. The five closers had no test that would notice a regression.

verification

  • Site suite: 5588 tests pass. Lint and astro check are clean.
  • check-dev.mjs --badge-centring passes 846 samples at 1x and 2x, light and dark. Its chip check covers 25 chips, 14 of them wrapped, and catches all four controls.
  • Each new test fails on a planted mutation.

tony added 7 commits October 24, 2026 00:51
why: Ruby writes an instance method as `Server#list_panes`. The break
rule offered no opportunity before `#`, so a name such as
`LibTmux::Server#search_panes` stayed whole in a chip or a tree row
until the container could hold all of it, where a reader would break it
after the class.

what:
- `wordBreak` also breaks before a `#` that sits between two word
  characters: `Async::Server#list_panes` breaks after `::`, before `#`
  and before `_`. Other ports break as before, and a leading or trailing
  hash is not a break point.
- A unit test pins the break points of Ruby names, the unchanged ports,
  and that the parts join back to the name.

Verified: the new test fails when `#` is removed from the pattern and
passes with it.
why: On the Scala Server page at 1440px the Related APIs chips were
crushed. `Session (io.github.libtmux.scaladsl)` wraps onto three lines
in the contents column, but a chip was fixed at the height of one line
and clips its overflow, so each chip showed only `scaladsl)` and the
rest of the name was cut off above it. The same chip draws the "In
other ports" and command-related lists, which crush the same way when a
name wraps (`LibTmux\New-TmuxServer` at 390px).

what:
- A chip has `min-height` of its snapped one-line height instead of
  `height`. A one-line chip keeps exactly the box it had and a wrapped
  name grows the chip by a line each.
- The mark is held to the first line (`align-self: flex-start`, one line
  tall). The name takes the space the first line has in a one-line chip
  as its top margin, so the first line sits level with the mark however
  many lines follow; lines are set at 1.3, which the trimmed text does
  not show on one line. A browser without `text-box` keeps the old rule.
- The rail check expects the mark flush with the chip's corner and as
  tall as the first line, not as tall as the chip. Its controls now name
  the problem each break must cause (link padding insets the mark; a
  squeezed chip does not hold its name; a short mark does not fill a
  line), and fail if the check says something else or nothing. The
  padding control stopped failing once the chip grew around padding.
- `checkChipGrowth` measures the Related APIs chips on the Scala Server,
  Session, Window, Pane and Client pages at 1440px. Each chip must hold
  every line of its name, be taller than a line when it wraps, keep its
  mark one line tall at its top-left corner and level with the first
  line, stay inside the column and clear the next chip. Its controls
  reinstate the old fixed height, stretch the mark down the chip, take
  the first-line offset away and lay one chip over another.
- The judgement is a function of measured boxes, so a unit test writes
  the boxes down for clean, wrapped and each broken chip, and reads the
  stylesheet for the fixed height, the stretched mark and touching
  lines. `CONTRIBUTING.md` says what the gate measures.

Verified against a dev server on port 4531: before the change every
Related APIs chip with a wrapped name was 20px tall around a 28px name;
after it a three-line chip is 47.2px and the one-line chips are 20px as
before. `check-dev.mjs --badge-centring` passes, including the chip
growth check (25 chips, 14 wrapped, four controls caught).

The same check run against a dev server on the previous stylesheet
fails on the Server page, where it stops: the name starts 19px above
the chip, the chip is still one line tall and the first line is 21px off
the mark.

In the unit test, planting back a fixed height, a stretched mark,
touching lines, a dropped overlap rule or a dropped flush rule each
fails the case that names it.
why: A kind mark's border, fill and ink come from several stylesheets
(the palette, the mark treatments, the tree and the generic badge). A
rule of equal specificity in two of them paints one colour or the other
by load order, which is how Ruby's `Server/list_sessions` lost its
border. The fix was source-approved without a test that loads the
sheets in more than one order.

what:
- Load every stylesheet that names a mark into Chromium in the listed
  order, reversed, and with each sheet first and last, and require the
  painted border, fill, ink and ring of every kind to be identical.
- Each kind in the palette is drawn in the places a mark appears: bare,
  in the tree, selected, in a table, in a callout, in the contents
  column, in a related chip and as the legend chip. A kind no family
  claims is drawn too, and must keep the neutral fallback.
- Run in explicit light, explicit dark and system dark. The stylesheets
  are found by what they say, so a new one joins the set.
- The case is an outer-loop test, since only a browser computes the
  cascade, `color-mix()` and `round()` the marks use.

Verified: a `.api-nav__kind { border-color: red }` rule appended to
`api-tree.css` equals the specificity of the mark's base rule in
`kind-marks.css`, and fails all three schemes with the border that
changes; the same rule on `background` in `api-kinds.css` also fails.
Both pass again once removed.
why: External links take a glyph after their text unless they are only
an icon. The footer's GitHub link is that icon, but the checks for icon
links used synthetic markup, so nothing failed if the footer gained text
beside the icon, lost its accessible name or the stylesheet drew the
glyph on icon links.

what:
- Render the real footer, run the external-link installer on it and
  require its one external link to be flagged as an icon, to miss the
  selector the stylesheet draws the glyph on, to hold a hidden svg and
  no text, and to be named `GitHub` with the destination in its
  description.
- Require that no footer link matches the glyph selector, and that a
  text link beside it does, so the selector is not vacuous.
- Require the stylesheet's glyph selector to exclude icon links.

Verified: removing `aria-label`, adding visible text beside the icon and
dropping `:not([data-external-link-icon])` from the stylesheet each fail
the case that names it.
…acing

why: A previewable link carries one dotted underline. The check for it
counted underline owners but not what the owner draws, so the dots could
turn neutral, sit on the frame's bottom border or lose their thickness,
and a name in a code frame could regain its own decoration, without a
failure.

what:
- For a code-chip link, a code frame around a link, a mixed label, a
  plain name and a name beside a kind mark, require exactly one
  underline owner per link, dotted, in `currentColor`.
- Require `.08em` offset and `1px` thickness for a name in a code frame,
  where the dots stay clear of the frame's bottom border, and the looser
  `.2em` with the browser's thickness elsewhere.
- Require the name inside a link to state `text-decoration-line: none`
  where the link owns the cue, so no second line is drawn beneath it.

Verified: changing the framed offset to `.2em`, dropping the thickness,
dropping the `code` rule that states no decoration and setting a white
decoration colour each fail the case.
why: The port palette colours the `#` of a linked `Owner#member` through
`.api-reference-separator`, which `ApiDoc` wraps around the hash. A
sentence written in an `.astro` template renders through `ProseText`,
which linked `java.lang.AutoCloseable#close` as one run, so the same
reference had a coloured hash in a doc comment and a plain one in a
template.

what:
- `ProseText` wraps the `#` of a linked member reference in
  `.api-reference-separator`, by the rule `ApiDoc` uses: a dotted owner,
  a hash and a member. Unlinked code, `C#`, `# comment` and `#{pane_id}`
  stay as they were, and the text, link and copy are unchanged.
- The member-reference pattern and its split live in `api-labels.ts`.
  `ApiDoc` keeps its own copy, since five test harnesses compile it with
  a fixed import list; a test fails if the two patterns differ.
- Tests render the real template with the resolver's decision fixed:
  the hash is marked and takes the link colour of the port it is on,
  other hashes are not, and the pattern matches `ApiDoc`'s.

Verified: leaving the span out, marking every linked hash and changing
the shared pattern each fail the case that names it.
why: A breadcrumb trail mixes a link, a group and a current symbol
crumb. The symbol crumb names code, so a code face is the easy mistake,
and a rule on the toolbar or a port outlet could change the family of
one trail and not another. The existing tests read crumb names and
destinations, not what face they are set in.

what:
- Render the real toolbar with a linked, a group and a current symbol
  crumb. Each crumb is text, with only `<wbr>` break points in the
  symbol crumb, and neither it nor its ancestors up to the trail is code
  markup, carries a `font-*` class other than sans or has inline style.
- Require one implementation of the trail in `src`, so the root shell and
  every port outlet draw it through `PageToolbar`.
- Require that every stylesheet rule on the trail, the toolbar or its
  controls, in a stylesheet or a component `<style>`, that sets
  `font-family` or `font` names `--font-sans`.
- Require the native outlets' `--font-sans` to equal the shell's.

Verified: wrapping the symbol crumb in `<code>`, adding `font-mono` to
the trail, a `[data-breadcrumb-item]` rule in the mono face, a `font`
shorthand on a toolbar control, a native `--font-sans` that names the
mono face and a second `Breadcrumb` navigation each fail the case that
names it. On a dev server the computed family of every crumb on the root
shell and on the Scala, TypeScript, Go, Rust MCP and Python pages is
IBM Plex Sans at 14px and weight 400.
@tony
tony merged commit fcf9965 into main Oct 24, 2026
3 checks passed
@tony
tony temporarily deployed to docs-preview-cleanup October 24, 2026 08:44 — with GitHub Actions Inactive
tony added a commit to libtmux/libtmux-powershell that referenced this pull request Oct 28, 2026
why: The site still presented libtmux as an alpha: badges, notices,
install commands and examples carried alpha pins and prerelease flags,
and a docs channel stood for a release state that no libtmux release
has. A Sphinx project had no inventory to link to, tmux commands and
cross-port links sat in small rows under each declaration, TypeScript
aliases showed no declaration, and native Python documentation pages
listed every page in one flat sidebar column.

what:
- Publish `objects.inv` and `targets.json` at the root of each port
  version, naming the pages, headings, workspace table rows, MCP schema
  fields, command options and API declarations the build rendered, and
  stop the build when an API declaration has no rendered target
  (`inventory.ts`, `inventory-publisher.ts`, `inventory-targets.ts`,
  `targets.ts`; libtmux/docs#166)
- Link the footer of a port page to the inventory of its port version,
  to the full inventory and to a guide on linking from Sphinx, and list
  the same inventory and target files in the `docs.json` manifest
  (`SiteFooter.astro`, `inventory-links.ts`, `docs.json.ts`;
  libtmux/docs#166)
- Export the rows of the shared workspace command and configuration
  tables as Sphinx option, setting and environment variable targets, and
  keep a page's identity across a move through `inventoryId` and
  `inventoryAliases` in its frontmatter (`rehype-row-anchors.ts`,
  `load.md`, `panes.md`, `environment.md`, `content.config.ts`;
  libtmux/docs#166)
- Link the AI policy, which the root site publishes at
  `/meta/ai-policy/`, from the footer (`SiteFooter.astro`,
  `ai-policy.md`; libtmux/docs#194)
- Show a final release on its badge as its series, 0.x for 0.1.0, with
  the line "Released; the API may change.", and replace the alpha notice
  with an early-release notice that returns once for a reader who
  dismissed it (`ports.ts`, `registry.json`, `PrereleaseNotice.astro`;
  libtmux/docs#200)
- Remove the stable docs channel: a release tag publishes at its own
  version, a prerelease also as `next`, and the newest final release tag
  is the default and indexed version, or `latest` while the port has
  none; an older tag pushed later does not take the default
  (`port-docs-identity.sh`, `publish-plan.mjs`, `gen-versions.mjs`,
  `versions.ts`; libtmux/docs#201)
- Leave a release-numbering label such as 0.1.N plain in prose instead
  of resolving it as an API name (`resolver.ts`; libtmux/docs#204)
- Give a symbol's tmux commands, tmux C declarations, hooks, options and
  formats, Guides and equivalents in other ports their own sections on
  its API reference page and in its Markdown export, ahead of Related
  types (`api-tmux-sections.ts`, `ApiTmuxSections.astro`,
  `ApiReference.astro`; libtmux/docs#202)
- Draw the nested guide line in every sidebar layout, set Grouped's
  group headings bold as Outline's are, and make the API glossary the
  last row of the reference sidebar and the last search result
  (`api-tree.css`, `ApiTree.astro`, `api-tree.ts`; libtmux/docs#208)
- Open the preview card of a glossary link only after the pointer rests
  on it for a second, and let Escape cancel a card that has not opened
  (`link-preview-browser.ts`; libtmux/docs#211)
- Let Tab move from the footer's inventory help link to the link in its
  tooltip at once (`SiteFooter.astro`; libtmux/docs#211)
- Set the title of an index-style reference page, such as API reference,
  in the sans face (`ApiReference.astro`; libtmux/docs#211)
- Offer Outline, Focus and Grouped layouts in the reference sidebar's
  menu on the API pages and the Reference pages of each product, keep
  the reader's choice from page to page (`api-tree.ts`), and add Up to
  the selected declaration's parent and Root to the reference index at
  the bottom of the menu (`ApiTree.astro`, `api-sidebar.ts`;
  libtmux/docs#189)
- Fold a sibling list longer than a window into "N more" rows around the
  selected row, which open on a click or from the keyboard and, without
  JavaScript, link to the first page they hold (`api-sidebar.ts`;
  libtmux/docs#189)
- Draw every hover card from one description that the page and the
  browser both render (`link-preview-card.ts`): the legend chip of the
  declaration's kind heads the card, followed by the owner and member in
  the language's own separator (`native-name.ts`; libtmux/docs#190)
- Label a related type with its owner when more than one type in the
  port carries its name (`api-labels.ts`; libtmux/docs#183)
- Record which tmux command each library symbol sends, and at which
  scope, in reviewed records of each library's source, for the tmux
  command of its reference page (`tmux-library-usage.ts`;
  libtmux/docs#184)
- Link a standard-library or SDK name to the page and anchor of the
  symbol it names, not to the pages, options or labels of its manual
  (`inventory.ts`), and never link a dollar-prefixed variable or the
  placeholder text of a printed object (`never-links.ts`;
  libtmux/docs#187)
- Group Elixir under BEAM, beside the JVM and .NET groups, in the port
  picker (`port-families.ts`; libtmux/docs#185)
- Build with `astro` 7.4.2 (was 7.3.5), `@astrojs/mdx` 8.1.1 (was 8.0.3)
  for MDX pages, `@astrojs/markdown-remark` 7.3.4 (was 7.3.2) for
  Markdown and `astro-expressive-code` 0.44.3 (was 0.44.2) for code
  blocks, with the viewport-prefetch patch regenerated for the new Astro
  (`astro@7.4.2.patch`), and install with `pnpm` 12.15.0 (was 12.13.0)
- Link a port's repository, its package host and, where the host serves
  one apart from the package page, its API reference straight from the
  page header (`HeaderLinks.astro`), replacing the GitHub, Packages and
  Docs menus; an unpublished package is never linked (libtmux/docs#181)
- Add a Packages disclosure (`HeaderPicker.astro`) that lists every
  other package, module, product and companion of the port as source,
  package and API reference links from a typed inventory
  (`port-inventory.ts`), with a search over names, coordinates, import
  aliases, repository names, kinds and hosts (libtmux/docs#181)
- Grow a related or In other ports chip with the lines of its name,
  keeping its kind mark one line tall on the first line, where a fixed
  height clipped a name that wrapped (`kind-marks.css`;
  libtmux/docs#182)
- List Elixir with the other ports in the port picker
  (`PagePortSwitcher.astro`) and, for every API reference entry that
  maps to a shared concept, in its In other ports list (`concepts.ts`),
  linking the Elixir counterpart or saying that none is recorded
  (libtmux/docs#179)
- PowerShell header: GitHub opens `src/LibTmux.PowerShell`, the
  PowerShell Gallery link opens the `LibTmux` module, and the Packages
  disclosure lists the repository and `LibTmux.Workspace`
  (libtmux/docs#181)
- Link each of PowerShell's common parameters to its own heading on the
  Microsoft Learn page that documents them, built by one function
  (`powershell-common-parameters.ts`; libtmux/docs#187)
- Show the PowerShell install commands without a prerelease flag:
  `Install-Module` and `Install-PSResource` for LibTmux and
  LibTmux.Workspace, and the three example pages that install LibTmux;
  the attaching guide pins `-Version 0.1.0` (`ports.ts`,
  `attaching-to-tmux.md`, `create-layout.md`; libtmux/docs#200)
- Navigate PowerShell's .NET dependency at LibTmux 0.1.0, in place of an
  alpha pin (`ports.ts`; libtmux/docs#204)
- Regenerate the C# reference that PowerShell pages link into at LibTmux
  0.1.0, which adds `TmuxUnsupportedOnReleaseException` and drops
  `TmuxVersionTooLowException.ActualVersion` (`csharp.json`;
  libtmux/docs#204)
- Link `InnerException` and `NotImplemented` to their .NET pages, and
  let a PowerShell page reach the C# workspace and MCP symbols it cites
  by qualified name, taking a bare member name only when exactly one
  qualified type named earlier in its paragraph has it (`builtins.ts`,
  `mentions.ts`, `parent-inventory.ts`; libtmux/docs#204)
- Record the tmux commands that the PowerShell cmdlets and the C#
  methods send at 0.1.0, with their source lines (`powershell.json`,
  `csharp.json`; libtmux/docs#204)

Shared source: libtmux/docs
From: de7abd597bd9205c54d01498d8cdcb0bb0ec37d9
To:   e1ab401f7d6fca5ac9c418bc6c77ca382320cd2e

This branch was previously deployed

2 inactive deployments
docs-preview-cleanup — 35d3d1c2 Deployed Oct 24, 2026 by tony via cleanup #157
docs-preview — 35d3d1c2 Deployed Oct 24, 2026 by tony via publish-preview / publish #914
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant