@phantompixeldev/retrocss 2.8.1 → 3.0.1

package/MIGRATION.md

@@ -1,3 +1,212 @@
+# Migrating to RetroCSS 3.0
+
+3.0 is a visual release. Nothing was renamed and no class was removed, but two
+changes are visible on every page that consumes the framework, so they are
+called out first.
+
+> **If you are on 3.0.0, upgrade to 3.0.1.** 3.0.0 shipped a regression that
+> rounded eleven components. See [section 2](#2-border-radius-is-no-longer-important).
+
+## 1. Body text is 16px
+
+`--retro-font-size` moves from `0.875rem` (14px) to `1rem` (16px). The rest of
+the scale is expressed in `rem` against the root, so headings, buttons, badges
+and inputs all move with it.
+
+14px is the authentic Win9x metric and 16px is not. The trade was made
+deliberately: the framework is used to build things people read, and 14px is
+below the size at which most people read comfortably. One line puts it back:
+
+```css
+:root { --retro-font-size: 0.875rem; }
+```
+
+Expect layouts that were tuned to the pixel at 14px to need a little room. If
+you pinned a width in `px` to fit a specific string, it will now clip.
+
+## 2. `border-radius: 0` is no longer `!important`
+
+The reset was `* { border-radius: 0 !important }`, which meant nothing in a
+consuming application could round a corner — including `.retro-rounded`, which
+had to fight the reset, and `_modal.scss`, which needed its own `!important` to
+get 4px back. The default is still square:
+
+```css
+* { border-radius: 0; }
+```
+
+If you were relying on the reset to flatten a third-party widget's corners,
+that widget's own radius now wins, and you will need to zero it yourself.
+
+### The 3.0.0 regression, fixed in 3.0.1
+
+Dropping the `!important` had a consequence nobody caught: the reset had been
+suppressing 31 hardcoded `border-radius` declarations scattered through the
+components, written over the years by people who never saw them take effect.
+All of them came alive at once. **3.0.0 renders these rounded**, and 3.0.1
+returns them to square:
+
+| Component | 3.0.0 | 3.0.1 |
+| --- | --- | --- |
+| `.retro-nav-pills .retro-nav-item` | 999px | 999px *(kept, see below)* |
+| `.retro-tag` | 12px | 12px *(kept, see below)* |
+| `.retro-list` / `.retro-list li` | 6px / 4px | 0 |
+| `.retro-rating-star` | 6px | 0 |
+| `.retro-tag-input`, `.retro-search-bar`, `.retro-file-upload`, `.retro-tooltip`, `.retro-sidebar`, `.retro-tab` | 4px | 0 |
+| `.retro-breadcrumbs`, `.retro-dropdown-menu`, `.retro-pagination .retro-btn`, `.retro-divider-vertical` | 2px | 0 |
+
+Those declarations now read `var(--retro-border-radius)`, which is `0` by
+default. So the fix is not a second reversal — it is the radius system finally
+being wired up. **You can round all of them at once:**
+
+```css
+:root { --retro-border-radius: 4px; }
+```
+
+`.retro-nav-pills` and `.retro-tag` keep their shapes deliberately: a pill and
+a chip are the shapes those components are named for, and they are the one
+place the framework spends a modern idiom on purpose.
+
+Note that the core Win9x chrome — card, button, badge, table, input, modal,
+alert, progress, carousel — sets `border-radius: 0` directly and does **not**
+follow the token. Rounding those too is a change under consideration; if you
+need it today, override them yourself.
+
+`scripts/check-radius.mjs` now runs in CI and fails the build on any new
+hardcoded radius, so this cannot recur.
+
+### Radio buttons and the spinner are round again
+
+The same reset had been squaring six declarations that were never chrome:
+`.retro-radio` and its checked dot, `input[type="radio"].retro-input` and its
+dot, `.retro-spinner`, and the `.retro-list` bullet. A Windows 95 radio button
+is a circle, so squaring them was a long-standing bug. They are circular from
+3.0.0 onward and stay that way. If you were relying on square radios, set
+`border-radius: 0` on them yourself.
+
+## 3. On-fill text follows the theme
+
+If you built a component that pairs a RetroCSS hue fill with white text:
+
+```css
+/* before */
+.my-chip { background: var(--retro-primary); color: var(--retro-white); }
+```
+
+...that pair breaks in dark mode. `--retro-white` inverts to `#3a3a3a` while
+the fill *lightens* to `#4a90e2`, so both move and the contrast collapses —
+this was measuring 3.45:1 on the framework's own active nav items. Use the
+`-fg` token, which is defined as "text on this fill" and is contrast-gated in
+both themes:
+
+```css
+/* after */
+.my-chip { background: var(--retro-primary); color: var(--retro-primary-fg); }
+```
+
+The `--retro-black` / `--retro-white` pair is still fine *together* — both
+invert, so a black chip with white text simply becomes a white chip with dark
+text.
+
+## 4. Tooltips are instant
+
+`.retro-tooltip` toggles `display` rather than `opacity` + `visibility`, so the
+0.2s fade is gone. This was not a style choice: a hidden tooltip kept its box in
+the page's scrollable overflow region, so a `.retro-tooltip-right` on a trigger
+near the viewport edge widened the whole page while invisible. Instant tooltips
+are period-correct anyway.
+
+If you were animating `.retro-tooltip` yourself, animate a child instead.
+
+## Smaller changes
+
+- **Nav variants and breadcrumbs wrap.** `.retro-nav-tabbed`,
+  `.retro-nav-underlined`, `.retro-nav-buttons` and `.retro-breadcrumbs` were
+  single unwrapped flex rows, so a long set of labels pushed the page sideways
+  on narrow viewports. They wrap onto a second line now.
+- **`.retro-nav-vertical`** is capped at `max-width: 100%`; it was sized to its
+  longest label with `width: max-content`.
+- **`.retro-alert-close`** inherits the alert's own text colour and no longer
+  renders at `opacity: 0.7`.
+- **Unfilled `.retro-rating-star`** uses `--retro-text-muted` instead of
+  `--retro-border-dark`, which was invisible on the dark chassis.
+- **`.retro-heading-variant`** drops its `letter-spacing`. Uppercase plus
+  monospace already carries the emphasis.
+
+## Removed
+
+Everything here was already dead: unreachable, uninitialised, or compiling to
+nothing. If you were using any of it, it was not doing what its name implied.
+
+- **`window.RetroSidebar` / `src/js/sidebar.js`** — 234 lines that were bundled
+  but never initialised. Wiring it in would have injected a toggle button and a
+  full-screen overlay into every consuming page, hijacked every sidebar link
+  with smooth scrolling and `history.pushState`, overwritten whichever link the
+  author had marked `.active`, and bound an unthrottled `scroll` listener that
+  re-queried `section[id], div[id]` across the whole document on every event.
+  That is application logic, not framework logic. The CSS stays —
+  `.retro-sidebar`, `.retro-sidebar-toggle` and `.retro-sidebar-overlay` are all
+  still styled, so the same UI is a few lines of your own JS.
+- **Eleven `@container` blocks** in `utilities/_container-queries.scss`:
+  `.retro-cq-sm`, `-md`, `-lg`, `-xl`, `-wide`, `-tall`, `-landscape`,
+  `-portrait`, `-size-sm`, `-size-md`, `-size-lg`. Every one had a comment for a
+  body and compiled to nothing. The blocks with real declarations
+  (`.retro-cq-hide`, `-show`, `-text-lg`, `-text-xl`, `-flex-row`, `-flex-col`,
+  `-p-4`, `-p-6`, `-grid-2`, `-grid-3`) are untouched.
+- **Five Sass mixins**: `retro-border`, `retro-hover`, `retro-active`,
+  `retro-transition`, `retro-z-index`. None was called from anywhere in the
+  framework. Their values are all reachable directly as custom properties —
+  `--retro-border-dark`, `--retro-border-sunken`, `--retro-z-index-modal` and so
+  on — which is what the components use. `retro-box-shadow`, `retro-focus`,
+  `retro-focus-ring` and `retro-breakpoint` are still here.
+- **Five devDependencies**: `concat-cli`, `copyfiles`, `mkdirp`, `onchange`,
+  `uglify-js`. No script, workflow or config invoked any of them.
+
+## New
+
+- **Sortable tables actually work.** `.retro-table-sortable` had working JS and
+  no styles, no markup anywhere in the repo, and no way to reach it from the
+  keyboard. Headers are now focusable and respond to Enter and Space, carry
+  `aria-sort`, and show a direction indicator. Columns are sniffed as numeric or
+  text, or declared:
+
+  ```html
+  <table class="retro-table retro-table-sortable">
+    <thead>
+      <tr>
+        <th>Name</th>
+        <th data-sort="number">Size</th>
+        <th data-sort="none">Actions</th>
+      </tr>
+    </thead>
+    <tbody>...</tbody>
+  </table>
+  ```
+
+  A cell can carry `data-sort-value` to sort a formatted value ("2 days ago",
+  "$1,204.00") by what it means. The numeric sniff is deliberately strict: a
+  loose `parseFloat` reads `2023-09-01` as `2023` and `SKU-001` as `-1`, which
+  quietly sorts a date column by year and an ID column by the digits after the
+  first dash.
+
+- **Code blocks get a copy button.** `code-copy.js` was bundled but never
+  initialised, so `.retro-code-copy` existed only in the stylesheet. It now runs
+  from `RetroCSS.init()`. Outside a secure context, where
+  `navigator.clipboard` is undefined, it selects the code and says
+  `Press Ctrl+C` rather than failing silently.
+
+- **`npm run docs:api`** renders the SassDoc blocks the SCSS has always carried
+  to `docs/api/`. `sassdoc` was installed and never wired up.
+
+## Verifying your own pages
+
+`npm run check:pages` renders every page in the repo in real Chromium, in both
+themes, at 1200/980/760/420/360px, and fails on console errors, horizontal
+overflow, a missing or duplicated `h1`, contrast below AA on any rendered text,
+or an input glyph off-centre. It is worth pointing at your own pages.
+
+---
+
 # Migrating to RetroCSS 2.0
 
 2.0 is an accessibility and readability release. Nothing was renamed and no

package/README.md

@@ -175,9 +175,24 @@ Typography is tokenised the same way: `--retro-font`, `--retro-font-heading`,
 default; for a modern heading font, set
 `--retro-font-heading: 'Segoe UI', Tahoma, sans-serif;`.
 
-> **Upgrading from 1.x?** See [MIGRATION.md](MIGRATION.md). No classes were
-> renamed or removed, but 2.0 visibly restyles a few things to meet WCAG AA —
-> each with a one-line override.
+Corners are square, because Windows 95 was. One token softens the components
+that opt in — lists, dropdowns, breadcrumbs, tooltips, the search bar, the
+sidebar, tabs, pagination and the file uploader:
+
+```css
+:root { --retro-border-radius: 4px; }
+```
+
+The core chrome — card, button, badge, table, input, modal — stays square
+regardless, and `.retro-rounded` / `-lg` / `-full` still round one element at a
+time.
+
+> **Upgrading?** See [MIGRATION.md](MIGRATION.md). No class has ever been
+> renamed, but 3.0 raises the body text to 16px and drops the `!important` from
+> the `border-radius` reset, both of which are visible on every page — each with
+> a one-line override. **On 3.0.0, upgrade to 3.0.1**: dropping that
+> `!important` woke 31 dormant radius declarations and rounded eleven
+> components. 2.0 restyled a few things to meet WCAG AA.
 
 ## Utilities
 
@@ -210,6 +225,13 @@ themes. `npm run check:a11y` compiles the SCSS and asserts it, and fails the
 build on a regression — it also catches any `var(--retro-*)` that resolves to
 nothing.
 
+That proves the *tokens* are sound. `npm run check:pages` proves the *pages*
+are: it renders every page in the repo in real Chromium, in both themes, at
+1200/980/760/420/360px, and fails on a console error, horizontal overflow, a
+missing or duplicated `<h1>`, any rendered text below AA against the surface
+actually painted behind it, or an input glyph off its field's centre line. Both
+run in CI on every push.
+
 Beyond colour:
 
 - **Focus rings are `:focus-visible`.** Keyboard and assistive-tech users get a
@@ -224,6 +246,8 @@ Beyond colour:
   Tab all behave. Escape returns focus to the toggle.
 - **`prefers-reduced-motion` is honoured** — every animation and transition is
   neutralised, with the looping text effects switched off outright.
+- **Sortable tables are operable.** `.retro-table-sortable` headers are
+  focusable, sort on Enter and Space as well as click, and carry `aria-sort`.
 - **`.retro-sr-only`** labels icon-only controls; `.retro-sr-only-focusable`
   gives you a skip link.
 
@@ -262,6 +286,25 @@ Watch for changes:
 npm run watch
 ```
 
+Run the gates:
+
+```bash
+npm run check:a11y && npm run check:radius && npm run check:pages
+```
+
+`check:a11y` gates the tokens (every `var(--retro-*)` resolves, every
+text/surface pair clears WCAG AA), `check:radius` gates the shape (nothing
+hardcodes a corner behind `--retro-border-radius`), and `check:pages` gates the
+rendered result across 8 pages × 2 themes × 5 widths.
+
+`check:pages` needs a browser once: `npx playwright install chromium`.
+
+Render the SassDoc API reference to `docs/api/`:
+
+```bash
+npm run docs:api
+```
+
 ## License
 
 MIT