@recursica/adapter-mui-v7 1.0.0

package/src/components/Tooltip/Tooltip.stories.tsx

@@ -0,0 +1,165 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { Tooltip, type TooltipProps } from "./Tooltip";
+import { Button } from "../Button";
+
+/**
+ * Tooltip story axes:
+ * - position: tooltip alignment relative to target
+ * - withBeak: beak (arrow) indicator on the tooltip
+ * - openDelay / closeDelay: hover timing controls
+ * - multiline: text wrapping behavior
+ * - disabled: suppress the tooltip entirely
+ * - layer: tested via the global Layer decorator (withLayer/layer args)
+ */
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type TooltipStoryArgs = Record<string, any>;
+
+const meta: Meta = {
+  title: "UI-Kit/Tooltip",
+  component: Tooltip,
+  tags: ["autodocs"],
+  argTypes: {
+    label: {
+      control: "text",
+      description: "Content displayed inside the tooltip.",
+    },
+    position: {
+      control: "select",
+      options: [
+        "bottom",
+        "bottom-start",
+        "bottom-end",
+        "top",
+        "top-start",
+        "top-end",
+        "left",
+        "left-start",
+        "left-end",
+        "right",
+        "right-start",
+        "right-end",
+      ],
+      description: "The position of the tooltip relative to the target.",
+    },
+    withBeak: {
+      control: "boolean",
+      description:
+        "Whether to display a beak (arrow) pointing to the target. Recursica equivalent of Mantine's withArrow.",
+    },
+    offset: {
+      control: "number",
+      description: "Distance in px between the tooltip and the target element.",
+    },
+    openDelay: {
+      control: "number",
+      description: "Delay in ms before the tooltip opens on hover.",
+    },
+    closeDelay: {
+      control: "number",
+      description: "Delay in ms before the tooltip closes when hover ends.",
+    },
+    disabled: {
+      control: "boolean",
+      description: "If set, the tooltip will not be rendered.",
+    },
+    opened: {
+      control: "boolean",
+      description:
+        "Force the tooltip to stay open. Useful for inspecting styling.",
+    },
+    // Hide auto-detected HTML attributes that leak from ElementProps<'div'>
+    defaultChecked: { table: { disable: true } },
+    defaultValue: { table: { disable: true } },
+    suppressContentEditableWarning: { table: { disable: true } },
+    suppressHydrationWarning: { table: { disable: true } },
+  },
+  parameters: {
+    layout: "centered",
+    docs: {
+      description: {
+        component: `
+The \`Tooltip\` component displays a floating label when the user hovers over or focuses a target element. It wraps Mantine's \`Tooltip\` while enforcing strict Recursica design token styling.
+
+### API
+
+Unlike \`HoverCard\`, Tooltip is a single component — content is passed via the \`label\` prop:
+\`\`\`tsx
+<Tooltip label="Helpful text" withBeak>
+  <Button>Hover me</Button>
+</Tooltip>
+\`\`\`
+
+### Static Sub-Components
+- \`Tooltip.Floating\` — A tooltip that follows the cursor position
+- \`Tooltip.Group\` — Groups multiple tooltips to share hover delay
+
+### Key Behaviors
+- The beak (arrow) is shown by default (\`withBeak={true}\`)
+- Supports \`openDelay\` and \`closeDelay\` for timing control
+- Set \`multiline\` to allow text wrapping within max-width
+        `,
+      },
+    },
+  },
+};
+
+export default meta;
+
+type Story = StoryObj<TooltipStoryArgs>;
+
+export const Default: Story = {
+  args: {
+    label: "This is a helpful tooltip",
+    position: "top",
+    withBeak: true,
+    offset: 5,
+    openDelay: 0,
+    closeDelay: 0,
+    disabled: false,
+  },
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  render: ({ withLayer, layer, ...args }: TooltipStoryArgs) => {
+    return (
+      <Tooltip {...(args as TooltipProps)}>
+        <Button variant="solid">Hover me</Button>
+      </Tooltip>
+    );
+  },
+};
+
+export const WithoutBeak: Story = {
+  args: {
+    label: "Tooltip without a beak indicator",
+    position: "top",
+    withBeak: false,
+    offset: 5,
+  },
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  render: ({ withLayer, layer, ...args }: TooltipStoryArgs) => {
+    return (
+      <Tooltip {...(args as TooltipProps)}>
+        <Button variant="outline">Without Beak</Button>
+      </Tooltip>
+    );
+  },
+};
+
+export const LongContent: Story = {
+  args: {
+    label:
+      "This is a longer tooltip message that demonstrates how text wraps within the maximum width defined by the design system.",
+    position: "top",
+    withBeak: true,
+    opened: true,
+    offset: 5,
+  },
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  render: ({ withLayer, layer, ...args }: TooltipStoryArgs) => {
+    return (
+      <Tooltip {...(args as TooltipProps)}>
+        <Button variant="solid">Long Content</Button>
+      </Tooltip>
+    );
+  },
+};

