@recursica/mantine-adapter 0.9.4 → 0.11.0

package/src/components/Stack/Stack.stories.tsx

@@ -0,0 +1,108 @@
+import React from "react";
+import type { Meta, StoryObj } from "@storybook/react";
+import { Stack } from "./Stack";
+import { Button } from "../Button";
+import { Text } from "../Text/Text";
+
+type StackStoryProps = React.ComponentProps<typeof Stack>;
+
+const meta: Meta<StackStoryProps> = {
+  title: "UI-Kit/Stack",
+  component: Stack,
+  tags: ["autodocs"],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          "Stack is a flex vertical layout container that maps directly to Mantine's Stack component allowing safe layout property passing.",
+      },
+    },
+  },
+  args: {
+    gap: "rec-default",
+    align: "stretch",
+    justify: "flex-start",
+  },
+  argTypes: {
+    gap: {
+      control: "select",
+      options: [
+        "rec-none",
+        "rec-sm",
+        "rec-default",
+        "rec-md",
+        "rec-lg",
+        "rec-xl",
+        "rec-2xl",
+        "xs",
+        "sm",
+        "md",
+        "lg",
+        "xl",
+      ],
+      description: "Gap between elements",
+    },
+    align: {
+      control: "select",
+      options: ["flex-start", "center", "flex-end", "stretch"],
+      description: "Align-items property",
+    },
+    justify: {
+      control: "select",
+      options: [
+        "flex-start",
+        "center",
+        "flex-end",
+        "space-between",
+        "space-around",
+      ],
+      description: "Justify-content property",
+    },
+    defaultChecked: {
+      table: { disable: true },
+    },
+  },
+};
+
+export default meta;
+
+type Story = StoryObj<StackStoryProps>;
+
+export const Default: Story = {
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars, @typescript-eslint/no-explicit-any
+  render: ({ withLayer, layer, ...args }: any) => (
+    <Stack {...args}>
+      <Button variant="solid">Primary Block</Button>
+      <Button variant="outline">Secondary Block</Button>
+      <Text>Text element within Stack</Text>
+    </Stack>
+  ),
+};
+
+export const StaticGapSmall: Story = {
+  args: {
+    gap: "rec-sm",
+  },
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars, @typescript-eslint/no-explicit-any
+  render: ({ withLayer, layer, ...args }: any) => (
+    <Stack {...args}>
+      <Button variant="solid">Item 1</Button>
+      <Button variant="solid">Item 2</Button>
+      <Button variant="solid">Item 3</Button>
+    </Stack>
+  ),
+};
+
+export const StaticGapLarge: Story = {
+  args: {
+    gap: "rec-xl",
+  },
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars, @typescript-eslint/no-explicit-any
+  render: ({ withLayer, layer, ...args }: any) => (
+    <Stack {...args}>
+      <Button variant="solid">Item 1</Button>
+      <Button variant="solid">Item 2</Button>
+      <Button variant="solid">Item 3</Button>
+    </Stack>
+  ),
+};

package/src/components/Stack/Stack.tsx

@@ -0,0 +1,66 @@
+import React, { forwardRef } from "react";
+import {
+  Stack as MantineStack,
+  type StackProps as MantineStackProps,
+} from "@mantine/core";
+import {
+  filterStylingProps,
+  type RecursicaOverStyled,
+  type RecursicaSpacing,
+} from "../../utils/filterStylingProps";
+import styles from "./Stack.module.css";
+
+export interface RecursicaStackProps {
+  /**
+   * Children components inside the stack
+   */
+  children?: React.ReactNode;
+  gap?: MantineStackProps["gap"] | RecursicaSpacing;
+}
+
+/**
+ * Stack flex layout wrapper
+ */
+export type StackProps = RecursicaOverStyled<
+  MantineStackProps & RecursicaStackProps
+>;
+
+export const Stack = forwardRef<HTMLDivElement, StackProps>(function Stack(
+  { children, overStyled = false, gap = "rec-default", ...rest },
+  ref,
+) {
+  const sanitizedProps = filterStylingProps({ ...rest, gap }, overStyled);
+  const restRecord = sanitizedProps as Record<string, unknown>;
+
+  const mergedClassNames: Partial<Record<string, string>> = {
+    root: styles.root,
+  };
+
+  const classNamesProp = restRecord.classNames;
+  if (
+    classNamesProp &&
+    typeof classNamesProp === "object" &&
+    !Array.isArray(classNamesProp)
+  ) {
+    const o = classNamesProp as Partial<Record<string, string>>;
+    mergedClassNames.root = o.root ? `${styles.root} ${o.root}` : styles.root;
+  }
+
+  const classNameProp = restRecord.className as string | undefined;
+  const finalClass = classNameProp
+    ? `${styles.root} ${classNameProp}`
+    : styles.root;
+
+  return (
+    <MantineStack
+      ref={ref}
+      className={finalClass}
+      classNames={mergedClassNames}
+      {...sanitizedProps}
+    >
+      {children}
+    </MantineStack>
+  );
+});
+
+Stack.displayName = "Stack";

