its-swiss 0.1.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 844fa90d3877d55f3c22b850b00bedfe6156241216b1165aad929ad3540edbd8
-  data.tar.gz: 470159b689994419fb692d26c0d1ede1cd48c73508090a4cb9f472ffa95788cc
+  metadata.gz: d30726333f8265818004958fdb2276a6421ee240b3fbc0b7fc977adf1f39ddb3
+  data.tar.gz: 73e52320a14d39e0cb6da2fc22c8b55de7a57167d746a650232c603d12a7d7fc
 SHA512:
-  metadata.gz: 40e2d6de3e683bc1adffbaabefd3863e3886ce7462c4e071ed916ff45a743f08b1d590535b6c0732821fa56017299d182045c631da1a1e30a9f84e3c00b5d666
-  data.tar.gz: e3ef3c8e93c892330619ad27ac091a0e9a3e9f3b8613db69dda8ed5ddf0da0548e406f83912770a1cfd010612380481906060cc8163aebc85d682846d7b20e52
+  metadata.gz: b8c711d2e82584e464c4bc47777a6340a118d53165e20664aff36ab5a43b582273dc60e7f13bbeb55de368054f9e7e9924d637e164d10608db09f1ef97f38631
+  data.tar.gz: 6dc95c59d9c700ac68c18c2f8915e0a44e2a79d3701fdaa30ea579ec024cb39a65379498ee40f778f09fa2d3575b3830f6c4eec9e626c586d6e1e443acb71ee0

data/CHANGELOG.md

@@ -2,6 +2,232 @@
 
 Semver. Consumers pin `~> 0.1`.
 
