eidotter 0.41.2 → 0.41.3

package/llms.txt

@@ -28,7 +28,7 @@ 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.41.2` (0.41.0 shipped before its review fixes).
+- 0.x caret gotcha: `^0.40.x` never resolves to 0.41.0; bump the range explicitly, to `^0.41.3` (0.41.0 shipped before its review fixes).
 
 ## Token Categories
 - `--color-semantic-*`: USE THESE for components (background, text, border, status)
@@ -144,6 +144,7 @@ Components originate from different projects. Use `getComponentsByOrigin(project
 - NEVER use sans-serif fonts (DOS theme)
 
 ## Integration Quick Start
+Without Tailwind, or with Tailwind v3:
 ```css
 /* In your globals.css */
 @import "eidotter/tokens.css";
@@ -164,6 +165,18 @@ module.exports = {
 }
 ```
 
+Tailwind v4 apps: load eidotter's CSS in a cascade layer before your utilities. dist/eidotter.css ships ~200 component-used stock utilities (.flex, .flex-col, .hidden, ...) unlayered, and unlayered CSS beats @layer utilities (an app's md:flex-row loses to eidotter's .flex-col).
+```css
+/* globals.css: the layer statement comes first */
+@layer theme, base, components, eidotter, utilities;
+@import "tailwindcss";
+@import "eidotter/styles" layer(eidotter);
+```
+- Remove the JS `import 'eidotter/styles'` (a second, unlayered copy brings the problem back).
+- Never @source / content-scan node_modules/eidotter/dist.
+- Trade-off: inside the layer, eidotter loses to the app's UNLAYERED global rules (an unlayered `* { margin: 0; padding: 0 }` beats eidotter's component utilities), and eidotter's reset beats element defaults in the app's `@layer base`. Keep app resets layered; put global element styles in a layer declared after `eidotter`.
+- Guide: node_modules/eidotter/migrations/0.41.0.md, "Tailwind v4 apps".
+
 ## Links
 - npm: https://www.npmjs.com/package/eidotter
 - Storybook: See docs/ folder

package/migrations/0.41.0.md

@@ -10,7 +10,7 @@ You are reading this from `node_modules/eidotter/migrations/0.41.0.md`, or from
 the repository's `migrations/` folder. If you are upgrading across several
 minors, read [`README.md`](./README.md) in this folder first.
 
-> **Install 0.41.1 or later.** 0.41.0 was published before the release review fixes. It lacks the eidotter token utilities that section 2 promises, its reset still cancels Tailwind v4 utilities, and `Stat` loses its colours. 0.41.1 fixes all of this with no API change, and everything in this guide applies to it.
+> **Install the latest 0.41.x (0.41.3 or later).** 0.41.0 was published before the release review fixes. It lacks the eidotter token utilities that section 2 promises, its reset still cancels Tailwind v4 utilities, and `Stat` loses its colours. 0.41.1 fixes all of this with no API change, and 0.41.2 stops `TextScramble` (and `Stat` `scramble`) from shipping random glyphs in server HTML, a hydration error. 0.41.3 fixes what the first consumer bumps found (empty `Header` nav, brand focus ring, end-slot clipping, `Terminal` role). Everything in this guide applies to the latest 0.41.x.
 
 ## Who must act
 
@@ -41,6 +41,7 @@ utility classes you used without having Tailwind yourself.
 |---|---|
 | Tailwind 3 or 4 with `eidotter/tailwind.preset` | 1 (16px floor), 3, 5, 6, 7 |
 | Tailwind 4 without the preset | 1 (component sizes only), 3, 5, 6, 7 |
+| Any Tailwind 4 app | also "Tailwind v4 apps: load eidotter's CSS in a cascade layer" |
 | No Tailwind (plain CSS, Astro, Vite React) | 2 (utilities removed), 4 (reset no longer leaks), 3, 5, 6, 7 |
 | Next.js App Router (server components) | all of the above plus "RSC deep imports" |
 
@@ -48,11 +49,20 @@ utility classes you used without having Tailwind yourself.
 
 0.x caret ranges stop at the next minor: `^0.40.2` means `>=0.40.2 <0.41.0`.
 Older ranges such as `^0.38.0`, `^0.37.0` or `^0.33.0` are the same: none of
-them reach 0.41.0. Change the range explicitly:
+them reach 0.41.0.
+
+First, **before `npm install`**, save a copy of the old bundle. The install
+overwrites it, and you need it for the class diff in section 2:
 
 ```bash
-npm install eidotter@^0.41.2
-# check what actually resolved
+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.41.3
+# check what actually resolved: 0.41.3 or later
 npm ls eidotter
 ```
 
@@ -60,15 +70,62 @@ Install from the npm registry. Do not point the dependency at a local checkout
 (`file:../eidotter`): `npm ci` passes, but CI, Docker and Vercel builds fail
 with "Module not found".
 
-Before you bump, save a copy of the old bundle. You need it for the class diff
-in section 2:
+If you are coming from older than 0.40, also read
+"Jumping from older versions" at the end.
+
+## Tailwind v4 apps: load eidotter's CSS in a cascade layer (recommended)
 
