@recursica/mantine-adapter 0.50.6 → 0.51.0

package/package.json

@@ -13,7 +13,7 @@
     "url": "git+https://github.com/borderux/recursica.git",
     "directory": "packages/mantine-adapter"
   },
-  "version": "0.50.6",
+  "version": "0.51.0",
   "type": "module",
   "main": "./dist/mantine-adapter.cjs",
   "module": "./dist/mantine-adapter.js",

package/src/components/Accordion/ACCORDION_IMPLEMENTATION_NOTES.md

@@ -60,3 +60,13 @@ and silently override the `leftIcon`-derived element (spread order would let it
 to set that slot is through `leftIcon`. Mantine's separate, per-control `chevron` override
 is _not_ omitted — nothing here computes it, so it still passes through safely if a caller
 wants to override the cascaded container-level chevron for a single item.
+
+---
+
+## `.label` descender clipping (Matt Massey, 2026-08-28)
+
+`.label` 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/Accordion/Accordion.module.css

@@ -211,7 +211,11 @@
   text-align: left;
   color: inherit;
   padding: 0; /* Clear Mantine inner padding */
-  overflow: hidden;
+  overflow: clip; /* HARDCODE: `hidden` clipped descenders (e.g. "g") whenever the text_line-height
+    token 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 fix project-wide,
+    see Chip/FileInput's IMPLEMENTATION_NOTES.md for the original discovery. */
+  overflow-clip-margin: 0.35em;
   white-space: nowrap;
   text-overflow: ellipsis;
 }

package/src/components/AutoComplete/AUTOCOMPLETE_IMPLEMENTATION_NOTES.md

@@ -34,4 +34,9 @@ rendering with our own value comparison.
 
 ## `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`, which re-enables wrapping (`white-space: normal; overflow-wrap: anywhere`) for both children — same later-cascade-wins mechanism (`.optionTextWrap > *` declared after `.optionText > *`, equal specificity) as the rest of this file's overrides. `renderRichOption`/`renderRichOptionContent` (shared util, both adapters) take `wrapItemText` as a third parameter and combine 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`, which re-enables wrapping (`white-space: normal; overflow-wrap: anywhere`) for both children — same later-cascade-wins mechanism (`.optionTextWrap > *` declared after `.optionText > *`, equal specificity) as the rest of this file's overrides. `renderRichOption`/`renderRichOptionContent` (shared util, both adapters) take `wrapItemText` as a third parameter and combine 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`.

package/src/components/AutoComplete/AutoComplete.module.css

@@ -304,7 +304,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.module.css

@@ -72,7 +72,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/Button/IMPLEMENTATION_NOTES.md