+## 0.4.0 — 2026-08-31
+
+**Breaking.** The baseline is now the line, not a third of it. Applications
+setting `--baseline` need to set `--line` instead; everything else follows.
+
+### The grid
+
+0.3.0 put the type on a baseline grid and then registered it to eight pixels —
+a third of the body line. A block could be a whole number of thirds and still
+land every line of type after it somewhere new, which is what a label on a
+sixteen-pixel leading and a section head on thirty-two did, all the way down a
+column. A third of a line is a spacing unit. It is not a baseline.
+
+- **`--line` (24px) replaces `--baseline` (8px)** as the interval everything
+  vertical registers to. It is also the body leading, because in a baseline
+  grid those are one number.
+- **Every leading is a whole number of lines.** `h1` and `h2` move from 40 and
+  32 to 48; the page title from 48 to 72; labels and captions from 16 to 24.
+  The page is airier, and that is what the convention looks like.
+- **`--line-2`, `--line-3`, `--line-4`, `--line-6`** for whole-line spacing.
+  `--space-*` survives, renamed at its root to `--space-unit`, as the
+  **horizontal** step: an inline gap has no baseline to miss.
+- **`--half-line` and `.subgrid`**, the one subgrid, for a block of small
+  type. It halves `--line` for the block's *children* — the block's own
+  margins belong to the column outside it and are owed whole lines. Declaring
+  it on the block itself halved the gap above it and landed the column half a
+  line out, which the specimen caught.
+
+### Pictures, rules, controls
+
+- **`.figure` puts a picture on the line at any width.** Its box is the
+  natural height taken up to the next whole line with `round()`, recomputed as
+  the container resizes; the picture is fitted inside with `contain`, so
+  nothing of it is lost. `.figure--cover` crops instead. `--ratio` is the
+  application's to declare. Tested at four widths.
+- `hr` is a line-tall box rather than a rule with margins either side.
+- A text control is two lines of box: one the text sits on, one the rule
+  closes. A checkbox is reset out of that, since the browser draws it at a
+  size of its own.
+
+### Guards
+
+- The box test measures in lines, and honours `.subgrid` — a block that
+  declares a half-line may use one; the block itself still owes whole lines.
+- A picture is measured at 1400, 1100, 903 and 712 pixels wide.
+- `--baseline` may not reappear in the library. A token that no longer means
+  what it says is worse than one that is gone.
+
+## 0.3.0 — 2026-09-01
+
+The vertical rhythm, twice: once to put every box on the baseline, and again
+to put the type on it. Found from outside, in a page that embedded the
+specimen and turned the baseline overlay on — the grid was drawn correctly and
+nothing sat on it.
+
+Rendering moves. Every ruled component is a pixel or two shorter, and where a
+browser can trim a text box the leading comes out of the block, so a page is
+tighter than 0.2.0 by a few pixels per block. Read this section before
+upgrading.
+
+### Fixed
+
+- **The vertical rhythm was decorative.** Every line box was a whole number of
+  baselines and the page was still off the grid, because a line box is not a
+  box: wherever a rule sat on a padded edge, its width was *added* to a box
+  whose padding was already whole baselines. A hairline is a pixel, so each
+  one moved everything below it by a pixel — and since the masthead, the
+  footer, `hr`, every table row, every field control, every button, the
+  pagination and the errors block all did it, the error accumulated down the
+  column rather than showing up once. On the specimen the page was one pixel
+  out by the first heading and seven by the footer.
+
+  Every rule now comes out of the padding it sits on — `calc(var(--space-1) -
+  var(--rule-hair))` — and `hr` draws its rule on the top edge of a box one
+  baseline tall instead of compensating in a margin, because a margin
+  compensation collapses away exactly where a rule leads or precedes a
+  section. Boxes that change height: a button and a table row are 40px rather
+  than 42 and 41, a field control 32 rather than 33, a `select` 32 rather than
+  29.
+- **A token in a line of prose grew the line.** `code`, `kbd` and `samp` set
+  in the mono stack are a second font on the line, with an ascent and a
+  descent of their own that the line box had to hold — a pixel at body size,
+  four under the page title, and only on the lines that happened to mention a
+  token. Their leading is now zero, which leaves the line box to the strut;
+  the glyphs are untouched.
+- **`select` ignored its leading.** `font: inherit` hands a control the family
+  and the size and puts its line box back to `normal`, so a select stood 29px
+  where every other control stood 32. It is now given the height the rest of
+  the ladder produces.
+- **A checkbox row was 20px.** The label beside a checkbox took the micro
+  register's 16px line box, which is not the row a 13px control sits on. It
+  now takes the same 24px line the library already gives the micro type you
+  can tap.
+- **Table rows landed on half pixels.** With `border-collapse: collapse` the
+  shared rule belongs to the boundary rather than to either cell, and the
+  browser splits it: every row sat at `x.5` and the header row was half a
+  pixel short. Nothing in the library draws a border two cells could share, so
+  borders are separate — with the spacing still zero — and a row is exactly as
+  tall as the ladder says.
+
+### Added
+
+- **The type sits on the baseline now, not merely in step with it.** Boxes in
+  step are not a baseline grid. Where a line's baseline falls inside its line
+  box depends on the font's ascent and the leading either side of it, so at
+  0.2.0 a paragraph's baselines sat a pixel off the grid, a caption's four,
+  and the two were three pixels out of register with each other — every
+  register keeping its own grid, none of them the page's.
+
+  Every text register is now trimmed — `text-box: trim-both cap alphabetic` —
+  which makes a block's over edge the cap of its first line and its under edge
+  the baseline of its last. What then separates the box from the grid is the
+  cap height, and one padding rounds it up: `calc(round(up, 1cap,
+  var(--baseline)) - 1cap)`, measured by the browser in cap units, so a
+  library that leaves the typeface to the application still never has to be
+  told the font's metrics. It is published as `--cap-correction`, which any
+  component setting its own padding adds to it — `calc(var(--space-1) +
+  var(--cap-correction))` is the right padding in both paths.
+
+  Behind `@supports`, and the fallback is the box rhythm below: Chromium and
+  Safari trim, Firefox does not yet. **The two do not render identically.**
+  Trimming takes the leading out of a block's own box, so the spacing you
+  declare is the spacing you see; a trimmed page is a few pixels tighter per
+  block than the same page in Firefox, and the ladder means what it says
+  rather than what it says plus half a line. Both stay on the grid.
+
+  Controls opt out — a button is five baselines of box with its label centred,
+  and trimming the label would take the box with it — as does any block whose
+  content is not type. `text-box: normal; padding-block-start: 0` is how.
+
+### Fixed
+
+- **`rake release` did not exist.** The release workflow runs
+  `bundle exec rake release`, which is Bundler's task and arrives with
+  `require "bundler/gem_tasks"` — which the Rakefile did not have. So a
+  release passed every check it makes, minted its credentials over OIDC, and
+  stopped at *Don't know how to build task 'release'*. 0.2.0 never reached
+  RubyGems for this reason, and 0.1.0 only did because it was pushed by hand
+  before the workflow existed, which the "already published" guard then read
+  as nothing to do. Guarded now, along with the workflow's own tag-versus-
+  gemspec check.
+- **Every browser test was skipping in CI.** The suite looks for a browser and
+  a driver, and a candidate found on the `PATH` came back as the bare name it
+  was looked up by. Selenium wants a file — given `"chromedriver"` it raises
+  *not a file* — so the harness caught that, fell back to `rack_test` and
+  skipped, on a runner that had just installed a driver for it. The job was
+  green and had checked nothing: 12 runs, 12 skips. Candidates now resolve to
+  where they actually are, and the CI job now names the browser and the driver
+  the same step installed — the runner image ships a chromedriver of its own,
+  and a driver a major version ahead of the browser refuses to start a session
+  at all — and sets `REQUIRE_BROWSER`, which turns a skip into a failure — a skipped browser test is invisible in a passing
+  job, and the assertions that need a browser are the ones about what the
+  cascade and the box model actually did.
+- **The `:head` slot rendered before the library's own stylesheets**, so a
+  layer named there took its place in the order ahead of every layer the
+  library declares and lost to all of them. The specimen's own furniture is
+  one such stylesheet, and it could not override the library it documents. The
+  slot now comes after.
+
+### Guards added
+
+- **Every register's last baseline is on a baseline**, measured in the
+  browser. Under `trim-both … alphabetic` a block's under edge *is* that
+  baseline, so measuring the box measures the type — and it is measured rather
+  than probed on purpose: inserting a span to read a baseline re-lays out a
+  trimmed page and moves the thing it was measuring. Skips where the browser
+  cannot trim.
+- **The correction is zero where the browser cannot trim**, read from the
+  source, so the enhancement can never become a requirement.
+- **Every box on the specimen starts on a baseline and is a whole number of
+  them tall**, measured in the browser on the page that holds one of
+  everything. The suite already asserted that every *line box* was a whole
+  number of baselines, which was true throughout and is what let all of the
+  above through.
+- The leading guard now admits `0`, the one value that is not a measurement:
+  an inline box that takes no part in the line it sits on.
+
+## 0.2.0 — 2026-08-31
+
+Everything here was found by the second consumer inside a day of building on
+0.1.0, which is roughly the point of having one.
+
+### Fixed
+
+- **The pagination partial printed its own source.** Its opening comment held
+  a worked example written in ERB; the example's own closing delimiter ended
+  the comment, and the two lines after it were emitted as page content. On
+  every page that rendered it — including the specimen, the library's own
+  documentation and regression fixture, for the whole of 0.1.0. The example
+  now lives in the README, where it can be quoted.
+- **`.table .numeric` zeroed the end padding of every numeric cell**, not just
+  one in the final column, because it set the padding with the `padding-inline`
+  shorthand. Anywhere else in a table the next column's text began exactly
+  where the number ended. Now sets only `padding-inline-start`, and leaves the
+  final column to the `:last-child` rule that already handled it.
+
+### Changed
+
+- **`its_swiss:install` generates a nested layout** — `app/views/layouts/
+  application.html.erb` ending in `render template: "layouts/its_swiss/shell"`
+  — instead of injecting `layout "its_swiss/shell"` into `ApplicationController`.
+  The shell is filled through `content_for`, which has to run while a view is
+  rendering; naming it on the controller rendered the shell but left nowhere
+  to fill it once, so an application wrote its masthead into every view. The
+  generated layout also **links `theme.css`**, which nothing did before: an
+  application that followed the README exactly got no accent and no grid, with
+  no error anywhere.
+
+  Existing installs keep working. To move: delete the `layout` line from
+  `ApplicationController` and add the layout, or re-run the generator.
+
+### Guards added
+
+Three of the four findings were in views, a generator and a form builder —
+surfaces a CSS library's tests do not reach. Two new ones, both of which fail
+on the bugs above:
+
+- The rendered specimen contains no template delimiters. Every other assertion
+  in that file was about markup that should be present; none about output that
+  should not be.
+- No view's comment quotes ERB. A comment ends at the first closing delimiter
+  it meets, so an example inside one is an example that truncates it.
+
+The specimen's table now has a numeric column that is not last, and a browser
+test measures its end padding — the case that broke.
+
 ## 0.1.0 — 2026-08-31
 
 The first extraction, from Pandatone, which ships on it.