package/src/components/Stepper/Stepper.stories.tsx

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

package/src/components/Stepper/Stepper.tsx

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

package/src/components/Switch/SWITCH_IMPLEMENTATION_NOTES.md

@@ -0,0 +1,28 @@
+# Switch Implementation Notes
+
+This document acts as a living record tracking the layout decisions, architectural tradeoffs, and structural hacks explicitly applied to the `Switch` component wrapper to bridge Mantine's defaults with the Recursica UI Kit's rigid requirements.
+
+## 1. Stripping Mantine's Size Engine
+
+Mantine uses properties like `size`, `color`, and `radius` to dynamically map CSS layout values across its `.track` and `.thumb` nodes. We proactively strip and delete these properties using `filterStylingProps` to entirely neutralize this native behavior.
+
+## 2. Hardcoded Values & Transitions
+
+Mantine injects dynamic width/height attributes into its switch through inline CSS variables (e.g. `--switch-height`). To strictly enforce the UI Kit tokens without breaking Mantine's internal math, our `Switch.module.css` structurally remaps Mantine's internal variables explicitly:
+
+```css
+--switch-width: var(--switch-track-width);
+--switch-height: calc(
+  var(--switch-thumb-height) + (var(--switch-track-padding) * 2)
+);
+```
+
+We also hardcode `border: none` since the UI kit designs rely purely on box-shadow elevations and background color tracking. Mantine’s default border logic is entirely disabled.
+
+## 3. ReadOnly Behavior
+
+Similar to `Checkbox`, the `Switch` component handles `readOnly` presentation by dropping the entire underlying node tree and falling back structurally onto `<FormControlWrapper>` when `readOnly: true`. This strictly preserves exact baseline alignment across all primitives without trying to hack disabled CSS to look like read-only text.
+
+## 4. Hover State Reset
+
+Mantine forcefully triggers track hover color states globally. Since Recursica currently does not map specific hover states to switch backgrounds across themes (falling back to standard unselected tokens or simply providing a cursor), we structurally wipe out Mantine's `.track:hover` class block inside `Switch.module.css`.

package/src/components/Switch/Switch.module.css

