@recursica/adapter-mantine-v8 1.0.0

package/src/components/index.ts

@@ -0,0 +1,52 @@
+export * from "./Accordion";
+export * from "./AssistiveElement/AssistiveElement";
+export * from "./AutoComplete/AutoComplete";
+export * from "./Avatar";
+export * from "./Badge/Badge";
+export * from "./Breadcrumb/Breadcrumb";
+export * from "./Button";
+export * from "./Card/Card";
+export * from "./Checkbox/Checkbox";
+export * from "./Checkbox/CheckboxGroup";
+export * from "./Chip/Chip";
+export * from "./Container/Container";
+export * from "./DatePicker/DatePicker";
+export * from "./Dropdown/Dropdown";
+export * from "./FileInput/FileInput";
+export * from "./FileUpload/FileUpload";
+export * from "./Flex/Flex";
+export * from "./FormControlLayout/FormControlLayout";
+export * from "./Grid/Grid";
+export * from "./Group/Group";
+export * from "./Heading/Heading";
+export * from "./HoverCard/HoverCard";
+export * from "./Link/Link";
+export * from "./Loader/Loader";
+export * from "./Label";
+export * from "./Menu/Menu";
+export * from "./Modal/Modal";
+export * from "./NumberInput/NumberInput";
+export * from "./Pagination/Pagination";
+export * from "./Panel/Panel";
+export * from "./Popover";
+export * from "./Radio/Radio";
+export * from "./Radio/RadioGroup";
+export * from "./ReadOnlyField";
+export * from "./SegmentedControl/SegmentedControl";
+export * from "./Slider/Slider";
+export * from "./Stack/Stack";
+export * from "./Stepper/Stepper";
+export * from "./Switch/Switch";
+export * from "./Switch/SwitchGroup";
+export * from "./Table/Table";
+export * from "./Tabs/Tabs";
+export * from "./Text/Text";
+export * from "./TextArea/TextArea";
+export * from "./TextField/TextField";
+export * from "./TimePicker/TimePicker";
+export * from "./Timeline/Timeline";
+export * from "./Timeline/TimelineItem";
+export * from "./Toast";
+export * from "./Tooltip/Tooltip";
+export * from "./TransferList/TransferList";
+export * from "./Tree";

package/src/env.d.ts

@@ -0,0 +1,7 @@
+/// <reference types="vite/client" />
+/// <reference types="vite-plugin-svgr/client" />
+
+declare module "*.module.css" {
+  const classes: { readonly [key: string]: string };
+  export default classes;
+}

package/src/index.ts

@@ -0,0 +1,179 @@
+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 Link = rawComponents.Link;
+export const Text = rawComponents.Text;
+
+// 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 Heading = wrapComponent(
+  rawComponents.Heading,
+) as typeof rawComponents.Heading;
+export const HoverCard = wrapComponent(
+  rawComponents.HoverCard,
+) as typeof rawComponents.HoverCard;
+export const Loader = wrapComponent(
+  rawComponents.Loader,
+) as typeof rawComponents.Loader;
+export const Label = wrapComponent(
+  rawComponents.Label,
+) as typeof rawComponents.Label;
+export const Menu = wrapComponent(
+  rawComponents.Menu,
+) as typeof rawComponents.Menu;
+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 Tabs = wrapComponent(
+  rawComponents.Tabs,
+) as typeof rawComponents.Tabs;
+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 {
+  RecursicaCheckboxGroupProps,
+  RecursicaDatePickerProps,
+  RecursicaDropdownProps,
+  RecursicaNumberInputProps,
+  RecursicaRadioGroupProps,
+  RecursicaReadOnlyFieldProps,
+  RecursicaReadOnlyTextFieldProps,
+  RecursicaSliderProps,
+  RecursicaSwitchGroupProps,
+  RecursicaTextAreaProps,
+  RecursicaTextFieldProps,
+  RecursicaTimePickerProps,
+} 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/mantine.d.ts

@@ -0,0 +1,7 @@
+import type { ComboboxItem as RecursicaComboboxItem } from "./index";
+import "@mantine/core";
+
+declare module "@mantine/core" {
+  // eslint-disable-next-line @typescript-eslint/no-empty-object-type
+  export interface ComboboxItem extends RecursicaComboboxItem {}
+}

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,27 @@
+import { useMantineColorScheme } from "@mantine/core";
+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;
+}) {
+  const { setColorScheme } = useMantineColorScheme();
+
+  useEffect(() => {
+    const handleColorScheme = (value: boolean) => {
+      const theme = value ? "dark" : "light";
+      setColorScheme(theme);
+      document.documentElement.setAttribute("data-recursica-theme", theme);
+    };
+
+    channel.on(DARK_MODE_EVENT_NAME, handleColorScheme);
+    return () => channel.off(DARK_MODE_EVENT_NAME, handleColorScheme);
+  }, [setColorScheme]);
+
+  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,
+  mapLayoutProps,
+} 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", bg: "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("mapLayoutProps", () => {
+  it("maps rec- spacing tokens on layout props", () => {
+    expect(mapLayoutProps({ mt: "rec-xl" })).toEqual({
+      mt: SPACING_MAP["rec-xl"],
+    });
+  });
+
+  it("leaves non-layout props untouched even if they look like a token", () => {
+    expect(mapLayoutProps({ variant: "rec-xl" })).toEqual({
+      variant: "rec-xl",
+    });
+  });
+});