-```bash
-cp node_modules/eidotter/dist/eidotter.css /tmp/eidotter-old.css
+`dist/eidotter.css` ships the stock Tailwind utilities its components use
+(about 200: `.flex`, `.hidden`, `.flex-col`, `.items-center`, …) **unlayered**.
+Your Tailwind v4 utilities live in `@layer utilities`, and an unlayered rule
+beats every layered one whatever its specificity or load order. So where your
+markup uses the same class names, eidotter's copy wins over your variants: a
+`flex flex-col md:flex-row` header stays a column at every width, because
+eidotter's unlayered `.flex-col` beats your layered `md:flex-row`.
+
+The fix is on your side: import eidotter's CSS into a named layer that sits
+before your utilities. In your main CSS file (the one with
+`@import "tailwindcss"`):
+
+```css
+/* app/globals.css: the layer statement must come first */
+@layer theme, base, components, eidotter, utilities;
+@import "tailwindcss";
+@import "eidotter/styles" layer(eidotter);
 ```
 
-If you are coming from older than 0.40, also read
-"Jumping from older versions" at the end.
+- Remove the JS `import 'eidotter/styles'` (in `layout.tsx`, `main.tsx`, …):
+  it would load a second, unlayered copy and bring the problem back.
+- Do not let Tailwind scan eidotter's build output: no `@source` (v4) or
+  `content` (v3) entry for `node_modules/eidotter/dist`. eidotter's CSS already
+  contains what its components need.
+- eidotter's own internal layers (its reset in `base.eidotter`, the safelisted
+  token utilities in `utilities.eidotter`) nest inside `eidotter` and keep
+  working.
+
+**Trade-off: keep your own global rules layered too.** Inside a layer,
+eidotter loses to anything of yours that is unlayered. An unlayered reset such
+as `* { margin: 0; padding: 0 }` then beats eidotter's component utilities
+(and your own Tailwind utilities). Put resets and element defaults in a layer.
+Because `eidotter` comes after `base`, eidotter's reset (`h1`–`h6`
+`font-size: inherit`, list and link resets) also beats element defaults you put
+in `@layer base`. If you style elements globally (heading sizes, list markers),
+declare a layer of your own after `eidotter` and put them there:
+
+```css
+@layer theme, base, components, eidotter, app, utilities;
+@layer app { h1 { font-size: var(--typography-font-size-display-sm); } }
+```
+
+**Verify.** At a desktop width, an element with `flex flex-col md:flex-row`
+reports `getComputedStyle(el).flexDirection === 'row'`. Checked against 0.41.2
+`dist/eidotter.css` with `@tailwindcss/postcss` and Chromium: unlayered import
+gives `column`, the layered import gives `row`; an app `@layer base { h1 {…} }`
+size loses to eidotter's reset, the same rule in a layer after `eidotter` wins;
+an unlayered `* { padding: 0 }` beats a `p-7` utility.
+
+Apps without Tailwind, and Tailwind v3 apps, keep the plain
+`import 'eidotter/styles'`.
 
 ---
 
@@ -441,7 +498,8 @@ rg -n 'z-index' --glob '*.{css,scss}' src app styles | rg -i 'modal|lightbox|ove
 .eidotter-modal__container .eidotter-dialog__head { /* … */ }
 ```
 
-**Verify.** Open each Modal, Lightbox and CmdPalette in your app. Escape and a
+**Verify.** Open each Modal, Lightbox and CmdPalette in your app (CmdPalette:
+Ctrl+K on Linux and Windows, ⌘K on macOS). Escape and a
 backdrop click close them, focus returns to the trigger, and nothing of yours
 paints over the dialog. A Modal with a long title wraps instead of clipping.
 
@@ -487,12 +545,16 @@ delete or retarget them.
   zoom views and the master-detail pane fade instead of rising. Several
   components share keyframes now (`eidotter-pop-in/out`,
   `eidotter-fade-in/out`, `eidotter-breathe`). If your CSS overrode eidotter's
-  internal keyframe names (`modal-crt-enter`, `cmdpal-enter`, `tag-enter`,
+  internal keyframe names (`modal-crt-enter`, `cmdpal-enter`, `cmdpal-exit`,
+  `cmdpal-backdrop-open`, `cmdpal-backdrop-close`, `tag-enter`,
   `badge-enter`, `alert-enter`, `notification-enter`, `select-pop-in`,
   `eidotter-mark-morph`, `eidotter-card-enter`, `eidotter-inline-expand-fade`,
   `eidotter-timeline-node-enter`, `eidotter-skeleton-breathe`,
-  `eidotter-health-breathe`, …), those names no longer exist. Find:
-  `rg -n 'modal-crt|cmdpal-|badge-enter|tag-enter|tag-exit|alert-enter|notification-enter|select-pop|backdrop-open|timeline-fade-in|master-detail-fade|blink-loading|eidotter-(mark-morph|card-enter|inline-expand-fade|timeline-node-enter|skeleton-breathe|health-breathe)' --glob '*.{css,scss}'`.
+  `eidotter-health-breathe`, …), those names no longer exist. Find (the
+  `cmdpal-` names are listed in full so the search does not hit your own
+  classes such as `.cmdpal-demo__*`; eidotter's live CmdPalette classes all
+  start with `eidotter-cmdpal`):
+  `rg -n 'modal-crt|cmdpal-(enter|exit|backdrop-(open|close))|badge-enter|tag-enter|tag-exit|alert-enter|notification-enter|select-pop|backdrop-open|timeline-fade-in|master-detail-fade|blink-loading|eidotter-(mark-morph|card-enter|inline-expand-fade|timeline-node-enter|skeleton-breathe|health-breathe)' --glob '*.{css,scss}'`.
 - **Progress** sizes are distinct again: `sm`/`md`/`lg` render 16/20/22px (were
   16/16/18px).
 