@@ -0,0 +1,199 @@
+/* HARDCODED VALUES 
+ *
+ * 1. track border: none; (we do not use border for the switch track)
+ * 2. thumb border: none; (we do not use border for the thumb)
+ * 3. outline: none; (focus rings handled internally by mantine)
+ */
+
+.root {
+  /* Provide a stable cursor when not disabled */
+  cursor: pointer;
+
+  --switch-track-padding: var(
+    --recursica_ui-kit_components_switch_properties_track-inner-padding,
+    2px
+  );
+  --switch-thumb-width: var(
+    --recursica_ui-kit_components_switch_properties_thumb-width
+  );
+  --switch-thumb-height: var(
+    --recursica_ui-kit_components_switch_properties_thumb-height
+  );
+  --switch-track-width: var(
+    --recursica_ui-kit_components_switch_properties_track-width
+  );
+}
+
+.root[data-disabled] {
+  cursor: not-allowed;
+  opacity: var(--recursica_brand_states_disabled, 0.4);
+}
+
+.body {
+  display: flex;
+  align-items: center;
+  gap: var(--recursica_ui-kit_components_switch_properties_label-switch-gap);
+}
+
+/* HARDCODE: disable native hover color transitions applied by Mantine */
+.track:hover {
+  background-color: var(
+    --recursica_ui-kit_components_switch_properties_colors_track-unselected
+  );
+}
+.root input:checked + .track:hover {
+  background-color: var(
+    --recursica_ui-kit_components_switch_properties_colors_track-selected
+  );
+}
+
+.track {
+  width: var(--switch-track-width);
+  height: calc(var(--switch-thumb-height) + (var(--switch-track-padding) * 2));
+  border-radius: var(
+    --recursica_ui-kit_components_switch_properties_track-border-radius
+  );
+  background-color: var(
+    --recursica_ui-kit_components_switch_properties_colors_track-unselected
+  );
+  box-shadow: var(
+    --recursica_ui-kit_components_switch_properties_track-elevation,
+    none
+  );
+  padding: var(--switch-track-padding);
+  border: none; /* HARDCODE */
+
+  /* Mantine uses variables internally for these, but we explicitly override the CSS to ensure our dimensions */
+  --switch-width: var(--switch-track-width);
+  --switch-height: calc(
+    var(--switch-thumb-height) + (var(--switch-track-padding) * 2)
+  );
+  --switch-thumb-size: var(--switch-thumb-width);
+
+  display: flex;
+  align-items: center;
+  box-sizing: border-box;
+  transition: background-color 150ms ease;
+  cursor: inherit;
+}
+
+.root input:checked + .track {
+  background-color: var(
+    --recursica_ui-kit_components_switch_properties_colors_track-selected
+  );
+  border-color: transparent;
+}
+
+.thumb {
+  width: var(--switch-thumb-width);
+  height: var(--switch-thumb-height);
+  border-radius: var(
+    --recursica_ui-kit_components_switch_properties_thumb-border-radius
+  );
+  background-color: var(
+    --recursica_ui-kit_components_switch_properties_colors_thumb-unselected
+  );
+  box-shadow: var(
+    --recursica_ui-kit_components_switch_properties_thumb-elevation,
+    none
+  );
+  border: none; /* HARDCODE */
+
+  transition: background-color 150ms ease;
+}
+
+.root input:checked + .track .thumb {
+  background-color: var(
+    --recursica_ui-kit_components_switch_properties_colors_thumb-selected
+  );
+}
+
+.labelWrapper {
+  display: flex;
+  flex-direction: column;
+}
+
+.label {
+  font-family: var(
+    --recursica_ui-kit_components_switch_properties_label-text_font-family
+  );
+  font-size: var(
+    --recursica_ui-kit_components_switch_properties_label-text_font-size
+  );
+  font-weight: var(
+    --recursica_ui-kit_components_switch_properties_label-text_font-weight
+  );
+  font-style: var(
+    --recursica_ui-kit_components_switch_properties_label-text_font-style
+  );
+  line-height: var(
+    --recursica_ui-kit_components_switch_properties_label-text_line-height
+  );
+  letter-spacing: var(
+    --recursica_ui-kit_components_switch_properties_label-text_letter-spacing
+  );
+  text-transform: var(
+    --recursica_ui-kit_components_switch_properties_label-text_text-transform
+  );
+  text-decoration: var(
+    --recursica_ui-kit_components_switch_properties_label-text_text-decoration
+  );
+  cursor: inherit;
+}
+
+.thumbIconWrapper {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  width: 100%;
+  height: 100%;
+  position: relative;
+}
+
+.checkIcon,
+.closeIcon {
+  width: 10px;
+  height: 10px;
+  position: absolute;
+  transition:
+    opacity 150ms ease,
+    transform 150ms ease;
+}
+
+/* Unchecked state */
+.checkIcon {
+  opacity: 0;
+  transform: scale(0.5);
+  color: var(
+    --recursica_ui-kit_components_switch_properties_colors_track-selected
+  );
+}
+
+.closeIcon {
+  opacity: 1;
+  transform: scale(1);
+  color: var(
+    --recursica_ui-kit_components_switch_properties_colors_track-unselected
+  );
+}
+
+/* Checked state */
+.root input:checked + .track .thumb .checkIcon {
+  opacity: 1;
+  transform: scale(1);
+}
+
+.root input:checked + .track .thumb .closeIcon {
+  opacity: 0;
+  transform: scale(0.5);
+}
+
+.groupRoot {
+  display: flex;
+  flex-direction: column;
+  align-items: flex-start;
+  gap: var(
+    --recursica_ui-kit_components_switch_properties_label-switch-gap,
+    16px
+  );
+}

package/src/components/Switch/Switch.stories.tsx

