@recursica/mantine-adapter 0.9.3 → 0.10.0

package/src/components/ReadOnlyField/WithReadOnlyWrapper.tsx

@@ -0,0 +1,85 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import React, { forwardRef } from "react";
+import { type ReadOnlyFieldType } from "@recursica/adapter-common";
+import {
+  FormControlWrapper,
+  type FormControlWrapperProps,
+} from "../FormControlWrapper/FormControlWrapper";
+import { ReadOnlyField } from "./ReadOnlyField";
+
+export interface WithReadOnlyWrapperProps
+  extends Omit<FormControlWrapperProps, "children" | "overStyled"> {
+  /** Injects whether the field defaults to reading mode natively */
+  readOnly?: boolean;
+  /** Explicit React component directly overtaking the baseline text renderer when read-only mode is active */
+  readOnlyComponent?: React.ReactNode;
+  /** Instructs the underlying generic ReadOnlyField which raw visual structure to bridge automatically */
+  readOnlyType?: ReadOnlyFieldType;
+  /** The isolated raw data value intercepted explicitly into the ReadOnly formatters */
+  readOnlyValue?: any;
+  /** Safely enables deep Mantine overrides transparently bypassing block filters */
+  overStyled?: boolean;
+  /** The nested active node dynamically exposed exclusively when read-only bounds are disabled */
+  activeComponent: React.ReactNode;
+}
+
+/**
+ * Universal execution barrier trapping readOnly states globally.
+ * Natively delegates active logic down avoiding duplicative internal component bindings dynamically.
+ */
+export const WithReadOnlyWrapper = forwardRef<
+  HTMLDivElement,
+  WithReadOnlyWrapperProps
+>(function WithReadOnlyWrapper(
+  {
+    readOnly,
+    readOnlyComponent,
+    readOnlyType = "text",
+    readOnlyValue,
+    activeComponent,
+    overStyled,
+    onLabelEditClick,
+    ...wrapperProps
+  },
+  ref,
+) {
+  if (readOnly) {
+    if (readOnlyComponent) {
+      return (
+        <FormControlWrapper
+          ref={ref}
+          {...wrapperProps}
+          onLabelEditClick={onLabelEditClick}
+          overStyled={overStyled as true}
+        >
+          {readOnlyComponent}
+        </FormControlWrapper>
+      );
+    }
+
+    return (
+      <ReadOnlyField
+        ref={ref}
+        type={readOnlyType}
+        value={readOnlyValue}
+        onLabelEditClick={onLabelEditClick}
+        overStyled={overStyled as true}
+        {...wrapperProps}
+      />
+    );
+  }
+
+  // Active Standard Execution natively forwarding bound children implicitly
+  return (
+    <FormControlWrapper
+      ref={ref}
+      {...wrapperProps}
+      onLabelEditClick={onLabelEditClick}
+      overStyled={overStyled as true}
+    >
+      {activeComponent}
+    </FormControlWrapper>
+  );
+});
+
+WithReadOnlyWrapper.displayName = "WithReadOnlyWrapper";

package/src/components/ReadOnlyField/index.ts

@@ -0,0 +1,3 @@
+export * from "./ReadOnlyField";
+export * from "./WithReadOnlyWrapper";
+export * from "./ReadOnlyTextField";

package/src/components/Search/Search.stories.tsx

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

package/src/components/Search/Search.tsx

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

package/src/components/SegmentedControl/SegmentedControl.stories.tsx

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

package/src/components/SegmentedControl/SegmentedControl.tsx

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

package/src/components/Slider/Slider.stories.tsx

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

package/src/components/Slider/Slider.tsx

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

package/src/components/Stack/STACK_IMPLEMENTATION_NOTES.md

@@ -0,0 +1,4 @@
+# Stack Implementation Notes
+
+The `Stack` component is a generic flex layout wrapper mapped directly to Mantine's `Stack`.
+It currently does not require any custom logical layouts or CSS workarounds since it serves only to organize layout structure, and doesn't enforce any strict design-system token styling itself. All gap, align, and justify properties pass safely through via the `filterStylingProps` layout-property allowance.

package/src/components/Stack/Stack.module.css

@@ -0,0 +1,7 @@
+/* HARDCODED VALUES:
+ * None. This is a generic flex layout wrapper.
+ */
+
+.root {
+  /* Mantine handles flex, gap, align, justify. No intrinsic design-system styles required for pure layout wrappers. */
+}

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

@@ -0,0 +1,105 @@
+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 = {
+  render: (args) => (
+    <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",
+  },
+  render: (args) => (
+    <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",
+  },
+  render: (args) => (
+    <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,207 @@
+/* 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;
+  gap: var(
+    --recursica_ui-kit_components_switch_properties_label-switch-gap,
+    16px
+  );
+}
+
+.groupRoot[data-layout="stacked"] {
+  flex-direction: column;
+  align-items: flex-start;
+}
+
+.groupRoot[data-layout="side-by-side"] {
+  flex-direction: row;
+  align-items: center;
+}