@recursica/mantine-adapter 0.9.3 → 0.10.0

package/src/components/Radio/Radio.tsx

@@ -0,0 +1,115 @@
+import { forwardRef } from "react";
+import {
+  Radio as MantineRadio,
+  type RadioProps as MantineRadioProps,
+} from "@mantine/core";
+import { type ReadOnlyControlProps } from "@recursica/adapter-common";
+import { RadioGroup } from "./RadioGroup";
+import {
+  filterStylingProps,
+  type RecursicaOverStyled,
+} from "../../utils/filterStylingProps";
+import styles from "./Radio.module.css";
+
+const RadioIcon: React.FC<{
+  className?: string;
+  style?: React.CSSProperties;
+}> = ({ className, style }) => (
+  <svg
+    xmlns="http://www.w3.org/2000/svg"
+    viewBox="0 0 16 16"
+    fill="currentColor"
+    className={className}
+    style={style}
+  >
+    <circle cx="8" cy="8" r="5" />
+  </svg>
+);
+
+export type RecursicaRadioProps = Omit<
+  MantineRadioProps,
+  "size" | "color" | "radius" | "iconColor" | "variant"
+> &
+  ReadOnlyControlProps;
+
+export type RadioProps = RecursicaOverStyled<RecursicaRadioProps>;
+
+type RadioComponent = React.ForwardRefExoticComponent<
+  RadioProps & React.RefAttributes<HTMLInputElement>
+> & {
+  Group: typeof RadioGroup;
+};
+
+export const Radio = forwardRef<HTMLInputElement, RadioProps>(function Radio(
+  { overStyled = false, readOnly, readOnlyComponent, disabled, ...rest },
+  ref,
+) {
+  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"];
+  delete restRecord["iconColor"];
+
+  if (readOnly && readOnlyComponent) {
+    // Safely fallback explicitly returning mapped elements natively without macro wrappers
+    return <>{readOnlyComponent}</>;
+  }
+
+  const mergedClassNames: Partial<Record<string, string>> = {
+    root: styles.root,
+    body: styles.body,
+    inner: styles.inner,
+    radio: styles.radio,
+    icon: styles.icon,
+    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.inner = o.inner
+      ? `${styles.inner} ${o.inner}`
+      : styles.inner;
+    mergedClassNames.radio = o.radio
+      ? `${styles.radio} ${o.radio}`
+      : styles.radio;
+    mergedClassNames.icon = o.icon ? `${styles.icon} ${o.icon}` : styles.icon;
+    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;
+
+  // We omit Mantine's sizing/coloring so we rely strictly on variables from Radio.module.css
+  return (
+    <MantineRadio
+      ref={ref}
+      icon={RadioIcon}
+      className={finalClass}
+      classNames={mergedClassNames}
+      disabled={readOnly || disabled}
+      {...(sanitizedProps as unknown as MantineRadioProps)}
+    />
+  );
+}) as RadioComponent;
+
+Radio.displayName = "Radio";
+Radio.Group = RadioGroup;

package/src/components/Radio/RadioGroup.stories.tsx

@@ -0,0 +1,98 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { Radio } from "./Radio";
+import { RadioGroup } from "./RadioGroup";
+import { useState } from "react";
+import { formControlArgTypes } from "../../../.storybook/commonArgTypes";
+
+const meta: Meta<typeof RadioGroup> = {
+  title: "UI-Kit/RadioGroup",
+  component: RadioGroup,
+  tags: ["autodocs"],
+  parameters: {
+    docs: {
+      description: {
+        component: `
+The \`RadioGroup\` component is the mandatory organizational wrapper aggregating multiple \`Radio\` primitives into structurally bound unified selection arrays. It inherently leverages the \`FormControlWrapper\` granting native access to macroscopic layout structuring, assistive descriptions, and strict flex arrays.
+
+We exclusively utilize the \`formLayout\` parameter to control macro-level form flow:
+- **\`formLayout="stacked"\`**: Top-to-bottom layout cascading the Label bounding box down vertically into a standard stacked radio column array.
+- **\`formLayout="side-by-side"\`**: Flow architecture pulling the grouping Label dynamically to the left while structurally organizing the internal radios cleanly alongside it horizontally.
+`,
+      },
+    },
+  },
+  argTypes: {
+    ...formControlArgTypes,
+    readOnly: {
+      control: "boolean",
+      description:
+        "Toggles structural read-only data presentation bypassing interaction boundaries completely.",
+    },
+  },
+};
+
+export default meta;
+
+type Story = StoryObj<typeof RadioGroup>;
+
+export const GroupStacked: Story = {
+  args: {
+    formLayout: "stacked",
+    required: true,
+    label: "Hosting Provider",
+    error: "You must select a deployment provider.",
+  },
+  render: function GroupStackedRender(args) {
+    const [value, setValue] = useState<string>("aws");
+    return (
+      <RadioGroup {...args} value={value} onChange={setValue}>
+        <Radio value="aws" label="Amazon Web Services" />
+        <Radio
+          value="gcp"
+          label="Google Cloud Platform (with completely distributed edge computing environments bridging local runtime boundaries seamlessly.)"
+        />
+        <Radio value="azure" label="Microsoft Azure" />
+      </RadioGroup>
+    );
+  },
+};
+
+export const GroupSideBySide: Story = {
+  args: {
+    formLayout: "side-by-side",
+    labelOptionalText: "Recommended",
+    labelWithEditIcon: true,
+    label: "Deployment Region",
+    assistiveText: "Select the data center closest to your user base.",
+  },
+  render: function GroupSideBySideRender(args) {
+    const [value, setValue] = useState<string>("us-east");
+    return (
+      <RadioGroup {...args} value={value} onChange={setValue}>
+        <Radio value="us-east" label="US East (N. Virginia)" />
+        <Radio value="us-west" label="US West (Oregon)" />
+        <Radio value="eu-central" label="EU Central (Frankfurt)" />
+      </RadioGroup>
+    );
+  },
+};
+
+export const StaticReadOnlyGroup: Story = {
+  args: {
+    readOnly: true,
+    formLayout: "stacked",
+    required: true,
+    label: "Selected Framework",
+    assistiveText: "This selection cannot be changed after initialization.",
+    readOnlyComponent: <span>React (Standard Build)</span>,
+  },
+  render: function StaticReadOnlyGroupRender(args) {
+    const [value, setValue] = useState<string>("react");
+    return (
+      <RadioGroup {...args} value={value} onChange={setValue}>
+        <Radio value="react" label="React" />
+        <Radio value="vue" label="Vue" />
+      </RadioGroup>
+    );
+  },
+};

package/src/components/Radio/RadioGroup.tsx

@@ -0,0 +1,138 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import React, { forwardRef } from "react";
+import {
+  Radio as MantineRadio,
+  type RadioGroupProps as MantineRadioGroupProps,
+} from "@mantine/core";
+import { type ReadOnlyControlProps } from "@recursica/adapter-common";
+import {
+  filterStylingProps,
+  type RecursicaOverStyled,
+} from "../../utils/filterStylingProps";
+import {
+  FormControlWrapper,
+  type RecursicaFormControlWrapperProps,
+} from "../FormControlWrapper/FormControlWrapper";
+import styles from "./Radio.module.css";
+
+export interface RecursicaRadioGroupProps
+  extends Omit<MantineRadioGroupProps, "size" | "labelProps">,
+    Omit<
+      RecursicaFormControlWrapperProps,
+      "controlMaxWidth" | "controlMinWidth"
+    >,
+    ReadOnlyControlProps {}
+
+export type RadioGroupProps = RecursicaOverStyled<RecursicaRadioGroupProps>;
+
+export const RadioGroup = forwardRef<HTMLDivElement, RadioGroupProps>(
+  function RadioGroup(
+    {
+      overStyled = false,
+      formLayout = "stacked",
+
+      // Label Wrappers
+      labelSize,
+      labelAlignment,
+      labelOptionalText,
+      labelWithEditIcon,
+      onLabelEditClick,
+
+      // Base Mantine Extracted Attributes
+      label,
+      description,
+      assistiveText,
+      assistiveWithIcon,
+      error,
+      required,
+      withAsterisk,
+      id,
+      className,
+      style,
+      children,
+      readOnly,
+      readOnlyComponent,
+      ...rest
+    },
+    ref,
+  ) {
+    const sanitizedProps = filterStylingProps(rest, overStyled);
+    const restRecord = sanitizedProps as Record<string, unknown>;
+
+    // Delete prohibited sizing hooks from bypassing the variables
+    delete restRecord["size"];
+
+    if (readOnly && readOnlyComponent) {
+      return (
+        <FormControlWrapper
+          className={className}
+          style={style as React.CSSProperties}
+          controlMaxWidth="var(--recursica_ui-kit_components_radio-button-item_properties_max-width)"
+          controlMinWidth={undefined}
+          overStyled={overStyled as true}
+          labelElement="div"
+          formLayout={formLayout}
+          labelSize={labelSize}
+          labelAlignment={labelAlignment}
+          labelOptionalText={labelOptionalText}
+          labelWithEditIcon={labelWithEditIcon}
+          onLabelEditClick={onLabelEditClick}
+          label={label}
+          description={description}
+          assistiveText={assistiveText}
+          assistiveWithIcon={assistiveWithIcon}
+          error={error}
+          required={required}
+          withAsterisk={withAsterisk}
+          id={id}
+        >
+          {readOnlyComponent}
+        </FormControlWrapper>
+      );
+    }
+
+    return (
+      <FormControlWrapper
+        className={className}
+        style={style as React.CSSProperties}
+        controlMaxWidth="var(--recursica_ui-kit_components_radio-button-item_properties_max-width)"
+        controlMinWidth={undefined}
+        overStyled={overStyled as true}
+        labelElement="div" // Strictly override. ARIA grouping prohibits interactive radios nested natively inside <label>.
+        formLayout={formLayout}
+        labelSize={labelSize}
+        labelAlignment={labelAlignment}
+        labelOptionalText={labelOptionalText}
+        labelWithEditIcon={labelWithEditIcon}
+        onLabelEditClick={onLabelEditClick}
+        label={label}
+        description={description}
+        assistiveText={assistiveText}
+        assistiveWithIcon={assistiveWithIcon}
+        error={error}
+        required={required}
+        withAsterisk={withAsterisk}
+        id={id}
+      >
+        <MantineRadio.Group
+          ref={ref}
+          /* Natively bind local disabled lock dynamically */
+          {...(sanitizedProps as unknown as MantineRadioGroupProps)}
+        >
+          <div className={styles.groupRoot} data-layout={formLayout}>
+            {React.Children.map(children, (child) => {
+              if (React.isValidElement(child)) {
+                return React.cloneElement(child as React.ReactElement<any>, {
+                  disabled: readOnly || (child.props as any).disabled,
+                });
+              }
+              return child;
+            })}
+          </div>
+        </MantineRadio.Group>
+      </FormControlWrapper>
+    );
+  },
+);
+
+RadioGroup.displayName = "RadioGroup";

package/src/components/ReadOnlyField/READ_ONLY_FIELD_IMPLEMENTATION_NOTES.md

@@ -0,0 +1,15 @@
+# ReadOnlyField Implementation Notes
+
+This document acts as a living record tracking edge cases and architectural choices made specific to the `ReadOnlyField` and its internal blocks (like `ReadOnlyTextField`).
+
+## 1. Stripping Mantine Assumptions
+
+Unlike standard input variables, standard HTML output `<p>` tags inherently carry margin and spacing assumptions from core browser stylesheets. To correctly map `ReadOnlyTextField` elements gracefully inside the generic `FormControlWrapper` bounded context, we hardcode resets:
+
+- `margin: 0` explicitly strips block flow gap so `FormControlWrapper` handles vertical rhythm.
+- `min-height`: Native `Input` boxes typically have baseline padding borders. We map directly to `var(--recursica_ui-kit_components_read-only-field_properties_min-height)` to ensure a side-by-side editable `TextField` and `ReadOnlyField` perfectly share roughly identical visual heights.
+
+## 2. Unidirectional Editable Mode
+
+The main wrapper intercepts `readOnly` boolean blocks, maintaining its own `isReadOnly` state. Natively, if a user clicks an exposed 'Edit' action (like our legacy SVG or custom `labelActionArea`), the context permanently switches to active.
+There is intentionally no built-in reverse toggle inside typical field bindings (like input "Blur") to revert state. Parents must pass external controls to `readOnly` forcing the internal hooks to reset via standard `useEffect` propagation.

package/src/components/ReadOnlyField/ReadOnlyField.module.css

@@ -0,0 +1,49 @@
+/* HARDCODED VALUES:
+   - margin: 0; padding: overrides native paragraph margins mapping back to form element flows.
+*/
+.textField {
+  margin: 0; /* HARDCODE: Reset paragraph margin; assume wrapper controls layout */
+  display: flex;
+  align-items: center;
+  word-break: break-word;
+  padding: 0; /* HARDCODE: read-only fields have no specific padding defined by tokens, zeroing it. */
+  font-family: var(
+    --recursica_ui-kit_components_read-only-field_properties_text_font-family,
+    inherit
+  );
+  font-size: var(
+    --recursica_ui-kit_components_read-only-field_properties_text_font-size,
+    1rem
+  );
+  font-weight: var(
+    --recursica_ui-kit_components_read-only-field_properties_text_font-weight,
+    normal
+  );
+  letter-spacing: var(
+    --recursica_ui-kit_components_read-only-field_properties_text_letter-spacing,
+    normal
+  );
+  line-height: var(
+    --recursica_ui-kit_components_read-only-field_properties_text_line-height,
+    1.5
+  );
+  font-style: var(
+    --recursica_ui-kit_components_read-only-field_properties_text_font-style,
+    normal
+  );
+  text-decoration: var(
+    --recursica_ui-kit_components_read-only-field_properties_text_text-decoration,
+    none
+  );
+  text-transform: var(
+    --recursica_ui-kit_components_read-only-field_properties_text_text-transform,
+    none
+  );
+  color: var(
+    --recursica_ui-kit_components_read-only-field_properties_colors_text
+  );
+  min-height: var(
+    --recursica_ui-kit_components_read-only-field_properties_min-height,
+    32px
+  );
+}

package/src/components/ReadOnlyField/ReadOnlyField.stories.tsx

@@ -0,0 +1,120 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import type { Meta, StoryObj } from "@storybook/react";
+import { ReadOnlyField } from "./ReadOnlyField";
+import { EmptyValueRenderer } from "@recursica/adapter-common";
+
+const meta: Meta<typeof ReadOnlyField> = {
+  title: "UI Kit/ReadOnlyField",
+  component: ReadOnlyField,
+  tags: ["autodocs"],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          "The ReadOnlyField safely natively wraps data sets bypassing active HTML interaction hooks while natively retaining exact bounding visual layouts defined by internal Design System Tokens. Useful for creating strict data-review profiles or conditional form read-overs.",
+      },
+    },
+  },
+  args: {
+    label: "Read Only Label",
+    value: "Fixed Data Set Value",
+    assistiveText: "Helper description text beneath the node.",
+    type: "text",
+  },
+  argTypes: {
+    type: {
+      control: "select",
+      options: ["text", "number"], // Add more as we support them
+    },
+    labelWithEditIcon: {
+      control: "boolean",
+    },
+    // We cannot natively control a React.ElementType through standard primitive storybook panels.
+  },
+};
+
+export default meta;
+
+type Story = StoryObj<typeof ReadOnlyField>;
+
+/**
+ * Playground story demonstrating standard structural blocks of the ReadOnlyField module dynamically.
+ */
+export const Default: Story = {
+  args: {},
+};
+
+/**
+ * Shows the default handler replacing missing mapping data directly with 'N/A'.
+ */
+export const EmptyValue: Story = {
+  args: {
+    value: "",
+    label: "Empty String Evaluated Automatically (Default 'N/A')",
+  },
+};
+
+const CustomEmptyTextRenderer: React.FC<{ value?: any }> & {
+  check?: (v: any) => boolean;
+} = (props) => <EmptyValueRenderer {...props} emptyText="No Data Found" />;
+CustomEmptyTextRenderer.check = EmptyValueRenderer.check;
+
+/**
+ * Demonstrates overriding the baseline verbiage internally utilizing the exported `EmptyValueRenderer` while inheriting default evaluation checks.
+ */
+export const CustomEmptyText: Story = {
+  args: {
+    value: null,
+    label: "Custom Empty Text Default",
+    emptyValueComponent: CustomEmptyTextRenderer,
+  },
+};
+
+const CustomEmptyCheckRenderer: React.FC<{ value?: any }> & {
+  check?: (v: any) => boolean;
+} = () => {
+  return <i>Custom HTML Markup Provided</i>;
+};
+CustomEmptyCheckRenderer.check = (val) => val === "EMPTY_MOCK";
+
+/**
+ * Validates a fully overridden emptyValueComponent injecting custom rendering boundaries alongside explicitly tailored validation rules evaluating datasets dynamically.
+ */
+export const CustomEmptyRenderer: Story = {
+  args: {
+    value: "EMPTY_MOCK",
+    label: "Custom Logic Evaluation Binding",
+    emptyValueComponent: CustomEmptyCheckRenderer,
+  },
+};
+
+/**
+ * Validates the core read-only label execution and base default spacing bindings globally.
+ */
+export const StackedDefault: Story = {
+  args: {
+    formLayout: "stacked",
+    value: "Some fixed readable text",
+  },
+};
+
+/**
+ * Binds side-by-side structures globally maintaining correct inline gutter layouts.
+ */
+export const SideBySide: Story = {
+  args: {
+    formLayout: "side-by-side",
+    value: "Some fixed readable text mapping horizontally",
+  },
+};
+
+/**
+ * Tests the fallback structural logic when Edit icon natively overrides required bindings.
+ */
+export const WithEditIcon: Story = {
+  args: {
+    labelWithEditIcon: true,
+    required: true,
+    value: "Editable fixed structure",
+  },
+};

