eidotter 0.42.0 → 0.43.0

package/llms.txt

@@ -3,7 +3,7 @@
 > DOS-themed React component library with authentic CGA/amber phosphor aesthetics.
 
 ## Quick Facts
-- 59 components (Accordion, AIText, Alert, Badge, Brand (Logo, Mark, Wordmark, BrandLockup), Breadcrumb, Button, CalendarHeatmap, Card, Chat (ChatMessage, ChatHistory, ChatInput, ChatContainer), Checkbox, ChecklistRow, CmdPalette, CommandPrompt, Connector, CopyButton, DecayStrip, DosDialog, DosFigure, DosWindow, EmptyState, FilterBar, Footer, Gauge, Header, HoldToComplete, Icon, IconButton, InlineExpand, InlineLink, Input, LabeledProgress, LedgerRow, LegalPage, Lightbox, Meter (MeterGroup), Modal, Nav, Notification, Progress, ProgressRing, RangeBar, RetroEffects, SectionHeading, Select, Separator, SeriesBars, Skeleton, Stat, Switch, Tabs, Tag, Terminal, TextScramble, TimelineContainer, TimelineFeed, TimelineNode, TimelinePage, VitalsStrip)
+- 61 components (Accordion, AIText, Alert, Badge, Bench, Brand (Logo, Mark, Wordmark, BrandLockup), Breadcrumb, Button, CalendarHeatmap, Card, Chat (ChatMessage, ChatHistory, ChatInput, ChatContainer), Checkbox, ChecklistRow, CmdPalette, CommandPrompt, Connector, CopyButton, DecayStrip, DosDialog, DosFigure, DosWindow, EmptyState, FilterBar, Footer, Gauge, Header, HoldToComplete, Icon, IconButton, InlineExpand, InlineLink, Input, LabeledProgress, LedgerRow, LegalPage, Lightbox, Meter (MeterGroup), Modal, Nav, Notification, PageShell (PageSection), Progress, ProgressRing, RangeBar, RetroEffects, SectionHeading, Select, Separator, SeriesBars, Skeleton, Stat, Switch, Tabs, Tag, Terminal, TextScramble, TimelineContainer, TimelineFeed, TimelineNode, TimelinePage, VitalsStrip)
 - Amber theme is the default (amber-on-black phosphor CRT); a light theme ("amber in daylight") is in progress (DMNC-1058). Components paint via semantic roles so they re-theme — do not hardcode dark-only assumptions.
 - CSS custom properties + Tailwind preset
 - React 18/19, Tailwind 3/4 compatible
@@ -27,8 +27,8 @@ Apps default to the amber theme and offer the light theme via a consistent setti
 
 ## Upgrading
 - Every minor with breaking/visible changes ships a guide at `node_modules/eidotter/migrations/<version>.md` (index: `migrations/README.md`).
-- Read every guide between the installed and the target version, oldest first, and follow its checklist. First guide: `migrations/0.41.0.md`.
-- 0.x caret gotcha: `^0.40.x` never resolves to 0.41.0; bump the range explicitly, to `^0.42.0` (0.41.0 shipped before its review fixes).
+- Read every guide between the installed and the target version, oldest first, and follow its checklist. Guides: `migrations/0.41.0.md`, `migrations/0.43.0.md`.
+- 0.x caret gotcha: `^0.40.x` never resolves to 0.41.0; bump the range explicitly, to `^0.43.0`.
 
 ## Token Categories
 - `--color-semantic-*`: USE THESE for components (background, text, border, status)

package/migrations/0.41.0.md

@@ -61,8 +61,9 @@ cp node_modules/eidotter/dist/eidotter.css /tmp/eidotter-old.css
 Then change the range explicitly to the latest 0.41.x (0.41.3 or later):
 
 ```bash
-npm install eidotter@^0.42.0
+npm install eidotter@^0.41.3
 # check what actually resolved: 0.41.3 or later
+# going further? read 0.43.0.md next, then install ^0.43.0
 npm ls eidotter
 ```
 