package/src/components/Tooltip/Tooltip.test.tsx

@@ -0,0 +1 @@
+// Placeholder for future Tooltip component tests. Add tests here if/when needed.

package/src/components/Tooltip/Tooltip.tsx

@@ -0,0 +1,78 @@
+import {
+  Tooltip as MuiTooltip,
+  type TooltipProps as MuiTooltipProps,
+} from "@mui/material";
+import {
+  filterStylingProps,
+  mergeClassNames,
+  type RecursicaOverStyled,
+} from "../../utils/filterStylingProps";
+import styles from "./Tooltip.module.css";
+
+// ============================================================
+// TOOLTIP
+// ============================================================
+
+/**
+ * Recursica-specific props for Tooltip.
+ */
+import { type RecursicaTooltipProps } from "@recursica/adapter-common";
+
+/**
+ * Recursica Tooltip component wrapping Mui's Tooltip.
+ *
+ * Displays a floating label when the user hovers over or focuses a target element.
+ * Unlike HoverCard, Tooltip is a single component (not composable) — content is
+ * passed via the `label` prop, and the trigger is passed as `children`.
+ *
+ * ```tsx
+ * <Tooltip label="Helpful information" withBeak>
+ *   <Button>Hover me</Button>
+ * </Tooltip>
+ * ```
+ *
+ * Static sub-components available via dot-notation:
+ * - `// Tooltip.Floating` — Tooltip that follows the cursor
+ * - `// Tooltip.Group` — Shared hover delay group for multiple tooltips
+ */
+export type TooltipProps = RecursicaOverStyled<
+  MuiTooltipProps & RecursicaTooltipProps
+>;
+
+const TooltipBase = function Tooltip({
+  overStyled = false,
+  withBeak = true,
+  label,
+  opened,
+  ...rest
+}: TooltipProps & { label?: React.ReactNode; opened?: boolean }) {
+  const { title, ...restProps } = rest;
+  const sanitizedProps = filterStylingProps(restProps, overStyled);
+
+  // Bind CSS module classes to Mui's internal classNames API. Note MUI's actual prop is
+  // "classes", not "classNames" (that's Mantine's naming) — this used to read the wrong key,
+  // silently no-op-ing any caller-supplied classes.
+  const mergedClassNames = mergeClassNames(
+    {
+      tooltip: styles.tooltip,
+      arrow: styles.arrow,
+    },
+    (sanitizedProps as Record<string, unknown>).classes as
+      | Partial<Record<string, string>>
+      | undefined,
+  );
+
+  return (
+    <MuiTooltip
+      {...(sanitizedProps as unknown as Omit<MuiTooltipProps, "title">)}
+      title={label || title || ""}
+      open={opened}
+      placement="top" /* Recursica default; Mui defaults to "bottom" */
+      arrow={withBeak}
+      classes={mergedClassNames}
+    />
+  );
+};
+TooltipBase.displayName = "Tooltip";
+
+export const Tooltip = TooltipBase;

package/src/components/Tooltip/USAGE.md