package/src/components/ReadOnlyField/ReadOnlyField.tsx

@@ -0,0 +1,75 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import React, { forwardRef } from "react";
+import {
+  ReadOnlyFieldType,
+  EmptyValueRenderer,
+} from "@recursica/adapter-common";
+import {
+  filterStylingProps,
+  type RecursicaOverStyled,
+} from "../../utils/filterStylingProps";
+import {
+  type FormControlWrapperProps,
+  FormControlWrapper,
+} from "../FormControlWrapper/FormControlWrapper";
+import { ReadOnlyTextField } from "./ReadOnlyTextField";
+
+export interface RecursicaReadOnlyFieldProps
+  extends Omit<FormControlWrapperProps, "children" | "overStyled"> {
+  /** The specific value to be rendered in read-only mode explicitly matching the original field input */
+  value?: any;
+  /** The data type formatting rules bounding how the string is presented to the user */
+  type?: ReadOnlyFieldType;
+  /** Custom renderer explicitly responsible for formatting missing/empty value mappings (overriding default 'N/A') */
+  emptyValueComponent?: React.ElementType<{ value?: any }>;
+}
+
+export type ReadOnlyFieldProps =
+  RecursicaOverStyled<RecursicaReadOnlyFieldProps>;
+
+/**
+ * A native generic form control wrapper exclusively responsible for displaying fixed data.
+ * Internally maps to structural ReadOnly primitive blocks bridging standard `FormControlWrapper` layouts natively.
+ */
+export const ReadOnlyField = forwardRef<HTMLDivElement, ReadOnlyFieldProps>(
+  function ReadOnlyField(
+    { value, type = "text", emptyValueComponent, overStyled = false, ...rest },
+    ref,
+  ) {
+    let content: React.ReactNode = null;
+
+    // We still pass sanitized properties (like className/style/etc) strictly down.
+    const sanitizedProps = filterStylingProps(rest, overStyled);
+
+    const Renderer = emptyValueComponent || EmptyValueRenderer;
+    const isValueEmpty = (Renderer as any).check
+      ? (Renderer as any).check(value)
+      : EmptyValueRenderer.check(value);
+
+    const displayValue = isValueEmpty ? <Renderer value={value} /> : value;
+
+    switch (type) {
+      case "text":
+      default:
+        content = (
+          <ReadOnlyTextField
+            value={displayValue}
+            overStyled={overStyled as true}
+          />
+        );
+        break;
+    }
+
+    return (
+      <FormControlWrapper
+        ref={ref}
+        overStyled={overStyled as true}
+        {...(sanitizedProps as any)}
+      >
+        {content}
+      </FormControlWrapper>
+    );
+  },
+);
+
+ReadOnlyField.displayName = "ReadOnlyField";

