@recursica/mui-adapter 0.28.0 → 0.30.0

package/package.json

@@ -13,7 +13,7 @@
     "url": "git+https://github.com/borderux/recursica.git",
     "directory": "packages/mui-adapter"
   },
-  "version": "0.28.0",
+  "version": "0.30.0",
   "publishConfig": {
     "access": "public"
   },
@@ -102,8 +102,8 @@
     "vitest": "^3.2.4"
   },
   "dependencies": {
-    "@recursica/adapter-common": "*",
-    "@recursica/official-release": "*",
+    "@recursica/adapter-common": "^0.21.0",
+    "@recursica/official-release": "^2.8.0",
     "dayjs": "^1.11.21"
   },
   "peerDependencies": {

package/src/components/Accordion/Accordion.tsx

@@ -43,7 +43,12 @@ const AccordionContext = createContext<{
 
 // ==== ACCORDION CONTAINER ====
 export type AccordionProps = RecursicaOverStyled<
-  React.HTMLAttributes<HTMLDivElement> & RecursicaAccordionProps
+  React.HTMLAttributes<HTMLDivElement> &
+    RecursicaAccordionProps & {
+      // MUI has no native multi-panel accordion group to match (its own `Accordion` is a
+      // single controlled item) — this signature is Recursica's own, same as TransferList.
+      onChange?: (value: string | string[] | null) => void;
+    }
 >;
 
 const AccordionBase = forwardRef<HTMLDivElement, AccordionProps>(

package/src/components/Checkbox/CheckboxGroup.tsx

@@ -36,7 +36,11 @@ export interface RecursicaCheckboxGroupProps
       | "defaultValue"
     >,
     ReadOnlyControlProps,
-    BaseRecursicaCheckboxGroupProps {}
+    BaseRecursicaCheckboxGroupProps {
+  // MUI has no native checkbox-group concept to match (its own `FormGroup` is layout-only,
+  // no value/onChange) — this signature is Recursica's own, same as TransferList/Accordion.
+  onChange?: (value: unknown[]) => void;
+}
 
 export type CheckboxGroupProps =
   RecursicaOverStyled<RecursicaCheckboxGroupProps>;
@@ -72,7 +76,6 @@ export const CheckboxGroup = forwardRef<HTMLDivElement, CheckboxGroupProps>(
       value,
       defaultValue,
       onChange,
-      row,
       ...rest
     } = props;
     // NOTE: this component's props surface (HTMLAttributes<HTMLDivElement>-based) has no native
@@ -125,7 +128,6 @@ export const CheckboxGroup = forwardRef<HTMLDivElement, CheckboxGroupProps>(
           >
             <MuiFormGroup
               ref={ref}
-              row={row}
               {...(sanitizedProps as any)}
               className={`${styles.groupRoot} ${(sanitizedProps as any).className || ""}`.trim()}
               data-layout={formLayout}

package/src/components/Chip/CHIP_IMPLEMENTATION_NOTES.md

@@ -44,7 +44,7 @@ a child span directly (which is exactly what happens once you `.focus()` the rem
 imperatively, as `FileUpload`'s roving-tabindex group does below). A plain `<span>` also gets no
 native Enter/Space-triggers-click behavior the way a real `<button>` would. Fixed by adding
 `role="button"`, `aria-label={removeLabel}`, and an explicit `onKeyDown` for `Enter`/`Space` that
-calls `onRemove` directly — matching the mantine-adapter `Chip`'s remove icon, which already did all
+calls `onDelete` directly — matching the mantine-adapter `Chip`'s remove icon, which already did all
 three.
 
 ### Roving tabindex support for chip groups (Matt Massey, 2026-08-17)
@@ -83,11 +83,11 @@ string size variants (`sm`/`md`/`lg`), so `size` is omitted from `RecursicaChipP
 
 ### A non-interactive chip still looked clickable, and had a phantom Tab stop (Matt Massey, 2026-08-18)
 
-A `Chip` with no `onRemove`/`onClick`/`onChange` (e.g. `FileUpload`'s `readOnly` file list) still
+A `Chip` with no `onDelete`/`onClick`/`onChange` (e.g. `FileUpload`'s `readOnly` file list) still
 showed a pointer cursor on hover — `.root.root` hardcoded `cursor: pointer` unconditionally, with
 no notion of whether the chip actually did anything. Added an `isInteractive` check (mirroring the
 one added to mantine-adapter's `Chip`, see its `CHIP_IMPLEMENTATION_NOTES.md`) based on
-`onRemove`/`onClick`/`onChange` — this adapter's `Chip` has no `checked`-driven native-input case to
+`onDelete`/`onClick`/`onChange` — this adapter's `Chip` has no `checked`-driven native-input case to
 misread the way Mantine's did, since MUI's `Chip` has no real underlying form control. A new
 `data-interactive` attribute (set from `isInteractive`) gates `cursor: pointer` in CSS; without it,
 the chip falls back to whatever MUI's own non-clickable `Chip` renders as (no cursor override, no

package/src/components/Chip/Chip.module.css

@@ -63,7 +63,7 @@
   transition: all 0.2s ease;
 }
 
-/* Only a chip with a real handler (onRemove/onClick/onChange — see Chip.tsx's `isInteractive`)
+/* Only a chip with a real handler (onDelete/onClick/onChange — see Chip.tsx's `isInteractive`)
    gets the pointer cursor. A display-only chip (e.g. a read-only FileUpload file list) has
    nothing for a click to do, so it shouldn't look clickable. */
 .root.root[data-interactive] {
@@ -235,11 +235,11 @@
 
 /* Doubled selector for specificity parity with MUI's own compound
    `.MuiChip-root .MuiChip-deleteIcon` rule (same reasoning as .leadingIcon). */
-.removeIconWrapper.removeIconWrapper {
+.deleteIconWrapper.deleteIconWrapper {
   display: inline-flex;
   align-items: center;
   justify-content: center;
-  flex-shrink: 0; /* HARDCODE: keep the remove icon visible when the label truncates instead */
+  flex-shrink: 0; /* HARDCODE: keep the delete icon visible when the label truncates instead */
   color: var(--chip-close);
   width: var(--recursica_ui-kit_components_chip_properties_close-icon-size);
   height: var(--recursica_ui-kit_components_chip_properties_close-icon-size);
@@ -250,7 +250,7 @@
   margin: 0;
 }
 
-.removeIconWrapper.removeIconWrapper:focus-visible {
+.deleteIconWrapper.deleteIconWrapper:focus-visible {
   box-shadow:
     0 0 0 var(--recursica_brand_states_focus_border-size)
       var(--recursica_brand_states_focus_color),
@@ -259,7 +259,7 @@
       var(--recursica_brand_states_focus_color);
 }
 
-.removeIconWrapper svg {
+.deleteIconWrapper svg {
   width: 100%;
   height: 100%;
 }

package/src/components/Chip/Chip.stories.tsx

@@ -12,7 +12,7 @@ const meta: Meta<ChipStoryProps> = {
     docs: {
       description: {
         component:
-          "The Chip component is used to represent interactive selections, descriptive tags, or dynamic filters natively bounded to Recursica variables. It can be used as a toggleable input, can render a custom leading `icon`, and handles close constraints automatically via the `onRemove` property.",
+          "The Chip component is used to represent interactive selections, descriptive tags, or dynamic filters natively bounded to Recursica variables. It can be used as a toggleable input, can render a custom leading `icon`, and handles close constraints automatically via the `onDelete` property.",
       },
     },
   },
@@ -86,7 +86,7 @@ export const Removable: Story = {
   args: {
     children: "Dismissible",
     checked: false,
-    onRemove: () => console.log("Removal Action Triggered"),
+    onDelete: () => console.log("Removal Action Triggered"),
   },
   render: (args: ChipStoryProps) => <Chip {...args} />,
 };

package/src/components/Chip/Chip.tsx

@@ -62,10 +62,10 @@ export const Chip = forwardRef<HTMLInputElement, ChipProps>(function Chip(
   {
     error = false,
     icon,
-    onRemove,
-    removeLabel = "Remove",
-    removeTabIndex,
-    removeIconRef,
+    onDelete,
+    deleteLabel = "Delete",
+    deleteTabIndex,
+    deleteIconRef,
     children,
     checked,
     overStyled = false,
@@ -83,7 +83,7 @@ export const Chip = forwardRef<HTMLInputElement, ChipProps>(function Chip(
       root: styles.root,
       label: styles.label,
       icon: styles.leadingIcon,
-      deleteIcon: styles.removeIconWrapper,
+      deleteIcon: styles.deleteIconWrapper,
     },
     restRecord.classes as Partial<Record<string, string>> | undefined,
   );
@@ -96,13 +96,13 @@ export const Chip = forwardRef<HTMLInputElement, ChipProps>(function Chip(
   // Determine state
   const dataError = error ? "" : undefined;
   const dataChecked = checked ? "" : undefined;
-  const isIconOnly = !children && (!!icon || !!onRemove);
+  const isIconOnly = !children && (!!icon || !!onDelete);
   // A chip only counts as interactive when something actually responds to it — merely passing a
   // `checked` value (e.g. to pin a display-only chip to a fixed visual state, as FileUpload's
   // read-only file list does) isn't itself an interaction, since clicking it with no onChange/
   // onClick wired does nothing observable.
   const isInteractive =
-    onRemove !== undefined ||
+    onDelete !== undefined ||
     restRecord.onClick !== undefined ||
     restRecord.onChange !== undefined;
 
@@ -127,25 +127,26 @@ export const Chip = forwardRef<HTMLInputElement, ChipProps>(function Chip(
           </span>
         ) : undefined
       }
-      onDelete={onRemove}
+      onDelete={onDelete}
       deleteIcon={
-        onRemove ? (
+        onDelete ? (
           <span
-            ref={removeIconRef}
+            ref={deleteIconRef}
             role="button"
-            className={styles.removeIconWrapper}
-            aria-label={removeLabel}
-            tabIndex={removeTabIndex ?? 0}
+            className={styles.deleteIconWrapper}
+            aria-label={deleteLabel}
+            tabIndex={deleteTabIndex ?? 0}
             onKeyDown={(e) => {
-              // MUI's own `onDelete` wiring only reacts to Backspace/Delete, and only when this
-              // span itself is both the event's target and currentTarget — neither holds once a
-              // parent (e.g. FileUpload's roving-tabindex group) moves real focus onto this span
-              // directly. A plain `<span>` also gets no native Enter/Space-triggers-click behavior
-              // the way a real `<button>` would, so it's handled explicitly here instead.
+              // MUI's native `onDelete` wiring (distinct from our own `onDelete` prop above) only
+              // reacts to Backspace/Delete, and only when this span itself is both the event's
+              // target and currentTarget — neither holds once a parent (e.g. FileUpload's
+              // roving-tabindex group) moves real focus onto this span directly. A plain `<span>`
+              // also gets no native Enter/Space-triggers-click behavior the way a real `<button>`
+              // would, so it's handled explicitly here instead.
               if (e.key === "Enter" || e.key === " ") {
                 e.preventDefault();
                 e.stopPropagation();
-                onRemove(
+                onDelete(
                   e as unknown as React.MouseEvent<HTMLSpanElement, MouseEvent>,
                 );
               }

package/src/components/Chip/USAGE.md

@@ -45,11 +45,11 @@ Chip does not support a `size` prop; chips render at a fixed size.
 
 ### Building a keyboard-navigable chip group
 
-`removeTabIndex` and `removeIconRef` are optional escape hatches for composing a _group_ of chips
+`deleteTabIndex` and `deleteIconRef` are optional escape hatches for composing a _group_ of chips
 with roving-tabindex keyboard navigation (Tab reaches one chip at a time, arrow keys move between
 them) — see `FileUpload`'s file list for a working example. Ignore both for a standalone chip; they
-default to a normal `tabIndex={0}` remove icon with no ref.
+default to a normal `tabIndex={0}` delete icon with no ref.
 
 Also pass a plain `tabIndex={-1}` on the `<Chip>` itself in a group like this — MUI's `Chip` root
-becomes a focusable element on its own whenever `onRemove` is set, which would otherwise be a
-second, unwanted tab stop ahead of the remove icon (see `CHIP_IMPLEMENTATION_NOTES.md`).
+becomes a focusable element on its own whenever `onDelete` is set, which would otherwise be a
+second, unwanted tab stop ahead of the delete icon (see `CHIP_IMPLEMENTATION_NOTES.md`).

package/src/components/FileInput/FILEINPUT_IMPLEMENTATION_NOTES.md

@@ -20,7 +20,7 @@ The control is one clickable, focusable `<div role="button">` containing:
    single- and multiple-file mode render identically here; only the selection/replace behavior
    differs (see "`multiple` defaults to `false`" below).
 3. **A trailing "clear" `Button`** — shown whenever a file is selected; clears the entire current
-   selection (see "Trailing clear button" below).
+   selection, icon overridable via `clearIcon` (see "Trailing clear button" below).
 4. **A hidden `<input type="file">`**, triggered programmatically — same approach as
    `FileUpload`'s dropzone, not the "invisible overlay input" pattern some styled file inputs use
    (that pattern would need every interactive child — chip remove icons, the clear icon — to sit
@@ -107,7 +107,9 @@ color/disabled states, so `file-input`'s own `properties_colors_trailing-icon` t
 entirely. Clicking/activating it calls `onFileRemove` once per currently-selected file (reusing
 the same callback `FileUpload`'s individual chip removal uses, rather than introducing a separate
 `onClear` prop) — in single-file mode that's one call; in multiple-file mode it clears everything
-at once, distinct from a chip's own individual remove icon.
+at once, distinct from a chip's own individual remove icon. The icon itself defaults to the
+built-in X glyph and is overridable via `clearIcon` — the same pattern as the leading `icon`,
+giving Forge's `leading-icon`/`trailing-icon` token pair a matching pair of override props.
 
 ## Why each chip is wrapped with its own `stopPropagation`
 
@@ -140,7 +142,7 @@ already made for `.value`'s ellipsis truncation.
 
 `readOnly` renders the same content (placeholder/filename/chip row) but the root loses its
 `role="button"` interactivity (no `tabIndex`, no click/keyboard/drag handlers), chips render with
-no `removeLabel`/`onRemove` (so `Chip` itself renders no remove icon, same as `FileUpload`'s
+no `removeLabel`/`onDelete` (so `Chip` itself renders no remove icon, same as `FileUpload`'s
 read-only chips), and the trailing clear icon is omitted entirely. `disabled` keeps the control
 structurally the same but inert (`tabIndex={-1}`, `aria-disabled`, no handlers, native `<input>`
 disabled) — both are computed together as a single `interactive` flag used throughout, but remain

package/src/components/FileInput/FileInput.stories.tsx

@@ -63,6 +63,9 @@ The \`FileInput\` component is a single-line, \`TextField\`-shaped control for c
     icon: {
       table: { disable: true },
     },
+    clearIcon: {
+      table: { disable: true },
+    },
     files: {
       table: { disable: true },
     },

package/src/components/FileInput/FileInput.tsx

@@ -124,6 +124,7 @@ export const FileInput = forwardRef<HTMLDivElement, FileInputProps>(
         ? `Maximum of ${maxFiles} files allowed`
         : "Only one file is allowed",
       icon,
+      clearIcon,
       placeholder = "Select a file...",
       browseLabel = "Choose file",
       removeFileLabel = "Remove",
@@ -234,10 +235,10 @@ export const FileInput = forwardRef<HTMLDivElement, FileInputProps>(
     };
 
     // Roving tabindex across the file chip list (single- or multiple-file mode): only the
-    // "active" chip's remove icon is a tab stop, and Left/Right/Up/Down move it — same pattern
+    // "active" chip's delete icon is a tab stop, and Left/Right/Up/Down move it — same pattern
     // as FileUpload, see FILEINPUT_IMPLEMENTATION_NOTES.md.
     const [activeChipIndex, setActiveChipIndex] = useState(0);
-    const removeIconRefs = useRef<Array<HTMLSpanElement | null>>([]);
+    const deleteIconRefs = useRef<Array<HTMLSpanElement | null>>([]);
     const prevFileCountRef = useRef(files?.length ?? 0);
 
     useEffect(() => {
@@ -245,7 +246,7 @@ export const FileInput = forwardRef<HTMLDivElement, FileInputProps>(
       if (count > 0 && count < prevFileCountRef.current) {
         const nextIndex = Math.min(activeChipIndex, count - 1);
         setActiveChipIndex(nextIndex);
-        removeIconRefs.current[nextIndex]?.focus();
+        deleteIconRefs.current[nextIndex]?.focus();
       }
       prevFileCountRef.current = count;
       // Only react to the file list itself shrinking/growing, not to activeChipIndex changes.
@@ -267,7 +268,7 @@ export const FileInput = forwardRef<HTMLDivElement, FileInputProps>(
       event.preventDefault();
       event.stopPropagation();
       setActiveChipIndex(nextIndex);
-      removeIconRefs.current[nextIndex]?.focus();
+      deleteIconRefs.current[nextIndex]?.focus();
     };
 
     // The built-in `accept`/cap-mismatch message is only shown when the integrator hasn't
@@ -351,14 +352,14 @@ export const FileInput = forwardRef<HTMLDivElement, FileInputProps>(
                     >
                       <Chip
                         tabIndex={-1}
-                        removeLabel={readOnly ? undefined : removeFileLabel}
-                        removeTabIndex={
+                        deleteLabel={readOnly ? undefined : removeFileLabel}
+                        deleteTabIndex={
                           !readOnly && index === activeChipIndex ? 0 : -1
                         }
-                        removeIconRef={(el) => {
-                          removeIconRefs.current[index] = el;
+                        deleteIconRef={(el) => {
+                          deleteIconRefs.current[index] = el;
                         }}
-                        onRemove={
+                        onDelete={
                           readOnly || disabled
                             ? undefined
                             : () => onFileRemove?.(itemId)
@@ -378,7 +379,7 @@ export const FileInput = forwardRef<HTMLDivElement, FileInputProps>(
               overStyled
               variant="text"
               size="small"
-              icon={<ClearIcon />}
+              icon={clearIcon ?? <ClearIcon />}
               aria-label={clearLabel}
               className={styles.trailingIcon}
               disabled={disabled}

package/src/components/FileInput/USAGE.md

@@ -57,6 +57,7 @@ rather than appending — picking a new file in single-file mode always replaces
 | `invalidFileTypeMessage` | `React.ReactNode`           | Error message shown when a file is rejected for not matching `accept`. Defaults to `"File type not accepted"`. An explicit `error` prop always takes priority over this.                                                             |
 | `maxFilesMessage`        | `React.ReactNode`           | Error message shown when a file is rejected for exceeding the cap. Defaults to `"Maximum of {maxFiles} files allowed"` when `multiple`, or `"Only one file is allowed"` otherwise. An explicit `error` prop always wins.             |
 | `icon`                   | `React.ReactNode`           | Leading icon shown inside the control. Defaults to the built-in upload icon.                                                                                                                                                         |
+| `clearIcon`              | `React.ReactNode`           | Trailing clear-all icon shown once a file is selected. Defaults to the built-in X icon.                                                                                                                                              |
 | `placeholder`            | `React.ReactNode`           | Text shown when no file is selected. Defaults to `"Select a file..."`.                                                                                                                                                               |
 | `browseLabel`            | `string`                    | Screen-reader label for the control itself (it's the sole interactive/focusable surface, there being no separate "Browse" button). Defaults to `"Choose file"`.                                                                      |
 | `removeFileLabel`        | `string`                    | Screen-reader label for a file chip's remove button. Defaults to `"Remove"`.                                                                                                                                                         |

package/src/components/FileUpload/FILEUPLOAD_IMPLEMENTATION_NOTES.md

@@ -10,7 +10,7 @@ core or as a separate package). The component composes:
    (`onDragOver`/`onDrop`), containing an upload icon, instructional text, and a hidden
    `<input type="file">` triggered by...
 2. **The browse button** — this adapter's own `<Button variant="outline" size="small">`.
-3. **The file list** — this adapter's own `<Chip>` component (with `onRemove`), one per entry in
+3. **The file list** — this adapter's own `<Chip>` component (with `onDelete`), one per entry in
    the controlled `files` prop.
 
 This shape is **not configurable** — there is no prop to render a bare native file input without
@@ -37,7 +37,7 @@ change (the runtime already accepted arbitrary `children`). (Matt Massey, 2026-0
 (spacing between/around file entries) but **no color/border tokens of its own for the file
 entries themselves** — the visual design intentionally delegates that to the existing `Chip`
 component's own token namespace (`--recursica_ui-kit_components_chip_...`). Reusing `<Chip
-onRemove={...}>` directly (rather than reimplementing a similar-looking element) keeps that
+onDelete={...}>` directly (rather than reimplementing a similar-looking element) keeps that
 separation intact per the canonical guide's "Component Specificity" rule — `FileUpload.module.css`
 never reaches into `chip`'s namespace, and `Chip.module.css` never reaches into `file-upload`'s.
 
@@ -105,9 +105,9 @@ list's read-only form is the same chip list, just without the ability to remove
 `readOnly` is handled directly in `FileUpload.tsx` rather than reusing `WithReadOnlyWrapper`:
 
 - The dropzone (icon, instructional text, Browse button, hidden `<input>`) is omitted entirely.
-- Each `Chip` is rendered with no `onRemove` (and no `removeTabIndex`/`removeIconRef`/roving
+- Each `Chip` is rendered with no `onDelete` (and no `removeTabIndex`/`removeIconRef`/roving
   keyboard handlers, which only exist to manage the remove icon) — `Chip` itself already renders no
-  `deleteIcon` at all when `onRemove` is `undefined`, so this falls out for free rather than needing
+  `deleteIcon` at all when `onDelete` is `undefined`, so this falls out for free rather than needing
   a separate `readOnly` prop on `Chip`. (It also means MUI's own `ButtonBase`-on-`onDelete` quirk —
   see the keyboard-navigation section below — never triggers in read-only mode either.)
 - `disabled` is independent of `readOnly` and has no effect when `readOnly` is set (there's no
@@ -225,7 +225,7 @@ triggers both.
 ## Read-only chips were still interactive (Matt Massey, 2026-08-18)
 
 The `readOnly` file list (added 2026-08-18, see USAGE.md §7) rendered each filename as a
-`<Chip tabIndex={-1}>` with no `onRemove`, expecting that to be fully inert. It wasn't, because of
+`<Chip tabIndex={-1}>` with no `onDelete`, expecting that to be fully inert. It wasn't, because of
 a bug shared with the Mantine adapter that lives entirely in `Chip`/`Chip.module.css`, not
 `FileUpload` — see the Mantine adapter's `FILEUPLOAD_IMPLEMENTATION_NOTES.md` for the parallel
 write-up. The MUI-specific pieces:
@@ -233,7 +233,7 @@ write-up. The MUI-specific pieces:
 - **The chip's cursor still showed `pointer` on hover with no real interaction wired.** `.root.root`
   hardcoded `cursor: pointer` unconditionally — unlike Mantine, this wasn't inherited from MUI's own
   base styles, just a pre-existing hardcode here that never accounted for a non-interactive chip.
-  Added an `isInteractive` check to `Chip.tsx` (`onRemove`/`onClick`/`onChange` — MUI's `Chip` has
+  Added an `isInteractive` check to `Chip.tsx` (`onDelete`/`onClick`/`onChange` — MUI's `Chip` has
   no `checked`-driven native-input case to misread, unlike Mantine's) and a `data-interactive`
   attribute that gates `cursor: pointer` in CSS; a chip with none of those handlers now falls back
   to whatever MUI's own un-clickable `Chip` renders as (no cursor override, no `ButtonBase`).

package/src/components/FileUpload/FileUpload.tsx

@@ -193,11 +193,11 @@ export const FileUpload = forwardRef<HTMLDivElement, FileUploadProps>(
       event.target.value = "";
     };
 
-    // Roving tabindex across the file chip list: only the "active" chip's remove icon is a tab
+    // Roving tabindex across the file chip list: only the "active" chip's delete icon is a tab
     // stop (Tab lands on the first chip), and Left/Right/Up/Down move it — see
     // FILEUPLOAD_IMPLEMENTATION_NOTES.md.
     const [activeChipIndex, setActiveChipIndex] = useState(0);
-    const removeIconRefs = useRef<Array<HTMLSpanElement | null>>([]);
+    const deleteIconRefs = useRef<Array<HTMLSpanElement | null>>([]);
     const prevFileCountRef = useRef(files?.length ?? 0);
 
     useEffect(() => {
@@ -207,7 +207,7 @@ export const FileUpload = forwardRef<HTMLDivElement, FileUploadProps>(
       if (count > 0 && count < prevFileCountRef.current) {
         const nextIndex = Math.min(activeChipIndex, count - 1);
         setActiveChipIndex(nextIndex);
-        removeIconRefs.current[nextIndex]?.focus();
+        deleteIconRefs.current[nextIndex]?.focus();
       }
       prevFileCountRef.current = count;
       // Only react to the file list itself shrinking/growing, not to activeChipIndex changes.
@@ -228,7 +228,7 @@ export const FileUpload = forwardRef<HTMLDivElement, FileUploadProps>(
       if (nextIndex === undefined) return;
       event.preventDefault();
       setActiveChipIndex(nextIndex);
-      removeIconRefs.current[nextIndex]?.focus();
+      deleteIconRefs.current[nextIndex]?.focus();
     };
 
     // The built-in `accept`-mismatch message is only shown when the integrator hasn't supplied
@@ -328,12 +328,12 @@ export const FileUpload = forwardRef<HTMLDivElement, FileUploadProps>(
                     <Chip
                       key={itemId}
                       tabIndex={-1}
-                      removeLabel={removeFileLabel}
-                      removeTabIndex={index === activeChipIndex ? 0 : -1}
-                      removeIconRef={(el) => {
-                        removeIconRefs.current[index] = el;
+                      deleteLabel={removeFileLabel}
+                      deleteTabIndex={index === activeChipIndex ? 0 : -1}
+                      deleteIconRef={(el) => {
+                        deleteIconRefs.current[index] = el;
                       }}
-                      onRemove={
+                      onDelete={
                         disabled ? undefined : () => onFileRemove?.(itemId)
                       }
                     >

package/src/components/Link/Link.module.css

@@ -51,6 +51,10 @@ HARDCODED VALUES:
   );
 }
 
+.root:hover {
+  text-decoration: var(--recursica_brand_states_link_decoration);
+}
+
 /* Icon Support */
 .iconWrapper {
   /* HARDCODE: maintain intrinsic icon bounds */

package/src/components/Radio/RadioGroup.stories.tsx

@@ -44,7 +44,7 @@ export const Default: Story = {
   render: function StoryRender({ withLayer, layer, ...args }: any) {
     const [value, setValue] = useState<string>("");
     return (
-      <RadioGroup {...args} value={value} onChange={setValue}>
+      <RadioGroup {...args} value={value} onChange={(_e, val) => setValue(val)}>
         <Radio value="1" label="Option 1" />
         <Radio value="2" label="Option 2" />
       </RadioGroup>
@@ -63,7 +63,7 @@ export const StackedLayout: Story = {
   render: function StoryRender({ withLayer, layer, ...args }: any) {
     const [value, setValue] = useState<string>("aws");
     return (
-      <RadioGroup {...args} value={value} onChange={setValue}>
+      <RadioGroup {...args} value={value} onChange={(_e, val) => setValue(val)}>
         <Radio value="aws" label="Amazon Web Services" />
         <Radio
           value="gcp"
@@ -87,7 +87,7 @@ export const SideBySideLayout: Story = {
   render: function StoryRender({ withLayer, layer, ...args }: any) {
     const [value, setValue] = useState<string>("us-east");
     return (
-      <RadioGroup {...args} value={value} onChange={setValue}>
+      <RadioGroup {...args} value={value} onChange={(_e, val) => setValue(val)}>
         <Radio value="us-east" label="US East (N. Virginia)" />
         <Radio value="us-west" label="US West (Oregon)" />
         <Radio value="eu-central" label="EU Central (Frankfurt)" />
@@ -108,7 +108,7 @@ export const ReadOnly: Story = {
   render: function StoryRender({ withLayer, layer, ...args }: any) {
     const [value, setValue] = useState<string>("react");
     return (
-      <RadioGroup {...args} value={value} onChange={setValue}>
+      <RadioGroup {...args} value={value} onChange={(_e, val) => setValue(val)}>
         <Radio value="react" label="React" />
         <Radio value="vue" label="Vue" />
       </RadioGroup>

package/src/components/Radio/RadioGroup.tsx

@@ -18,13 +18,7 @@ import { type RecursicaRadioGroupProps as BaseRecursicaRadioGroupProps } from "@
 export interface RecursicaRadioGroupProps
   extends Omit<
       MuiRadioGroupProps,
-      | "size"
-      | "labelProps"
-      | "classes"
-      | "ref"
-      | "onChange"
-      | "value"
-      | "defaultValue"
+      "size" | "labelProps" | "classes" | "ref" | "value" | "defaultValue"
     >,
     Omit<
       RecursicaFormControlWrapperProps,
@@ -70,7 +64,6 @@ export const RadioGroup = forwardRef<HTMLDivElement, RadioGroupProps>(
       emptyValueComponent,
       value,
       defaultValue,
-      onChange,
       ...rest
     } = props;
     // NOTE: MuiRadioGroupProps (via FormGroupProps) has no native "size" (or other
@@ -111,10 +104,6 @@ export const RadioGroup = forwardRef<HTMLDivElement, RadioGroupProps>(
             {...(sanitizedProps as unknown as MuiRadioGroupProps)}
             value={value}
             defaultValue={defaultValue}
-            // MUI natively calls onChange(event, value); the Recursica contract is
-            // single-argument (value only), matching Mantine's native RadioGroup
-            // onChange (the cross-adapter source of truth) — normalize here.
-            onChange={onChange ? (_event, val) => onChange(val) : undefined}
             className={styles.groupRoot}
             data-layout={formLayout}
           >

package/src/components/SegmentedControl/IMPLEMENTATION_NOTES.md

@@ -4,3 +4,11 @@
 
 - **Root cause:** `--recursica_ui-kit_components_segmented-control-item_variants_selection-states_{unselected,selected}_properties_text_text-transform` resolves to `--recursica_tokens_font_cases_original`, which has no definition in `recursica_variables_scoped.css` (only `_lowercase`/`_titlecase`/`_uppercase` are defined there). The resulting `var()` on `.label` is invalid, and since `text-transform` is an inherited property, the invalid value falls back to the inherited value from `.control` (`.MuiToggleButton-root`) — which carries MUI's own `text-transform: uppercase` button default. Mantine's control has no such native uppercase default, so the same broken token never surfaced there.
 - **Fix:** Reset `text-transform: none` on `.root .control` alongside the other MUI ToggleButton baseline resets (padding/border/etc.) already there, so nothing uppercase is left to inherit. Matches the existing `text-transform: none` MUI-baseline reset pattern in `Button.module.css`. Not a design-token value — it's a structural reset of MUI's own default, same category as the other hardcoded resets already exempted at the top of this file.
+
+## Per-item `icon`
+
+`RecursicaSegmentedControlProps.data` objects accept an optional `icon`, rendered ahead of `label` inside the existing `.label` div (already a flex container with the icon-size/gap tokens wired), so no CSS changes were needed.
+
+## Whole-control `disabled`
+
+`RecursicaSegmentedControlProps.disabled` was previously typed `never` and stripped at runtime. It's now a real `boolean?`, passed straight through to MUI's native `ToggleButtonGroup.disabled`, which cascades to every child `ToggleButton` via `ToggleButtonGroupContext`. Per-item `data[].disabled` now passes `undefined` (not `false`) when unset, so it doesn't mask that context cascade — an item's own explicit `disabled` still overrides the group.

package/src/components/SegmentedControl/SegmentedControl.stories.tsx

@@ -21,7 +21,9 @@ const meta: Meta<typeof SegmentedControl> = {
     fullWidth: {
       control: "boolean",
     },
-    disabled: { table: { disable: true } },
+    disabled: {
+      control: "boolean",
+    },
     data: { table: { disable: true } },
     defaultChecked: { table: { disable: true } },
   },
@@ -64,6 +66,17 @@ export const Vertical: Story = {
   },
 };
 
+export const Disabled: Story = {
+  args: {
+    data: ["Preview", "Code", "Edit"],
+    disabled: true,
+  },
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any, @typescript-eslint/no-unused-vars
+  render: ({ withLayer, layer, ...args }: any) => {
+    return <SegmentedControl {...args} />;
+  },
+};
+
 const CheckIcon = () => (
   <svg
     viewBox="0 0 24 24"
@@ -81,33 +94,9 @@ const CheckIcon = () => (
 export const WithIcons: Story = {
   args: {
     data: [
-      {
-        value: "daily",
-        label: (
-          <>
-            <CheckIcon />
-            <span>Daily</span>
-          </>
-        ),
-      },
-      {
-        value: "weekly",
-        label: (
-          <>
-            <CheckIcon />
-            <span>Weekly</span>
-          </>
-        ),
-      },
-      {
-        value: "monthly",
-        label: (
-          <>
-            <CheckIcon />
-            <span>Monthly</span>
-          </>
-        ),
-      },
+      { value: "daily", label: "Daily", icon: <CheckIcon /> },
+      { value: "weekly", label: "Weekly", icon: <CheckIcon /> },
+      { value: "monthly", label: "Monthly", icon: <CheckIcon /> },
     ],
   },
   // eslint-disable-next-line @typescript-eslint/no-explicit-any, @typescript-eslint/no-unused-vars