@@ -0,0 +1,40 @@
+# Tooltip - Usage Guide
+
+This document describes how to integrate and use the `Tooltip` component in your projects using `@recursica/adapter-mui-v7`.
+
+---
+
+## 1. Import Reference
+
+```tsx
+import { Tooltip } from "@recursica/adapter-mui-v7";
+```
+
+---
+
+## 2. Basic Example
+
+```tsx
+import React from "react";
+import { Tooltip } from "@recursica/adapter-mui-v7";
+
+export default function Demo() {
+  return (
+    <Tooltip label="This is a helpful tooltip">
+      <Button variant="primary">Hover Me</Button>
+    </Tooltip>
+  );
+}
+```
+
+---
+
+## 3. Design System Integration
+
+All Recursica components in the `@recursica/adapter-mui-v7` package adhere strictly to design system spacing, scaling, and behavior patterns.
+
+> [!IMPORTANT]
+>
+> - **Anti-override protection**: Rogues style injections (like inline `style` or arbitrary `className`) are automatically blocked by our prop layer unless `overStyled={true}` is explicitly provided.
+> - **No Direct Layers**: Do not pass a `layer` prop to this component. To place it on a specific visual layer, wrap it in a `<Layer layer={0|1|2|3}>` component natively.
+> - **Variables and Theming**: Styling is entirely determined by local CSS variables defined in `recursica_variables_scoped.css` and mapped in the component's CSS module.

package/src/components/Tooltip/index.ts

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

package/src/components/TransferList/TRANSFERLIST_IMPLEMENTATION_NOTES.md

