npm - why-hydration - Versions diffs - 0.1.5 → 0.3.0 - Mend

why-hydration 0.1.5 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (31) hide show

package/CHANGELOG.md +116 -0
package/README.md +155 -35
package/dist/chunk-CER5NQRR.js +1333 -0
package/dist/chunk-CER5NQRR.js.map +1 -0
package/dist/{chunk-AS5DZZHI.js → chunk-KP4S6CRL.js} +560 -230
package/dist/chunk-KP4S6CRL.js.map +1 -0
package/dist/{chunk-AT6A77X3.cjs → chunk-QFHUKJ5K.cjs} +568 -229
package/dist/chunk-QFHUKJ5K.cjs.map +1 -0
package/dist/chunk-RWMRFTQ4.cjs +1356 -0
package/dist/chunk-RWMRFTQ4.cjs.map +1 -0
package/dist/index.cjs +25 -17
package/dist/index.d.cts +37 -6
package/dist/index.d.ts +37 -6
package/dist/index.js +1 -1
package/dist/next/index.cjs +4 -4
package/dist/next/index.d.cts +1 -1
package/dist/next/index.d.ts +1 -1
package/dist/next/index.js +2 -2
package/dist/react.cjs +4 -4
package/dist/react.d.cts +24 -3
package/dist/react.d.ts +24 -3
package/dist/react.js +2 -2
package/dist/{types-6wTih14e.d.cts → types-C14vcpBO.d.cts} +9 -0
package/dist/{types-6wTih14e.d.ts → types-C14vcpBO.d.ts} +9 -0
package/package.json +22 -4
package/dist/chunk-3I6F4K4L.js +0 -642
package/dist/chunk-3I6F4K4L.js.map +0 -1
package/dist/chunk-AS5DZZHI.js.map +0 -1
package/dist/chunk-AT6A77X3.cjs.map +0 -1
package/dist/chunk-OFVFNPE6.cjs +0 -665
package/dist/chunk-OFVFNPE6.cjs.map +0 -1

package/CHANGELOG.md CHANGED Viewed

@@ -1,5 +1,121 @@
 # Changelog
