@cerebruminc/cerebellum 20.3.1 → 20.4.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # react-component-lib-boilerplate
 
+## [20.4.0](https://github.com/cerebruminc/cerebellum/compare/v20.3.1...v20.4.0) (2026-09-04)
+
+
+### Features
+
+* **datatable:** style columns from columnDef.meta ([e466fdf](https://github.com/cerebruminc/cerebellum/commit/e466fdf3cdef67a434541f8a2451b26ffae20a22))
+
+
+### Bug Fixes
+
+* **icons:** drop the styled-components dependency from icons ([394fa8e](https://github.com/cerebruminc/cerebellum/commit/394fa8e72c1d7fdce6933f907536b02ba0a416dc))
+
 ## [20.3.1](https://github.com/cerebruminc/cerebellum/compare/v20.3.0...v20.3.1) (2026-09-03)
 
 

package/package.json

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

package/src/components/Icons/IconComponentStyles.module.css

@@ -0,0 +1,45 @@
+/**
+ * @file src/components/Icons/IconComponentStyles.module.css
+ * @summary The three boxes an icon renders into, plus the svg itself.
+ * @remarks Per-instance values (box size, box colour, padding, scale) arrive as inline
+ * custom properties rather than generated classes, so the sheet stays static. Each one
+ * carries a fallback, so a primitive rendered without it behaves as it did before.
+ */
+
+/* Unboxed icons: a full-bleed positioning context for the absolutely placed svg. */
+.boringSpan {
+  display: block;
+  height: 100%;
+  position: relative;
+  width: 100%;
+}
+.boringSpan svg {
+  position: absolute;
+  height: 100%;
+  width: 100%;
+}
+
+/* Boxed and round icons get a fixed outer square instead. */
+.iconBox {
+  display: block;
+  height: var(--cb-icon-box-size, auto);
+  width: var(--cb-icon-box-size, auto);
+}
+
+.innerIconBox {
+  display: block;
+  background-color: var(--cb-icon-box-color, transparent);
+  border-radius: 6px;
+  height: 100%;
+  padding: var(--cb-icon-box-padding, 28.4%);
+  width: 100%;
+}
+.innerIconBox[data-round] {
+  border-radius: 50%;
+}
+
+.svg {
+  height: 100%;
+  width: 100%;
+  transform: scale(var(--cb-icon-scale, 1));
+}

package/src/components/Icons/IconComponentStyles.tsx

@@ -1,56 +1,39 @@
-import { styled } from "styled-components";
+import { CSSProperties, FC, PropsWithChildren, SVGProps } from "react";
 
+import styles from "./IconComponentStyles.module.css";
 import { IconBoxProps, InnerIconBoxProps, SvgProps } from "./types";
-// ------- Storybook styles ---------
-export const IconContainer = styled.div`
-  display: inline-block;
-  margin: 30px 20px;
-  width: 150px;
-`;
+// The $-prefixed prop names are a leftover of the styled-components transient-prop
+// convention. They are kept so the 180-odd icon files that pass them need no change.
+export const BoringSpan: FC<PropsWithChildren> = ({ children }) => <span className={styles.boringSpan}>{children}</span>;
 
-export const IconItem = styled.div`
-  height: 67px;
-  margin: 10px auto;
-  width: 67px;
-  /* background-color: papayawhip; */
-`;
+export const IconBox: FC<PropsWithChildren<IconBoxProps>> = ({ $boxedSize, children }) => (
+  <span
+    className={styles.iconBox}
+    style={{ "--cb-icon-box-size": $boxedSize === undefined ? undefined : `${$boxedSize}px` } as CSSProperties}
+  >
+    {children}
+  </span>
+);
 
-export const Name = styled.p`
-  font-size: 16px;
-  margin-top: 20px;
-  text-align: center;
-`;
+export const InnerIconBox: FC<PropsWithChildren<InnerIconBoxProps>> = ({ $boxColor, $paddingString, $round, children }) => (
+  <span
+    className={styles.innerIconBox}
+    data-round={$round || undefined}
+    style={{ "--cb-icon-box-color": $boxColor, "--cb-icon-box-padding": $paddingString } as CSSProperties}
+  >
+    {children}
+  </span>
+);
 
-// ------- Component styles ---------
-export const BoringSpan = styled.span`
-  display: block;
-  height: 100%;
-  position: relative;
-  width: 100%;
-  svg {
-    position: absolute;
-    height: 100%;
-    width: 100%;
-  }
-`;
-
-export const IconBox = styled.span<IconBoxProps>`
-  display: block;
-  height: ${({ $boxedSize }) => $boxedSize}px;
-  width: ${({ $boxedSize }) => $boxedSize}px;
-`;
-
-export const InnerIconBox = styled.span<InnerIconBoxProps>`
-  display: block;
-  background-color: ${({ $boxColor }) => $boxColor};
-  border-radius: ${({ $round }) => ($round ? "50%" : "6px")};
-  height: 100%;
-  padding: ${({ $paddingString }) => $paddingString || "28.4%"};
-  width: 100%;
-`;
-
-export const Svg = styled.svg<SvgProps>`
-  height: 100%;
-  width: 100%;
-  transform: ${(props) => `scale(${props.scale})`};
-`;
+// scale is pulled out of the spread so it never lands on the svg as an attribute, where
+// it is not valid; the class reads it back as a custom property instead. className and
+// style are pulled out for the same reason: rest is spread first so nothing can knock
+// them off by accident, and a caller that supplies either one is then taken at its word
+// — className replaces the default styling, and an icon's own transform (BackArrow's
+// scaleX(-1)) outranks the class rule from its inline position.
+export const Svg: FC<SVGProps<SVGSVGElement> & SvgProps> = ({ scale = 1, className, style, children, ...rest }) => (
+  // biome-ignore lint/a11y/noSvgWithoutTitle: each icon supplies its own title, or aria-hidden when decorative
+  <svg {...rest} className={className ?? styles.svg} style={{ ...style, "--cb-icon-scale": scale } as CSSProperties}>
+    {children}
+  </svg>
+);

package/src/components/Icons/IconList.module.css

@@ -0,0 +1,38 @@
+/**
+ * @file src/components/Icons/IconList.module.css
+ * @summary A responsive grid of named icon tiles.
+ * @remarks The grid replicates the default rendering of the shared GridContainer,
+ * which IconList used before the icons moved off styled-components.
+ */
+
+.grid {
+  display: grid;
+  grid-template-columns: repeat(4, 1fr);
+  gap: 20px;
+  padding: 20px;
+  background-color: white;
+}
+
+@media all and (max-width: 1000px) {
+  .grid {
+    grid-template-columns: repeat(2, 1fr);
+  }
+}
+
+.iconContainer {
+  display: inline-block;
+  margin: 30px 20px;
+  width: 150px;
+}
+
+.iconItem {
+  height: 67px;
+  margin: 10px auto;
+  width: 67px;
+}
+
+.name {
+  font-size: 16px;
+  margin-top: 20px;
+  text-align: center;
+}

package/src/components/Icons/IconList.tsx

@@ -1,7 +1,6 @@
 import { FC } from "react";
-import { GridContainer } from "./../../SharedStorybook/GridStyles";
 import { colors } from "./../../const/colors";
-import { IconContainer, IconItem, Name } from "./IconComponentStyles";
+import styles from "./IconList.module.css";
 import { IconListProps } from "./types";
 
 import * as iconList from ".";
@@ -25,15 +24,15 @@ export const IconList: FC<IconListProps> = (props: IconListProps) => {
   let lastIndex = 0;
 
   return (
-    <GridContainer>
+    <div className={styles.grid}>
       {iconNames.map((name) => {
         const colorIndex = getRandomInt(colorLib.length, lastIndex);
         lastIndex = colorIndex;
         // @ts-ignore
         const IconComponent = iconList[name];
         return (
-          <IconContainer key={name}>
-            <IconItem>
+          <div className={styles.iconContainer} key={name}>
+            <div className={styles.iconItem}>
               <IconComponent
                 fill={boxed || round ? colorLib[colorIndex].icon : "#444"}
                 boxed={boxed}
@@ -42,11 +41,11 @@ export const IconList: FC<IconListProps> = (props: IconListProps) => {
                 round={round}
                 title={`${name}: use a descriptive title, or don't include one if the icon is decorative`}
               />
-            </IconItem>
-            <Name>{name}</Name>
-          </IconContainer>
+            </div>
+            <p className={styles.name}>{name}</p>
+          </div>
         );
       })}
-    </GridContainer>
+    </div>
   );
 };

package/src/components/Icons/Icons.test.tsx

@@ -0,0 +1,222 @@
+import { readFileSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import { render } from "@testing-library/react";
+
+import { Accessibility, BackArrow, IconProps, IconType } from ".";
+import * as iconList from ".";
+import { Cerebrum } from "../../assets/icons/Cerebrum";
+import { Cognition } from "../../assets/icons/Cognition";
+import { Cortex } from "../../assets/icons/Cortex";
+import { Neuron } from "../../assets/icons/Neuron";
+import { colors } from "../../const/colors";
+import ResizeIcon from "../Textarea/ResizeIcon";
+
+const boxes = (container: HTMLElement) => {
+  const outer = container.firstElementChild as HTMLElement;
+  const inner = outer.firstElementChild as HTMLElement;
+  const svg = inner.firstElementChild as SVGSVGElement;
+  return { outer, inner, svg };
+};
+
+describe("icon primitives", () => {
+  it("renders an unboxed icon as span > span > svg", () => {
+    const { outer, inner, svg } = boxes(render(<Accessibility />).container);
+
+    expect(outer.tagName).toBe("SPAN");
+    expect(outer).toHaveClass("boringSpan");
+    expect(inner.tagName).toBe("SPAN");
+    expect(inner).toHaveClass("boringSpan");
+    expect(svg.tagName).toBe("svg");
+    expect(svg).toHaveClass("svg");
+  });
+
+  it("sizes and colours a boxed icon through custom properties", () => {
+    const { outer, inner } = boxes(render(<Accessibility boxed boxedSize={40} boxColor="#abcdef" />).container);
+
+    expect(outer).toHaveClass("iconBox");
+    expect(outer.style.getPropertyValue("--cb-icon-box-size")).toBe("40px");
+    expect(inner).toHaveClass("innerIconBox");
+    expect(inner.style.getPropertyValue("--cb-icon-box-color")).toBe("#abcdef");
+    expect(inner.style.getPropertyValue("--cb-icon-box-padding")).toBe("25.4%");
+    expect(inner).not.toHaveAttribute("data-round");
+  });
+
+  it("falls back to the default box size when none is given", () => {
+    const { outer } = boxes(render(<Accessibility boxed />).container);
+
+    expect(outer.style.getPropertyValue("--cb-icon-box-size")).toBe("67px");
+  });
+
+  it("marks a round icon with data-round and its wider padding", () => {
+    const { inner } = boxes(render(<Accessibility round />).container);
+
+    expect(inner).toHaveAttribute("data-round");
+    expect(inner.style.getPropertyValue("--cb-icon-box-padding")).toBe("35%");
+  });
+
+  it("derives the box colour from fill when boxColor is omitted", () => {
+    const { inner } = boxes(render(<Accessibility boxed fill={colors.BLUE_100} />).container);
+
+    expect(inner.style.getPropertyValue("--cb-icon-box-color")).toBe(colors.BLUE_5);
+  });
+
+  it("falls back to black for a fill boxColorLookup has no entry for", () => {
+    const { inner } = boxes(render(<Accessibility boxed fill="var(--cb-table-sort-indicator)" />).container);
+
+    expect(inner.style.getPropertyValue("--cb-icon-box-color")).toBe(colors.BLACK);
+  });
+
+  it("passes scale to the svg as a custom property rather than an attribute", () => {
+    const { svg } = boxes(render(<Accessibility scale={2} />).container);
+
+    expect(svg.style.getPropertyValue("--cb-icon-scale")).toBe("2");
+    // styled-components used to forward scale onto the element, where it is not a
+    // valid SVG attribute and did nothing.
+    expect(svg).not.toHaveAttribute("scale");
+  });
+
+  it("keeps an icon's own transform ahead of the scale custom property", () => {
+    const { svg } = boxes(render(<BackArrow scale={3} />).container);
+
+    expect(svg.style.transform).toBe("scaleX(-1)");
+    expect(svg.style.getPropertyValue("--cb-icon-scale")).toBe("3");
+  });
+
+  it("leaks none of the transient-style props onto the DOM", () => {
+    const rendered = [
+      boxes(render(<Accessibility />).container),
+      boxes(render(<Accessibility boxed />).container),
+      boxes(render(<Accessibility round />).container),
+    ];
+
+    for (const { outer, inner, svg } of rendered) {
+      for (const el of [outer, inner, svg]) {
+        for (const name of el.getAttributeNames()) {
+          expect(name).not.toContain("$");
+          expect(["boxedsize", "boxcolor", "paddingstring", "round", "scale"]).not.toContain(name);
+        }
+      }
+    }
+  });
+
+  it("threads fill onto the drawn shapes", () => {
+    const { container } = render(<Accessibility fill="var(--cb-test-colour)" />);
+
+    const paths = Array.from(container.querySelectorAll("path"));
+    expect(paths.length).toBeGreaterThan(0);
+    for (const path of paths) {
+      expect(path).toHaveAttribute("fill", "var(--cb-test-colour)");
+    }
+  });
+
+  it("labels a titled icon and hides an untitled one", () => {
+    const { svg: titled, ...rest } = boxes(render(<Accessibility title="Accessibility" />).container);
+    const titleId = titled.getAttribute("aria-labelledby");
+
+    expect(titleId).toBeTruthy();
+    expect(rest.outer.querySelector(`title#${titleId}`)).toHaveTextContent("Accessibility");
+    expect(titled).not.toHaveAttribute("aria-hidden");
+
+    const { svg: untitled } = boxes(render(<Accessibility />).container);
+    expect(untitled).toHaveAttribute("aria-hidden", "true");
+    expect(untitled.querySelector("title")).toBeNull();
+  });
+});
+
+describe("every exported icon", () => {
+  const names = Object.keys(iconList);
+  const modes: Array<[string, IconProps]> = [
+    ["plain", {}],
+    ["boxed", { boxed: true }],
+    ["round", { round: true }],
+  ];
+
+  it.each(names.flatMap((name) => modes.map(([mode, props]): [string, string, IconProps] => [name, mode, props])))(
+    "%s renders an svg when %s",
+    (name, _mode, props) => {
+      const Icon = (iconList as Record<string, IconType>)[name];
+
+      const { container } = render(<Icon {...props} title={name} />);
+      expect(container.querySelector("svg")).toBeInTheDocument();
+    }
+  );
+});
+
+// These live outside src/components/Icons but build on the same four primitives, so the
+// barrel-driven sweep above never reaches them.
+describe("the icons built on the primitives from elsewhere", () => {
+  it.each([
+    ["Cerebrum", Cerebrum],
+    ["Cortex", Cortex],
+    ["Neuron", Neuron],
+  ])("%s renders an svg", (name, Icon) => {
+    const { container } = render(<Icon boxed title={name} />);
+    expect(container.querySelector("svg")).toBeInTheDocument();
+  });
+
+  it("Cognition renders an image rather than an svg", () => {
+    const { inner } = boxes(render(<Cognition boxed />).container);
+
+    expect(inner).toHaveClass("innerIconBox");
+    expect(inner.firstElementChild?.tagName).toBe("IMG");
+  });
+
+  it("ResizeIcon leaves the box colour to the stylesheet fallback", () => {
+    const { inner } = boxes(render(<ResizeIcon boxed />).container);
+
+    expect(inner).toHaveClass("innerIconBox");
+    expect(inner.style.getPropertyValue("--cb-icon-box-color")).toBe("");
+  });
+});
+
+describe("the icon stylesheets", () => {
+  const dir = __dirname;
+  const modules = ["IconComponentStyles.module.css", "IconList.module.css"];
+  const read = (file: string) => readFileSync(join(dir, file), "utf8");
+  const withoutComments = (css: string) => css.replace(/\/\*[\s\S]*?\*\//g, "");
+
+  it.each(modules)("%s avoids native nesting", (file) => {
+    // Consumers compile these modules with their own pipeline, so nesting is unsafe.
+    // Nesting needs no "&", so the real check is a block inside a block — with at-rule
+    // blocks such as @media stripped first, since those legitimately wrap rules.
+    const css = withoutComments(read(file)).replace(/@[\w-]+[^{]*\{/g, "");
+
+    expect(css).not.toContain("&");
+    expect(css).not.toMatch(/\{[^{}]*\{/);
+  });
+
+  it.each(["IconComponentStyles", "IconList"])("%s only uses classes its stylesheet declares", (name) => {
+    const declared = new Set(Array.from(withoutComments(read(`${name}.module.css`)).matchAll(/\.([a-zA-Z][\w-]*)/g), (m) => m[1]));
+    const used = Array.from(readFileSync(join(dir, `${name}.tsx`), "utf8").matchAll(/\bstyles\.([\w$]+)/g), (m) => m[1]);
+
+    // Jest maps CSS to identity-obj-proxy, so a class missing from the stylesheet still
+    // renders its own name and every toHaveClass above would pass regardless.
+    expect(used.length).toBeGreaterThan(0);
+    for (const className of used) {
+      expect([...declared]).toContain(className);
+    }
+  });
+
+  it("positions the svg absolutely only for unboxed icons", () => {
+    const css = withoutComments(read("IconComponentStyles.module.css"));
+    const boringSpanSvg = css.match(/\.boringSpan svg \{([^}]*)\}/);
+
+    expect(boringSpanSvg?.[1]).toContain("position: absolute");
+    expect(css.match(/position: absolute/g)).toHaveLength(1);
+  });
+
+  it("keeps the icon directory free of styled-components", () => {
+    const sources = (function walk(from: string): string[] {
+      return readdirSync(from, { withFileTypes: true }).flatMap((entry) => {
+        const path = join(from, entry.name);
+        if (entry.isDirectory()) return walk(path);
+        return (entry.name.endsWith(".tsx") || entry.name.endsWith(".ts")) && entry.name !== "Icons.test.tsx" ? [path] : [];
+      });
+    })(dir);
+
+    expect(sources.length).toBeGreaterThan(180);
+    for (const path of sources) {
+      expect(readFileSync(path, "utf8")).not.toMatch(/["']styled-components/);
+    }
+  });
+});

package/src/components/Icons/types.tsx

@@ -18,11 +18,14 @@ export interface IconListProps {
   round?: boolean;
 }
 
+// Every prop is optional: BoringSpan stands in for both boxes on an unboxed icon, and
+// ResizeIcon renders InnerIconBox without a box colour. The CSS carries a fallback for
+// each one.
 export interface IconBoxProps {
-  $boxedSize: number;
+  $boxedSize?: number;
 }
 export interface InnerIconBoxProps {
-  $boxColor: string;
+  $boxColor?: string;
   $paddingString?: string;
   $round?: boolean;
 }

package/src/index.ts

@@ -687,6 +687,7 @@ export {
 export type {
   DataTableBarProps,
   DataTableBodyProps,
+  DataTableColumnMeta,
   DataTableContentProps,
   DataTableDensity,
   DataTableFilterProps,

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

@@ -167,7 +167,13 @@
   gap: 6px;
   letter-spacing: inherit;
   padding: 0;
-  text-align: left;
+  /*
+   * Only here to undo the UA's `text-align: center` on a button, which shows up
+   * when a header label wraps to a second line. `inherit` does that just as well
+   * as `left` did -- the th resolves to left unless it is aligned -- and picks up
+   * a `meta.align` for free instead of needing a fourth rule to override it.
+   */
+  text-align: inherit;
 }
 
 .sortControl.sortControl:focus-visible {
@@ -206,16 +212,120 @@
 /*
  * A `meta.fixedWidth` column is the track, so the cell keeps none of the 16px
  * inset the auto-width columns carry -- the old ColumnType.fixedWidth columns were
- * exact grid tracks. The cell still sets its width inline (see fixedWidthProps),
+ * exact grid tracks. The cell still sets its width inline (see cellProps),
  * because a class cannot carry a per-column number.
  *
  * The compact rules above reach (0,5,0) and so does this, which is a tie -- broken
  * by source order, which is decided here rather than by the consumer's bundler,
- * since both rules live in this file. That is why this sits below them.
+ * since both rules live in this file. That is why this sits below them. Naming only
+ * the two sides is also what leaves the compact density's 8px top and bottom in
+ * place, rather than having to restate them.
  */
 .table.table .td.td[data-fixed-width],
 .table.table .th.th[data-fixed-width] {
-  padding: 0;
+  padding-left: 0;
+  padding-right: 0;
+}
+
+/*
+ * A column's `meta.align`. The two halves are deliberately asymmetric, per the
+ * doubling rule at the top of this file: Mantine declares `text-align: left` on
+ * the th (and `right` under [dir="rtl"]) at (0,1,0), so that half is doubled to
+ * beat it; nothing declares it on the td, so that half is left undoubled.
+ *
+ * Note the attribute already carries a point of specificity, so even the
+ * undoubled half lands at (0,2,0) rather than a class's (0,1,0) -- a consumer
+ * overriding it needs at least that much, or the inline `style` the file header
+ * points them at. Undoubled still buys them the cheaper target of the two.
+ *
+ * Nothing above declares text-align on a cell, so unlike the fixed-width reset
+ * these do not depend on where in the file they sit.
+ *
+ * Physical left/right, not the logical properties: there is no RTL anywhere in
+ * this package, and the rest of the module is physical too.
+ */
+.td[data-align="left"],
+.th.th[data-align="left"] {
+  text-align: left;
+}
+
+.td[data-align="center"],
+.th.th[data-align="center"] {
+  text-align: center;
+}
+
+.td[data-align="right"],
+.th.th[data-align="right"] {
+  text-align: right;
+}
+
+/*
+ * The sortable header needs its own pair, and text-align cannot stand in for it.
+ * .sortControl is a <button>, which sizes to fit-content under `width: auto` even
+ * with `display: flex` -- so it hugs its label at the cell's start edge, where
+ * text-align has no inline content left to move and justify-content has no slack
+ * to distribute. Giving it the cell's width supplies that slack.
+ *
+ * Gated on the aligned values rather than declared on the base: a full-width
+ * button would stretch every existing sortable header's focus ring from "hugs the
+ * label" to "spans the cell". Aligned headers accept that; unaligned ones should
+ * not have to.
+ */
+.th.th[data-align="center"] .sortControl {
+  justify-content: center;
+  width: 100%;
+}
+
+.th.th[data-align="right"] .sortControl {
+  justify-content: flex-end;
+  width: 100%;
+}
+
+/*
+ * A column's `meta.textStyle` -- the legacy BodyS* set, which was all 15px on a
+ * 22.5px line (theme.text.lineHeightSmall) and differed only in weight and colour.
+ *
+ * Single-class throughout: Mantine declares none of these on a td, and the value
+ * a cell would otherwise use is inherited from the table, which loses to any
+ * declared value whatever its specificity. So there is nothing here to outrank.
+ * The attribute still puts these at (0,2,0), above a bare class -- a consumer
+ * overriding them needs equal specificity or an inline `style`.
+ *
+ * Only `secondary` needs a custom property: COOL_GREY_100 and COOL_GREY_65 are
+ * gray[9] and gray[8], and both are already black in the high-contrast tuple, so
+ * they need no theme branch. COOL_GREY_75 has no shade -- see mantineTheme.ts.
+ */
+.td[data-text-style] {
+  font-size: 15px;
+  /*
+   * Declared, not inherited: every BodyS* carried its own weight, so `primary`,
+   * `secondary` and `tertiary` reset a bolder cell rather than picking it up.
+   * `emphasis` below ties this at (0,2,0) and wins on source order, which is this
+   * file's to decide since both rules live in it.
+   */
+  font-weight: 400;
+  line-height: 22.5px;
+}
+
+.td[data-text-style="primary"] {
+  color: var(--mantine-color-gray-9);
+  letter-spacing: 0.36px;
+}
+
+.td[data-text-style="emphasis"] {
+  color: var(--mantine-color-gray-9);
+  font-weight: 700;
+  letter-spacing: 0.39px;
+}
+
+.td[data-text-style="secondary"] {
+  color: var(--cb-table-cell-secondary);
+  letter-spacing: 0.39px;
+}
+
+.td[data-text-style="tertiary"] {
+  color: var(--mantine-color-gray-8);
+  letter-spacing: 0.39px;
 }
 
 /* rowBorderRadius: 4. Only the outer cells round, so the row reads as one shape. */