@recursica/adapter-mui-v7 1.0.0

package/src/index.ts

@@ -0,0 +1,194 @@
+import "@recursica/adapter-common/style.css";
+import * as rawComponents from "./components";
+import { wrapComponent } from "@recursica/adapter-common";
+
+export * from "@recursica/adapter-common";
+
+// Expose unwrapped structural layout primitives to preserve their polymorphic types
+export const Flex = rawComponents.Flex;
+export const Grid = rawComponents.Grid;
+export const GridCol = rawComponents.GridCol;
+export const Group = rawComponents.Group;
+export const Stack = rawComponents.Stack;
+export const Container = rawComponents.Container;
+export const Typography = rawComponents.Typography;
+
+// Statically wrap and export components to inject overStyled visual highlight in dev mode
+export const Accordion = wrapComponent(
+  rawComponents.Accordion,
+) as typeof rawComponents.Accordion;
+export const AccordionItem = wrapComponent(
+  rawComponents.AccordionItem,
+) as typeof rawComponents.AccordionItem;
+export const AccordionControl = wrapComponent(
+  rawComponents.AccordionControl,
+) as typeof rawComponents.AccordionControl;
+export const AccordionPanel = wrapComponent(
+  rawComponents.AccordionPanel,
+) as typeof rawComponents.AccordionPanel;
+export const AssistiveElement = wrapComponent(
+  rawComponents.AssistiveElement,
+) as typeof rawComponents.AssistiveElement;
+export const AutoComplete = wrapComponent(
+  rawComponents.AutoComplete,
+) as typeof rawComponents.AutoComplete;
+export const Avatar = wrapComponent(
+  rawComponents.Avatar,
+) as typeof rawComponents.Avatar;
+export const Badge = wrapComponent(
+  rawComponents.Badge,
+) as typeof rawComponents.Badge;
+export const Breadcrumb = wrapComponent(
+  rawComponents.Breadcrumb,
+) as typeof rawComponents.Breadcrumb;
+export const Button = wrapComponent(
+  rawComponents.Button,
+) as typeof rawComponents.Button;
+export const Card = wrapComponent(
+  rawComponents.Card,
+) as typeof rawComponents.Card;
+export const Checkbox = wrapComponent(
+  rawComponents.Checkbox,
+) as typeof rawComponents.Checkbox;
+export const CheckboxGroup = wrapComponent(
+  rawComponents.CheckboxGroup,
+) as typeof rawComponents.CheckboxGroup;
+export const Chip = wrapComponent(
+  rawComponents.Chip,
+) as typeof rawComponents.Chip;
+export const DatePicker = wrapComponent(
+  rawComponents.DatePicker,
+) as typeof rawComponents.DatePicker;
+export const Dropdown = wrapComponent(
+  rawComponents.Dropdown,
+) as typeof rawComponents.Dropdown;
+export const FileInput = wrapComponent(
+  rawComponents.FileInput,
+) as typeof rawComponents.FileInput;
+export const FileUpload = wrapComponent(
+  rawComponents.FileUpload,
+) as typeof rawComponents.FileUpload;
+export const FormControlLayout = wrapComponent(
+  rawComponents.FormControlLayout,
+) as typeof rawComponents.FormControlLayout;
+export const FormControlWrapper = wrapComponent(
+  rawComponents.FormControlWrapper,
+) as typeof rawComponents.FormControlWrapper;
+export const Heading = wrapComponent(
+  rawComponents.Heading,
+) as typeof rawComponents.Heading;
+export const HoverCard = wrapComponent(
+  rawComponents.HoverCard,
+) as typeof rawComponents.HoverCard;
+export const Label = wrapComponent(
+  rawComponents.Label,
+) as typeof rawComponents.Label;
+export const Link = wrapComponent(
+  rawComponents.Link,
+) as typeof rawComponents.Link;
+export const Loader = wrapComponent(
+  rawComponents.Loader,
+) as typeof rawComponents.Loader;
+export const Menu = wrapComponent(
+  rawComponents.Menu,
+) as typeof rawComponents.Menu;
+export const MenuItem = wrapComponent(
+  rawComponents.MenuItem,
+) as typeof rawComponents.MenuItem;
+export const MenuDivider = wrapComponent(
+  rawComponents.MenuDivider,
+) as typeof rawComponents.MenuDivider;
+export const Modal = wrapComponent(
+  rawComponents.Modal,
+) as typeof rawComponents.Modal;
+export const NumberInput = wrapComponent(
+  rawComponents.NumberInput,
+) as typeof rawComponents.NumberInput;
+export const Pagination = wrapComponent(
+  rawComponents.Pagination,
+) as typeof rawComponents.Pagination;
+export const Panel = wrapComponent(
+  rawComponents.Panel,
+) as typeof rawComponents.Panel;
+export const PanelFooter = wrapComponent(
+  rawComponents.PanelFooter,
+) as typeof rawComponents.PanelFooter;
+export const Popover = wrapComponent(
+  rawComponents.Popover,
+) as typeof rawComponents.Popover;
+export const Radio = wrapComponent(
+  rawComponents.Radio,
+) as typeof rawComponents.Radio;
+export const RadioGroup = wrapComponent(
+  rawComponents.RadioGroup,
+) as typeof rawComponents.RadioGroup;
+export const ReadOnlyField = wrapComponent(
+  rawComponents.ReadOnlyField,
+) as typeof rawComponents.ReadOnlyField;
+export const SegmentedControl = wrapComponent(
+  rawComponents.SegmentedControl,
+) as typeof rawComponents.SegmentedControl;
+export const Slider = wrapComponent(
+  rawComponents.Slider,
+) as typeof rawComponents.Slider;
+export const Stepper = wrapComponent(
+  rawComponents.Stepper,
+) as typeof rawComponents.Stepper;
+export const Switch = wrapComponent(
+  rawComponents.Switch,
+) as typeof rawComponents.Switch;
+export const SwitchGroup = wrapComponent(
+  rawComponents.SwitchGroup,
+) as typeof rawComponents.SwitchGroup;
+export const Table = wrapComponent(
+  rawComponents.Table,
+) as typeof rawComponents.Table;
+export const Tab = wrapComponent(rawComponents.Tab) as typeof rawComponents.Tab;
+export const TabPanel = wrapComponent(
+  rawComponents.TabPanel,
+) as typeof rawComponents.TabPanel;
+export const Tabs = wrapComponent(
+  rawComponents.Tabs,
+) as typeof rawComponents.Tabs;
+export const Text = wrapComponent(
+  rawComponents.Text,
+) as typeof rawComponents.Text;
+export const TextArea = wrapComponent(
+  rawComponents.TextArea,
+) as typeof rawComponents.TextArea;
+export const TextField = wrapComponent(
+  rawComponents.TextField,
+) as typeof rawComponents.TextField;
+export const TimePicker = wrapComponent(
+  rawComponents.TimePicker,
+) as typeof rawComponents.TimePicker;
+export const Timeline = wrapComponent(
+  rawComponents.Timeline,
+) as typeof rawComponents.Timeline;
+export const TimelineItem = wrapComponent(
+  rawComponents.TimelineItem,
+) as typeof rawComponents.TimelineItem;
+export const Toast = wrapComponent(
+  rawComponents.Toast,
+) as typeof rawComponents.Toast;
+export const Tooltip = wrapComponent(
+  rawComponents.Tooltip,
+) as typeof rawComponents.Tooltip;
+export const TransferList = wrapComponent(
+  rawComponents.TransferList,
+) as typeof rawComponents.TransferList;
+export const Tree = wrapComponent(
+  rawComponents.Tree,
+) as typeof rawComponents.Tree;
+
+export type {
+  RecursicaAutocompleteProps,
+  RecursicaDropdownProps,
+  RecursicaFormControlWrapperProps,
+  RecursicaNumberInputProps,
+  RecursicaSliderProps,
+  RecursicaTextAreaProps,
+  RecursicaTextFieldProps,
+  RecursicaTimePickerProps,
+  RecursicaToastProps,
+} from "./components";