@@ -53,5 +279,7 @@ They are in the boundary the handoff drew and they break the library's own
 rule about two applications; they are the two components most likely to move
 when Stripeclub lands.
 
+*(Both of them shipped broken. See 0.2.0.)*
+
 `.footer` is the same shape of guess — the shell has the slot and Pandatone
 does not fill it.

data/README.md

@@ -14,7 +14,7 @@ the consuming application's to set — it is not a theme with the colour left
 out, it is a style whose argument is that the values are enough.
 
 ```ruby
-gem "its-swiss"
+gem "its-swiss", "~> 0.1"
 ```
 
 ```sh
@@ -62,7 +62,67 @@ holding all of them. Nothing here has a default the gem could pick honestly.
 | `--accent`, `--accent-ink` | State and emphasis only. Unset, the accent is ink |
 | `--font-family` | The typeface. The gem ships none — declare `@font-face` and name it |
 | `--value-chroma`, `--value-hue` | Warms the whole value scale together. Neutral as shipped |
-| `--columns`, `--gutter`, `--baseline` | How many fields this problem has, and the unit everything vertical is measured in |
+| `--columns`, `--gutter` | How many fields this problem has |
+| `--line` | The baseline: the interval everything vertical registers to |
+| `--ratio` | A picture's aspect ratio, per figure — the library cannot read one |
+| `--cap-correction` | Read, not set: what a trimmed register adds above its cap to reach the next baseline |
+
+### The baseline
+
+`--line` (24px) is the interval everything vertical registers to, and the
+leading of the body text. In this style those are one number, because that is
+what a baseline grid is: Müller-Brockmann's horizontal lines are one line of
+text apart and a field is a whole number of them.
+
+Every leading is `var(--line)` or a whole multiple of it — `--line-2`,
+`--line-3`, `--line-4`, `--line-6`. Every margin, padding and gap on the
+vertical axis is too. `--space-*` survives as the **horizontal** step: an
+inline gap has no baseline to miss.
+
+Boxes in step are only the easy half. Where a line's baseline falls inside its
+line box depends on the font's ascent and the leading either side of it, so a
+caption and a paragraph can both be in step and still be out of register with
+each other. So every text register is trimmed to its own type: `text-box:
+trim-both cap alphabetic` makes a block's over edge the cap of its first line
+and its under edge the baseline of its last, and one padding rounds the cap
+height up to the next line —
+
+```css
+padding-block-start: calc(round(up, 1cap, var(--line)) - 1cap);
+```
+
+— which the browser computes in cap units, so the library still never has to
+be told the font's metrics. It is published as `--cap-correction`: a component
+that sets its own padding on trimmed text adds it, as
+`calc(var(--half-line) + var(--cap-correction))`, which is the right padding
+whether or not the browser trims.
+
+Two things opt out, with `text-box: normal; padding-block-start: 0`: a control,
+whose box is the target and whose label is centred in it, and any block whose
+content is not type — an image, a swatch, a diagram.
+
+It is behind `@supports`, and the fallback is the box rhythm above. Chromium
+and Safari trim; Firefox does not yet. The two do not render identically:
+trimming takes the leading out of a block's own box, so a trimmed page is a
+few pixels tighter per block. Both stay on the grid.
+
+#### The one subgrid
+
+A block of small type may sit on a half-line — a dense run of captions, a
+table of figures:
+
+```html
+<div class="subgrid">…</div>
+```
+
+It halves `--line` for the block's **children**, and the leadings, the spacing
+and the cap correction all follow. The children, not the block: a block's own
+margins belong to the column outside it and are owed whole lines. Set on the
+block itself it halves the gap above it and lands the column half a line out.
+
+A block, and only a block. An inline `<small>` shares its paragraph's line and
+must not change it.
+
 
 ### The value scale
 
@@ -98,6 +158,27 @@ Within three units a channel, which is the cost of the four hand-picked
 values becoming one ladder with a single chroma and a single hue. Measured in
 Chromium, not calculated.
 
+### Pictures
+
+The one case that nearly does not transfer from print. A picture's height is
+its fluid width over its ratio, so without help one picture puts the whole
+column below it off the grid at every width but a few.
+
+```html
+<figure class="figure" style="--ratio: 1.618">
+  <img src="…" alt="…">
+  <figcaption class="micro">…</figcaption>
+</figure>
+```
+
+The box is the picture's natural height taken up to the next whole line, by
+`round()`, recomputed as the container resizes. The picture is fitted inside
+it — `contain` by default, because a library must not crop an image it did not
+choose. `.figure--cover` crops instead, which is the Müller-Brockmann move and
+yours to make where you own the picture.
+
+`--ratio` is yours to declare; CSS cannot read an intrinsic one.
+
 ### The grid
 
 The gem ships primitives and never a grid.
@@ -126,12 +207,28 @@ it stops on a field line:
 
 ## The layout shell
 
-```ruby
-class ApplicationController < ActionController::Base
-  layout "its_swiss/shell"
-end
+The installer writes `app/views/layouts/application.html.erb` as a layout
+**for** the shell rather than one instead of it:
+
+```erb
+<% content_for :head do %>
+  <%= stylesheet_link_tag "theme", "data-turbo-track": "reload" %>
+<% end %>
+
+<% content_for :mark do %><%= link_to "Your app", root_path %><% end %>
+
+<%= render template: "layouts/its_swiss/shell" %>
 ```
 