package/src/utils/filterStylingProps.ts

@@ -0,0 +1,150 @@
+/**
+ * filterStylingProps
+ *
+ * This utility acts as the central gatekeeper for strict design-system adherence across
+ * all Recursica components mapped over Mantine.
+ *
+ * PHILOSOPHY:
+ * Recursica components are designed to be explicitly sandboxed tokens. Allowing external
+ * `className` or Mantine style system props (`bg`, `p`, 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 classNames).
+ * 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 Mantine 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",
+  "classNames",
+  "style",
+  "styles",
+  "vars", // Internal structure hooks
+  "p",
+  "px",
+  "py",
+  "pt",
+  "pb",
+  "pl",
+  "pr", // Padding
+  "bg",
+  "c",
+  "opacity", // Color
+  "ff",
+  "fz",
+  "fw",
+  "lts",
+  "ta",
+  "lh",
+  "fs",
+  "tt",
+  "td", // Typography
+  "bd",
+  "bdw",
+  "bds",
+  "bdc",
+  "bdr", // Borders
+  "shadow", // Effects
+  "w",
+  "miw",
+  "maw",
+  "h",
+  "mih",
+  "mah", // Dimensions
+] 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",
+  "gap",
+  "rowGap",
+  "columnGap",
+  "gutter",
+  "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 function mapLayoutProps<T extends Record<string, unknown>>(props: T): T {
+  const mapped = { ...props };
+  for (const [key, value] of Object.entries(mapped)) {
+    if (
+      typeof value === "string" &&
+      value.startsWith("rec-") &&
+      LAYOUT_PROPS.has(key)
+    ) {
+      if (value in SPACING_MAP) {
+        (mapped as Record<string, unknown>)[key] = SPACING_MAP[value];
+      }
+    }
+  }
+  return mapped;
+}
+
+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,65 @@
+import React from "react";
+import {
+  type ComboboxStringItem,
+  type ComboboxLikeRenderOptionInput,
+} from "@mantine/core";
+
+// `ComboboxStringItem`/`ComboboxItem` only type `value`/`label`/`disabled` —
+// `leadingIcon`/`supportingText` are extra fields Mantine's own `getParsedComboboxData` passes
+// through untouched whenever an item already has both `value` and `label` (see
+// get-parsed-combobox-data.mjs), so they reach `option` here at runtime even though the upstream
+// type doesn't know about them. Generic over both Autocomplete's `ComboboxStringItem` (optional
+// `label`) and Dropdown's `ComboboxItem` (required `label`) — the same renderer serves both.
+type RichComboboxItem = ComboboxStringItem & {
+  label?: string;
+  leadingIcon?: React.ReactNode;
+  supportingText?: string;
+};
+
+export interface RichOptionClassNames {
+  optionContent: string;
+  optionIcon: string;
+  optionText: string;
+  /** Combined with `optionText` when `wrapItemText` is true — see `renderRichOption` below. */
+  optionTextWrap: string;
+  optionSupportingText: string;
+}
+
+/**
+ * `renderOption` for Autocomplete/Dropdown that renders an item's `leadingIcon`/`supportingText`
+ * (see MANTINE_ADAPTER_RICH_OPTION_DATA.md) inside the option row. Falls back to plain
+ * `option.label` — the same rendering Mantine uses when no `renderOption` is supplied at all — so
+ * items without the new fields are unaffected.
+ *
+ * `wrapItemText` (default `false`) controls whether `label`/`supportingText` wrap onto additional
+ * lines or truncate to a single line with an ellipsis.
+ */
+export function renderRichOption<T extends ComboboxStringItem>(
+  { option }: ComboboxLikeRenderOptionInput<T>,
+  classNames: RichOptionClassNames,
+  wrapItemText = false,
+): React.ReactNode {
+  const { label, leadingIcon, supportingText } = option as RichComboboxItem;
+  const displayLabel = label ?? option.value;
+  if (!leadingIcon && !supportingText) {
+    return displayLabel;
+  }
+  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>{displayLabel}</span>
+        {supportingText && (
+          <span className={classNames.optionSupportingText}>
+            {supportingText}
+          </span>
+        )}
+      </span>
+    </span>
+  );
+}