package/src/types/index.ts

@@ -0,0 +1,9 @@
+export interface ComboboxItem {
+  value: string;
+  label: string;
+  disabled?: boolean;
+  // icon?: IconName;
+  onClick?: () => void;
+}
+
+// Export other shared types here

package/src/types/scss-modules.d.ts

@@ -0,0 +1,9 @@
+declare module "*.scss" {
+  const content: { [className: string]: string };
+  export default content;
+}
+
+declare module "*.module.scss" {
+  const content: { [className: string]: string };
+  export default content;
+}

package/src/utils/ColorSchemeWrapper.tsx

@@ -0,0 +1,23 @@
+import { useEffect } from "react";
+import { addons } from "storybook/internal/preview-api";
+import { DARK_MODE_EVENT_NAME } from "storybook-dark-mode";
+
+const channel = addons.getChannel();
+
+export function ColorSchemeWrapper({
+  children,
+}: {
+  children: React.ReactNode;
+}) {
+  useEffect(() => {
+    const handleColorScheme = (value: boolean) => {
+      const theme = value ? "dark" : "light";
+      document.documentElement.setAttribute("data-recursica-theme", theme);
+    };
+
+    channel.on(DARK_MODE_EVENT_NAME, handleColorScheme);
+    return () => channel.off(DARK_MODE_EVENT_NAME, handleColorScheme);
+  }, []);
+
+  return <>{children}</>;
+}