+Nested, not `layout "its_swiss/shell"` on a controller. `content_for` has to
+run while a view is rendering, and these slots are set once for the whole
+application — naming the shell on the controller renders it but leaves
+nowhere to fill it, so every view ends up writing the same masthead.
+
+Note the `:head` slot links `theme.css`. The shell links the library's six
+stylesheets and stops; the accent and the grid live in yours, and nothing
+links it but this.
+
 Slots, all optional:
 
 | Slot | |
@@ -157,6 +254,19 @@ beyond the shell is the application's, for the same reason its grid is.
 | `its_swiss_form_with(...)` | `form_with`, already holding the library's builder |
 | `its_swiss_page_numbers(page, pages)` | Which numbers a run of them shows, elided |
 
+### Pagination
+
+The library has no paginator and no opinion about which one you use — it takes
+a page, a total, and something that turns a number into a URL:
+
+```erb
+<%= render "its_swiss/shared/pagination",
+      page: @page, pages: @pages, url: ->(n) { colors_path(page: n) } %>
+```
+
+Long runs are elided around the current page. `window:` (default 2) sets how
+many neighbours show; `label:` names the `<nav>` for a screen reader.
+
 ## The form builder
 
 One shape for every field: a label, a control, and — when there is something to
@@ -211,10 +321,11 @@ every line box is measured in baselines, that no signal rests on colour alone.
 The rest needs a browser, because a rule on the wrong selector reads correctly
 in the CSS and does nothing on a page. Those assert what Chromium actually
 resolved: that an unlayered declaration beats the library's layered one, that
