its-swiss 0.9.1 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7ab6df97c9cfca52b616b05f5e985aa37df4253563fd1b1177c9c67890706cad
-  data.tar.gz: 6e9d6316b70b2670b7b307b33ec64955e88d562d085c95a86e07836e635d1a97
+  metadata.gz: e87eed3705a969f109f9e21d5c4242173bcbcbbb6d0700441fbeb588c5aa6845
+  data.tar.gz: ac3ab6f0964280e6ea4f2ac67db52975ab7f55cfd9a341976515a76718275d2b
 SHA512:
-  metadata.gz: 5a3f8671a25c996f2883add93ead145a89244a8a5bbec670022c0b3d49d587d19dd1b5a664eb94bd49908b1d8a4b28877e66b180ac49d3b653b47b0493cf7d02
-  data.tar.gz: 286de25b2203d9928f9a4cbf596341aa8d450c3cfaecf016cafff44737586df4d4cd65d98271d102f2dcf2af9e8f9e058413ead233ad86602a3e242a5f471a4d
+  metadata.gz: 38eb6ffa9089d649da9a1f6fd57ebc71e54515445051147acb4aad296c2d68bf1641926113f45b8a79f757cc52f1a5034a19f447d11ce01b2cd51c8b4e32b055
+  data.tar.gz: f48734b201bf2528f749c1990065d7ae68c1da803d3d67aec8f717f11bf48da95620f9a1b469ec0294fc794d603c3ad2be3c038475d4e670e5e9eefddcb76201

data/CHANGELOG.md

@@ -1,6 +1,86 @@
 # Changelog
 
-Semver. Consumers pin `~> 0.1`.
+Semver. Consumers pin `~> 1.0`.
+
+## 1.0.0 — 2026-09-08
+
+The surface three applications settled on, reviewed as a whole: what a tech
+lead found and what Müller-Brockmann would have said. The library's
+arguments now live in `DESIGN.md`, once.
+
+### Fixed
+
+- **`--span` no longer inherits.** A custom property inherits by default, so
+  a grid inside a spanned item started every child of its own at the parent's
+  span. `--span` is a registered property with `inherits: false` and no
+  initial value, so a child that says nothing still runs the whole field.
+- **The metric-override script carries the page's nonce.** The shell renders
+  `csp_meta_tag`, and a content security policy blocked the one inline script
+  the library writes, which left Safari in step and not registered with
+  nobody seeing why.
+- **A field is the page's field.** `--field` was derived from `--page-max`,
+  so below 82rem `.fields` was wider than the viewport and the measure was
+  600px on a phone. It is measured in container units from the `.page` the
+  fields are laid out in; `.fields` never exceeds its box.
+- **A control's focus is its rule.** The focus ring was a box drawn 3px
+  outside a two-line control whose only visible part is a rule, and it
+  crossed the label above it. The focus is the rule going heavy, in the
+  accent, with the box still two lines.
+
+### Added
+
+- **The measure is a count of characters.** `--measure-characters` (65) in
+  the type's own font, taken up to the nearest whole run of fields with
+  `round()`, and never past the page. Three fields whatever the count was a
+  proportion: a quarter of a twelve-column page, and wider than a phone.
+- **The module.** `--module` (6) is a field's height in lines: the columns
+  divide the page across and the module divides it down. `.modules` is a
+  block of whole modules and `.figure--modular` a picture in one, which is
+  the grid's proportion rather than the window's.
+- **The dense form.** `.form--dense` puts each label on its control's line of
+  air, directly above the text on its rule: three lines a field rather than
+  four, for a form of many fields or a panel.
+- **A textarea is measured in lines.** `rows:` on the builder's `text_area`
+  writes `--rows`, which the stylesheet reads; four when it is not given.
+- **The library registers its own controllers.** `its_swiss.js` registers
+  the clipboard and the live search with the host's Stimulus application,
+  and the shell imports it. A host has nothing to write; the two lines it
+  wrote before are harmless.
+- **`DESIGN.md`.** The arguments, moved out of the stylesheets and stated
+  once; the stylesheets say what a rule is for in a sentence.
+
+### Changed
+
+- **A form has no width of its own.** `.form` was at the measure and started
+  its children on the left; a form laid out on the fields had to undo both.
+  `its_swiss_form_with` writes `class="form measure"`, so a form written
+  through the helper is where it was. A form written with `form_with` and
+  `class: "form"` is full width now: add `measure`.
+- **One filled button.** `.button--accent` is gone: the primary action is in
+  ink, and a second filled box was a standing temptation against the one red
+  a page has.
+- **The explanation's mark is a word.** `explain` writes "About" in the
+  small register rather than a question mark; `label:` says another word.
+- **The control's rule at rest is the strong rule**, `--rule-strong`, which
+  the library had declared and never used; ink under the hand, the accent
+  when refused or focused.
+- **Tokens nothing used are gone**: `--space-5`, `--space-13`, `--line-6`.
+  `--space-6`, `--space-8` and `--line-4` remain. Pandatone read two of them
+  and will move to the ladder when it takes 1.0.
+- **The tests that pinned formatting pin behaviour.** Three assertions that
+  matched exact runs of CSS text are computed-style assertions in the
+  browser suite; the guards that are about the source stay.
+
+### Migration
+
+- `gem "its-swiss", "~> 1.0"`.
+- A `form_with(..., class: "form")` that wants the measure adds `measure`.
+- `.button--accent` becomes `.button--primary`.
+- `--space-5` becomes `--space-6` or a line; `--space-13` becomes
+  `calc(var(--space-unit) * 13)` if it is truly wanted; `--line-6` becomes
+  `calc(var(--line) * 6)`.
+- The two Stimulus registrations in the host's `controllers/index.js` can go.
+- A test that read the explanation's `?` reads "About".
 
 ## 0.9.1 — 2026-09-07
 

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", "~> 0.1"
+gem "its-swiss", "~> 1.0"
 ```
 
 ```sh