package/src/utils/RequireAccessibleLabel.ts

@@ -0,0 +1 @@
+export { type RequireAccessibleLabel } from "@recursica/adapter-common";

package/src/utils/copyToClipboard.ts

@@ -0,0 +1,36 @@
+import React from "react";
+
+/**
+ * Helper function for copy text to clipboard
+ * @param {string} textToCopy The text string for copying to the clipboard
+ * @param {element|node} componentRef The ref of the component that we want to trigger the copy
+ */
+const copyToClipboard = (
+  textToCopy: string,
+  componentRef: React.RefObject<HTMLElement | null>,
+): Promise<void> => {
+  const currentFocus = document.activeElement as HTMLInputElement;
+  return new Promise((resolve, reject) => {
+    if (componentRef && componentRef.current) {
+      const textArea = document.createElement("textarea");
+      textArea.readOnly = true;
+      textArea.defaultValue = textToCopy;
+      componentRef.current.appendChild(textArea);
+      textArea.select();
+      const wasCopied = document.execCommand("copy");
+      componentRef.current.removeChild(textArea);
+      if (currentFocus) {
+        currentFocus.focus();
+      }
+      if (wasCopied) {
+        resolve();
+      } else {
+        reject(new Error("Failed to copy"));
+      }
+    } else {
+      reject(new Error("Copy area reference is not defined"));
+    }
+  });
+};
+
+export { copyToClipboard };

package/src/utils/filterStylingProps.test.ts