@@ -69,3 +69,15 @@ Mantine's `.mantine-Button-label` flex centering breaks primitive truncation log
 **Bug:** with `overStyled` and a custom `className` (surfaced by Tree embedding a `Button` for its expand chevron — see `Tree/IMPLEMENTATION_NOTES.md`), `finalClass` (`` `${styles.root} ${classNameProp}` ``) was set explicitly on `<MantineButton>`, but `{...sanitizedProps}` was spread _after_ it — and `sanitizedProps` still contained the original, unmodified `className` key, since it had only been _read_, never deleted. The later spread would silently overwrite `finalClass` with just the caller's own class. Same bug class as `Dropdown.tsx`/`BareDropdown.tsx` had.
 
 **Why it wasn't visible here:** `classNames={{root: mergedClassNames.root, ...}}` is a _separate_ Mantine prop from the plain `className` string, unaffected by the overwrite, and `mergedClassNames.root` always includes `styles.root` independently — so the root element kept its Recursica styling regardless of the bug. mui-adapter's equivalent `Button.tsx` has no such secondary path (`@mui/material` only has a plain `className`), so the identical mistake there was fully visible (chevron rendered in MUI's own default color). Fixed in both regardless, since this is a real latent bug independent of whether it happens to be masked today.
+
+---
+
+## `.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) 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/Dropdown/DROPDOWN_IMPLEMENTATION_NOTES.md

@@ -8,5 +8,5 @@ The `Dropdown` component is mapped explicitly to Mantine's `<Select>` following
 4. **Popup Vertical Padding:** The gap above/below the option list inside `.dropdown` is explicitly set from the same `--recursica_..._dropdown_properties_vertical-padding` token the closed control uses — it was previously left to Mantine's own untokenized `--combobox-padding` (4px) default.
 5. **Clear Button Styling:** Mantine's native clear button (`clearButtonProps`, shown when `clearable` + a value are both present) is a bare `CloseButton` with its own hardcoded gray icon/hover styling by default. `Dropdown.tsx` merges in a `.clearButton` class (Dropdown.module.css) that overrides it with the same icon-size/trailing-icon-color/focus-ring tokens as the rest of the right section, using the double-class-selector specificity trick (same as Chip.module.css's `.root.root`) to beat Mantine's own CSS module rule without `!important`.
 6. **Rich Option Content (`leadingIcon`/`supportingText`):** `data` items now accept optional `leadingIcon`/`supportingText` fields, via the shared `RecursicaComboboxItem` type in `@recursica/adapter-common` (see `MANTINE_ADAPTER_RICH_OPTION_DATA.md` at the repo root) — the same type `AutoComplete` and both `mui-adapter` components use, so it's declared once and not redeclared per component/adapter. `label` on that shared type is optional, falling back to `value` (matches Mantine's own runtime default for both `Select` and `Autocomplete`). `Dropdown.tsx` installs a default `renderOption` (`../../utils/renderRichOption.tsx`, shared with `AutoComplete`) that reads `leadingIcon`/`supportingText` straight off Mantine's own parsed `option` — no separate lookup-by-value map is needed, since Mantine's `getParsedComboboxData` passes extra fields on an item through untouched whenever the item already has both `value` and `label`. Because `label` is now optional, `data` is first run through adapter-common's `normalizeComboboxData` (backfilling `label` from `value`) before being handed to Mantine, so items missing `label` don't have their `leadingIcon`/`supportingText` silently dropped by that same parser (see `AutoComplete.tsx`'s identical, longer-standing use of this — `Dropdown`'s `label` used to be required, which is why it didn't need this before). A caller-supplied `renderOption` always wins over the default. New CSS classes (`.optionContent`/`.optionIcon`/`.optionText`/`.optionSupportingText`) reuse the menu-item component's icon/supporting-text tokens — no dedicated dropdown-option tokens exist for either, same reasoning as the `.option[data-selected]` reuse above. The icon is only rendered when `leadingIcon` is present (a conditional child, not a hidden reserved slot), so label/supportingText shift left when there's no icon; `.optionContent`'s `align-items: center` keeps the label vertically centered when there's no `supportingText` to stack under it.
-7. **`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, same mechanism as this file's other CSS overrides. `renderRichOption`/`renderRichOptionContent` take `wrapItemText` as a third parameter and combine the two class names when it's true.
+7. **`wrapItemText`:** `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, same mechanism as this file's other CSS overrides. `renderRichOption`/`renderRichOptionContent` take `wrapItemText` as a third parameter and combine 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`.
 8. **Selected Option Highlight (bug fix):** The `.option[data-selected="true"], .option[data-combobox-active="true"]` background/text-color rule (and the matching `.optionIcon`/`.optionSupportingText` color rules) used to key off `data-combobox-selected` instead of `data-combobox-active`. Despite the name, `data-combobox-active` is what Mantine sets when an option's value matches the current field value (`OptionsDropdown.mjs`: `active: checked`, consumed by `ComboboxOption.mjs`'s `mod` map); `data-combobox-selected` is an unrelated, transient keyboard-navigation highlight that Mantine sets/clears imperatively via `element.setAttribute` outside React (`use-combobox.mjs`'s `selectOption`/`clearSelectedItem`), not tied to the chosen value at all. The bug: the real selected option only showed the brand background while being arrow-key-navigated, and lost it entirely on a normal open/close (matches Playwright verification — `data-combobox-active="true"` is present and gets the token background after a plain click-select-reopen, with no keyboard involved).

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

@@ -408,7 +408,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

@@ -16,7 +16,12 @@ Mantine internally handles scroll state natively, dynamically showing/hiding a d
 
 ### 3. Title truncation
 
-`.title` truncates with an ellipsis (`overflow: hidden`, `white-space: nowrap`, `text-overflow: ellipsis`) rather than wrapping. It also needs `flex: 1 1 auto; min-width: 0;` since it's a flex child of `.header` alongside the close button — without `min-width: 0`, a flex item won't shrink below its content's intrinsic width, so ellipsis never engages. `.header`'s `display: flex` is likewise explicit rather than relied upon from Mantine's own header class, so the mui-adapter's plain-`<div>` header gets identical layout.
+`.title` truncates with an ellipsis (`overflow: clip; overflow-clip-margin: 0.35em`, `white-space: nowrap`, `text-overflow: ellipsis`) rather than wrapping. It also needs `flex: 1 1 auto; min-width: 0;` since it's a flex child of `.header` alongside the close button — without `min-width: 0`, a flex item won't shrink below its content's intrinsic width, so ellipsis never engages. `.header`'s `display: flex` is likewise explicit rather than relied upon from Mantine's own header class, so the mui-adapter's plain-`<div>` header gets identical layout.
+
+`.title` used plain `overflow: hidden` until 2026-08-28 (Matt Massey) — it clipped descenders
+(e.g. "g" in a long title) 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`.
 
 ### 4. Width was pinned to Mantine's `md` size, not content-driven
 

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

@@ -78,7 +78,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

@@ -104,3 +104,13 @@ Mantine's Drawer content does not set `border-style` natively. Without this, the
 - **Scrollable** — Internal scrollbar enabled when content exceeds the panel height. Header and footer CTAs remain pinned.
 
 Mantine's Drawer handles this automatically — the `body` section scrolls when content overflows, while the `header` remains fixed. The `Panel.Footer` uses `margin-top: auto` to stay at the bottom.
+
+---
+
+## `.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/Text/TEXT_IMPLEMENTATION_NOTES.md

@@ -0,0 +1,12 @@
+# Text – Implementation Notes
+
+## `.root` `text-wrap: balance` (Matt Massey, 2026-08-28)
+
+**Decision:** Added `text-wrap: balance` via a new `Text.module.css` `.root` class, merged onto the
+typography class alongside the caller's own `className`.
+
+**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`. Chromium/Firefox only balance up to ~6 lines; longer
+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/Text/Text.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/Text/Text.tsx

@@ -10,6 +10,7 @@ import {
 } from "../../utils/filterStylingProps";
 
 import { type RecursicaTextProps } from "@recursica/adapter-common";
+import styles from "./Text.module.css";
 
 export type TextProps = RecursicaOverStyled<
   Omit<MantineTextProps, "variant"> & RecursicaTextProps
@@ -24,9 +25,9 @@ const _Text = forwardRef<HTMLDivElement, TextProps>(function Text(
     .className as string | undefined;
 
   const typographyClass = `recursica_brand_typography_${variant}`;
-  const mergedClassName = classNameProp
-    ? `${typographyClass} ${classNameProp}`
-    : typographyClass;
+  const mergedClassName = [typographyClass, styles.root, classNameProp]
+    .filter(Boolean)
+    .join(" ");
 
   return (
     <MantineText

package/src/components/Title/TITLE_IMPLEMENTATION_NOTES.md

@@ -0,0 +1,12 @@
+# Title – Implementation Notes
+
+## `.root` `text-wrap: balance` (Matt Massey, 2026-08-28)
+
+**Decision:** Added `text-wrap: balance` via a new `Title.module.css` `.root` class, merged onto
+the typography class for every `order` (h1–h6), alongside the caller's own `className`.
+
+**Implementation:** UX asked for more evenly balanced multi-line wrapping instead of a ragged last
+line — headings are the primary intended use case for this property. Not a design token — it's a
+layout algorithm choice, so it's hardcoded rather than pulled from `recursica_variables_scoped.css`.
+Chromium/Firefox only balance up to ~6 lines, which comfortably covers heading text. No fallback
+needed — browsers that don't support the value just ignore the declaration.

package/src/components/Title/Title.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/Title/Title.tsx

@@ -10,6 +10,7 @@ import {
 } from "../../utils/filterStylingProps";
 
 import { type RecursicaTitleProps } from "@recursica/adapter-common";
+import styles from "./Title.module.css";
 
 export type TitleProps = RecursicaOverStyled<
   Omit<MantineTitleProps, "size"> & RecursicaTitleProps
@@ -36,9 +37,9 @@ export const Title = forwardRef<HTMLHeadingElement, TitleProps>(function Title(
     .className as string | undefined;
 
   const typographyClass = `recursica_brand_typography_h${order}`;
-  const mergedClassName = classNameProp
-    ? `${typographyClass} ${classNameProp}`
-    : typographyClass;
+  const mergedClassName = [typographyClass, styles.root, classNameProp]
+    .filter(Boolean)
+    .join(" ");
 
   return (
     <MantineTitle