@@ -0,0 +1,111 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { Switch } from "./Switch";
+import { Stack } from "../Stack/Stack";
+
+const meta: Meta<typeof Switch> = {
+  title: "UI-Kit/Switch",
+  component: Switch,
+  tags: ["autodocs"],
+  parameters: {
+    docs: {
+      description: {
+        component: `
+The \`Switch\` component is an atomic form primitive representing boolean states, natively aligned to the Recursica design system.
+
+> [!IMPORTANT]  
+> Unlike \`Checkbox\`, the \`Switch\` is typically used for standalone settings toggles. It fully supports the universal \`ReadOnlyField\` boundaries when passed the \`readOnly\` attribute.
+
+### Usage
+To render a standard switch:
+\`\`\`tsx
+<Switch label="Enable Notifications" defaultChecked />
+\`\`\`
+`,
+      },
+    },
+  },
+  argTypes: {
+    checked: {
+      control: "boolean",
+    },
+    required: {
+      control: "boolean",
+    },
+    error: {
+      control: "boolean",
+    },
+    defaultChecked: {
+      control: "boolean",
+    },
+    readOnly: {
+      control: "boolean",
+      description:
+        "Toggles structural read-only data presentation bypassing interaction boundaries completely.",
+    },
+    controlMaxWidth: { table: { disable: true } },
+    controlMinWidth: { table: { disable: true } },
+    emptyValueComponent: { table: { disable: true } },
+  },
+};
+
+export default meta;
+
+type Story = StoryObj<typeof Switch>;
+
+export const Default: Story = {
+  args: {
+    disabled: false,
+    label: "Standard Switch",
+  },
+  // We explicitly destructure global Storybook injected arguments so they do not leak into the DOM natively.
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars, @typescript-eslint/no-explicit-any
+  render: ({ withLayer, layer, ...args }: any) => <Switch {...args} />,
+};
+
+export const SideBySideLayout: Story = {
+  args: {
+    label: "Opt-in form alignment",
+    formLayout: "side-by-side",
+  },
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars, @typescript-eslint/no-explicit-any
+  render: ({ withLayer, layer, ...args }: any) => <Switch {...args} />,
+};
+
+export const StaticVariations: Story = {
+  args: {},
+  render: () => (
+    <Stack gap="xl">
+      <Switch label="Default Unchecked State" />
+      <Switch label="Checked State" defaultChecked />
+      <Switch label="Disabled Unchecked" disabled />
+      <Switch label="Disabled Checked" defaultChecked disabled />
+    </Stack>
+  ),
+};
+
+export const ReadOnly: Story = {
+  args: {
+    ...Default.args,
+    readOnly: true,
+  },
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars, @typescript-eslint/no-explicit-any
+  render: ({ withLayer, layer, ...args }: any) => <Switch {...args} />,
+};
+
+export const CustomReadOnly: Story = {
+  args: {
+    ...Default.args,
+    readOnly: true,
+  },
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars, @typescript-eslint/no-explicit-any
+  render: ({ withLayer, layer, ...args }: any) => (
+    <Switch
+      {...args}
+      readOnlyComponent={({ checked, label }) => (
+        <span style={{ fontWeight: "bold", color: checked ? "green" : "red" }}>
+          {label} {checked ? "ENABLED" : "DISABLED"}
+        </span>
+      )}
+    />
+  ),
+};

package/src/components/Switch/Switch.tsx