-the accent unset is ink, that quiet ink clears 4.5:1, that every line box is a
-whole number of baselines, that nothing escapes the page at 390px, and that the
-measure lands on a field line the browser really laid out. They skip loudly
-rather than pretending to have checked.
+the accent unset is ink, that quiet ink clears 4.5:1, that every box on the
+specimen starts on a baseline and is a whole number of them tall, that every
+register's last baseline lands on one, that nothing escapes the page at 390px,
+and that the measure lands on a field line the browser really laid out. They
+skip loudly rather than pretending to have checked.
 
 There are no pixel tests.
 
@@ -230,7 +341,8 @@ ladder; the names are the library's rather than the application's.
 | `--ink-quiet`, `--ink` | unchanged |
 | `--accent` | unchanged — still the application's to set |
 | `--font` | `--font-family` |
-| `--size-1..5`, `--space-N`, `--baseline`, `--measure`, `--page-max` | unchanged |
+| `--size-1..5`, `--space-N`, `--measure`, `--page-max` | unchanged |
+| `--baseline` (8px) | **gone.** `--line` (24px) is the baseline now — see 0.4.0 |
 | `.masthead__nav` | `.nav` |
 | `.channels` | `.pairs` |
 | `.form`, `.field`, `.button*`, `.copy`, `.errors`, `.hint`, `.empty` | unchanged |