@@ -26,8 +26,8 @@ Then open `/its-swiss/specimen`.
 The current specimen is also published, for anywhere that cannot run Rails:
 **[bobbymeyer.github.io/its-swiss](https://bobbymeyer.github.io/its-swiss/)**.
 `bin/specimen out` writes it as one static file, and a Pages workflow does
-that on every push to `main`, keeping each released version alongside the
-current one at `/<version>.html` for anything that needs to pin.
+that on every push to `main`; the versions kept in `published/` are copied
+alongside it at `/<version>.html` for anything that needs to pin.
 
 ## What is in the gem, and what stays in the application
 
@@ -70,6 +70,8 @@ holding all of them. Nothing here has a default the gem could pick honestly.
 | `--value-chroma`, `--value-hue` | Warms the whole value scale together. Neutral as shipped |
 | `--columns`, `--gutter` | How many fields this problem has |
 | `--line` | The baseline: the interval everything vertical registers to |
+| `--module` | A field's height, in lines: what divides the page down |
+| `--measure-characters` | How many characters a line of prose holds; the grid is what it stops on |
 | `--ratio` | A picture's aspect ratio, per figure — the library cannot read one |
 | `--card` | How many fields a card takes, and at which widths |
 | `--filter-label` | The column a filter's label occupies, so every register's choices start on one line |
@@ -78,120 +80,24 @@ holding all of them. Nothing here has a default the gem could pick honestly.
 ### 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 is the font's decision: half the leading down, then the font's own
-ascent, and the ascent is a number in the font file that the library has never
-been told. A caption and a paragraph can both be in step and still be out of
-register with each other, and a page on the grid in one font is off it in the
-next. 0.5.0 trimmed every register to its type with `text-box-trim`, which
-registered the page in the one browser that trims and left the rest to their
-fonts.
-
-So the library sets every register in a face of its own. `faces.css` declares
-the machine's grotesque three times over `src: local()`, each time with its
-ascent set to a ratio of leading to size and its descent and line gap set to
-nothing:
-
-```css
-@font-face {
-  font-family: "its-swiss-150";
-  src: local("Helvetica Neue"), local("Arial"), local("Liberation Sans"), …;
-  ascent-override: 150%;
-  descent-override: 0%;
-  line-gap-override: 0%;
-}
-```
-
-A line box is then exactly the ascent tall, there is no half-leading for the
-type to sit inside, and the baseline is the under edge of the line box — in
-every line, whatever the font underneath, in a browser that honours the
-descriptors. Chromium and Firefox do. The ladder produces three ratios and
-there are three faces: body, subhead and page title are set on one and a half
-times their size, the small register and the section on twice it, and the
-subgrid puts the small register on its own size. A register is three
-declarations, and the third is what makes the first two a grid:
-
-```css
-.micro { font-family: var(--face-200), var(--font-family); font-size: var(--size-1); line-height: var(--line); }
-```
-
-Safari loads the faces and ignores what they say about their metrics, so
-there every text block is also trimmed to its type: `text-box: trim-both cap
-alphabetic` makes the 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 up to the
-block's own leading —
-
-```css
-padding-block-start: calc(round(up, 1cap, 1lh) - round(1cap, 1px));
-```
-
-— measured by the browser in cap and line units, so the library still never
-has to be told the font's metrics. The cap is rounded to a pixel because that
-is the cap WebKit trims to, and WebKit is the browser this is for. It is
-published as `--cap-correction`: a component that puts padding above its type
-adds it. Only where it is needed, though, and only when told: a trimmed box
-is a 64th of a pixel short as often as not on the engine the correction is
-written for, and half a pixel out per block on one that trims to the exact
-cap, which down a long column is a visible drift. So one line of script ahead
-of the stylesheets marks the document `no-metric-overrides` where the faces
-are not honoured, and the trim steps in there and nowhere else;
-`its_swiss_stylesheet_tags` writes it, and anything linking the stylesheets
-by hand should too:
+leading of the body text: one number, because that is what a baseline grid
+is. Every leading, margin, padding and gap on the vertical axis is a whole
+number of lines; `--space-*` is the horizontal step.
+
+Every baseline is the under edge of its line box, two ways. The library sets
+every register in a face of its own, the machine's grotesque declared again
+with its ascent set to the register's ratio of leading to size and no
+descent, which Chromium and Firefox honour. Where a browser ignores what a
+face says about its metrics, Safari, every text block is trimmed to its type
+instead, and one line of script ahead of the stylesheets says which is in
+force. `its_swiss_stylesheet_tags` writes it; anything linking the
+stylesheets by hand should too:
 
 ```html
 <script>if (!("ascentOverride" in FontFace.prototype)) document.documentElement.classList.add("no-metric-overrides")</script>
 ```
 
-Without it the page is on the faces alone: exact in Chromium and Firefox, and
-in Safari in step but not registered. The faces are the mechanism and the
-trim is the fallback. Three things follow.
-
-Anything that changes size *inside* a line — `code`, a `small`, a
-superscript — is given no leading at all, so it never asks the line for room;
-its glyphs still sit on the strut's baseline, which is the grid's.
-
-No row asks the browser to find a baseline. Every box's baselines are whole
-lines below its own over edge, so a row that starts its items on one line has
-put their baselines on one line; `.run` aligns on `flex-start`, the masthead
-and the nav on `end`, a table cell on `top`, and none of them on `baseline`,
-which is a question three kinds of box answer three ways.
-
-Text lives in text elements. The trim is asked of headings, paragraphs,
-terms, cells, captions, labels, list items and definitions that hold text,
-nav links, pagination, buttons — and not of the boxes that hold those, since
-a box that holds blocks is trimmed through its first and last child and would
-be corrected twice. Plain text dropped straight into a `<footer>` or a `<div>`
-is in step and, in Safari, off the baseline; put it in a paragraph. The shell
-does, for the `:footer` slot.
-
-A control is two lines: a line of air under the label, then the line the
-type is set on, which the rule closes, with the rule's width taken out of the
-first — so the type stands on its rule the way a line of handwriting stands
-on a ruled page. A button is a box, two lines tall with
-its label centred in it, and its label's baseline is the one baseline in the
-library that is not on a line — on purpose, since a label set on the second
-line of a two-line box reads as a field with a rule under it. Its keyline is
-an inset shadow rather than a border, so the box is the label's line and two
-paddings and nothing else.
-
-A control's own text — an input, a select, a textarea — is the other run of
-type the library takes off the baseline, and it does so on purpose too. A
-browser sets that text in a box of its own, centres it there and clips it
-there, and on a face with no descent every descender was cut off at the
-rule. So the text is set in `--font-family` itself, with the font's own
-metrics, on the line the rule closes: the box is on the grid, the line is
-the ladder's, and where the baseline falls inside the line is the font's. Which means the typeface has to exist under its own name as well as
-under the faces; `its_swiss_typeface` declares it there when given
-`family:`, and `--font-family` names it.
+The whole argument, and what follows from it, is in `DESIGN.md`.
 
 #### Your own typeface
 
@@ -204,35 +110,21 @@ it:
 <%= its_swiss_typeface variable: "inter.woff2", family: "Inter" %>
 ```
 
-Put it after the library's stylesheets. The declarations are unlayered, and a
-name defined outside a layer beats the same name defined inside one — the way
-the application's rules beat the library's — but a browser that resolves a
-name by order rather than by layer wants it last too. `--font-family` is only
-what a machine with none of the faces falls through to: the page is still
-readable and still in step, and no longer registered.
-
-The faces are the ladder's. Re-proportion `--line` or a size and the ratios
-move with them, and the faces have to be declared again for the ratios the new
-ladder produces.
+Put it after the library's stylesheets. `family:` declares the typeface under
+its own name as well, which a control's text is set in; `--font-family` is
+what a machine with none of the faces falls through to.
 
 #### The one subgrid
 
-A block of small type may sit on a half-line — a dense run of captions, a
-table of figures:
+A block of small type may sit on a half-line:
 
 ```html
 <div class="subgrid">…</div>
 ```
 
 It halves `--line` for the block's **children** and moves the small register
-onto the face for its new ratio, and the leadings and the spacing 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.
-
+onto the face for its new ratio. A block, and only a block: an inline
+`<small>` shares its paragraph's line.
 
 ### The value scale
 
@@ -294,27 +186,33 @@ yours to make where you own the picture.
 The gem ships primitives and never a grid.
 
 ```css
-.page    /* the one measured container: --page-max wide, --page-inset either side */
-.grid    /* repeat(var(--columns), minmax(0, 1fr)) with --gutter between */
-.measure /* three fields wide */
-.fields  /* --span fields wide */
-.run     /* items on a shared baseline, a space apart, wrapping when they must */
-.stack   /* the same, turned ninety degrees */
+.page     /* the one measured container: --page-max wide, --page-inset either side, and the container a field is measured in */
+.grid     /* repeat(var(--columns), minmax(0, 1fr)) with --gutter between */
+.measure  /* the measure: --measure-characters of the type, stopped on a field line */
+.fields   /* --span fields wide */
+.modules  /* --modules modules tall */
+.run      /* items on a shared baseline, a space apart, wrapping when they must */
+.stack    /* the same, turned ninety degrees */
 ```
 
 A child of `.grid` says how many fields it takes with `--span`; a child that
-says nothing runs the whole field, because that is what nearly everything on a
-page does.
+says nothing runs the whole field. `--span` is registered not to inherit, so a
+grid inside a spanned item starts its own children on the whole field.
 
-`--field` is derived from the page rather than measured, so anything built on
-it stops on a field line:
+A field is the page's actual width, less the gutters, divided, measured in
+container units from the `.page` the fields are laid out in:
 
 ```css
---field: calc((var(--page-max) - var(--page-inset) * 2
-               - var(--gutter) * (var(--columns) - 1)) / var(--columns));
---measure: calc(var(--field) * 3 + var(--gutter) * 2);
+--field: calc((100cqw - var(--gutter) * (var(--columns) - 1)) / var(--columns));
 ```
 
+The measure is a count of characters, and the grid is what it stops on:
+`--measure-characters` (65) in the type's own font, taken up to the nearest
+whole run of fields, and never past the page. The module is a field's height
+in lines, `--module` (6): the columns divide the page across and the module
+divides it down, and `.modules` and `.figure--modular` size a block or a
+picture to whole ones.
+
 ### The page head
 
 What a page is and what can be done to it, in one shape on every page: the
@@ -342,10 +240,10 @@ on every page.
 
 ### Explanations
 
-What a section means, behind one mark. A sentence over every table is needed
+What a section means, behind one word. A sentence over every table is needed
 on the first day and never again, and a tool used daily is read on every
-other day; so `explain` writes it in the hint register, closed, and a
-question mark on the line opens it.
+other day; so `explain` writes it in the hint register, closed, and the word
+"About" in the small register opens it. `label:` says another word.
 
 ```erb
 <%= explain "The repeat, in order along the stripe normal." %>
@@ -413,8 +311,8 @@ 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 seven
-stylesheets and stops; the accent and the grid live in yours, and nothing
-links it but this.
+stylesheets and the module that registers its controllers, and stops; the
+accent and the grid live in yours, and nothing links it but this.
 
 Slots, all optional:
 
@@ -429,23 +327,23 @@ Slots, all optional:
 | `:footer` | Whatever belongs after the page |
 
 The shell writes the view transition opt-in, the seven stylesheet links, the
-importmap tags, a skip link, and the flash. It stops there — a page layout
+importmap tags, the library's JavaScript module, a skip link, and the flash. It stops there — a page layout
 beyond the shell is the application's, for the same reason its grid is.
 
 ## Helpers
 
 | | |
 | --- | --- |
-| `its_swiss_stylesheet_tags` | The seven links, tracked for Turbo |
+| `its_swiss_stylesheet_tags` | The seven links, tracked for Turbo, and the metric-override mark with the page's nonce |
 | `its_swiss_typeface(regular:, bold:)` | The application's typeface, declared under the library's face names |
 | `nav_link_to(name, url, current:)` | A destination, with `aria-current` when you are at it |
 | `nav_menu(label, current:) { links }` | A destination that opens into destinations, with no script |
 | `copy_button(value)` | A value that copies itself |
-| `its_swiss_form_with(...)` | `form_with`, already holding the library's builder |
+| `its_swiss_form_with(...)` | `form_with`, already holding the library's builder, at the measure |
 | `its_swiss_page_numbers(page, pages)` | Which numbers a run of them shows, elided |
 | `page_head(title, lede:, sections:) { actions }` | The one shape every page opens with |
 | `page_sections(sections)` | The surfaces of one page, the one shown in the weight |
-| `explain(text) { }` | What a section means, behind one mark |
+| `explain(text, label:) { }` | What a section means, behind one word |
 | `filter_register(label, choices, name:)` | One register of a filter block |
 | `search_form(url, frame:, keep:)` | A search that narrows a list as you type |
 
@@ -464,21 +362,12 @@ many neighbours show; `label:` names the `<nav>` for a screen reader.
 
 ### JavaScript
 
-Two Stimulus controllers, pinned by the engine so an application that upgrades
-the gem gets the new file without touching its importmap. They are outside
-`controllers/`, so an application registers them by hand, once:
-
-```js
-// app/javascript/controllers/index.js
-import ItsSwissClipboardController from "its_swiss/clipboard_controller"
-import ItsSwissLiveSearchController from "its_swiss/live_search_controller"
-application.register("its-swiss-clipboard", ItsSwissClipboardController)
-application.register("its-swiss-live-search", ItsSwissLiveSearchController)
-```
-
-`copy_button` and `search_form` write the `data-controller` attributes; a page
-without the registrations still works, with the value selectable and the
-search's button on the page.
+Two Stimulus controllers, pinned by the engine, and a module that registers
+them with the host's Stimulus application, which the shell imports. A host
+has nothing to write; one that registers the two by hand still can, and
+registering them twice is harmless. `copy_button` and `search_form` write
+the `data-controller` attributes; a page without script still works, with
+the value selectable and the search's button on the page.
 
 ## The form builder
 
@@ -501,7 +390,13 @@ builder wires `for`, `aria-describedby`, `aria-invalid` and `.field--invalid`
 every time.
 
 `label: false` hides the label rather than removing it — the name moves onto
-the control as `aria-label`.
+the control as `aria-label`. A textarea's `rows:` is how many lines tall it
+is. `class: "form form--dense"` puts each label on its control's line of
+air, three lines a field rather than four, for a form of many fields.
+
+A control's rule is the strong rule at rest, ink under the hand, and the
+accent, heavy, when the control has the focus or has been refused. The focus
+is the rule, not a box.
 
 ## The specimen
 
@@ -565,6 +460,7 @@ ladder; the names are the library's rather than the application's.
 | `--font` | `--font-family` |
 | `--size-1..5`, `--space-N`, `--measure`, `--page-max` | unchanged |
 | `--baseline` (8px) | **gone.** `--line` (24px) is the baseline now — see 0.4.0 |
+| `--space-5`, `--space-13`, `--line-6` | **gone** in 1.0.0: nothing in the library used them. `--space-6`, `--space-8` and `--line-4` remain |
 | `.masthead__nav` | `.nav` |
 | `.channels` | `.pairs` |
 | `.form`, `.field`, `.button*`, `.copy`, `.errors`, `.hint`, `.empty` | unchanged |
@@ -585,12 +481,11 @@ Two behavioural differences to know about:
 
 ## Versioning
 
-Semver with a changelog. Consumers pin `~> 0.1`.
+Semver with a changelog. Consumers pin `~> 1.0`.
 
-`0.1.0` ships with one consumer — Pandatone — and that is what the leading
-zero is for: the boundary was drawn from one real application and the second
-has not been built yet. The surface will move. Read `CHANGELOG.md` before
-upgrading, and see `RELEASING.md` for how a version gets out.
+1.0.0 is the surface three applications settled on, and what changes it now
+changes a major. Read `CHANGELOG.md` before upgrading, and see `RELEASING.md`
+for how a version gets out.
 
 ## License
 

data/app/assets/javascripts/its_swiss.js

@@ -0,0 +1,12 @@
+// Registers the library's two controllers with the host's Stimulus
+// application. controllers/application is what stimulus-rails installs in
+// every host, and it is the one thing this file assumes about the JavaScript
+// around it. The shell imports this module, so a host has nothing to write;
+// a host that registers the two by hand still can, and registers them twice
+// harmlessly.
+import { application } from "controllers/application"
+import ClipboardController from "its_swiss/clipboard_controller"
+import LiveSearchController from "its_swiss/live_search_controller"
+
+application.register("its-swiss-clipboard", ClipboardController)
+application.register("its-swiss-live-search", LiveSearchController)