@cerebruminc/cerebellum 20.0.6 → 20.0.7

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # react-component-lib-boilerplate
 
+## [20.0.7](https://github.com/cerebruminc/cerebellum/compare/v20.0.6...v20.0.7) (2026-08-19)
+
+
+### Bug Fixes
+
+* **mantine:** merge Modal and Notification classNames instead of replacing them ([5718033](https://github.com/cerebruminc/cerebellum/commit/57180332c8a1ca206e9e52c9eba4e4f936c5cad7))
+* **mantine:** stop the inline filled-button shadow from outranking its :disabled reset ([dbcdd46](https://github.com/cerebruminc/cerebellum/commit/dbcdd460d81401bbe8ca403e76cf13ae20e1f73d))
+* **notifications:** stop inline styles from blocking the stylesheet rules meant to override them ([0fee4cd](https://github.com/cerebruminc/cerebellum/commit/0fee4cd1212eb62aa82c365cabb4dd1524cdd1b1))
+
 ## [20.0.6](https://github.com/cerebruminc/cerebellum/compare/v20.0.5...v20.0.6) (2026-08-18)
 
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cerebruminc/cerebellum",
-  "version": "20.0.6",
+  "version": "20.0.7",
   "description": "Cerebrum's React Component Library",
   "type": "module",
   "main": "src/index.ts",

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

@@ -52,8 +52,20 @@
   display: none;
 }
 
-.root:disabled,
-.root[data-disabled] {
+/* The filled variant's glow. The base value lives here, not in the theme's `styles`:
+   Mantine applies `styles` inline, and an inline box-shadow would outrank the
+   `:disabled` reset below. `--button-shadow` is set in the theme's Button `vars`,
+   which Mantine also applies inline -- but a custom property is only a value, so the
+   cascade below still decides who gets to use it. Scoped to the filled variant so no
+   other variant gains a box-shadow declaration it did not have before. */
+.root[data-variant="filled"] {
+  box-shadow: var(--button-shadow, none);
+}
+
+/* Doubled so this outranks the rule above regardless of source order, and beats a
+   consuming app's own single-class rule too. */
+.root.root:disabled,
+.root.root[data-disabled] {
   box-shadow: none;
 }
 

package/src/mantine/mantineTheme.test.tsx

@@ -0,0 +1,249 @@
+/**
+ * @file src/mantine/mantineTheme.test.tsx
+ * @summary Guards the theme against inline styles that break the stylesheet.
+ * @remarks
+ * Mantine applies `styles` and `vars` INLINE — get-style.mjs flat-spreads every
+ * resolved slot into one `style` object — and @mantine/emotion is not installed.
+ * That fails two ways, and this file guards both:
+ *
+ * 1. A key that only means something in a stylesheet (`@media`, `:hover`, `::before`,
+ *    a descendant selector) is silently discarded.
+ * 2. A *base* value left in `styles` is silently applied inline, where it outranks
+ *    the stylesheet rule meant to override it. This is the one that shipped four
+ *    visual bugs, so it gets the STYLESHEET_OWNED table below.
+ *
+ * Anything needing a selector or a breakpoint belongs in a component CSS Module,
+ * wired through the theme's `classNames`.
+ *
+ * Both scans run over PROPS_MATRIX, not just each block's defaults. `styles` and
+ * `vars` branch on props, so resolving a block once leaves every other branch
+ * unscanned — which is how an inline `boxShadow` on `variant="filled"` outranked
+ * Button.module.css's `:disabled` reset without any test noticing.
+ */
+import { DEFAULT_THEME, MantineProvider, type MantineTheme, Modal, mergeMantineTheme } from "@mantine/core";
+import { render } from "@testing-library/react";
+import modalClasses from "./components/Modal.module.css";
+import { createCustomMantineTheme } from "./mantineTheme";
+import type { Color, NotificationTone, NotificationType, TextVariant } from "./types";
+
+const theme: MantineTheme = mergeMantineTheme(DEFAULT_THEME, createCustomMantineTheme());
+
+type Props = Record<string, unknown>;
+type Slots = Record<string, Props>;
+
+/** The shape this file relies on. Mantine types every one of these as `any`. */
+type ThemeBlock = {
+  classNames?: Record<string, string>;
+  defaultProps?: Props;
+  styles?: (theme: MantineTheme, props: Props) => Slots;
+  vars?: (theme: MantineTheme, props: Props) => Slots;
+};
+
+const HOOKS = ["styles", "vars"] as const;
+
+const componentNames = Object.keys(theme.components);
+const blockFor = (name: string): ThemeBlock => theme.components[name] as ThemeBlock;
+
+/** Keys that cannot work as an inline style property. `--custom-props` can, so exempt them. */
+const STYLESHEET_ONLY = /^[@.]|[&:\s>[\]{},]/;
+const isNestedKey = (key: string) => !key.startsWith("--") && STYLESHEET_ONLY.test(key);
+
+const nestedKeysIn = (value: unknown, path: string, seen = new WeakSet<object>()): string[] => {
+  if (!value || typeof value !== "object" || Array.isArray(value) || seen.has(value)) {
+    return [];
+  }
+  seen.add(value);
+
+  return Object.entries(value).flatMap(([key, child]) => {
+    const here = `${path}.${key}`;
+    return isNestedKey(key) ? [here] : nestedKeysIn(child, here, seen);
+  });
+};
+
+/*
+ * Enumerating a union as a Record forces the compiler to flag a member added later,
+ * so the matrix below cannot quietly fall behind the types it covers.
+ */
+const membersOf = <T extends string>(union: Record<T, true>) => Object.keys(union) as T[];
+
+const TEXT_VARIANTS = membersOf<TextVariant>({
+  "body-xs": true,
+  "body-sm": true,
+  "body-md": true,
+  "body-lg": true,
+  "title-xl": true,
+  "title-lg": true,
+  "title-md": true,
+  "title-sm": true,
+  "title-xs": true,
+  "title-2xs": true,
+  "semibold-sm": true,
+});
+const NOTIFICATION_TYPES = membersOf<NotificationType>({ toast: true, bar: true, dialog: true });
+const NOTIFICATION_TONES = membersOf<NotificationTone>({ positive: true, negative: true, neutral: true });
+const PILL_COLORS = membersOf<Color>({
+  aqua: true,
+  blue: true,
+  brand: true,
+  gray: true,
+  orange: true,
+  peach: true,
+  purple: true,
+  red: true,
+  yellow: true,
+});
+
+/** Every block reading `props.size` funnels into the same `getInputVars` branches. */
+const INPUT_SIZES: Props[] = ["xs", "sm", "md", "lg", "xl", undefined].map((size) => ({ size }));
+
+/*
+ * One entry per theme block whose `styles`/`vars` reads props. Each row is merged
+ * over that block's own `defaultProps`, and the block's bare defaults are always
+ * scanned too, so a row only has to name what it changes.
+ */
+const PROPS_MATRIX: Record<string, Props[]> = {
+  Button: [
+    ...INPUT_SIZES,
+    { variant: "filled" },
+    { variant: "filled", color: "gray" },
+    { variant: "filled", w: 200 },
+    { variant: "light" },
+    { variant: "light", color: "gray" },
+    { variant: "subtle" },
+    { variant: "subtle", color: "gray" },
+    { variant: "outline" },
+    { variant: "default" },
+    { boxed: true },
+    { boxed: true, variant: "subtle" },
+  ],
+  Text: [...TEXT_VARIANTS.map((variant) => ({ variant })), { variant: undefined }, { variant: "not-a-variant" }],
+  Notification: [
+    ...NOTIFICATION_TYPES.flatMap((notificationType) =>
+      NOTIFICATION_TONES.flatMap((tone) => [
+        { notificationType, tone },
+        { notificationType, tone, icon: "icon" },
+      ])
+    ),
+    { notificationType: undefined, tone: undefined },
+  ],
+  Pill: [...PILL_COLORS.flatMap((color) => [{ color }, { color, withRemoveButton: true }]), { color: undefined }],
+  TextInput: INPUT_SIZES,
+  PasswordInput: INPUT_SIZES,
+  Textarea: INPUT_SIZES,
+  Select: INPUT_SIZES,
+  MultiSelect: INPUT_SIZES,
+  DateInput: INPUT_SIZES,
+  DatePickerInput: INPUT_SIZES,
+  Autocomplete: INPUT_SIZES,
+  InputBase: INPUT_SIZES,
+};
+
+/** A block's defaults, plus every matrix row layered over them. */
+const permutationsFor = (name: string) => {
+  const defaults = { ...blockFor(name).defaultProps };
+
+  return [
+    { label: "defaultProps", props: defaults },
+    ...(PROPS_MATRIX[name] ?? []).map((row) => ({ label: JSON.stringify(row), props: { ...defaults, ...row } })),
+  ];
+};
+
+describe("no stylesheet-only keys in inline styles", () => {
+  it.each(["@media (max-width: 600px)", "&:hover", ":hover", "::before", "> .thumb", "[data-x] span"])("rejects %s", (key) => {
+    expect(isNestedKey(key)).toBe(true);
+  });
+
+  it.each(["padding", "backgroundColor", "--badge-fz"])("allows %s", (key) => {
+    expect(isNestedKey(key)).toBe(false);
+  });
+
+  it("finds no stylesheet-only key in any theme block, under any props in the matrix", () => {
+    const offenders = componentNames.flatMap((name) => {
+      const block = blockFor(name);
+
+      return HOOKS.flatMap((hook) => {
+        const resolve = block[hook];
+        if (typeof resolve !== "function") {
+          return [];
+        }
+
+        return permutationsFor(name).flatMap(({ label, props }) => nestedKeysIn(resolve(theme, props), `${name}.${hook} [${label}]`));
+      });
+    });
+
+    expect(offenders.sort()).toEqual([]);
+  });
+
+  /* A block that reads props but has no matrix row would be scanned once, under its
+     defaults, leaving every other branch dark. Fail until someone adds the row. */
+  it("has a matrix entry for every block that reads props", () => {
+    const unscanned = componentNames.flatMap((name) =>
+      HOOKS.filter((hook) => {
+        const resolve = blockFor(name)[hook];
+        return typeof resolve === "function" && resolve.length >= 2 && !PROPS_MATRIX[name]?.length;
+      }).map((hook) => `${name}.${hook} reads props but PROPS_MATRIX has no entry for ${name}`)
+    );
+
+    expect(unscanned.sort()).toEqual([]);
+  });
+});
+
+/*
+ * Each row: this slot's CSS owns these properties, so the theme must not set them.
+ * Setting one inline is what killed the Modal's responsive padding, the notification
+ * close button's hover, and the filled Button's `:disabled` shadow reset.
+ */
+const STYLESHEET_OWNED = [
+  { component: "Modal", slot: "header", properties: [/^padding/], owner: "components/Modal.module.css" },
+  { component: "Modal", slot: "body", properties: [/^padding/], owner: "components/Modal.module.css" },
+  { component: "Button", slot: "root", properties: [/^boxShadow/], owner: "components/Button.module.css" },
+  {
+    component: "Notification",
+    slot: "closeButton",
+    properties: ["opacity", /^transition/, /^background/],
+    owner: "services/NotificationAction.module.css",
+  },
+];
+
+describe("styles the stylesheet owns", () => {
+  it.each(STYLESHEET_OWNED)("leaves the $slot slot of $component to $owner", ({ component, slot, properties, owner }) => {
+    const block = blockFor(component);
+    const offenders = permutationsFor(component).flatMap(({ label, props }) =>
+      Object.keys(block.styles?.(theme, props)?.[slot] ?? {})
+        .filter((key) => properties.some((p) => (typeof p === "string" ? p === key : p.test(key))))
+        .map((key) => `${component}.styles.${slot}.${key} [${label}] is applied inline, outranking ${owner}`)
+    );
+
+    expect(offenders).toEqual([]);
+  });
+
+  /* The CSS is only reachable if the module class is wired to the slot. */
+  it.each(STYLESHEET_OWNED)("wires $owner to the $slot slot of $component", ({ component, slot }) => {
+    expect(blockFor(component).classNames?.[slot]).toEqual(expect.any(String));
+  });
+});
+
+/* `defaultProps` goes through a shallow spread in use-props.mjs, so a caller passing
+   any `classNames` replaces the theme's wholesale. Top-level `classNames` merges per
+   slot instead. This ran for Modal and Notification only; every block needs it. */
+it("keeps classNames out of defaultProps in every theme block", () => {
+  const nested = componentNames.filter((name) => blockFor(name).defaultProps?.classNames !== undefined);
+
+  expect(nested).toEqual([]);
+});
+
+/* The regression test for the above: openConfirmModal passes its own classNames,
+   which used to replace the theme's outright. */
+it("keeps Modal's module classes when the caller passes classNames too", () => {
+  render(
+    <MantineProvider theme={createCustomMantineTheme()}>
+      <Modal opened onClose={() => {}} title="Confirm" classNames={{ content: "caller-content" }}>
+        Body copy
+      </Modal>
+    </MantineProvider>
+  );
+
+  expect(document.querySelector(".caller-content")).toHaveClass(modalClasses.content);
+  expect(document.querySelectorAll(`.${modalClasses.header}`)).toHaveLength(1);
+  expect(document.querySelectorAll(`.${modalClasses.body}`)).toHaveLength(1);
+});

package/src/mantine/mantineTheme.ts

@@ -32,8 +32,8 @@ import buttonClasses from "./components/Button.module.css";
 import modalClasses from "./components/Modal.module.css";
 import pillClasses from "./components/Pill.module.css";
 import scrollAreaClasses from "./components/ScrollArea.module.css";
-import notificationActionClasses from "./services/NotificationAction.module.css";
 import notificationClasses from "./services/Notification.module.css";
+import notificationActionClasses from "./services/NotificationAction.module.css";
 
 type TonedNotificationProps = NotificationProps &
   Record<`data-${string}`, unknown> & {
@@ -106,10 +106,8 @@ const getInputVars = (size?: MantineSize | (string & {})) => {
   wrapper["--input-height-lg"] = "calc(3.4375rem * var(--mantine-scale))"; // 55px
   wrapper["--input-height-xl"] = "calc(3.75rem * var(--mantine-scale))"; // 60px
 
-  wrapper["--input-fz"] =
-    wrapper[`--input-fz-${resolvedSize}` as keyof typeof wrapper];
-  wrapper["--input-height"] =
-    wrapper[`--input-height-${resolvedSize}` as keyof typeof wrapper];
+  wrapper["--input-fz"] = wrapper[`--input-fz-${resolvedSize}` as keyof typeof wrapper];
+  wrapper["--input-height"] = wrapper[`--input-height-${resolvedSize}` as keyof typeof wrapper];
 
   return { wrapper };
 };
@@ -470,6 +468,7 @@ export const createCustomMantineTheme = (optionsOrBrandColor?: CreateCustomManti
               | "--button-hover"
               | "--button-hover-color"
               | "--button-color"
+              | "--button-shadow"
               | "--button-subtle-bg"
               | "--button-subtle-underline",
               string | undefined
@@ -520,6 +519,21 @@ export const createCustomMantineTheme = (optionsOrBrandColor?: CreateCustomManti
             root["--button-subtle-underline"] = subtleUnderlineColor;
           }
 
+          /*
+           * The filled variant's glow, as a custom property rather than a `styles`
+           * entry. `styles` is applied inline, and an inline box-shadow outranks
+           * Button.module.css's `:disabled` reset no matter how specific that
+           * selector is -- which is why disabled buttons kept glowing. Custom
+           * properties do work inline, so this keeps the value colour-derived while
+           * leaving the stylesheet able to override it.
+           */
+          if (props.variant === "filled") {
+            const color = props.color || theme.primaryColor;
+            const colorScale = theme.colors[color] || theme.colors[theme.primaryColor];
+
+            root["--button-shadow"] = theme.other.highContrast ? "none" : `0 0 20px -6px ${rgba(colorScale[6], 1)}`;
+          }
+
           // gray does not follow the same tone progression as the other colors;
           // filled variant gets white text via variantColorResolver, so skip it here
           if (props.color === "gray" && props.variant !== "filled") {
@@ -529,16 +543,14 @@ export const createCustomMantineTheme = (optionsOrBrandColor?: CreateCustomManti
           return { root };
         },
         styles: (theme: MantineTheme, props: ButtonProps) => {
-          const color = props.color || theme.primaryColor;
-          const colorScale = theme.colors[color] || theme.colors[theme.primaryColor];
-          const colorValue = colorScale[6];
-
           return {
+            /*
+             * No `boxShadow` here. The filled variant's glow is set as
+             * `--button-shadow` in `vars` above and applied by Button.module.css,
+             * beside the `:disabled` rule that clears it. Setting it here would land
+             * inline and that reset could never win.
+             */
             root: {
-              // Add box-shadow to filled variant buttons using button's color
-              ...(props.variant === "filled" && {
-                boxShadow: theme.other.highContrast ? "none" : `0 0 20px -6px ${rgba(colorValue, 1)}`,
-              }),
               // Light variant gets a border in high contrast to match SecondaryButton/BoxedButton
               ...(props.variant === "light" &&
                 theme.other.highContrast && {
@@ -616,12 +628,19 @@ export const createCustomMantineTheme = (optionsOrBrandColor?: CreateCustomManti
         vars: (_theme: MantineTheme, props: SelectProps) => getInputVars(props.size),
       },
       Modal: {
+        /*
+         * Top level, not inside `defaultProps`. Mantine merges
+         * `theme.components.X.classNames` additively per slot, but `defaultProps` goes
+         * through a shallow spread in `use-props.mjs`, so a caller passing any
+         * `classNames` replaces these wholesale. `openConfirmModal` does exactly that,
+         * which is why confirm modals were losing their padding and scrollbar.
+         */
+        classNames: {
+          header: modalClasses.header,
+          body: modalClasses.body,
+          content: modalClasses.content,
+        },
         defaultProps: {
-          classNames: {
-            header: modalClasses.header,
-            body: modalClasses.body,
-            content: modalClasses.content,
-          },
           withCloseButton: false,
           radius: "10px",
           centered: true,
@@ -634,18 +653,18 @@ export const createCustomMantineTheme = (optionsOrBrandColor?: CreateCustomManti
             color: highContrast ? "#4F6CEA" : "var(--mantine-color-blue-7)",
           },
         },
+        /*
+         * Header/body padding is owned entirely by Modal.module.css, base values
+         * included. A base value set here lands inline, and inline `padding` outranks
+         * any stylesheet rule without `!important`, so the module's `@media`
+         * padding-inline overrides could never apply.
+         */
         styles: (theme: MantineTheme) => ({
           title: {
             fontSize: "30px",
             fontWeight: 600,
             lineHeight: 1.33333,
           },
-          header: {
-            padding: "49px 71px 0",
-          },
-          body: {
-            padding: "20px 71px 61px",
-          },
           close: {
             position: "absolute",
             top: "19px",
@@ -766,11 +785,11 @@ export const createCustomMantineTheme = (optionsOrBrandColor?: CreateCustomManti
         },
       },
       Notification: {
-        defaultProps: {
-          classNames: {
-            root: notificationClasses.root,
-            closeButton: notificationActionClasses.closeButton,
-          },
+        // Top level so a caller's `classNames` merges with these instead of
+        // replacing them -- see the Modal block above.
+        classNames: {
+          root: notificationClasses.root,
+          closeButton: notificationActionClasses.closeButton,
         },
         vars: (theme: MantineTheme, props: TonedNotificationProps) => {
           const notificationType = String(props.notificationType || "toast");
@@ -850,10 +869,13 @@ export const createCustomMantineTheme = (optionsOrBrandColor?: CreateCustomManti
               // Make the button and icon larger
               "--cb-size": "calc(2rem * var(--mantine-scale))",
               "--cb-icon-size": "calc(1.5rem * var(--mantine-scale))",
-              backgroundColor: "transparent",
               color: theme.colors.gray[8],
-              opacity: 0.6,
-              transition: "opacity 350ms ease, background-color 350ms ease",
+              /*
+               * opacity, transition and background-color belong to
+               * NotificationAction.module.css, beside the :hover state. They have to:
+               * an inline `opacity: 0.6` here outranks the stylesheet's
+               * `:hover { opacity: 1 }` no matter how specific that selector is.
+               */
               ...(isToast && {
                 display: "none",
               }),
@@ -874,7 +896,7 @@ export const createCustomMantineTheme = (optionsOrBrandColor?: CreateCustomManti
             icon: React.createElement(
               "span",
               { style: { display: "block", width: "12px", height: "12px", position: "relative" } },
-              React.createElement(X, { fill: "currentColor" }),
+              React.createElement(X, { fill: "currentColor" })
             ),
           },
         },

package/src/mantine/services/NotificationAction.module.css

@@ -1,5 +1,7 @@
 .action.action {
+  color: var(--mantine-color-gray-8);
   text-underline-offset: 5px;
+  transition: color 350ms ease;
   white-space: nowrap;
 }
 
@@ -7,6 +9,14 @@
   color: var(--mantine-color-gray-9);
 }
 
+/* Base state lives here, not in the theme's `styles`: Mantine applies `styles`
+   inline, and an inline opacity would outrank the :hover rule below. */
+.closeButton.closeButton {
+  background-color: transparent;
+  opacity: 0.6;
+  transition: opacity 350ms ease, background-color 350ms ease;
+}
+
 .closeButton.closeButton:hover {
   background-color: transparent;
   opacity: 1;

package/src/mantine/services/notifications.tsx

@@ -64,7 +64,11 @@ export const showBar = (notification: BarNotification, store?: NotificationsStor
       <Anchor
         component="button"
         variant="body-sm"
-        c="gray.8"
+        /*
+         * No `c` prop and no `styles.root` colour: both land as inline styles, which
+         * outrank any stylesheet rule, so the hover colour would never apply. The
+         * colour and its transition live in NotificationAction.module.css.
+         */
         classNames={{ root: classes.action }}
         onClick={(event) => {
           buttonClick?.(event);