package/src/components/ReadOnlyField/ReadOnlyTextField.tsx

@@ -0,0 +1,46 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import React from "react";
+import { Box } from "@mantine/core";
+import {
+  filterStylingProps,
+  type RecursicaOverStyled,
+} from "../../utils/filterStylingProps";
+import styles from "./ReadOnlyField.module.css";
+
+export interface RecursicaReadOnlyTextFieldProps {
+  /** The value strictly rendered as text output */
+  value?: any;
+}
+
+export type ReadOnlyTextFieldProps =
+  RecursicaOverStyled<RecursicaReadOnlyTextFieldProps>;
+
+export const ReadOnlyTextField: React.FC<ReadOnlyTextFieldProps> = ({
+  value,
+  overStyled = false,
+  ...rest
+}) => {
+  const sanitizedProps = filterStylingProps(rest, overStyled);
+  const classNameProp = (sanitizedProps as Record<string, unknown>)
+    .className as string | undefined;
+
+  return (
+    <Box
+      component="p"
+      className={
+        classNameProp
+          ? `${styles.textField} ${classNameProp}`
+          : styles.textField
+      }
+      {...sanitizedProps}
+    >
+      {value != null
+        ? React.isValidElement(value)
+          ? value
+          : String(value)
+        : ""}
+    </Box>
+  );
+};
+
+ReadOnlyTextField.displayName = "ReadOnlyTextField";