diff --git a/tests/test_ui_standard.py b/tests/test_ui_standard.py index 2fd6a952..7be6bf65 100644 --- a/tests/test_ui_standard.py +++ b/tests/test_ui_standard.py @@ -54,16 +54,34 @@ # Selectors whose motion is explanatory rather than chrome: a figure drawing # itself, a section arriving on scroll, a status pulse. Each is allowed to # exceed 300 ms, to own a curve, or to animate a layout property — and each -# says why. Matched inside the rule's selector at a selector boundary, so -# `.sweep` covers `.sweep.from-you` but not `.sweeper`. An entry must still -# match a rule that moves; the first test below refuses a ghost. +# says why. A key is found inside the rule's selector at a selector boundary +# on both sides, so `.sweep` covers `.sweep.from-you` but not `.sweeper`. A +# key that is itself a selector list (`main, footer`) exempts only the rule +# whose selector is exactly that list, not `main .panel` and not a bare +# `main`: a tag name found anywhere would exempt everything under it. An +# entry must still match a rule that moves; the first test below refuses a +# ghost. EXPLANATORY = { ".live i": "the archived Cover's live dot, a 2 s constant pulse", ".st::before": "the archived Cover's in-progress dot pulse on its ladder", ".sweep": "rungs 2 and 3's chips crossing 58 px of felt to the pot, one-shot, 400 ms", ".rungs-menu": "the old chrome's Rungs menu animates width on purpose; only the archived Cover still inlines it", + "main, footer": "the arrival, the page's content and footer fading in once, opacity only, 700 ms (`test_the_page_fades_in_once_on_arrival`)", } +# The arrival: the one entrance every page plays. Opacity only, so the chip +# stays the one thing that moves on load; one-shot; the ease-out token; and +# the same fade under reduced motion, because a fade is the gentler variant, +# not the thing to remove. +ARRIVAL = ("main", "footer") +ARRIVAL_MS = 700 +# A conditional operator right before ` dict[str, str]: SHEETS = _sheets() +def _exempts(key: str, selector: str) -> bool: + """Whether an `EXPLANATORY` key reaches a rule's selector. + + A key that lists selectors (`main, footer`) reaches exactly that list and + nothing else; any other key is found inside the selector at a selector + boundary on both sides, so `.sweep` reaches `.sweep.from-you`, not + `.sweeper`. + """ + if "," in key: + return _parts(key) == _parts(selector) + return re.search(rf"(? None: self.media = media @@ -144,9 +175,7 @@ def declarations(self, prop: str) -> list[str]: @property def explanatory(self) -> bool: - return any( - re.search(rf"{re.escape(key)}(?![\w-])", self.selector) for key in EXPLANATORY - ) + return any(_exempts(key, self.selector) for key in EXPLANATORY) def _rules(css: str, keyframes: dict[str, str] | None = None) -> list[Rule]: @@ -216,16 +245,143 @@ def _motion_values(rule: Rule) -> list[str]: @pytest.mark.parametrize("key", sorted(EXPLANATORY)) def test_every_allowlisted_selector_names_a_rule_that_moves(key: str) -> None: """An entry that exempts nothing is a ghost, and a ghost hides the next real exception.""" - pattern = rf"{re.escape(key)}(?![\w-])" moving = [ f"{name}: {rule!r}" for name, rules in RULES.items() for rule in rules - if re.search(pattern, rule.selector) and _motion_values(rule) + if _exempts(key, rule.selector) and _motion_values(rule) ] assert moving, f"EXPLANATORY names {key!r}, which matches no rule that moves; delete the entry" +# ------------------------------------------------------------- the arrival + + +def _arrival_rules(name: str, reduced: bool) -> list[Rule]: + """The rules of a sheet that name every `ARRIVAL` selector and animate.""" + return [ + r + for r in RULES[name] + if _reduced(r) is reduced + and set(ARRIVAL) <= _parts(r.selector) + and any(v.strip() != "none" for v in r.declarations("animation")) + ] + + +def test_the_page_fades_in_once_on_arrival() -> None: + """One theme rule fades `main` and `footer` in on arrival, and only fades them. + + Every surface renders one `main` under the still top bar (the generator's + shell and the five apps' `App.tsx`), so the rule reaches the whole site + from the theme. It is opacity only, so the chip stays the one thing that + *moves* on load; it is one-shot, on the ease-out token, `ARRIVAL_MS` long; + it fills `backwards`, never forwards, because `to` is the page's own state + and an animation still filling keeps `main` a stacking context, under + which nothing inside it could rise above the top bar; and under reduced + motion the same selectors keep a fade-only keyframe rather than going + dark, because the standard quiets by name and a fade is the gentler + variant. + """ + frames = KEYFRAMES["theme"] + moving = "|".join(MOVING_IN_KEYFRAMES) + for reduced in (False, True): + rules = _arrival_rules("theme", reduced) + where = "under reduced motion" if reduced else "in the chrome" + assert rules, f"theme: no rule animates {ARRIVAL} {where}" + for rule in rules: + for value in rule.declarations("animation"): + keyframe, loops = _animation_name_and_loops(value) + assert not loops, f"theme: {rule!r} loops; the arrival plays once" + assert "var(--ease-out)" in value, f"theme: {rule!r} does not read var(--ease-out)" + assert _durations_ms(value) == [ARRIVAL_MS], ( + f"theme: {rule!r} runs `{value}`; the arrival is {ARRIVAL_MS} ms with no delay" + ) + assert not re.search(r"\b(forwards|both)\b", value), ( + f"theme: {rule!r} fills forwards; `to` is the page's own state, so the arrival " + "ends and lets go (`backwards`)" + ) + body = frames.get(keyframe) + assert body is not None, f"theme: @keyframes {keyframe} is not defined in the theme" + assert "opacity" in body, f"theme: @keyframes {keyframe} does not fade" + assert not re.search(rf"(?:^|[;{{\s])({moving})\s*:", body), ( + f"theme: @keyframes {keyframe} moves something; the arrival is opacity only" + ) + + +@pytest.mark.parametrize("name", sorted(SHEETS)) +def test_no_sheet_quiets_the_arrival(name: str) -> None: + """No rule on `main` or `footer`, in any sheet or media block, sets the animation to `none`. + + The arrival test above finds a rule that animates and stops there; a later + `animation: none` on the same selector, in the theme's reduced-motion + block or in an app's own sheet (which loads after the theme and wins), + would cut the fade without failing it. The fade is already the gentler + variant, so nothing is allowed to switch it off. + """ + for rule in RULES[name]: + if not _parts(rule.selector) & set(ARRIVAL): + continue + for prop in ("animation", "animation-name"): + for value in rule.declarations(prop): + assert value.strip() != "none", ( + f"{name}: {rule!r} sets `{prop}: none`; the arrival is kept, not quieted" + ) + + +def test_every_surface_renders_one_main_and_one_footer() -> None: + """The premise of one theme rule: every surface has exactly one `main` and one `footer`. + + A tripwire over the source text, not a render: comments stripped, each + surface's shell (an app's `App.tsx` with its `ui/site.tsx`; a static + page) opens exactly one `` rendered by a child component would + escape this test; the arrival test's docstring states the premise so a + reader knows to keep it. + """ + comments = re.compile(r"|/\*.*?\*/", re.DOTALL) + shells = {page: (WEB / "cover" / page).read_text() for page in PAGES} + for app in APPS: + src = WEB / app / "src" + shells[app] = (src / "App.tsx").read_text() + (src / "ui" / "site.tsx").read_text() + for name, text in shells.items(): + text = comments.sub("", text) + for t in ARRIVAL: + found = re.findall(rf"<{t}\b", text) + assert len(found) == 1, f"{name}: {len(found)} <{t}> tags; the arrival expects exactly one" + assert not re.search(r"]*\bkey=", text), ( + f"{name}:
is keyed, so React would remount it and replay the arrival" + ) + hit = CONDITIONAL_MAIN.search(text) + assert hit is None, ( + f"{name}:
is rendered conditionally (`{' '.join(hit.group(0).split())}`); " + "it mounts once, always" + ) + + +@pytest.mark.parametrize( + ("text", "conditional"), + [ + ('{open &&
', True), + ("{open && (\n
", True), + ("{ready ? (
", True), + ("{x ?
: null}", True), + (":
}", True), + ('
', False), + ('
', False), + ("
", False), + ('
', False), + ("return (\n <>\n \n\n
", False), + ], +) +def test_the_conditional_main_pattern_reads_jsx_conditionals(text: str, conditional: bool) -> None: + """The probes behind `CONDITIONAL_MAIN`, kept so a later edit cannot loosen it unnoticed.""" + assert bool(CONDITIONAL_MAIN.search(text)) is conditional + + # -------------------------------------------------------------- the tokens diff --git a/web/DESIGN.md b/web/DESIGN.md index e4b1f873..8a19208a 100644 --- a/web/DESIGN.md +++ b/web/DESIGN.md @@ -116,10 +116,10 @@ Chrome never does. screen → `--ease-in-out`. Colour under the pointer → `ease`. Constant → `linear`. 4. **How long?** Press 160 ms. Hover colour 150 ms. Popover and sheet - 150–250 ms. Nothing in the chrome over 300 ms per declaration — and the - test reads every time in the declaration, delays included, because a - 300 ms delay is a wait the user feels just as a 300 ms slide is. Exits - faster than entrances. + 150–250 ms. The page's arrival 700 ms, once. Nothing else in the chrome + over 300 ms per declaration — and the test reads every time in the + declaration, delays included, because a 300 ms delay is a wait the user + feels just as a 300 ms slide is. Exits faster than entrances. ## The rules, each with the site's own before and after @@ -130,7 +130,7 @@ Chrome never does. | Entrances use `--ease-out`, never `ease-in` | rung 2's chips (and rung 3's) swept to the pot with `0.55s ease-in` | `.sweep`: `0.4s var(--ease-out)` | a chip pushed across felt leaves fast and settles; ease-in made it hesitate then lurch | | Chrome motion stays under 300 ms per declaration | — | the presses at 160 ms, hover colour at 150 ms, the solver's panes sheet (`.sheet`) arriving over 200 ms | a 180 ms dropdown feels more responsive than a 400 ms one, at the same frame rate | | Exits are faster than entrances; a cascade staggers 30–80 ms and never blocks | — | nothing on the site exits or staggers today; the first one added follows this | the user has decided; the page just answers | -| Nothing moves on load | the homepage's sections rose in on scroll (`.reveal`, 700 ms) | the static pages render still; the chip turning is the one thing that moves without being asked | a page that performs on arrival reads as a demo | +| Nothing moves on load; the page fades in once | the homepage's sections rose in on scroll (`.reveal`, 700 ms) | `main` and `footer` fade in from the paper under the top bar, opacity only, 700 ms on `--ease-out` (`arrive`), once per page and never again inside it; the chip turning is the one thing that moves without being asked | a page that performs on arrival reads as a demo; a page that is simply there, a beat after the chrome, reads as a page turning | | Hover transforms only where a pointer can hover | an arrow on the old front page nudged 4 px on `:hover`, which a tap leaves stuck out | no hover on the site moves anything; one that does goes inside `@media (hover: hover) and (pointer: fine)` | touch fires hover on tap and never un-fires it | | Reduced motion means fewer and gentler, not none | `* { animation: none !important; transition: none !important }` in the theme | the presses, the sweep and the sheet are quieted by name; colour transitions stay; the chip is drawn once (`mark.ts` and `chip.js` read the same query) | a state change still has to be legible to someone who turned motion off | | Reduced motion names the state's own selector, not just the base one | — | the theme quiets `.btn:active:not(:disabled)`, not `.btn:active` | `:not(:disabled)` adds specificity, so quieting the bare `:active` would leave the press in place | @@ -149,6 +149,14 @@ fails on an entry that exempts nothing): - `.sweep`: rungs 2 and 3's chips crossing 58 px of felt to the pot, one-shot, 400 ms; +- `main, footer`: the arrival, the page's content and footer fading in once + per page, opacity only, 700 ms. The key is the whole selector list, so it + exempts that one rule and nothing under `main` + (`test_the_page_fades_in_once_on_arrival` holds its shape: one-shot, the + ease-out token, a keyframe that moves nothing, a `backwards` fill that lets + go when the fade ends, the same fade kept under reduced motion and quieted + by no sheet; `test_every_surface_renders_one_main_and_one_footer` holds + the premise that one theme rule reaches every page); - `.rungs-menu`, `.live i`, `.st::before`: the archived Cover's menu width, live dot and in-progress pulse, kept as they were. diff --git a/web/rung0-viz/src/theme.css b/web/rung0-viz/src/theme.css index 94a18c04..537a721c 100644 --- a/web/rung0-viz/src/theme.css +++ b/web/rung0-viz/src/theme.css @@ -15,7 +15,8 @@ * commands; it is never a prose or UI voice. * 3. The chip is the mark: the ASCII chip turning in the top bar, a red * chip with black indents, and again where the footer closes - * the page. Nothing else moves on load. + * the page. Nothing else moves on load: the page's content fades in + * once under the still top bar, opacity only, and that is all. * 4. Figures are titled blocks, not windows: a number, a bold title that * states the finding, a one-line sub-title naming the measure and the * run, the figure, a caption of at most two sentences, on a top hairline. @@ -303,6 +304,38 @@ main { padding-bottom: 40px; } +/* ---------- the arrival -------------------------------------------------- */ + +/* The page's content and its footer fade in once, from the paper, under a top + bar that is already there: opacity only, so the chip stays the one thing + that moves on load, 700 ms on the ease-out curve, which brings the words up + fast and lets the last of the fade settle slowly. Every surface renders one + `main` and one `footer` (the generator's shell, the five apps' App.tsx), so + this one rule is the whole site's arrival; in an app it plays when React + mounts `main`, which is the first moment there is anything to see. The + fill is `backwards`, not `both`: `to` is the page's own state, so there is + nothing to hold after the fade ends, and an animation still filling + forwards keeps `main` a stacking context, which would flatten the z-order + of everything inside it against the chrome outside it: a popover or sheet + raised inside `main` could no longer rise above the top bar. It runs past + the chrome's 300 ms on purpose and is allowlisted as `main, footer` in + tests/test_ui_standard.py; a tab or view changing inside a page does not + replay it, because `main` stays mounted. */ +main, +footer { + animation: arrive 700ms var(--ease-out) backwards; +} + +@keyframes arrive { + from { + opacity: 0; + } + + to { + opacity: 1; + } +} + h1, h2, h3 { @@ -1220,4 +1253,13 @@ footer a:hover { .rail a:active { transform: none; } + + /* the standard quiets by name: every selector that animates has a + reduced-motion rule of its own (test_every_pulse_and_travel_is_quieted_ + under_reduced_motion). The arrival's quiet form is the same fade, because + a fade with nothing moving is already the gentler variant. */ + main, + footer { + animation: arrive 700ms var(--ease-out) backwards; + } } diff --git a/web/rung1-viz/src/theme.css b/web/rung1-viz/src/theme.css index 94a18c04..537a721c 100644 --- a/web/rung1-viz/src/theme.css +++ b/web/rung1-viz/src/theme.css @@ -15,7 +15,8 @@ * commands; it is never a prose or UI voice. * 3. The chip is the mark: the ASCII chip turning in the top bar, a red * chip with black indents, and again where the footer closes - * the page. Nothing else moves on load. + * the page. Nothing else moves on load: the page's content fades in + * once under the still top bar, opacity only, and that is all. * 4. Figures are titled blocks, not windows: a number, a bold title that * states the finding, a one-line sub-title naming the measure and the * run, the figure, a caption of at most two sentences, on a top hairline. @@ -303,6 +304,38 @@ main { padding-bottom: 40px; } +/* ---------- the arrival -------------------------------------------------- */ + +/* The page's content and its footer fade in once, from the paper, under a top + bar that is already there: opacity only, so the chip stays the one thing + that moves on load, 700 ms on the ease-out curve, which brings the words up + fast and lets the last of the fade settle slowly. Every surface renders one + `main` and one `footer` (the generator's shell, the five apps' App.tsx), so + this one rule is the whole site's arrival; in an app it plays when React + mounts `main`, which is the first moment there is anything to see. The + fill is `backwards`, not `both`: `to` is the page's own state, so there is + nothing to hold after the fade ends, and an animation still filling + forwards keeps `main` a stacking context, which would flatten the z-order + of everything inside it against the chrome outside it: a popover or sheet + raised inside `main` could no longer rise above the top bar. It runs past + the chrome's 300 ms on purpose and is allowlisted as `main, footer` in + tests/test_ui_standard.py; a tab or view changing inside a page does not + replay it, because `main` stays mounted. */ +main, +footer { + animation: arrive 700ms var(--ease-out) backwards; +} + +@keyframes arrive { + from { + opacity: 0; + } + + to { + opacity: 1; + } +} + h1, h2, h3 { @@ -1220,4 +1253,13 @@ footer a:hover { .rail a:active { transform: none; } + + /* the standard quiets by name: every selector that animates has a + reduced-motion rule of its own (test_every_pulse_and_travel_is_quieted_ + under_reduced_motion). The arrival's quiet form is the same fade, because + a fade with nothing moving is already the gentler variant. */ + main, + footer { + animation: arrive 700ms var(--ease-out) backwards; + } } diff --git a/web/rung2-viz/src/theme.css b/web/rung2-viz/src/theme.css index 94a18c04..537a721c 100644 --- a/web/rung2-viz/src/theme.css +++ b/web/rung2-viz/src/theme.css @@ -15,7 +15,8 @@ * commands; it is never a prose or UI voice. * 3. The chip is the mark: the ASCII chip turning in the top bar, a red * chip with black indents, and again where the footer closes - * the page. Nothing else moves on load. + * the page. Nothing else moves on load: the page's content fades in + * once under the still top bar, opacity only, and that is all. * 4. Figures are titled blocks, not windows: a number, a bold title that * states the finding, a one-line sub-title naming the measure and the * run, the figure, a caption of at most two sentences, on a top hairline. @@ -303,6 +304,38 @@ main { padding-bottom: 40px; } +/* ---------- the arrival -------------------------------------------------- */ + +/* The page's content and its footer fade in once, from the paper, under a top + bar that is already there: opacity only, so the chip stays the one thing + that moves on load, 700 ms on the ease-out curve, which brings the words up + fast and lets the last of the fade settle slowly. Every surface renders one + `main` and one `footer` (the generator's shell, the five apps' App.tsx), so + this one rule is the whole site's arrival; in an app it plays when React + mounts `main`, which is the first moment there is anything to see. The + fill is `backwards`, not `both`: `to` is the page's own state, so there is + nothing to hold after the fade ends, and an animation still filling + forwards keeps `main` a stacking context, which would flatten the z-order + of everything inside it against the chrome outside it: a popover or sheet + raised inside `main` could no longer rise above the top bar. It runs past + the chrome's 300 ms on purpose and is allowlisted as `main, footer` in + tests/test_ui_standard.py; a tab or view changing inside a page does not + replay it, because `main` stays mounted. */ +main, +footer { + animation: arrive 700ms var(--ease-out) backwards; +} + +@keyframes arrive { + from { + opacity: 0; + } + + to { + opacity: 1; + } +} + h1, h2, h3 { @@ -1220,4 +1253,13 @@ footer a:hover { .rail a:active { transform: none; } + + /* the standard quiets by name: every selector that animates has a + reduced-motion rule of its own (test_every_pulse_and_travel_is_quieted_ + under_reduced_motion). The arrival's quiet form is the same fade, because + a fade with nothing moving is already the gentler variant. */ + main, + footer { + animation: arrive 700ms var(--ease-out) backwards; + } } diff --git a/web/rung3-viz/src/theme.css b/web/rung3-viz/src/theme.css index 94a18c04..537a721c 100644 --- a/web/rung3-viz/src/theme.css +++ b/web/rung3-viz/src/theme.css @@ -15,7 +15,8 @@ * commands; it is never a prose or UI voice. * 3. The chip is the mark: the ASCII chip turning in the top bar, a red * chip with black indents, and again where the footer closes - * the page. Nothing else moves on load. + * the page. Nothing else moves on load: the page's content fades in + * once under the still top bar, opacity only, and that is all. * 4. Figures are titled blocks, not windows: a number, a bold title that * states the finding, a one-line sub-title naming the measure and the * run, the figure, a caption of at most two sentences, on a top hairline. @@ -303,6 +304,38 @@ main { padding-bottom: 40px; } +/* ---------- the arrival -------------------------------------------------- */ + +/* The page's content and its footer fade in once, from the paper, under a top + bar that is already there: opacity only, so the chip stays the one thing + that moves on load, 700 ms on the ease-out curve, which brings the words up + fast and lets the last of the fade settle slowly. Every surface renders one + `main` and one `footer` (the generator's shell, the five apps' App.tsx), so + this one rule is the whole site's arrival; in an app it plays when React + mounts `main`, which is the first moment there is anything to see. The + fill is `backwards`, not `both`: `to` is the page's own state, so there is + nothing to hold after the fade ends, and an animation still filling + forwards keeps `main` a stacking context, which would flatten the z-order + of everything inside it against the chrome outside it: a popover or sheet + raised inside `main` could no longer rise above the top bar. It runs past + the chrome's 300 ms on purpose and is allowlisted as `main, footer` in + tests/test_ui_standard.py; a tab or view changing inside a page does not + replay it, because `main` stays mounted. */ +main, +footer { + animation: arrive 700ms var(--ease-out) backwards; +} + +@keyframes arrive { + from { + opacity: 0; + } + + to { + opacity: 1; + } +} + h1, h2, h3 { @@ -1220,4 +1253,13 @@ footer a:hover { .rail a:active { transform: none; } + + /* the standard quiets by name: every selector that animates has a + reduced-motion rule of its own (test_every_pulse_and_travel_is_quieted_ + under_reduced_motion). The arrival's quiet form is the same fade, because + a fade with nothing moving is already the gentler variant. */ + main, + footer { + animation: arrive 700ms var(--ease-out) backwards; + } } diff --git a/web/solver-viz/src/theme.css b/web/solver-viz/src/theme.css index 94a18c04..537a721c 100644 --- a/web/solver-viz/src/theme.css +++ b/web/solver-viz/src/theme.css @@ -15,7 +15,8 @@ * commands; it is never a prose or UI voice. * 3. The chip is the mark: the ASCII chip turning in the top bar, a red * chip with black indents, and again where the footer closes - * the page. Nothing else moves on load. + * the page. Nothing else moves on load: the page's content fades in + * once under the still top bar, opacity only, and that is all. * 4. Figures are titled blocks, not windows: a number, a bold title that * states the finding, a one-line sub-title naming the measure and the * run, the figure, a caption of at most two sentences, on a top hairline. @@ -303,6 +304,38 @@ main { padding-bottom: 40px; } +/* ---------- the arrival -------------------------------------------------- */ + +/* The page's content and its footer fade in once, from the paper, under a top + bar that is already there: opacity only, so the chip stays the one thing + that moves on load, 700 ms on the ease-out curve, which brings the words up + fast and lets the last of the fade settle slowly. Every surface renders one + `main` and one `footer` (the generator's shell, the five apps' App.tsx), so + this one rule is the whole site's arrival; in an app it plays when React + mounts `main`, which is the first moment there is anything to see. The + fill is `backwards`, not `both`: `to` is the page's own state, so there is + nothing to hold after the fade ends, and an animation still filling + forwards keeps `main` a stacking context, which would flatten the z-order + of everything inside it against the chrome outside it: a popover or sheet + raised inside `main` could no longer rise above the top bar. It runs past + the chrome's 300 ms on purpose and is allowlisted as `main, footer` in + tests/test_ui_standard.py; a tab or view changing inside a page does not + replay it, because `main` stays mounted. */ +main, +footer { + animation: arrive 700ms var(--ease-out) backwards; +} + +@keyframes arrive { + from { + opacity: 0; + } + + to { + opacity: 1; + } +} + h1, h2, h3 { @@ -1220,4 +1253,13 @@ footer a:hover { .rail a:active { transform: none; } + + /* the standard quiets by name: every selector that animates has a + reduced-motion rule of its own (test_every_pulse_and_travel_is_quieted_ + under_reduced_motion). The arrival's quiet form is the same fade, because + a fade with nothing moving is already the gentler variant. */ + main, + footer { + animation: arrive 700ms var(--ease-out) backwards; + } }