@@ -705,6 +767,14 @@ export default function RootLayout({ children }: { children: React.ReactNode })
 - Show a ⌘K hint (in the site `Footer` or the Header `end` slot) only where
   the palette is mounted. Not in `footerHint`, which renders only inside the
   open palette.
+- `maxResults` defaults to 20 and also caps the **empty** query: with no search
+  text the palette lists only the first 20 items. If the site has more routes,
+  pass `maxResults={items.length}` (or a larger number) so none is hidden
+  until the user types.
+- To verify: `mod+k` is ⌘K on macOS and **Ctrl+K on Linux and Windows**
+  (`mod` is `metaKey` on macOS, `ctrlKey` elsewhere). Meta+K does nothing on
+  Linux, including headless Chromium in Playwright on Linux CI: press
+  `Control+K` there.
 
 ### `eidotter/favicon.svg`
 
@@ -723,9 +793,28 @@ committing a copy that goes stale:
 }
 ```
 
-- **Next.js App Router:** copy to `app/icon.svg`. Next generates the
-  `<link rel="icon">` itself. Remove any old `app/favicon.ico` or `app/icon.*`
-  you no longer want.
+- **Next.js App Router:** copy to `app/icon.svg` (`src/app/icon.svg` with a
+  `src/` dir). Next generates the `<link rel="icon">` itself. Remove any old
+  `app/favicon.ico` or `app/icon.*` you no longer want.
+- **Next.js on Vercel (or any host that runs `next build` directly):** npm
+  `pre*` hooks only run for `npm run build`. When `vercel.json` sets
+  `"buildCommand": "next build"` (or the host calls `next build` itself),
+  `prebuild` never runs and the icon is missing. Copy from `next.config`
+  instead, which Next loads for every `next dev` and `next build`:
+
+  ```js
+  // next.config.mjs
+  import { copyFileSync } from 'node:fs';
+  import { createRequire } from 'node:module';
+
+  const require = createRequire(import.meta.url);
+  copyFileSync(
+    require.resolve('eidotter/favicon.svg'),
+    new URL('./src/app/icon.svg', import.meta.url), // or ./app/icon.svg
+  );
+
+  export default { /* your config */ };
+  ```
 - **Vite:** copy to `public/favicon.svg`, then in `index.html`:
   `<link rel="icon" type="image/svg+xml" href="/favicon.svg" />`.
 - **Astro:** copy to `public/favicon.svg`, then in the base layout `<head>`:
@@ -827,8 +916,9 @@ 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 the bump).
-- [ ] `npm install eidotter@^0.41.0`, then `npm ls eidotter` shows 0.41.x. Commit the lockfile.
+- [ ] `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.41.3`, 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).
 - [ ] Preset apps: review `text-xs` / `text-sm` hits; delete redundant 16px overrides (section 1).
@@ -855,6 +945,9 @@ additive or automatic unless noted. Details are in the eidotter
 [CHANGELOG](https://github.com/CinimoDY/eiDotter/blob/main/CHANGELOG.md). It is
 not shipped in the npm package; read it on GitHub.
 
+- **0.37.2:** two-tier typography. Display text stays Perfect DOS VGA
+  437 and body text (`.dos-body`, `font-dos-body`) is JetBrains Mono Nerd Font.
+  It shipped in 0.37.2; the CHANGELOG describes it under 0.38.0.
 - **0.38.0:** `article` entry kind for `TimelineContainer` (thumbnail strip and
   summary when collapsed; gallery, body and read-more when expanded). Additive.
 - **0.38.0:** `RetroEffects` `boot` no longer flashes content before the
@@ -876,8 +969,5 @@ not shipped in the npm package; read it on GitHub.
   ChatMessage, Terminal) is the DOS underscore `_`, not a `█` block. Visible.
 - **0.40.2:** `eidotter/favicon.svg` export (see "Adopt").
 
-- **0.38.0 entry:** two-tier typography. Display text stays Perfect DOS VGA
-  437 and body text (`.dos-body`, `font-dos-body`) is JetBrains Mono Nerd Font.
-
 Coming from 0.37 or older: also read the CHANGELOG entries for 0.33–0.37,
 including the RSC deep imports `eidotter/components/<Name>` (0.37.1, DMNC-1130).

package/package.json

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