@@ -917,7 +918,7 @@ Work top to bottom. Each step points at the section above that explains it.
 - [ ] Read every guide in `node_modules/eidotter/migrations/` between your old
       version and 0.41.0, oldest first (see `README.md` in that folder).
 - [ ] `cp node_modules/eidotter/dist/eidotter.css /tmp/eidotter-old.css` (before `npm install`).
-- [ ] Install the latest 0.41.x (0.41.3 or later): `npm install eidotter@^0.42.0`, then `npm ls eidotter` shows 0.41.3 or later. Commit the lockfile.
+- [ ] Install the latest 0.41.x (0.41.3 or later): `npm install eidotter@^0.41.3` (or straight to `^0.43.0` after reading `0.43.0.md`), then `npm ls eidotter` shows 0.41.3 or later. Commit the lockfile.
 - [ ] Tailwind v4 apps: load eidotter in a cascade layer (`@layer theme, base, components, eidotter, utilities;` then `@import "eidotter/styles" layer(eidotter);`), drop the JS `import 'eidotter/styles'`, keep your own resets layered ("Tailwind v4 apps" after "How to bump").
 - [ ] No-Tailwind apps: run the class diff from section 2 and fix every real hit.
 - [ ] No-preflight apps: set `html` font, colours and `a` colour yourself (section 4).

package/migrations/0.43.0.md

