@recursica/mui-adapter 0.37.0 → 0.39.0

package/package.json

@@ -13,7 +13,7 @@
     "url": "git+https://github.com/borderux/recursica.git",
     "directory": "packages/mui-adapter"
   },
-  "version": "0.37.0",
+  "version": "0.39.0",
   "publishConfig": {
     "access": "public"
   },
@@ -61,11 +61,13 @@
     "build": "vite build --mode library",
     "build-storybook": "storybook build -o storybook-static",
     "lint": "eslint .",
-    "storybook": "storybook dev -p 6012",
+    "storybook": "storybook dev",
     "analyze-tokens": "analyze-tokens --css ./recursica_variables_scoped.css --dir src/components --output token-analysis.json",
     "prebuild": "npm run analyze-tokens",
     "adapter-tester": "adapter-tester --serve",
     "adapter-tester:automated": "adapter-tester",
+    "adapter-tester:update-golden": "adapter-tester --update-golden",
+    "adapter-tester:source-of-truth": "adapter-tester --divergence-only",
     "test": "vitest run --project unit",
     "test:dom": "vitest run --project dom"
   },
@@ -111,7 +113,7 @@
     "vitest": "^3.2.4"
   },
   "dependencies": {
-    "@recursica/adapter-common": "^0.26.0",
+    "@recursica/adapter-common": "^0.28.0",
     "dayjs": "^1.11.21"
   },
   "peerDependencies": {

package/src/Introduction.stories.tsx

@@ -6,7 +6,8 @@ import { OverStylingInfo } from "./OverStyling";
 const DOCS_URL = "https://recursica.com";
 const FORGE_URL = "https://forge.recursica.com";
 
-import { Container, Box, Group, Heading, Text, Link } from "./components";
+import { Box } from "@mui/material";
+import { Container, Group, Heading, Text, Link } from "./components";
 
 function IntroductionContent() {
   return (

package/src/OverStyling.tsx

@@ -1,9 +1,8 @@
 import ReactMarkdown from "react-markdown";
-import { Paper, Divider } from "@mui/material";
+import { Box, Paper, Divider } from "@mui/material";
 import {
   Container,
   Stack,
-  Box,
   Text as RawText,
   Heading,
   Switch as RawSwitch,

package/src/Version.tsx

@@ -1,6 +1,6 @@
 import ReactMarkdown from "react-markdown";
-import { Paper, Divider } from "@mui/material";
-import { Container, Heading, Group, Link, Box } from "./components";
+import { Paper, Divider, Box } from "@mui/material";
+import { Container, Heading, Group, Link } from "./components";
 import pkg from "../package.json";
 import changelog from "../CHANGELOG.md?raw";
 

package/src/components/Accordion/Accordion.stories.tsx

@@ -123,6 +123,42 @@ export const WithIcons: StoryObj<typeof Accordion> = {
   },
 };
 
+export const LongTitleTruncation: StoryObj<typeof Accordion> = {
+  render: () => {
+    return (
+      // `style` is stripped from Accordion itself (only passes through with overStyled);
+      // constrain width on a plain wrapper div instead to force truncation.
+      <Layer layer={0} style={{ padding: "24px" }}>
+        <div style={{ maxWidth: 320 }}>
+          <Accordion defaultValue="long-title" chevron={<ChevronIcon />}>
+            <Accordion.Item value="long-title">
+              <Accordion.Control leftIcon={<SVGIcon />}>
+                This is a deliberately very long accordion item title used to
+                verify that overflowing text truncates with a CSS ellipsis
+                instead of wrapping or overflowing the header
+              </Accordion.Control>
+              <Accordion.Panel>
+                The header label above should truncate to a single line with a
+                trailing ellipsis (…) rather than wrapping onto multiple lines
+                or pushing the chevron out of view.
+              </Accordion.Panel>
+            </Accordion.Item>
+
+            <Accordion.Item value="short-title">
+              <Accordion.Control leftIcon={<SVGIcon />}>
+                Short Title
+              </Accordion.Control>
+              <Accordion.Panel>
+                A short title in the same accordion for visual comparison.
+              </Accordion.Panel>
+            </Accordion.Item>
+          </Accordion>
+        </div>
+      </Layer>
+    );
+  },
+};
+
 export const Disabled: StoryObj<typeof Accordion> = {
   render: () => {
     return (

package/src/components/{Autocomplete/Autocomplete.stories.tsx → AutoComplete/AutoComplete.stories.tsx}

@@ -1,8 +1,8 @@
 import type { Meta, StoryObj } from "@storybook/react";
-import { Autocomplete as AutoComplete } from "./Autocomplete";
+import { AutoComplete } from "./AutoComplete";
 import { formControlArgTypes } from "../../../.storybook/commonArgTypes";
 import { renderRichOptionContent } from "../../utils/renderRichOption";
-import styles from "./Autocomplete.module.css";
+import styles from "./AutoComplete.module.css";
 
 const meta: Meta<typeof AutoComplete> = {
   title: "UI-Kit/AutoComplete",

package/src/components/{Autocomplete/Autocomplete.tsx → AutoComplete/AutoComplete.tsx}

@@ -19,7 +19,7 @@ import {
 import { type RecursicaFormControlWrapperProps } from "../FormControlWrapper/FormControlWrapper";
 import { WithReadOnlyWrapper } from "../ReadOnlyField/WithReadOnlyWrapper";
 import { renderRichOptionContent } from "../../utils/renderRichOption";
-import styles from "./Autocomplete.module.css";
+import styles from "./AutoComplete.module.css";
 
 import { type RecursicaAutocompleteProps as BaseRecursicaAutocompleteProps } from "@recursica/adapter-common";
 
@@ -46,10 +46,10 @@ export interface RecursicaAutocompleteProps
     ReadOnlyControlProps,
     BaseRecursicaAutocompleteProps {}
 
-export type AutocompleteProps = RecursicaOverStyled<RecursicaAutocompleteProps>;
+export type AutoCompleteProps = RecursicaOverStyled<RecursicaAutocompleteProps>;
 
-export const Autocomplete = forwardRef<HTMLInputElement, AutocompleteProps>(
-  function Autocomplete(props, ref) {
+export const AutoComplete = forwardRef<HTMLInputElement, AutoCompleteProps>(
+  function AutoComplete(props, ref) {
     const {
       overStyled = false,
       formLayout = "stacked",
@@ -255,4 +255,4 @@ export const Autocomplete = forwardRef<HTMLInputElement, AutocompleteProps>(
   },
 );
 
-Autocomplete.displayName = "Autocomplete";
+AutoComplete.displayName = "AutoComplete";

package/src/components/AutoComplete/index.ts

@@ -0,0 +1 @@
+export * from "./AutoComplete";

package/src/components/FormControlLayout/FormControlLayout.stories.tsx

@@ -1,6 +1,7 @@
 import type { Meta, StoryObj } from "@storybook/react";
 import { FormControlLayout } from "./FormControlLayout";
 import { Switch } from "../Switch/Switch";
+import { Label } from "../Label/Label";
 
 const meta: Meta<typeof FormControlLayout> = {
   title: "UI-Kit/FormControlLayout",
@@ -80,3 +81,38 @@ export const SideBySideLayout: Story = {
     children: <Switch label="Offset switch aligning with grid" />,
   },
 };
+
+/**
+ * A real Label (not a placeholder) in a stacked layout, at `labelSize="default"`. Even
+ * though the label sits above the field rather than beside it, its own column still caps
+ * to the design system's stacked-layout width (224px) rather than stretching to the full
+ * container — long label text wraps instead of spanning edge-to-edge.
+ */
+export const StackedLayoutWithLabelDefault: Story = {
+  args: {
+    formLayout: "stacked",
+    labelSize: "default",
+    leftSection: (
+      <Label labelSize="default">
+        A fairly long label to show the stacked-layout width cap in action
+      </Label>
+    ),
+    children: <Switch label="Input area content" />,
+  },
+};
+
+/**
+ * Same as above, at `labelSize="small"` — the stacked-layout width cap is narrower (80px).
+ */
+export const StackedLayoutWithLabelSmall: Story = {
+  args: {
+    formLayout: "stacked",
+    labelSize: "small",
+    leftSection: (
+      <Label labelSize="small">
+        A fairly long label to show the stacked-layout width cap in action
+      </Label>
+    ),
+    children: <Switch label="Input area content" />,
+  },
+};

package/src/components/Label/Label.stories.tsx

@@ -1,9 +1,7 @@
-/* eslint-disable @typescript-eslint/no-explicit-any */
 import React from "react";
 import type { Meta, StoryObj } from "@storybook/react";
 import { Label } from "./Label";
-import { TextField } from "../TextField/TextField";
-import { formControlArgTypes } from "../../../.storybook/commonArgTypes";
+import { Button } from "../Button/Button";
 
 type LabelStoryProps = React.ComponentProps<typeof Label>;
 
@@ -15,12 +13,43 @@ const meta: Meta<LabelStoryProps> = {
     docs: {
       description: {
         component:
-          "The `Label` component is a strict Recursica-styled wrapper around Mantine's native `Input.Label`. It serves as the primary compositional primitive for all form fields, preserving Mantine's accessibility associations and context while strictly enforcing the Recursica atomic design system.\n\n### Usage with Form Inputs\nWhen working with form structures, render this `Label` component directly above your inputs or supply it to a component's overriding properties. The component automatically maps structural layout dimensions, dynamic alignment (`left` vs `right`), custom indicator gaps, and integrates a customized `optionalText` and `withEditIcon` flow that safely bypasses Mantine's native required asterisk mechanisms.",
+          "The `Label` component is a strict Recursica-styled wrapper around Mantine's native `Input.Label`. It serves as the primary compositional primitive for all form fields, preserving Mantine's accessibility associations and context while strictly enforcing the Recursica atomic design system.\n\n### Usage with Form Inputs\nThis component only renders the label itself — layout concerns like `stacked` vs `side-by-side` positioning relative to an input live on `FormControlLayout`/`FormControlWrapper`, not here. Render this `Label` in isolation to verify its own states, or see `UI-Kit/FormControlLayout` for how it composes into a full form field.",
       },
     },
   },
   argTypes: {
-    ...formControlArgTypes,
+    labelSize: {
+      control: "inline-radio",
+      options: ["default", "small", "md"],
+      description:
+        "Sizing metrics for the Label. Only visually distinguishable once composed inside a `side-by-side` FormControlLayout, which is where the resulting width constraint applies.",
+    },
+    labelAlignment: {
+      control: "inline-radio",
+      options: ["left", "right"],
+      description: "Text alignment of the label content.",
+    },
+    required: {
+      control: "boolean",
+      description:
+        "Renders the required asterisk (suppressed automatically when `labelWithEditIcon` is set, and mutually exclusive with `labelOptionalText`).",
+    },
+    labelOptionalText: {
+      control: "text",
+      description:
+        "Secondary text rendered beneath the label. Pass `true` for the default '(Optional)' string, or a custom node/string. Suppressed when `required` is true.",
+    },
+    labelWithEditIcon: {
+      control: "boolean",
+      description:
+        "Replaces the default edit icon slot with an interactive edit affordance; replaces the required asterisk visually when both are set.",
+    },
+    labelActionArea: {
+      table: { disable: true },
+    },
+    onLabelEditClick: {
+      table: { disable: true },
+    },
   },
 };
 
@@ -28,95 +57,75 @@ export default meta;
 
 type Story = StoryObj<LabelStoryProps>;
 
-// Utility mapping to pipe raw Label args structurally into TextField accurately
-const renderWithTextField = ({ children, ...args }: LabelStoryProps) => (
-  <TextField
-    label={children as React.ReactNode}
-    placeholder="Form Control primitive mapped..."
-    {...(args as any)}
-  />
-);
-
 export const Default: Story = {
   args: {
-    children: "Dynamic Label (Controls)",
-
+    children: "Label",
     labelSize: "default",
     labelAlignment: "left",
     required: false,
     labelOptionalText: "",
     labelWithEditIcon: false,
   },
-  render: renderWithTextField,
 };
 
-export const StackedDefault: Story = {
+export const Required: Story = {
   args: {
-    children: "Email Address",
+    children: "Required Field",
+    required: true,
   },
-  render: renderWithTextField,
 };
 
-export const StackedRequired: Story = {
+export const RequiredSuppressesOptionalText: Story = {
   args: {
-    children: "Primary Network Node",
-
+    children: "Full Name",
     required: true,
+    labelOptionalText: "This should not render",
   },
-  render: renderWithTextField,
 };
 
-export const StackedWithEditIcon: Story = {
+export const WithOptionalText: Story = {
   args: {
-    children: "Environment Variables",
-
-    labelWithEditIcon: true,
+    children: "Bio",
+    labelOptionalText: "Max 100 characters",
   },
-  render: renderWithTextField,
 };
 
-export const SideBySideDefault: Story = {
+export const BooleanOptionalText: Story = {
   args: {
-    children: "Status",
-
-    labelSize: "default",
+    children: "Middle Initial",
+    labelOptionalText: true,
   },
-  render: renderWithTextField,
 };
 
-export const RequiredSuppressesOptionalText: Story = {
+export const WithEditIcon: Story = {
   args: {
-    children: "Full Name",
-
-    required: true,
-    labelOptionalText: "This should not render",
+    children: "Shipping Address",
+    labelWithEditIcon: true,
   },
-  render: renderWithTextField,
 };
 
-export const BooleanOptionalText: Story = {
+export const RequiredWithEditIcon: Story = {
   args: {
-    children: "Middle Initial",
-
-    labelOptionalText: true,
+    children: "Primary Network Node",
+    required: true,
+    labelWithEditIcon: true,
   },
-  render: renderWithTextField,
 };
 
-export const WithEditIcon: Story = {
+export const RightAligned: Story = {
   args: {
-    children: "Shipping Address",
-
-    labelWithEditIcon: true,
+    children: "Status",
+    labelAlignment: "right",
   },
-  render: renderWithTextField,
 };
 
-export const LayerOneSideBySide: Story = {
+export const WithActionArea: Story = {
   args: {
     children: "Configuration",
-
-    labelWithEditIcon: true,
+    labelActionArea: (
+      <Button variant="text" size="small">
+        Edit
+      </Button>
+    ),
   },
-  render: renderWithTextField,
 };

package/src/components/Loader/Loader.animate.dom.test.tsx

@@ -0,0 +1,72 @@
+import React from "react";
+import { describe, it, expect } from "vitest";
+import { createRoot, type Root } from "react-dom/client";
+import { flushSync } from "react-dom";
+import { Loader } from "./Loader";
+
+function mount(node: React.ReactElement): {
+  container: HTMLElement;
+  root: Root;
+} {
+  const container = document.createElement("div");
+  document.body.appendChild(container);
+  const root = createRoot(container);
+  flushSync(() => root.render(node));
+  return { container, root };
+}
+
+function unmount({ container, root }: { container: HTMLElement; root: Root }) {
+  root.unmount();
+  container.remove();
+}
+
+/**
+ * `animate={false}` must deterministically freeze every variant — including
+ * the bars'/dots' individually-animated child spans, which the freeze rule
+ * can only reach via a descendant selector, not the `data-variant`-scoped
+ * rules the size/thickness CSS uses.
+ */
+describe("Loader animate prop", () => {
+  it.each(["oval", "bars", "dots"] as const)(
+    "freezes every animated element for variant=%s when animate is false, and animates by default",
+    (variant) => {
+      const animated = mount(<Loader variant={variant} />);
+      const frozen = mount(<Loader variant={variant} animate={false} />);
+
+      try {
+        const animatedRoot =
+          animated.container.querySelector("[data-variant]")!;
+        const frozenRoot = frozen.container.querySelector("[data-variant]")!;
+
+        const animatedTargets = [
+          animatedRoot,
+          ...Array.from(animatedRoot.querySelectorAll("*")),
+        ];
+        const frozenTargets = [
+          frozenRoot,
+          ...Array.from(frozenRoot.querySelectorAll("*")),
+        ];
+
+        // At least one element (or the root's own ::after, for oval) actually
+        // animates by default — otherwise this test would trivially pass.
+        const hasAnimation = (el: Element, pseudo?: string) =>
+          getComputedStyle(el, pseudo).animationName !== "none";
+        const animatedHasMotion =
+          animatedTargets.some((el) => hasAnimation(el)) ||
+          hasAnimation(animatedRoot, "::after");
+        expect(animatedHasMotion).toBe(true);
+
+        // Frozen: nothing animates, root included, pseudo-element included.
+        for (const el of frozenTargets) {
+          expect(getComputedStyle(el).animationName).toBe("none");
+        }
+        expect(getComputedStyle(frozenRoot, "::after").animationName).toBe(
+          "none",
+        );
+      } finally {
+        unmount(animated);
+        unmount(frozen);
+      }
+    },
+  );
+});

package/src/components/Loader/Loader.module.css

@@ -9,6 +9,16 @@
   box-sizing: border-box;
 }
 
+/* `animate={false}` — freezes every variant's animation (the oval's own
+ * spinning ::after, and the bars'/dots' individually-animated child spans)
+ * so the loader renders deterministically, e.g. for a visual-regression
+ * snapshot that would otherwise diff differently every run. */
+.root[data-animate="false"],
+.root[data-animate="false"] *,
+.root[data-animate="false"]::after {
+  animation: none !important;
+}
+
 /* data-size mapping */
 
 /* SMALL */

package/src/components/Loader/Loader.stories.tsx

@@ -41,6 +41,11 @@ const meta: Meta<LoaderStoryArgs> = {
       description:
         "Applies a wrapping context to observe rendering logic externally",
     },
+    animate: {
+      control: "boolean",
+      description:
+        "Freezes the CSS animation when false — deterministic, for visual regression",
+    },
   },
 };
 
@@ -48,6 +53,11 @@ export default meta;
 
 type Story = StoryObj<LoaderStoryArgs>;
 
+/**
+ * Animated — excluded from visual regression (`adapter-tester.config.json`),
+ * since a moving animation diffs differently every run. See the `Static*`
+ * stories below for the deterministic, visual-regression-covered equivalents.
+ */
 export const Default: Story = {
   args: {
     variant: "oval",
@@ -62,33 +72,43 @@ export const Default: Story = {
   ),
 };
 
+/** `animate: false` freezes the spin — deterministic for visual regression. */
 export const StaticOvalDefault: Story = {
   args: {
     variant: "oval",
     size: "default",
+    animate: false,
   },
   // eslint-disable-next-line @typescript-eslint/no-unused-vars, @typescript-eslint/no-explicit-any
   render: ({ withLayer, layer, ...args }: any) => <Loader {...args} />,
 };
 
+/** `animate: false` freezes the bars — deterministic for visual regression. */
 export const StaticBarsLarge: Story = {
   args: {
     variant: "bars",
     size: "large",
+    animate: false,
   },
   // eslint-disable-next-line @typescript-eslint/no-unused-vars, @typescript-eslint/no-explicit-any
   render: ({ withLayer, layer, ...args }: any) => <Loader {...args} />,
 };
 
+/** `animate: false` freezes the dots — deterministic for visual regression. */
 export const StaticDotsSmall: Story = {
   args: {
     variant: "dots",
     size: "sm",
+    animate: false,
   },
   // eslint-disable-next-line @typescript-eslint/no-unused-vars, @typescript-eslint/no-explicit-any
   render: ({ withLayer, layer, ...args }: any) => <Loader {...args} />,
 };
 
+/**
+ * Animated — excluded from visual regression, same as `Default`; this one
+ * additionally demonstrates rendering inside a `layer={2}` context.
+ */
 export const LayerTwoOval: Story = {
   args: {
     variant: "oval",

package/src/components/Loader/Loader.tsx

@@ -12,7 +12,13 @@ export type LoaderProps = RecursicaOverStyled<
 >;
 
 export const Loader = forwardRef<HTMLSpanElement, LoaderProps>(function Loader(
-  { variant = "oval", size = "default", overStyled = false, ...rest },
+  {
+    variant = "oval",
+    size = "default",
+    animate = true,
+    overStyled = false,
+    ...rest
+  },
   ref,
 ) {
   const mapSize = {
@@ -54,6 +60,7 @@ export const Loader = forwardRef<HTMLSpanElement, LoaderProps>(function Loader(
       ref={ref}
       data-variant={variant}
       data-size={resolvedSize}
+      data-animate={animate}
       {...sanitizedProps}
       className={finalClass}
     >

package/src/components/Table/TABLE_IMPLEMENTATION_NOTES.md

@@ -55,6 +55,17 @@ than Mantine's. `Table.module.css` resets `.row:global(.Mui-selected)` to
 `background-color: transparent` so only the Recursica token color shows — same
 override-the-library's-own-styling rule the canonical guide documents for hover.
 
+## Currency alignment on header/footer reuses the table-cell token
+
+`--recursica_ui-kit_components_table-cell_properties_currency-style_text-align` (`right`) is the
+only currency-style text-align token the UI Kit exports — there's no
+`table-header_properties_currency-style_*` block at all, and the
+`table-footer_properties_currency-style_*` block skips `text-align` specifically.
+`Table.module.css` reuses the table-cell token for both `thead .cell[data-currency="true"]` and
+`tfoot .cell[data-currency="true"]` so header/footer currency cells stay right-aligned in step
+with the body. `Table.Cell` already threads `variant`/`data-currency` through regardless of
+context, so no `Table.tsx` change was needed here (unlike `mantine-adapter`'s `Table.Th`).
+
 ## Selectable rows (checkboxes)
 
 See `mantine-adapter`'s `TABLE_IMPLEMENTATION_NOTES.md` — confirmed 2026-08-22 that neither

package/src/components/Table/Table.module.css

@@ -225,6 +225,15 @@
   );
 }
 
+/* Currency column header alignment override. No dedicated table-header currency-style token
+   exists yet, so this reuses the table-cell currency-style text-align token to match the
+   currency value cells below it. */
+.root thead .cell[data-currency="true"] {
+  text-align: var(
+    --recursica_ui-kit_components_table-cell_properties_currency-style_text-align
+  );
+}
+
 /* Sort label — MUI's TableSortLabel renders its own arrow icon; re-color it to inherit the
    cell's own text color (instead of MUI's default sort-label color) and size/space it with the
    same tokens Mantine's own inline chevron uses. */
@@ -425,6 +434,11 @@
   line-height: var(
     --recursica_ui-kit_components_table-footer_properties_currency-style_line-height
   );
+  /* No table-footer currency-style text-align token exists yet; reuse the table-cell one so
+     footer currency cells match the body's right alignment. */
+  text-align: var(
+    --recursica_ui-kit_components_table-cell_properties_currency-style_text-align
+  );
   text-decoration: var(
     --recursica_ui-kit_components_table-footer_properties_currency-style_text-decoration
   );

package/src/components/Table/Table.stories.tsx

@@ -128,7 +128,7 @@ export const CurrencyColumnWithFooter: Story = {
           <Table.Head>
             <Table.Row>
               <Table.Cell>Item</Table.Cell>
-              <Table.Cell>Price</Table.Cell>
+              <Table.Cell variant="currency">Price</Table.Cell>
             </Table.Row>
           </Table.Head>
           <Table.Body>

package/src/components/Table/USAGE.md

@@ -45,14 +45,14 @@ export default function Demo() {
 ## 3. Row and Cell States
 
 - **`Table.Row`**: `selected` applies the selected-row background (and MUI's own `selected`/`aria-selected`); `disabled` dims the row and applies the disabled cell colors to every cell in it.
-- **`Table.Cell`**: `sorted="asc" | "desc"` applies the sorted header style (pair with `Table.SortLabel` for the actual sort icon — see below); `variant="currency"` applies the currency text style; `disabled` dims the cell.
+- **`Table.Cell`**: `sorted="asc" | "desc"` applies the sorted header style (pair with `Table.SortLabel` for the actual sort icon — see below); `variant="currency"` applies the currency text style, right-aligning it in any context (header, body, or footer); `disabled` dims the cell.
 - **`Table.SortLabel`** (wraps MUI's `TableSortLabel`): renders the actual sort arrow. Compose it inside a `Table.Cell` the same way MUI's own docs do.
 
 ```tsx
 <Table.Head>
   <Table.Row>
     <Table.Cell>Name</Table.Cell>
-    <Table.Cell sorted="asc">
+    <Table.Cell sorted="asc" variant="currency">
       <Table.SortLabel active direction="asc">
         Balance
       </Table.SortLabel>