@@ -0,0 +1,85 @@
+import { describe, it, expect } from "vitest";
+import {
+  BLOCKED_STYLING_KEYS,
+  SPACING_MAP,
+  filterStylingProps,
+  filterSxProp,
+} from "./filterStylingProps";
+
+describe("filterStylingProps", () => {
+  it("strips every blocked styling key by default", () => {
+    const props = Object.fromEntries(
+      BLOCKED_STYLING_KEYS.map((key) => [key, "should-be-removed"]),
+    );
+
+    const sanitized = filterStylingProps(props);
+
+    for (const key of BLOCKED_STYLING_KEYS) {
+      expect(sanitized).not.toHaveProperty(key);
+    }
+  });
+
+  it("keeps props that aren't blocked styling keys", () => {
+    const sanitized = filterStylingProps({
+      disabled: true,
+      "aria-label": "Submit",
+    });
+
+    expect(sanitized).toEqual({ disabled: true, "aria-label": "Submit" });
+  });
+
+  it("keeps layout props (e.g. margin) untouched when not a rec- token", () => {
+    const sanitized = filterStylingProps({ m: "16px" });
+
+    expect(sanitized).toEqual({ m: "16px" });
+  });
+
+  it("maps rec- spacing tokens on layout props to their CSS variable", () => {
+    const sanitized = filterStylingProps({ m: "rec-lg", gap: "rec-sm" });
+
+    expect(sanitized).toEqual({
+      m: SPACING_MAP["rec-lg"],
+      gap: SPACING_MAP["rec-sm"],
+    });
+  });
+
+  it("does not map rec- tokens on props that aren't layout props", () => {
+    const sanitized = filterStylingProps({ "data-testid": "rec-lg" });
+
+    expect(sanitized).toEqual({ "data-testid": "rec-lg" });
+  });
+
+  it("leaves an unrecognized rec- value alone", () => {
+    const sanitized = filterStylingProps({ m: "rec-not-a-real-token" });
+
+    expect(sanitized).toEqual({ m: "rec-not-a-real-token" });
+  });
+
+  it("bypasses all filtering when overStyled is true", () => {
+    const props = { className: "custom", sx: { color: "red" }, m: "rec-lg" };
+
+    expect(filterStylingProps(props, true)).toEqual(props);
+  });
+
+  it("does not mutate the input props object", () => {
+    const props = { className: "custom", m: "rec-lg" };
+
+    filterStylingProps(props);
+
+    expect(props).toEqual({ className: "custom", m: "rec-lg" });
+  });
+});
+
+describe("filterSxProp", () => {
+  it("removes only the sx prop", () => {
+    const sanitized = filterSxProp({ sx: { color: "red" }, disabled: true });
+
+    expect(sanitized).toEqual({ disabled: true });
+  });
+
+  it("is a no-op when sx isn't present", () => {
+    const props = { disabled: true };
+
+    expect(filterSxProp(props)).toEqual(props);
+  });
+});

package/src/utils/filterStylingProps.ts

@@ -0,0 +1,143 @@
+/**
+ * filterStylingProps
+ *
+ * This utility acts as the central gatekeeper for strict design-system adherence across
+ * all Recursica components mapped over MUI.
+ *
+ * PHILOSOPHY:
+ * Recursica components are designed to be explicitly sandboxed tokens. Allowing external
+ * `className` or MUI style props (`sx`, `classes`, etc.) breaks the design system by
+ * allowing developers to leak arbitrary designs into components.
+ *
+ * By default (`overStyled=false`), this utility actively prevents developers from overriding
+ * internal component styles (such as background, colors, typography, or internal classes).
+ * It safely *permits* external layout overrides (like `margin` / `m`) so that components can
+ * easily be spaced alongside other DOM elements.
+ *
+ * If a developer passes `overStyled={true}`, this filter allows all styling properties to
+ * flow through to the underlying MUI component natively, at the developer's own risk.
+ *
+ * @param props - The raw component props passed down to the wrapper
+ * @param overStyled - Boolean toggle to allow raw external styling. Defaults to false.
+ * @returns Sanitized component props safe for internal styling merging
+ */
+
+export const BLOCKED_STYLING_KEYS = [
+  "className",
+  "classes", // MUI specific nested class overrides
+  "style",
+  "sx", // MUI's primary system style prop
+
+  // Potential Box/Typography system props to block (if we wrap those)
+  "color",
+  "bgcolor",
+  "backgroundColor",
+  "typography",
+  "fontFamily",
+  "fontSize",
+  "fontWeight",
+  "lineHeight",
+  "letterSpacing",
+  "textAlign",
+  "border",
+  "borderTop",
+  "borderBottom",
+  "borderLeft",
+  "borderRight",
+  "borderColor",
+  "borderRadius",
+  "boxShadow",
+  "display",
+  "position",
+  "zIndex",
+] as const;
+export {
+  type RecursicaSpacing,
+  type RecursicaSize,
+  type RecursicaOverStyled,
+  type BlockedStylingKeys,
+  type ForbiddenStyles,
+  type WithRecursicaSpacing,
+  omitUnsupportedProps,
+  withCallerOverride,
+  mergeClassNames,
+  mergeStyles,
+} from "@recursica/adapter-common";
+
+const LAYOUT_PROPS = new Set([
+  "m",
+  "my",
+  "mx",
+  "mt",
+  "mb",
+  "ml",
+  "mr",
+  "p",
+  "py",
+  "px",
+  "pt",
+  "pb",
+  "pl",
+  "pr",
+  "gap",
+  "rowGap",
+  "columnGap",
+  "top",
+  "left",
+  "bottom",
+  "right",
+]);
+
+export const SPACING_MAP: Record<string, string> = {
+  "rec-none": "var(--recursica_brand_dimensions_general_none)",
+  "rec-sm": "var(--recursica_brand_dimensions_general_sm)",
+  "rec-default": "var(--recursica_brand_dimensions_general_default)",
+  "rec-md": "var(--recursica_brand_dimensions_general_md)",
+  "rec-lg": "var(--recursica_brand_dimensions_general_lg)",
+  "rec-xl": "var(--recursica_brand_dimensions_general_xl)",
+  "rec-2xl": "var(--recursica_brand_dimensions_general_2xl)",
+};
+
+export type OmitSx<T> = Omit<T, "sx">;
+
+export function filterSxProp<T extends Record<string, unknown>>(
+  props: T,
+): Omit<T, "sx"> {
+  const sanitized = { ...props };
+  if ("sx" in sanitized) {
+    delete sanitized["sx"];
+  }
+  return sanitized as Omit<T, "sx">;
+}
+
+export function filterStylingProps<T extends Record<string, unknown>>(
+  props: T,
+  overStyled?: boolean,
+): Partial<T> {
+  if (overStyled) {
+    return props;
+  }
+
+  const sanitized = { ...props };
+
+  for (const prop of BLOCKED_STYLING_KEYS) {
+    if (prop in sanitized) {
+      delete sanitized[prop];
+    }
+  }
+
+  // Intercept Recursica spacing tokens for valid layout properties
+  for (const [key, value] of Object.entries(sanitized)) {
+    if (
+      typeof value === "string" &&
+      value.startsWith("rec-") &&
+      LAYOUT_PROPS.has(key)
+    ) {
+      if (value in SPACING_MAP) {
+        (sanitized as Record<string, unknown>)[key] = SPACING_MAP[value];
+      }
+    }
+  }
+
+  return sanitized;
+}

