@recursica/mui-adapter 0.34.4 → 0.35.0

package/package.json

@@ -13,7 +13,7 @@
     "url": "git+https://github.com/borderux/recursica.git",
     "directory": "packages/mui-adapter"
   },
-  "version": "0.34.4",
+  "version": "0.35.0",
   "publishConfig": {
     "access": "public"
   },

package/src/components/Autocomplete/AUTOCOMPLETE_IMPLEMENTATION_NOTES.md

@@ -10,7 +10,12 @@ New CSS classes (`.optionContent`/`.optionIcon`/`.optionText`/`.optionSupporting
 
 ## `wrapItemText`
 
-`label`/`supportingText` default to single-line truncation with an ellipsis (`.optionText > *` — `overflow: hidden; text-overflow: ellipsis; white-space: nowrap`). Passing `wrapItemText` adds `.optionTextWrap` alongside `.optionText`, re-enabling wrapping (`white-space: normal; overflow-wrap: anywhere`) for both children — later-cascade-wins, equal specificity. `renderRichOptionContent` takes `wrapItemText` as a third parameter and combines the two class names when it's true.
+`label`/`supportingText` default to single-line truncation with an ellipsis (`.optionText > *` — `overflow: clip; overflow-clip-margin: 0.35em; text-overflow: ellipsis; white-space: nowrap`). Passing `wrapItemText` adds `.optionTextWrap` alongside `.optionText`, re-enabling wrapping (`white-space: normal; overflow-wrap: anywhere`) for both children — later-cascade-wins, equal specificity. `renderRichOptionContent` takes `wrapItemText` as a third parameter and combines the two class names when it's true.
+
+`.optionText > *` used plain `overflow: hidden` until 2026-08-28 (Matt Massey) — it clipped
+descenders (e.g. "g") whenever `text_line-height` is tighter than the font's natural
+ascent+descent. `overflow-clip-margin` gives ink a small bleed allowance while still clipping
+genuinely overflowing text; same project-wide fix as Chip's `CHIP_IMPLEMENTATION_NOTES.md`.
 
 ## Selected Option Highlight (bug fix)
 

package/src/components/Autocomplete/Autocomplete.module.css

@@ -323,7 +323,10 @@
 
 /* Default: label/supportingText each truncate to a single line with an ellipsis. */
 .optionText > * {
-  overflow: hidden;
+  overflow: clip; /* HARDCODE: `hidden` clips descenders (e.g. "g") when text_line-height is
+    tighter than the font's natural ascent+descent; overflow-clip-margin gives ink a small bleed
+    allowance while still clipping genuinely overflowing text (see Chip's IMPLEMENTATION_NOTES.md). */
+  overflow-clip-margin: 0.35em;
   text-overflow: ellipsis;
   white-space: nowrap;
 }

package/src/components/Button/BUTTON_IMPLEMENTATION_NOTES.md

@@ -75,3 +75,15 @@ We explicitly pass `disableRipple` and `disableElevation` to block MUI's dynamic
 **Root cause:** `.root` has `width: fit-content` (to hug its own content instead of stretching in flex columns) but no `max-width`. Verified via Playwright: the wrapper measured exactly 250px, but `fit-content` on `.root` still resolved to its 534px `max-content` size — it doesn't reliably clamp against a narrower containing block on its own. Same root cause and identical fix in mantine-adapter.
 
 **Fix:** added `max-width: 100%` to `.root`. It's a no-op when the parent is wide enough (confirmed no change to `Default`/`IconOnly`/`TextWithIcon` story widths), and clamps the button to the parent's resolved width when the parent is narrower — at which point the existing `overflow: hidden` (`.root`) + `text-overflow: ellipsis`/`white-space: nowrap` (`.labelText`) take over, exactly as already documented above.
+
+---
+
+## `.labelText` descender clipping (Matt Massey, 2026-08-28)
+
+`.labelText` used plain `overflow: hidden` to make `text-overflow: ellipsis` work, which also
+clips descenders (e.g. the "g" in a long label) whenever `text_line-height` is tighter than the
+font's natural ascent+descent. Switched to `overflow: clip; overflow-clip-margin: 0.35em;` — same
+truncation, but ink can bleed slightly past the line box before it's actually clipped. `.root`'s
+own `overflow: hidden` (the max-width truncation bounding box, above) is untouched — it has
+padding around the label so it isn't tight against the glyphs the way `.labelText` is.
+Project-wide fix; see Chip's `CHIP_IMPLEMENTATION_NOTES.md` for the original discovery.

package/src/components/Button/Button.module.css

@@ -68,7 +68,10 @@
 .labelText {
   display: block;
   min-width: 0;
-  overflow: hidden;
+  overflow: clip; /* HARDCODE: `hidden` clips descenders (e.g. "g") when text_line-height is
+    tighter than the font's natural ascent+descent; overflow-clip-margin gives ink a small bleed
+    allowance while still clipping genuinely overflowing text (see Chip's IMPLEMENTATION_NOTES.md). */
+  overflow-clip-margin: 0.35em;
   text-overflow: ellipsis;
   white-space: nowrap;
   font-size: inherit;

package/src/components/Dropdown/DROPDOWN_IMPLEMENTATION_NOTES.md

@@ -12,4 +12,9 @@ New CSS classes (`.optionContent`/`.optionIcon`/`.optionText`/`.optionSupporting
 
 ## `wrapItemText`
 
-`label`/`supportingText` default to single-line truncation with an ellipsis (`.optionText > *` — `overflow: hidden; text-overflow: ellipsis; white-space: nowrap`). Passing `wrapItemText` adds `.optionTextWrap` alongside `.optionText`, re-enabling wrapping (`white-space: normal; overflow-wrap: anywhere`) for both children — later-cascade-wins, equal specificity. `renderRichOptionContent` takes `wrapItemText` as a third parameter and combines the two class names when it's true. `Dropdown.tsx` exposes this as a public prop; `BareDropdown.tsx` (internal-only, not part of the public `Dropdown`/`AutoComplete` API this was requested for) doesn't take the prop and always truncates.
+`label`/`supportingText` default to single-line truncation with an ellipsis (`.optionText > *` — `overflow: clip; overflow-clip-margin: 0.35em; text-overflow: ellipsis; white-space: nowrap`). Passing `wrapItemText` adds `.optionTextWrap` alongside `.optionText`, re-enabling wrapping (`white-space: normal; overflow-wrap: anywhere`) for both children — later-cascade-wins, equal specificity. `renderRichOptionContent` takes `wrapItemText` as a third parameter and combines the two class names when it's true. `Dropdown.tsx` exposes this as a public prop; `BareDropdown.tsx` (internal-only, not part of the public `Dropdown`/`AutoComplete` API this was requested for) doesn't take the prop and always truncates.
+
+`.optionText > *` used plain `overflow: hidden` until 2026-08-28 (Matt Massey) — it clipped
+descenders (e.g. "g") whenever `text_line-height` is tighter than the font's natural
+ascent+descent. `overflow-clip-margin` gives ink a small bleed allowance while still clipping
+genuinely overflowing text; same project-wide fix as Chip's `CHIP_IMPLEMENTATION_NOTES.md`.

package/src/components/Dropdown/Dropdown.module.css

@@ -454,7 +454,10 @@
 
 /* Default: label/supportingText each truncate to a single line with an ellipsis. */
 .optionText > * {
-  overflow: hidden;
+  overflow: clip; /* HARDCODE: `hidden` clips descenders (e.g. "g") when text_line-height is
+    tighter than the font's natural ascent+descent; overflow-clip-margin gives ink a small bleed
+    allowance while still clipping genuinely overflowing text (see Chip's IMPLEMENTATION_NOTES.md). */
+  overflow-clip-margin: 0.35em;
   text-overflow: ellipsis;
   white-space: nowrap;
 }

package/src/components/Modal/MODAL_IMPLEMENTATION_NOTES.md

@@ -0,0 +1,12 @@
+# Modal Implementation Notes
+
+## `.title` descender clipping (Matt Massey, 2026-08-28)
+
+`.title` truncates with an ellipsis (`white-space: nowrap; text-overflow: ellipsis`) rather than
+wrapping, needing `flex: 1 1 auto; min-width: 0;` since it's a flex child of `.header` alongside
+the close button. It used plain `overflow: hidden` to make the ellipsis work, which also clips
+descenders (e.g. the "g" in a long title) whenever `text_line-height` is tighter than the font's
+natural ascent+descent. Switched to `overflow: clip; overflow-clip-margin: 0.35em;` — same
+truncation, but ink can bleed slightly past the line box before it's actually clipped.
+Project-wide fix; see Chip's `CHIP_IMPLEMENTATION_NOTES.md` for the original discovery. Matches
+mantine-adapter's equivalent `.title` rule (see its own `MODAL_IMPLEMENTATION_NOTES.md`).

package/src/components/Modal/Modal.module.css

@@ -66,7 +66,10 @@
 .title {
   flex: 1 1 auto; /* HARDCODE: let the title claim the space between the header edge and the close button */
   min-width: 0; /* HARDCODE: required for text-overflow ellipsis to take effect on a flex child */
-  overflow: hidden;
+  overflow: clip; /* HARDCODE: `hidden` clips descenders (e.g. "g") when text_line-height is
+    tighter than the font's natural ascent+descent; overflow-clip-margin gives ink a small bleed
+    allowance while still clipping genuinely overflowing text (see Chip's IMPLEMENTATION_NOTES.md). */
+  overflow-clip-margin: 0.35em;
   white-space: nowrap;
   text-overflow: ellipsis;
 

package/src/components/Panel/PANEL_IMPLEMENTATION_NOTES.md

@@ -62,3 +62,13 @@ No tokens from other component namespaces are referenced.
 **Decision:** Accept `opened` prop to match the standard Recursica component API.
 
 **Implementation:** MUI Drawer natively expects the `open` boolean prop. The wrapper maps the incoming framework-agnostic `opened` prop to MUI's `open={Boolean(opened)}`, allowing consistent usage across both adapter implementations.
+
+---
+
+## `.titleTruncate` descender clipping (Matt Massey, 2026-08-28)
+
+`.titleTruncate` used plain `overflow: hidden` to make `text-overflow: ellipsis` work, which also
+clips descenders (e.g. the "g" in a long title) whenever `text_line-height` is tighter than the
+font's natural ascent+descent. Switched to `overflow: clip; overflow-clip-margin: 0.35em;` — same
+truncation, but ink can bleed slightly past the line box before it's actually clipped.
+Project-wide fix; see Chip's `CHIP_IMPLEMENTATION_NOTES.md` for the original discovery.

package/src/components/Panel/Panel.module.css

@@ -96,7 +96,10 @@
 .titleTruncate {
   composes: title;
   white-space: nowrap;
-  overflow: hidden;
+  overflow: clip; /* HARDCODE: `hidden` clips descenders (e.g. "g") when text_line-height is
+    tighter than the font's natural ascent+descent; overflow-clip-margin gives ink a small bleed
+    allowance while still clipping genuinely overflowing text (see Chip's IMPLEMENTATION_NOTES.md). */
+  overflow-clip-margin: 0.35em;
   text-overflow: ellipsis;
   display: block;
   flex: 1;

package/src/components/Typography/TYPOGRAPHY_IMPLEMENTATION_NOTES.md

@@ -0,0 +1,17 @@
+# Typography – Implementation Notes
+
+`Typography` is the shared rendering base for both `Text` and `Title` in mui-adapter — anything
+applied here reaches both components.
+
+## `.root` `text-wrap: balance` (Matt Massey, 2026-08-28)
+
+**Decision:** Added `text-wrap: balance` via a new `Typography.module.css` `.root` class, merged
+onto the typography class alongside the caller's own `className`. Since both `Text` and `Title`
+render through this component, it covers all `order` heading levels (h1–h6) and paragraph text in
+one place.
+
+**Implementation:** UX asked for more evenly balanced multi-line wrapping instead of a ragged last
+line. Not a design token — it's a layout algorithm choice, so it's hardcoded rather than pulled
+from `recursica_variables_scoped.css`. Most effective on short text (headings); Chromium/Firefox
+only balance up to ~6 lines, so long paragraphs silently fall back to normal wrapping past that
+point. No fallback needed — browsers that don't support the value just ignore the declaration.

package/src/components/Typography/Typography.module.css

@@ -0,0 +1,13 @@
+/*
+ * HARDCODED VALUES
+ * - `.root` `text-wrap: balance` — not a design token; a layout algorithm choice requested by
+ *   UX (Matt Massey, 2026-08-28) to even out wrapped line lengths. See TEXT_IMPLEMENTATION_NOTES.md.
+ */
+
+.root {
+  /* HARDCODE: balances wrapped line lengths instead of leaving a ragged short last line. Most
+     effective on short text; browsers cap balancing at ~6 lines, so long paragraphs silently
+     fall back to normal wrapping past that point — no fallback needed, unsupported browsers
+     just ignore the declaration. */
+  text-wrap: balance;
+}

package/src/components/Typography/Typography.tsx

@@ -7,6 +7,7 @@ import {
   filterStylingProps,
   type RecursicaOverStyled,
 } from "../../utils/filterStylingProps";
+import styles from "./Typography.module.css";
 
 export type TypographyProps = RecursicaOverStyled<
   Omit<MuiTypographyProps, "variant"> & {
@@ -24,9 +25,9 @@ export const Typography = forwardRef<HTMLElement, TypographyProps>(
     const restRecord = sanitizedProps as Record<string, unknown>;
 
     const classNameProp = restRecord.className as string | undefined;
-    const finalClass = classNameProp
-      ? `${typographyClass} ${classNameProp}`
-      : typographyClass;
+    const finalClass = [typographyClass, styles.root, classNameProp]
+      .filter(Boolean)
+      .join(" ");
 
     return (
       <MuiTypography