@@ -0,0 +1,140 @@
+# TransferList Implementation Notes
+
+## Architecture overview
+
+`TransferList` replaces the "coming soon" stub with a fully custom composite — neither
+`@mantine/core` nor `@mui/material` ships a real dual-listbox component (MUI's docs "Transfer
+List" is a List+Checkbox recipe, not a package export), so it's built from Recursica's own
+primitives, the same situation `FileUpload`/`FileInput` were in.
+
+Follows Matt's reference implementation (Forge's fallback `TransferList.tsx`) fairly closely:
+
+- Two side-by-side panes (source/target), each: a header row (pane label + `Badge` count,
+  `"selected / total"` once something's checked), a search `TextField`, then a scrollable list of
+  `Checkbox` rows (`CheckboxGroup` for items carrying a `group` field).
+- A column of four transfer `Button`s between the panes: single/double chevron, each direction —
+  single moves only the checked items in that pane, double moves everything in that pane.
+- Data model: `data`/`defaultData` as a `[sourceItems, targetItems]` tuple + `onChange`, matching
+  Forge's controlled/uncontrolled pattern (same shape as `FileUpload`'s `files`/`onFilesAdded`).
+
+## Routed through `FormControlWrapper` directly, not Forge's hand-rolled label/assistive
+
+Forge's reference renders its own `Label`/`AssistiveElement` directly instead of going through
+`FormControlWrapper`. Per direction, this build uses `FormControlWrapper` instead — consistent
+with every other form control in this codebase (and with `FileUpload`, which was reverted to
+`FormControlWrapper` rather than hand-rolling that same thing). `formLayout`
+(`stacked`/`side-by-side`), `label`, `required`, `assistiveText`/`description`/`helperText`, and
+`error` all come from the standard wrapper; only the two panes + transfer buttons are the
+component's own content.
+
+## `state` axis: `disabled`/`error` props, not Forge's `state` string
+
+Forge's reference takes a single `state="default"|"disabled"|"error"` prop. This build instead
+uses the same convention as every other Recursica control: a boolean `disabled` prop plus
+`FormControlWrapper`'s own `error` (message) prop — `error`'s mere presence is what triggers the
+error visuals, exactly like `TextArea`/`CheckboxGroup`. The token export only defines
+`disabled`/`error` state variants (no `focus`), matching Matt's direction to "follow the tokens."
+
+## `readOnly` mode (added 2026-08-19)
+
+Forge's reference has no read-only concept, but Matt asked for a `ReadOnly` story demonstrating
+the selected items as a read-only list. Switched from calling `FormControlWrapper` directly to
+routing through `WithReadOnlyWrapper` (the follow-up flagged in the original version of this note),
+matching `TextArea`'s shape: `readOnly`/`readOnlyComponent`/`emptyValueComponent` added to the prop
+surface via `ReadOnlyControlProps`, `readOnlyType="text"`, and `readOnlyValue` set to the target
+pane's item labels (`effectiveData[1].map(item => item.label)`). Renders as a comma-joined text
+list via the shared `ReadOnlyTextField`, same convention `CheckboxGroup`'s own read-only mode
+already uses for an array of values — no new read-only renderer needed. The two panes + transfer
+buttons (`activeComponent`) are skipped entirely when `readOnly` is set, same as every other
+control.
+
+## Height/gap/padding token audit (2026-08-19)
+
+Matt flagged the pane height as "too short" and asked that gap/padding be tied to recursica
+variables. Re-verified against `recursica_variables_scoped.css`: `properties_height` (200px),
+`properties_width`, `properties_vertical-padding`/`properties_horizontal-padding`, and
+`properties_gap` were already wired to their tokens (see "Token interpretation" above) — the 200px
+pane height is the design token's own value, not a hardcoded fallback. Two spacing values genuinely
+have no covering token in the 31-variable schema and are intentionally left as hardcoded pixels
+(see `TransferList.module.css` comments) rather than reusing another component's token: the gap
+between stacked `CheckboxGroup` blocks in `.paneList` (ungrouped row + each named group), and the
+gap between the four transfer buttons in `.transferColumn`. If a token is added to the schema for
+either, wire it in directly; until then this matches the established precedent (e.g. `FileUpload`'s
+untokened icon size) of leaving a truly uncovered value hardcoded with a documented reason instead
+of borrowing a sibling component's namespace.
+
+## Fixed: checkboxes inside `CheckboxGroup` ignored their own `checked`/`onChange` (2026-08-19)
+
+Matt's discrepancy report against the mantine source of truth: clicking an ungrouped checkbox in
+the `Grouped` story showed no checkmark and never toggled selection, though the pane's `Badge`
+count also never changed — meaning it silently did nothing, not "count going up" as literally
+worded, confirmed live via Playwright against both Storybooks (`isChecked()` stayed `false`, badge
+text stayed `5` across repeated clicks in mui; mantine correctly showed `1 / 5`, `2 / 5`).
+
+Root cause was in `Checkbox.tsx`, not `TransferList.tsx`: `TransferList` wraps its ungrouped items
+in a bare `<CheckboxGroup>` purely so they pick up the `item-gap` layout token (see the
+`RECURSICA_COMPONENTS`/gap fix from 2026-08-18), without ever passing that group a `value`/
+`onChange`. But `Checkbox.tsx` derived `isGrouped` from `groupContext !== null` alone — any
+`CheckboxGroup` ancestor forced grouped-array semantics (`isChecked = groupContext.value.includes(...)`,
+`handleChange` dispatching to `groupContext.onChange` instead of the checkbox's own `onChange`),
+even though the group had no `value` array and no `onChange` to dispatch to. `TransferList`'s own
+`checked={selected.has(item.value)}`/`onChange={() => onToggle(item.value)}` props were present but
+silently overridden/ignored. Mantine's `Checkbox.tsx` never had this bug — it doesn't consult any
+group context at all and always passes `checked`/`onChange` straight through to
+`@mantine/core`'s `Checkbox`.
+
+Fixed by only treating a `Checkbox` as group-controlled when it _doesn't_ already have its own
+explicit `checked` prop: `isGrouped = groupContext !== null && restRecord.checked === undefined`.
+A checkbox with its own `checked` (like `TransferList`'s rows) now always owns its source of truth;
+only checkboxes relying on `Checkbox.Group`'s array-tracking (no individual `checked`, matched by
+`value` — `CheckboxGroup.stories.tsx`'s usage) still defer to the group. Audited every
+`CheckboxGroup`/`Checkbox` pairing in adapter-mui-v7 (`CheckboxGroup.stories.tsx` and `TransferList`) —
+no existing usage combines both an individual `checked` and group-array `value`, so this is a
+straight bug fix with no regression risk.
+
+## Token interpretation: unlabeled tokens with more than one plausible layout target
+
+The 31-variable schema (`properties_*` + two `layouts.*` + `states.{disabled,error}`) has a few
+names that don't pin down a single location by themselves:
+
+- **`properties_gap`** — applied to the row holding `[source pane, transfer column, target pane]`.
+  It's the only _unnested_ gap the schema defines at the component's own level (not under
+  `header-style`, a state, or a layout), so it reads as the component's top-level layout gap.
+- **`properties_title-filter-gap`** — between each pane's header row (label + count `Badge`) and
+  its search field.
+- **`properties_filter-items-gap`** — between each pane's search field and its item list.
+- **`properties_header-style_*` / `properties_colors_header-color`** — typography/color for each
+  pane's own header text, not the overall `FormControlWrapper` label (which has its own type
+  styling already).
+- **`properties_width` (300px) / `properties_height` (200px)** — taken as each pane's own fixed
+  box size (`flex: 1 1 <width>`, so panes still stretch evenly in a wider container; `height` is
+  literal since a dual-listbox needs a bounded, independently-scrollable list).
+
+No exemptions needed beyond `border-size` (see below) — all 31 variables are referenced; verified
+zero broken/unused via `recursica-token-analyzer`.
+
+## Border-size intentionally unused
+
+Same house policy `TextField`/`TextArea`/`FileInput` already follow: `border-size` (base,
+`disabled`, `error`) is `recursica-ignore`d and a flat 1px border is applied uniformly instead, so
+switching states doesn't shift layout.
+
+## No forge-defined focus state
+
+`transfer-list` has no `states.focus` axis in the export — same as `FileInput`/`TextField`. Focus
+is handled per-control (each `Checkbox`/`TextField`/`Button` already has its own focus ring); the
+pane box itself has no focus state to render.
+
+## Grouping and search are local, not per-item persisted state
+
+Search filters each pane independently (`sourceSearch`/`targetSearch`); grouped items render under
+a `CheckboxGroup` keyed by `item.group`, ungrouped items render as plain `Checkbox` rows above the
+groups (alphabetized by group name) — same two-bucket split Forge's reference uses. Selection
+(`sourceSelected`/`targetSelected`) is cleared on every transfer, matching Forge's behavior.
+
+## Chevron icons are inline, not a shared icon set entry
+
+Same precedent as `Tree`'s `ExpandGlyph`/`FileInput`'s `ClearIcon`: a single-chevron and a
+double-chevron SVG are defined locally and flipped via `transform: scaleX(-1)` for the "left"
+direction, rather than maintaining four separate paths or adding new shared icon-set entries for a
+single component.

package/src/components/TransferList/TransferList.module.css

@@ -0,0 +1,174 @@
+/* TOKEN INTERPRETATION NOTES (see TRANSFERLIST_IMPLEMENTATION_NOTES.md):
+   - `properties_gap` is applied to the row that holds [source pane, transfer buttons, target pane] —
+     it's the only unnested gap the schema defines at the component's own level.
+   - `properties_title-filter-gap` sits between each pane's header row and its search field.
+   - `properties_filter-items-gap` sits between each pane's search field and its item list. */
+
+.layoutOverride {
+  --form-control-margin-bottom: var(
+    --recursica_ui-kit_components_transfer-list_variants_layouts_stacked_properties_top-bottom-margin
+  );
+}
+
+.layoutOverride[data-form-layout="side-by-side"] {
+  --form-control-margin-bottom: var(
+    --recursica_ui-kit_components_transfer-list_variants_layouts_side-by-side_properties_top-bottom-margin
+  );
+}
+
+.root {
+  display: flex;
+  width: 100%;
+}
+
+.panes {
+  display: flex;
+  align-items: stretch;
+  gap: var(--recursica_ui-kit_components_transfer-list_properties_gap);
+  width: 100%;
+}
+
+.pane {
+  display: flex;
+  flex-direction: column;
+  box-sizing: border-box;
+  min-width: 0;
+  flex: 1 1 var(--recursica_ui-kit_components_transfer-list_properties_width);
+  height: var(--recursica_ui-kit_components_transfer-list_properties_height);
+  padding: var(
+      --recursica_ui-kit_components_transfer-list_properties_vertical-padding
+    )
+    var(
+      --recursica_ui-kit_components_transfer-list_properties_horizontal-padding
+    );
+  border-width: 1px;
+  border-style: solid;
+  border-radius: var(
+    --recursica_ui-kit_components_transfer-list_properties_border-radius
+  );
+  border-color: var(
+    --recursica_ui-kit_components_transfer-list_properties_colors_border-color
+  );
+  background-color: var(
+    --recursica_ui-kit_components_transfer-list_properties_colors_background-color
+  );
+}
+
+.paneHeader {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  margin-bottom: var(
+    --recursica_ui-kit_components_transfer-list_properties_title-filter-gap
+  );
+  font-family: var(
+    --recursica_ui-kit_components_transfer-list_properties_header-style_fontFamily
+  );
+  font-size: var(
+    --recursica_ui-kit_components_transfer-list_properties_header-style_fontSize
+  );
+  font-style: var(
+    --recursica_ui-kit_components_transfer-list_properties_header-style_fontStyle
+  );
+  font-weight: var(
+    --recursica_ui-kit_components_transfer-list_properties_header-style_fontWeight
+  );
+  letter-spacing: var(
+    --recursica_ui-kit_components_transfer-list_properties_header-style_letterSpacing
+  );
+  line-height: var(
+    --recursica_ui-kit_components_transfer-list_properties_header-style_lineHeight
+  );
+  text-decoration: var(
+    --recursica_ui-kit_components_transfer-list_properties_header-style_textDecoration
+  );
+  text-transform: var(
+    --recursica_ui-kit_components_transfer-list_properties_header-style_textCase
+  );
+  color: var(
+    --recursica_ui-kit_components_transfer-list_properties_colors_header-color
+  );
+}
+
+.paneSearch {
+  margin-bottom: var(
+    --recursica_ui-kit_components_transfer-list_properties_filter-items-gap
+  );
+}
+
+.paneList {
+  flex: 1;
+  overflow-y: auto;
+  display: flex;
+  flex-direction: column;
+  /* No token exists for the gap between stacked CheckboxGroup blocks (ungrouped row +
+     each named group) — the 31-variable transfer-list schema only defines gaps at the
+     header/search/pane level (see TRANSFERLIST_IMPLEMENTATION_NOTES.md). Left as an
+     intentional hardcoded value rather than borrowing another component's token, same
+     as FileUpload's untokened icon size. */
+  gap: 2px;
+  min-height: 0;
+}
+
+.emptyState {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  flex: 1;
+  opacity: 0.6;
+  font-size: 14px;
+  padding: 16px;
+  text-align: center;
+}
+
+.transferColumn {
+  display: flex;
+  flex-direction: column;
+  align-items: center;
+  justify-content: center;
+  /* No token exists for spacing between the four transfer buttons — not part of the
+     31-variable schema. Left as an intentional hardcoded value (see TRANSFERLIST_IMPLEMENTATION_NOTES.md). */
+  gap: 4px;
+  flex-shrink: 0;
+}
+
+.chevron[data-direction="left"] {
+  transform: scaleX(-1);
+}
+
+/* -------------------------------------
+   STATE CASCADE
+-------------------------------------- */
+
+.root[data-error] .pane {
+  border-color: var(
+    --recursica_ui-kit_components_transfer-list_variants_states_error_properties_colors_border-color
+  ) !important;
+  background-color: var(
+    --recursica_ui-kit_components_transfer-list_variants_states_error_properties_colors_background-color
+  ) !important;
+}
+
+.root[data-error] .paneHeader {
+  color: var(
+    --recursica_ui-kit_components_transfer-list_variants_states_error_properties_colors_header-color
+  ) !important;
+}
+
+.root[data-disabled] .pane {
+  border-color: var(
+    --recursica_ui-kit_components_transfer-list_variants_states_disabled_properties_colors_border-color
+  ) !important;
+  background-color: var(
+    --recursica_ui-kit_components_transfer-list_variants_states_disabled_properties_colors_background-color
+  ) !important;
+  opacity: var(
+    --recursica_ui-kit_components_transfer-list_variants_states_disabled_properties_opacity
+  );
+}
+
+.root[data-disabled] .paneHeader {
+  color: var(
+    --recursica_ui-kit_components_transfer-list_variants_states_disabled_properties_colors_header-color
+  ) !important;
+}