package/src/utils/index.ts

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

package/src/utils/renderRichOption.tsx

@@ -0,0 +1,51 @@
+import React from "react";
+import { type RecursicaComboboxItemWithLabel } from "@recursica/adapter-common";
+
+export interface RichOptionClassNames {
+  optionContent: string;
+  optionIcon: string;
+  optionText: string;
+  /** Combined with `optionText` when `wrapItemText` is true — see `renderRichOptionContent` below. */
+  optionTextWrap: string;
+  optionSupportingText: string;
+}
+
+/**
+ * `MenuItem`/option children for Dropdown/Autocomplete that renders `leadingIcon`/`supportingText`
+ * (see MANTINE_ADAPTER_RICH_OPTION_DATA.md) inside the row. Falls back to plain `label` when
+ * neither is present, so items without the new fields render exactly as before.
+ *
+ * `wrapItemText` (default `false`) controls whether `label`/`supportingText` wrap onto additional
+ * lines or truncate to a single line with an ellipsis.
+ */
+export function renderRichOptionContent(
+  item: Pick<
+    RecursicaComboboxItemWithLabel,
+    "label" | "leadingIcon" | "supportingText"
+  >,
+  classNames: RichOptionClassNames,
+  wrapItemText = false,
+): React.ReactNode {
+  const { label, leadingIcon, supportingText } = item;
+  if (!leadingIcon && !supportingText) {
+    return label;
+  }
+  const optionTextClassName = wrapItemText
+    ? `${classNames.optionText} ${classNames.optionTextWrap}`
+    : classNames.optionText;
+  return (
+    <span className={classNames.optionContent}>
+      {leadingIcon && (
+        <span className={classNames.optionIcon}>{leadingIcon}</span>
+      )}
+      <span className={optionTextClassName}>
+        <span>{label}</span>
+        {supportingText && (
+          <span className={classNames.optionSupportingText}>
+            {supportingText}
+          </span>
+        )}
+      </span>
+    </span>
+  );
+}