@@ -0,0 +1,168 @@
+import { forwardRef } from "react";
+import {
+  Switch as MantineSwitch,
+  type SwitchProps as MantineSwitchProps,
+  CheckIcon,
+  CloseIcon,
+} from "@mantine/core";
+import { type ReadOnlyControlProps } from "@recursica/adapter-common";
+
+import {
+  filterStylingProps,
+  type RecursicaOverStyled,
+} from "../../utils/filterStylingProps";
+import { type RequireAccessibleLabel } from "../../utils/RequireAccessibleLabel";
+import {
+  FormControlLayout,
+  type FormControlLayoutProps,
+} from "../FormControlLayout/FormControlLayout";
+import styles from "./Switch.module.css";
+
+import { SwitchGroup } from "./SwitchGroup";
+
+export type RecursicaSwitchProps = RequireAccessibleLabel<
+  Omit<MantineSwitchProps, "size" | "color" | "radius" | "variant"> &
+    ReadOnlyControlProps &
+    Pick<
+      FormControlLayoutProps,
+      "formLayout" | "labelSize" | "controlMaxWidth" | "controlMinWidth"
+    >
+>;
+
+export type SwitchProps = RecursicaOverStyled<RecursicaSwitchProps>;
+
+type SwitchComponent = React.ForwardRefExoticComponent<
+  SwitchProps & React.RefAttributes<HTMLInputElement>
+> & {
+  Group: typeof SwitchGroup;
+};
+
+export const Switch = forwardRef<HTMLInputElement, SwitchProps>(
+  function Switch(props, ref) {
+    const {
+      overStyled = false,
+      readOnly,
+      readOnlyComponent,
+      disabled,
+      thumbIcon,
+      formLayout,
+      labelSize,
+      controlMaxWidth,
+      controlMinWidth,
+      ...rest
+    } = props;
+    const sanitizedProps = filterStylingProps(rest, overStyled);
+    const restRecord = sanitizedProps as Record<string, unknown>;
+
+    // Actively delete dimension bindings that bypass the abstraction
+    delete restRecord["size"];
+    delete restRecord["color"];
+    delete restRecord["radius"];
+    delete restRecord["variant"];
+
+    const mergedClassNames: Partial<Record<string, string>> = {
+      root: styles.root,
+      body: styles.body,
+      track: styles.track,
+      thumb: styles.thumb,
+      trackLabel: styles.trackLabel,
+      labelWrapper: styles.labelWrapper,
+      label: styles.label,
+    };
+
+    const classNamesProp = restRecord.classNames;
+    if (
+      classNamesProp &&
+      typeof classNamesProp === "object" &&
+      !Array.isArray(classNamesProp)
+    ) {
+      const o = classNamesProp as Partial<Record<string, string>>;
+      mergedClassNames.root = o.root ? `${styles.root} ${o.root}` : styles.root;
+      mergedClassNames.body = o.body ? `${styles.body} ${o.body}` : styles.body;
+      mergedClassNames.track = o.track
+        ? `${styles.track} ${o.track}`
+        : styles.track;
+      mergedClassNames.thumb = o.thumb
+        ? `${styles.thumb} ${o.thumb}`
+        : styles.thumb;
+      mergedClassNames.trackLabel = o.trackLabel
+        ? `${styles.trackLabel} ${o.trackLabel}`
+        : styles.trackLabel;
+      mergedClassNames.labelWrapper = o.labelWrapper
+        ? `${styles.labelWrapper} ${o.labelWrapper}`
+        : styles.labelWrapper;
+      mergedClassNames.label = o.label
+        ? `${styles.label} ${o.label}`
+        : styles.label;
+    }
+
+    const classNameProp = restRecord.className as string | undefined;
+    const finalClass = classNameProp
+      ? `${styles.root} ${classNameProp}`
+      : styles.root;
+
+    if (readOnly && !!readOnlyComponent) {
+      const isChecked = !!(restRecord.checked ?? restRecord.defaultChecked);
+      const ReadOnlyComp = readOnlyComponent;
+      const roNode = (
+        <ReadOnlyComp
+          {...props}
+          checked={isChecked}
+          label={restRecord.label as React.ReactNode}
+        />
+      );
+
+      if (formLayout) {
+        return (
+          <FormControlLayout
+            formLayout={formLayout}
+            labelSize={labelSize}
+            controlMaxWidth={controlMaxWidth}
+            controlMinWidth={controlMinWidth}
+          >
+            {roNode}
+          </FormControlLayout>
+        );
+      }
+
+      return <>{roNode}</>;
+    }
+
+    const FinalThumbIcon = (
+      <div className={styles.thumbIconWrapper}>
+        <CheckIcon className={styles.checkIcon} />
+        <CloseIcon className={styles.closeIcon} />
+      </div>
+    );
+
+    // We omit Mantine's sizing/coloring so we rely strictly on variables from Switch.module.css
+    const switchNode = (
+      <MantineSwitch
+        ref={ref}
+        className={finalClass}
+        classNames={mergedClassNames}
+        disabled={readOnly || disabled}
+        thumbIcon={thumbIcon ?? FinalThumbIcon}
+        {...(sanitizedProps as unknown as MantineSwitchProps)}
+      />
+    );
+
+    if (formLayout) {
+      return (
+        <FormControlLayout
+          formLayout={formLayout}
+          labelSize={labelSize}
+          controlMaxWidth={controlMaxWidth}
+          controlMinWidth={controlMinWidth}
+        >
+          {switchNode}
+        </FormControlLayout>
+      );
+    }
+
+    return switchNode;
+  },
+) as SwitchComponent;
+
+Switch.displayName = "Switch";
+Switch.Group = SwitchGroup;