+## 0.3.0
+### Minor Changes
+- Hebrew and Persian overlays, live prop updates, one report per invalid nesting.
+  **Hebrew and Persian**
+  - Pages whose `<html lang>` is Hebrew (`he`, `iw`) or Persian (`fa`, `prs`,
+    `pes`) now get the overlay in that language, right-to-left, alongside the
+    Arabic one. `overlay={{ locale }}` accepts `'he'` and `'fa'` too. Other
+    right-to-left languages, such as Urdu, keep the English left-to-right panel.
+  **`<HydrationInspector>` props apply while the app runs**
+  - Props were read once, at mount, and later changes were ignored until a
+    reload. Now a new `onReport` receives the next report, a new `overlay`
+    (on/off, `position`, `locale`) rebuilds the panel with the reports so far,
+    and new `ignore`, `classify` and `maxReports` apply from then on. Inline
+    values re-created on every render do not rebuild anything.
+  **Invalid HTML nesting is one report**
+  - A `<div>` inside a `<p>` used to surface as three wrongly labelled reports
+    ("browser-only API", "viewport branching" twice) next to React's own
+    warning, and a real text change inside it was never reported as one. The
+    browser repairs the server's HTML while parsing it, but React builds the
+    client DOM node by node, so the client side is now repaired the same way
+    before comparing. The nesting is one report at the misplaced element, and a
+    text difference inside it is its own report. Covers block elements in `<p>`,
+    nested `<a>`/`<button>`/`<form>`, and table content outside its section or
+    row, which the parser moves out of the whole table.
+  **Other fixes**
+  - A `roots` selector that matches nothing on the page — usually a typo — is
+    warned about once the settling window closes, instead of being skipped
+    silently.
+  - Reports no longer show the wrong component. A report parsed from one of
+    React's messages borrowed the component of whichever error came last, and
+    a text node the client added pointed at nothing, so its lookup fell back
+    the same way (a `localStorage` read labelled `<InvalidNesting>`). Each
+    report now carries only its own context, and an added text node points at
+    its parent element — which also lets `ignore` match it.
+  - Adjacent text nodes (`{label}: ` in JSX) are kept apart when the client
+    side of an invalid nesting is repaired, matching React's server HTML, so
+    they no longer show up as a bogus text change.
+  - The Release workflow no longer fails on every merge when no `NPM_TOKEN` is
+    set: it skips publishing with a notice and still opens version PRs.
+  - A GitHub Pages site (`docs/`) with search metadata, structured data and a
+    sitemap. A test keeps its error list identical to the README's.
+### Patch Changes
+- Make the package easier to find.
+  - The README has a "Searching for this error?" section quoting React's
+    hydration error messages exactly as React 18 and React 19 print them, so a
+    search for the error leads here. A test reads the list back out of the
+    README and checks the package recognizes every message on it.
+  - The npm description and keywords now cover the terms people search for:
+    Next.js, React 18 and 19, "hydration failed", "text content does not match",
+    `suppressHydrationWarning`, RTL and Arabic.
+  No code changes to this part.
+## 0.2.0
+### Minor Changes
+- The overlay now speaks Arabic, and renders right-to-left data correctly in any language.
+  **Arabic overlay**
+  - On a page whose `<html lang>` is Arabic, the whole panel is in Arabic and
+    laid out right-to-left — title, buttons, category names, explanations, fixes,
+    and the scroll hint, with correct Arabic plurals. Every other page, including
+    right-to-left pages in languages the overlay does not translate, gets the
+    English panel as before.
+  - New `overlay={{ locale: 'auto' | 'en' | 'ar' }}` option. `'auto'` is the
+    default and follows `<html lang>`.
+  - The console output and the `explanation`/`suggestion` strings in `onReport`
+    stay English and are byte-identical to 0.1.5. Every built-in cause now also
+    carries `messageId` and `params`, which is how the overlay finds the
+    translation.
+  **Right-to-left rendering fixes**
+  - Arabic values no longer have their sentence punctuation moved to the wrong
+    end. Each value cell takes its direction from its own content, in either
+    panel language.
+  - Arabic values are drawn in a proportional face instead of a monospace
+    fallback, which rendered them with their letters disconnected.
+  - Selectors, component names, file paths and attribute names are isolated
+    left-to-right, and quoted values inside explanations are isolated one by one,
+    so brackets cannot mirror and tokens cannot swap places.
+  - The panel declares its own `lang`. Previously an English panel on an Arabic
+    page inherited `lang="ar"`, so screen readers voiced it with an Arabic voice.
+  **Other fixes**
+  - Invisible bidi marks (LRM, RLM, isolates…) are drawn as labelled badges in
+    the value cells, so the bidi-mark case no longer shows two identical-looking
+    values. Value cells also preserve whitespace, so whitespace-only mismatches
+    are visible.
+  - Component attribution from a React component stack no longer names a DOM tag
+    such as `<p>`; it names the nearest component you wrote.
+  - React's bare "hydration failed" message no longer adds an empty card next to
+    a real mismatch. When it is the only signal it is still reported, with text
+    that says React did not name the node, instead of "inspect the values above".
+  - React 19 hydration errors no longer produce junk reports. React 19 prints a
+    bulleted list of possible causes above its diff tree, and each bullet was
+    read as a removed ("server") diff line — five bogus "Unknown" reports per
+    mismatch, with the real client value paired against the first bullet. Only
+    the tree after React's hydration-mismatch link is read as a diff now.
 ## 0.1.5
 ### Patch Changes

package/README.md CHANGED Viewed

