@recursica/mantine-adapter 0.6.0 → 0.7.0

package/src/components/Title/Title.tsx

@@ -0,0 +1,45 @@
+import { forwardRef } from "react";
+import {
+  Title as MantineTitle,
+  type TitleProps as MantineTitleProps,
+} from "@mantine/core";
+import {
+  filterStylingProps,
+  type RecursicaOverStyled,
+} from "../../utils/filterStylingProps";
+
+export type RecursicaTitleProps = Omit<MantineTitleProps, "order"> & {
+  /**
+   * Enforces semantic HTML headers (h1-h6) cleanly bound to native typographic scaling variables in the design system.
+   */
+  order?: 1 | 2 | 3 | 4 | 5 | 6;
+};
+
+export type TitleProps = RecursicaOverStyled<RecursicaTitleProps>;
+
+/**
+ * Enforces highly accessible structural markup utilizing semantic `<h1>` through `<h6>` tags securely bound directly to Recursica typographic scales.
+ */
+export const Title = forwardRef<HTMLHeadingElement, TitleProps>(function Title(
+  { overStyled = false, order = 1, ...rest },
+  ref,
+) {
+  const sanitizedProps = filterStylingProps(rest, overStyled);
+  const classNameProp = (sanitizedProps as Record<string, unknown>)
+    .className as string | undefined;
+
+  const typographyClass = `recursica_brand_typography_h${order}`;
+  const mergedClassName = classNameProp
+    ? `${typographyClass} ${classNameProp}`
+    : typographyClass;
+
+  return (
+    <MantineTitle
+      ref={ref}
+      order={order}
+      className={mergedClassName}
+      {...(sanitizedProps as unknown as MantineTitleProps)}
+    />
+  );
+});
+Title.displayName = "Title";

package/src/components/Toast/Toast.stories.tsx

@@ -0,0 +1,17 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { Toast } from "./Toast";
+import { ComingSoon } from "@recursica/storybook-template";
+
+const meta: Meta<typeof Toast> = {
+  title: "UI-Kit/🚧 Toast",
+  component: Toast,
+  tags: ["autodocs"],
+};
+
+export default meta;
+
+type Story = StoryObj<typeof Toast>;
+
+export const Default: Story = {
+  render: () => <ComingSoon componentName="Toast" />,
+};

package/src/components/Toast/Toast.tsx

@@ -0,0 +1,7 @@
+import React from "react";
+
+export type ToastProps = React.HTMLAttributes<HTMLDivElement>;
+
+export const Toast: React.FC<ToastProps> = (props) => {
+  return <div {...props}>Toast</div>;
+};

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

@@ -0,0 +1,17 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { Tooltip } from "./Tooltip";
+import { ComingSoon } from "@recursica/storybook-template";
+
+const meta: Meta<typeof Tooltip> = {
+  title: "UI-Kit/🚧 Tooltip",
+  component: Tooltip,
+  tags: ["autodocs"],
+};
+
+export default meta;
+
+type Story = StoryObj<typeof Tooltip>;
+
+export const Default: Story = {
+  render: () => <ComingSoon componentName="Tooltip" />,
+};

package/src/components/Tooltip/Tooltip.tsx

@@ -0,0 +1,7 @@
+import React from "react";
+
+export type TooltipProps = React.HTMLAttributes<HTMLDivElement>;
+
+export const Tooltip: React.FC<TooltipProps> = (props) => {
+  return <div {...props}>Tooltip</div>;
+};

package/src/components/TransferList/TransferList.stories.tsx

@@ -0,0 +1,17 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { TransferList } from "./TransferList";
+import { ComingSoon } from "@recursica/storybook-template";
+
+const meta: Meta<typeof TransferList> = {
+  title: "UI-Kit/🚧 TransferList",
+  component: TransferList,
+  tags: ["autodocs"],
+};
+
+export default meta;
+
+type Story = StoryObj<typeof TransferList>;
+
+export const Default: Story = {
+  render: () => <ComingSoon componentName="TransferList" />,
+};

package/src/components/TransferList/TransferList.tsx

@@ -0,0 +1,7 @@
+import React from "react";
+
+export type TransferListProps = React.HTMLAttributes<HTMLDivElement>;
+
+export const TransferList: React.FC<TransferListProps> = (props) => {
+  return <div {...props}>TransferList</div>;
+};

package/src/components/index.ts

@@ -0,0 +1,39 @@
+export * from "./Accordion";
+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 "./DatePicker/DatePicker";
+export * from "./Dropdown/Dropdown";
+export * from "./FileInput/FileInput";
+export * from "./FileUpload/FileUpload";
+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/Popover";
+export * from "./Radio/Radio";
+export * from "./ReadOnlyField";
+export * from "./Search/Search";
+export * from "./SegmentedControl/SegmentedControl";
+export * from "./Slider/Slider";
+export * from "./Stepper/Stepper";
+export * from "./Switch/Switch";
+export * from "./Table/Table";
+export * from "./Tabs/Tabs";
+export * from "./TextArea/TextArea";
+export * from "./TextField/TextField";
+export * from "./TimePicker/TimePicker";
+export * from "./Timeline/Timeline";
+export * from "./Toast/Toast";
+export * from "./Tooltip/Tooltip";
+export * from "./TransferList/TransferList";

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,3 @@
+import "@recursica/adapter-common/style.css";
+export * from "./components";
+export * from "@recursica/adapter-common";

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/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.ts

@@ -0,0 +1,139 @@
+/**
+ * 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 BlockedStylingKeys = (typeof BLOCKED_STYLING_KEYS)[number];
+
+export type RecursicaSpacing =
+  | "rec-none"
+  | "rec-sm"
+  | "rec-default"
+  | "rec-md"
+  | "rec-lg"
+  | "rec-xl"
+  | "rec-2xl";
+
+const LAYOUT_PROPS = new Set([
+  "m",
+  "my",
+  "mx",
+  "mt",
+  "mb",
+  "ml",
+  "mr",
+  "gap",
+  "rowGap",
+  "columnGap",
+  "top",
+  "left",
+  "bottom",
+  "right",
+]);
+
+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 ForbiddenStyles = { [K in BlockedStylingKeys]?: never };
+
+export type RecursicaOverStyled<T> =
+  | (Omit<T, BlockedStylingKeys> &
+      ForbiddenStyles & { overStyled?: false | undefined })
+  | (T & { overStyled: true });
+
+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";