@@ -0,0 +1,129 @@
+# Upgrading to eidotter 0.43.0
+
+From 0.42.x. Coming from older versions, read [0.41.0.md](./0.41.0.md) first.
+
+0.43.0 is mostly additive: a page template (`PageShell`, `PageSection`, `Bench`)
+and four opt-in `Header` props. One change is visible without touching your
+code: a long `Header` brand wraps instead of ending in an ellipsis.
+
+## Who must act
+
+- Apps that render `<Header>` with a long `brandName` on narrow screens:
+  check the header height (section 2).
+- Everyone else: bump and you are done. The new pieces are optional.
+
+## 1. How to bump
+
+0.x caret ranges stop at the next minor (`^0.42.0` never resolves to 0.43.0),
+so change the range explicitly:
+
+```bash
+npm install eidotter@^0.43.0
+npm ls eidotter   # 0.43.0 or later
+```
+
+Commit the lockfile.
+
+## 2. Visible change: the Header brand wraps
+
+**What changed.** The brand name in `Header` (`brand="lockup"`, `"mark"`,
+`"text"` or `children`) used to stay on one line and end in "…" when the brand,
+the `end` slot and the MENU trigger did not fit. Now the name moves onto a
+second line. The brand link shrinks before the `end` slot does; the end slot
+clips only once the brand reaches its floor (the icon plus about 8 tracked
+characters). Words break at spaces. Only a single word longer than the floor
+breaks mid-word. The icon top-aligns beside a two-line name. A brand that fits
+on one line renders exactly as before.
+
+**How to find it.** Open each page with a `Header` at 320px and 390px wide. If
+the brand name used to end in "…", it now wraps and the header is taller.
+
+**What to do.**
+
+- Nothing, if the taller header looks fine. This was the intended fix.
+- If something is sized to a fixed header height (`scroll-padding-top`, a
+  sticky sub-header's `top`, a hero's `min-height: calc(100vh - 64px)`), measure
+  the header instead, or give it room for two lines.
+- If you prefer just the icon on phones, pass `brandCollapse="mark"` (section 3).
+- CSS you wrote against the old ellipsis (`text-overflow` or `white-space` on
+  `.eidotter-header__brand-name`) can be deleted.
+
+**How to verify.** At 320px the full brand name is readable, nothing paints
+over it, and the MENU trigger stays on the right.
+
+## 3. New, opt-in
+
+All defaults render as in 0.42.
+
+### Header props
+
+| Prop | Values | Effect |
+|---|---|---|
+| `layout` | `'inline'` (default), `'stacked'` | `stacked`: the desktop nav gets its own row under the brand, on the brand's left edge. The `end` slot and MENU stay on the brand row. Below 768px it behaves like `inline`. |
+| `rule` | `true` (default), `false` | `false` removes the bottom line and the glow under it. |
+| `contained` | `false` (default), `true`, CSS length | Centres the header content in a column (`true` = 1240px, or e.g. `'72rem'`) with the PageShell gutter. The header band itself stays full width. |
+| `brandCollapse` | `'none'` (default), `'mark'` | `mark`: below 480px of header width only the icon shows. The name stays the link's accessible name. Needs `brand="lockup"` or `"mark"`. |
+
+### PageShell and PageSection
+
+One centred column for a whole page: `header`, `intro`, sections and `footer`
+share one left edge, 40px apart, with no dividers.
+
+```tsx
+import { Header, PageShell, PageSection } from 'eidotter';
+
+<PageShell
+  header={<Header brandName="Example" items={items} layout="stacked" rule={false} />}
+  intro={{
+    eyebrow: 'Review',
+    title: 'Page title',
+    lead: 'One paragraph, up to 68 characters wide.',
+    toc: [{ href: '#findings', label: 'Findings' }],
+  }}
+  footer={<Footer />}
+>
+  <PageSection id="findings" title="Findings">…</PageSection>
+</PageShell>
+```
+
+- `maxWidth` (default `'1240px'`), `contentAs` (`'main'` default; use `'div'`
+  if your layout already renders `<main>`), `contentId` (skip-link target).
+- A `Header` in the `header` slot drops its own inline padding, so its brand
+  sits on the column edge. Use `contained` only on a `Header` outside PageShell.
+- `PageSection`: `title` (an h2 by default, `headingLevel` 2 to 4), `id` for TOC
+  anchors.
+
+### Bench
+
+A before/after compare unit on `DosWindow`.
+
+```tsx
+import { Bench } from 'eidotter';
+
+<Bench
+  title="Home page"
+  note="Optional muted note"
+  panes={[
+    { label: 'Before', tone: 'before', content: <img src={before} alt="Home page before" /> },
+    { label: 'After', tone: 'after', content: <img src={after} alt="Home page after" /> },
+  ]}
+/>
+```
+
+- `chips` (ReactNode in the title strip), `headingLevel` (default 3),
+  `maxHeight` of each pane frame (default `'640px'`).
+- Pane `frame: 'phone'` centres the content at 390px. `frameLabel` names the
+  scrollable frame for screen readers.
+- Panes stack below 760px of bench width.
+
+Both components are server-safe. In a Next.js server component, deep-import
+them: `eidotter/components/PageShell`, `eidotter/components/Bench`.
+
+The Storybook story `Templates/ReviewPage` shows all of it composed.
+
+## Checklist
+
+- [ ] `npm install eidotter@^0.43.0`; `npm ls eidotter` shows 0.43.0 or later. Commit the lockfile.
+- [ ] Check every page with a `Header` at 320px and 390px; fix anything sized to a fixed header height (section 2).
+- [ ] Delete CSS that targeted the old brand ellipsis, if any.
+- [ ] Optional: adopt `layout="stacked"`, `rule={false}`, `brandCollapse="mark"`, `PageShell` or `Bench` (section 3).

package/migrations/README.md

@@ -34,6 +34,7 @@ The folder ships in the npm package:
 ```
 node_modules/eidotter/migrations/README.md
 node_modules/eidotter/migrations/0.41.0.md
+node_modules/eidotter/migrations/0.43.0.md
 ```
 
 It is also exported, so tooling can resolve a guide by path:
@@ -44,3 +45,4 @@ It is also exported, so tooling can resolve a guide by path:
 | Version | Summary |
 |---|---|
 | [0.41.0](./0.41.0.md) | 16px floor, CSS reset and unused utilities no longer leak, `text-secondary` meaning change, Header lockup default, overlays on `DosDialog` (removed classes), focus rings; adopt `IconButton`, `DosDialog`, `DosWindow`, the favicon export and the `amber-paper` theme |
+| [0.43.0](./0.43.0.md) | `Header` brand wraps instead of ellipsizing; adopt `PageShell`/`PageSection`, `Bench` and the opt-in `Header` `layout`/`rule`/`contained`/`brandCollapse` props |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "eidotter",
-  "version": "0.42.0",
+  "version": "0.43.0",
   "type": "module",
   "description": "A DOS Themed Design System",
   "main": "./dist/index.umd.js",