@@ -7,7 +7,7 @@
 [![node: >=18](https://img.shields.io/node/v/why-hydration)](#install)
 [![license: MIT](https://img.shields.io/npm/l/why-hydration.svg)](LICENSE)
-📦 **npm:** https://www.npmjs.com/package/why-hydration &nbsp;·&nbsp; 🐙 **GitHub:** https://github.com/razan-aboushi/why-hydration &nbsp;·&nbsp; 💼 **Author:** [Razan Aboushi](https://www.linkedin.com/in/razan-aboushi/)
+🌐 **Site:** https://razan-aboushi.github.io/why-hydration/ &nbsp;·&nbsp; 📦 **npm:** https://www.npmjs.com/package/why-hydration &nbsp;·&nbsp; 🐙 **GitHub:** https://github.com/razan-aboushi/why-hydration &nbsp;·&nbsp; 💼 **Author:** [Razan Aboushi](https://www.linkedin.com/in/razan-aboushi/)
 **Tells you which component broke hydration, what differed, and how to fix it — in dev, with zero production cost.**
@@ -60,9 +60,10 @@ together.
   incidental page noise.
 - 🌐 **Arabic-first locale detection** — digit-script mismatches (٠١٢ vs 012)
   are a first-class cause, not an afterthought.
-- 🔤 **RTL-safe overlay** — the overlay always renders left-to-right, even on
-  pages with `<html dir="rtl">`, since its content (paths, values, code) is
-  English.
+- 🔤 **Speaks Arabic, Hebrew and Persian, right-to-left** — on a page whose
+  `<html lang>` is one of those, the overlay is in that language and laid out
+  right-to-left; everywhere else it is in English. Page data renders in its own direction in both, and invisible bidi
+  marks are shown instead of hidden.
 - 🫧 **Zero production cost** — every code path is gated behind
   `process.env.NODE_ENV`, and CI fails the build if the production bundle for
   any entry point isn't tree-shaken to a no-op.
@@ -78,6 +79,7 @@ Supports **React 18 and 19**.
 - [Install](#install)
 - [Quick setup](#quick-setup)
 - [What is a hydration mismatch](#what-is-a-hydration-mismatch)
+  - [Searching for this error?](#searching-for-this-error)
 - [What why-hydration detects](#what-why-hydration-detects)
 - [How detection works](#how-detection-works)
 - [What you will see](#what-you-will-see)
@@ -237,6 +239,37 @@ resolved a different locale or timezone. React logs a warning to the console
 when it detects this and, depending on what mismatched, may or may not repair
 the DOM to match. `why-hydration` exists to make that warning actionable.
+### Searching for this error?
+If you landed here from one of these messages, this is the tool for it. Each
+is quoted exactly as React prints it, and `why-hydration` recognizes every one.
+With the [snapshot script](#quick-setup) in place it also names the component,
+shows the server and client values side by side — including for the messages
+that carry no values of their own — and tells you the likely cause and fix.
+**React 19** (and Next.js 15+, which uses it):
+```text
+Hydration failed because the server rendered text didn't match the client. As a result this tree will be regenerated on the client.
+Hydration failed because the server rendered HTML didn't match the client. As a result this tree will be regenerated on the client.
+A tree hydrated but some attributes of the server rendered HTML didn't match the client properties. This won't be patched up.
+In HTML, <div> cannot be a descendant of <p>. This will cause a hydration error.
+```
+**React 18** (and Next.js 13–14):
+```text
+Hydration failed because the initial UI does not match what was rendered on the server.
+There was an error while hydrating. Because the error happened outside of a Suspense boundary, the entire root will switch to client rendering.
+There was an error while hydrating this Suspense boundary. Switched to client rendering.
+Text content does not match server-rendered HTML.
+Warning: Text content did not match. Server: "…" Client: "…"
+Warning: Prop `className` did not match. Server: "…" Client: "…"
+Warning: Expected server HTML to contain a matching <div> in <div>.
+Warning: Did not expect server HTML to contain a <div> in <div>.
+Warning: validateDOMNesting(...): <div> cannot appear as a descendant of <p>.
+```
 ---
 ## What why-hydration detects
@@ -339,6 +372,7 @@ A page with no mismatches renders **nothing** — no overlay, no console output.
 | **✕** on the hint bar | Closes just the "scroll to see all" hint; the panel stays. |
 | `overlay={false}` | Never mounts it at all — `onReport` and the console output still work. |
 | `overlay={{ position }}` | `bottom-right` (default), `bottom-left`, `top-right`, `top-left`. |
+| `overlay={{ locale }}` | `'auto'` (default) follows `<html lang>`; `'en'`, `'ar'`, `'he'` or `'fa'` pins the language. See [RTL and Arabic support](#rtl-and-arabic-support). |
 The overlay is a *view* over the collected reports, not the collector itself:
 dismissing it does not stop detection, and `onReport` keeps firing. If a
@@ -368,24 +402,60 @@ there are more than fit:
 ## RTL and Arabic support
-An Arabic app gets the same diagnosis quality as an English one. That covers
-both how the overlay renders and what the engine can actually detect.
+An Arabic, Hebrew or Persian app gets the same diagnosis quality as an English
+one. That covers both how the overlay renders and what the engine can actually
+detect.
 ### The overlay
-- The overlay's own layout **always renders left-to-right**, on any page. Its
-  content — file paths, DOM selectors, code values, category names — is
-  English, so keeping it LTR keeps it readable regardless of the host page's
-  direction.
-- This is automatic and needs no configuration. The overlay lives in an
-  isolated Shadow DOM, sets `direction: ltr` on both `:host` and the panel, and
-  carries a `dir="ltr"` attribute as well — belt and braces, because the CSS
-  `all` shorthand deliberately excludes `direction` (per spec), so
-  `:host { all: initial }` alone would still let `direction: rtl` leak in and
-  flip the server/client diff columns.
-- Values are rendered as **text**, so Arabic, Hebrew and mixed bidi content
-  display intact inside the LTR panel without reordering the surrounding
-  layout.
+**The overlay speaks the page's language.** On a page whose `<html lang>` is
+Arabic, Hebrew or Persian, the whole panel is in that language and laid out
+right-to-left: title, buttons, category names, the explanation, the fix, and
+the scroll hint, with each language's plural rules.
+| `<html lang>` | Overlay |
+| ------------- | ------- |
+| `ar`, `ar-SA`, `ar-EG`, … and regional varieties (`arz`, `ary`, …) | Arabic |
+| `he`, `he-IL`, and the legacy `iw` | Hebrew |
+| `fa`, `fa-IR`, `fa-AF`, and `prs` (Dari), `pes` | Persian |
+| anything else — including other right-to-left languages such as Urdu | English, left-to-right |
+An untranslated right-to-left page keeps the English panel left-to-right rather
+than mirroring English text. Pin the language either way with
+`overlay={{ locale: 'en' }}`, `'ar'`, `'he'` or `'fa'`.
+What stays English: the console output, and `cause.explanation` /
+`cause.suggestion` in the report `onReport` receives. Those are what people log,
+grep and paste into issues, so they do not change with the page. Each report
+also carries `cause.messageId` and `cause.params`, which is how the overlay
+finds the translation — and how your own tooling can, too. The "Learn more"
+links point at this README, which is in English, and say so.
+**Page data renders in its own direction, in either panel.** A mismatched value
+can be in any script, so each value cell takes its direction from its own first
+strong character. `السعر: ١٬٤٠٠ د.ك.` reads right-to-left with its full stop at
+the end even inside the English panel, and `Price: 1,400 KWD.` reads
+left-to-right inside the Arabic one. Selectors, component names, file paths and
+attribute names are code, so they are always isolated left-to-right — otherwise
+a right-to-left line would mirror their brackets and reorder their segments.
+Class tokens and other values quoted inside a sentence are isolated one by one,
+so two Arabic tokens cannot swap places. Arabic is drawn in a proportional face
+(a monospace fallback renders it with its letters disconnected), and Arabic
+labels are never letter-spaced or uppercased, which breaks their joining.
+**What differs is what you see.** Value cells preserve whitespace, so a
+whitespace-only mismatch no longer looks like two identical strings. Invisible
+characters that change layout — `LRM`, `RLM`, `ALM`, the bidi embeddings and
+isolates, zero-width space, BOM — are drawn as small labelled badges rather than
+applied, so the [bidi-mark case](#cause-locale-format) shows a visible
+difference instead of two cells that look the same.
+**It is isolated from the page.** The panel lives in a Shadow DOM, and its
+direction is set inside it, so nothing in the host page's CSS can flip it — the
+`all` shorthand deliberately excludes `direction` (per spec), so
+`:host { all: initial }` alone would not be enough. The panel also declares its
+own `lang`, so a screen reader voices it in its own language: before this, an
+English panel on an Arabic page was read aloud with an Arabic voice.
 ### Detection
@@ -460,6 +530,14 @@ Wrap your app (or, for Next.js, use the `why-hydration/next` re-export).
 | `classify`   | `Classifier[]`                                  | `[]`          | Custom classification rules, run **before** the built-in ones. |
 | `maxReports` | `number`                                        | `25`          | Cap on the number of unique reports collected per page load. |
+Props can change while the app is running, and take effect without a reload:
+a new `onReport` receives the next report; a new `overlay` (switched on or off,
+or a different `position` or `locale`) rebuilds the panel with the reports so
+far; new `ignore`, `classify` or `maxReports` apply to everything reported from
+then on. Reports already made are kept as they were. Inline values that are
+re-created on every render, such as `overlay={{ position: 'top-left' }}`, do
+not rebuild anything unless they actually change.
 ### `createHydrationInspector(options)`
 For Vite/CRA/Remix, where you call `hydrateRoot` yourself. Accepts the same
@@ -490,6 +568,7 @@ effect setup → cleanup → setup.
 ```ts
 interface OverlayOptions {
   position?: 'bottom-right' | 'bottom-left' | 'top-right' | 'top-left'; // default 'bottom-right'
+  locale?: 'auto' | 'en' | 'ar' | 'he' | 'fa'; // default 'auto' — follows <html lang>
 }
 ```
@@ -538,9 +617,11 @@ interface HydrationReport {
   cause: {
     category: HydrationCauseCategory; // one of the categories below, or "unknown"
     confidence: number;               // 0–1
-    explanation: string;
-    suggestion: string;
+    explanation: string;              // always English
+    suggestion: string;               // always English
     docsUrl?: string;
+    messageId?: string;               // which message produced the text, e.g. "attribute-mismatch.class"
+    params?: Record<string, string | string[]>; // the values in it, e.g. { added: ['wide'], removed: [] }
   };
   raw?: { reactMessage?: string };   // the original React console message, if any
 }
@@ -662,6 +743,16 @@ JavaScript.
 A node was moved or ejected because the markup is invalid HTML (e.g. a `<div>`
 inside a `<p>`, or a nested `<a>`). The browser repairs the server-rendered DOM
 so it no longer matches what React expects.
+It is reported **once**, at the element that is misplaced. The browser repairs
+the server's HTML while parsing it, but React builds the client DOM node by
+node, so nothing repairs that side — and compared as-is, one invalid `<div>`
+used to surface as three unrelated reports. The client side is now put through
+the same parser repair before comparing, so the nesting shows up as a single
+report, and any real text difference inside it still shows up as its own.
+Covered: block elements inside `<p>`, nested `<a>`, `<button>` and `<form>`,
+and table content outside its section or row (which the parser moves out of
+the whole table).
 **Fix:** correct the markup validity — block elements cannot live inside
 `<p>`, anchors cannot nest, etc.
 **Reference:** [MDN — `<p>` (permitted content)](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/p).
@@ -701,6 +792,13 @@ drive the visual change with a CSS media query instead of a JS class toggle.
 A mismatch was detected but didn't match any of the rules above. The report
 still shows the exact server vs. client values and node path so you can
 diagnose it directly.
+React also logs a bare "hydration failed" message that names no node at all.
+When the DOM diff or another React message has already located the mismatch,
+that message adds nothing and is not shown. When it is the *only* signal —
+typically because the snapshot script is missing — it is reported once, with an
+explanation that says React did not name the node and a fix that points at the
+snapshot script, rather than asking you to inspect values that do not exist.
 **Fix:** compare the two values — the cause is usually one of the categories
 above. If you find a reliable signal for it, add a custom rule via the
 `classify` option (see [Contributing](#contributing)).
@@ -729,9 +827,12 @@ above. If you find a reliable signal for it, add a custom rule via the
   budget (`npm run size`) against a real production bundle built with webpack
   and terser — the same toolchain Next.js and CRA use for production — and
   fails the build if the tree-shaken output for any entry point isn't reduced
-  to a near-empty stub. Verified independently against Rollup, which is what
-  Vite uses for production builds: **99 B** under webpack, **166 B** under
-  Rollup, versus ~40 KB for the same entry built for development.
+  to a near-empty stub. The budgets sit just above today's output, so even a
+  small leak fails CI. Verified independently against Rollup, which is what
+  Vite uses for production builds: **99 B** minified + gzipped under webpack,
+  and **156 B** minified (not gzipped) under Rollup — versus ~59 KB minified
+  for the same entry built for development. The Arabic translations exist only
+  in that development build.
 - `<HydrationSnapshotScript>` also renders `null` outside development, so no
   snapshot script is emitted into your production HTML.
@@ -788,9 +889,11 @@ snapshot script is present in `<head>` and runs before your app's hydration
 script. Without the snapshot script, the tool still reports mismatches it can
 parse from React's own console warning, but loses the precise DOM-level diff.
 If you passed `roots`, check the console for a
-`[why-hydration] Skipping root:` warning — a root with no captured server HTML
-can never produce a DOM-level report, and it says so rather than failing
-silently.
+`[why-hydration] Skipping root:` warning. There are three: a selector that is
+not valid CSS, a root with no captured server HTML (it can never produce a
+DOM-level report), and a selector that matches nothing on the page — usually a
+typo. The last is only raised once the settling window has closed, so a root
+rendered a moment after hydration is not reported by mistake.
 **Does it work under `<React.StrictMode>`?** Yes. Strict Mode runs every mount
 effect setup → cleanup → setup in development, which tears the inspector down
@@ -802,6 +905,11 @@ to the rebuilt inspector rather than lost.
 suspend `requestAnimationFrame` on hidden pages, so scheduling races a frame
 against a 50 ms timer and no longer depends on the page being painted.
+**The component name in a report was a tag like `<p>`.** Fixed. React's
+component stacks list host elements first (`at p`, `at span`), and those were
+being taken as the component. The nearest component you wrote is used instead,
+and when there is none the report names no component rather than a tag.
 **The "Learn more →" link 404s.** The links point at this README on GitHub
 (`github.com/razan-aboushi/why-hydration#cause-…`). If you've forked the
 package under a different name or repository, update `DOCS_BASE` in
@@ -823,16 +931,28 @@ production. It's dev-only, runs a bounded diff across roughly 1.5 seconds
 right after hydration, then stops.
 **Does it work with `<html dir="rtl">`?** Yes — see
-[RTL and Arabic support](#rtl-and-arabic-support). The overlay stays
-left-to-right on purpose; this is not a bug. Detection covers Arabic-script
-formatting mismatches on both sides, not just Arabic-vs-Latin.
-**My Arabic app shows two identical-looking values as a mismatch.** They differ
-by invisible bidirectional control characters — `Intl` adds LRM/RLM/isolate
+[RTL and Arabic support](#rtl-and-arabic-support). The panel's language follows
+`<html lang>`, not `dir`: an Arabic, Hebrew or Persian page gets the panel in
+that language, right-to-left, and a right-to-left page in another language gets
+the English left-to-right one. Detection covers Arabic-script formatting
+mismatches on both sides, not just Arabic-vs-Latin.
+**I want the English panel on my Arabic site (or the reverse).** Pass
+`overlay={{ locale: 'en' }}` (or `'ar'`, `'he'`, `'fa'`). The console and
+`onReport` are English either way.
+**I changed a `<HydrationInspector>` prop and nothing happened.** Fixed —
+props used to be read once, at mount. They now apply while the app runs; see
+[`<HydrationInspector>`](#hydrationinspector).
+**My Arabic app reports a mismatch between two values that look the same.** They
+differ by invisible bidirectional control characters — `Intl` adds LRM/RLM/isolate
 marks around numbers and dates in RTL locales, and Node's ICU and the browser's
 ICU do not always agree on which. The report names this explicitly under
-[`locale-format`](#cause-locale-format). Format the value in one place and pass
-the string down, or add `suppressHydrationWarning` if the marks are harmless.
+[`locale-format`](#cause-locale-format), and the overlay draws each invisible
+mark as a small labelled badge (`RLM`, `LRM`, …) in the value cell, so you can
+see which side has it. Format the value in one place and pass the string down,
+or add `suppressHydrationWarning` if the marks are harmless.
 ---