@recursica/adapter-mantine-v8 1.0.0

package/src/components/Radio/RadioGroup.tsx

@@ -0,0 +1,124 @@
+/* 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,
+  omitUnsupportedProps,
+  type RecursicaOverStyled,
+} from "../../utils/filterStylingProps";
+import { type RecursicaFormControlWrapperProps } from "../FormControlWrapper/FormControlWrapper";
+import { WithReadOnlyWrapper } from "../ReadOnlyField/WithReadOnlyWrapper";
+import styles from "./Radio.module.css";
+
+import { type RecursicaRadioGroupProps as BaseRecursicaRadioGroupProps } from "@recursica/adapter-common";
+
+export interface RecursicaRadioGroupProps
+  extends Omit<
+      MantineRadioGroupProps,
+      "size" | "labelProps" | "defaultValue" | "value"
+    >,
+    Omit<
+      RecursicaFormControlWrapperProps,
+      "controlMaxWidth" | "controlMinWidth"
+    >,
+    ReadOnlyControlProps,
+    BaseRecursicaRadioGroupProps {}
+
+export type RadioGroupProps = RecursicaOverStyled<RecursicaRadioGroupProps>;
+
+export const RadioGroup = forwardRef<HTMLDivElement, RadioGroupProps>(
+  function RadioGroup(props, ref) {
+    const {
+      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,
+      emptyValueComponent,
+      value,
+      defaultValue,
+      ...rest
+    } = props;
+    // Props this component intentionally doesn't support — deleted at runtime so they can't leak
+    // through even if a caller forces them via plain JavaScript, bypassing the `Omit<>` above.
+    const UNSUPPORTED_PROPS = [
+      "size", // Recursica controls sizing via Radio.module.css variables, not Mantine's native size scale.
+    ] as const satisfies readonly (keyof MantineRadioGroupProps)[];
+
+    const sanitizedProps = omitUnsupportedProps(
+      filterStylingProps(rest, overStyled) as Record<string, unknown>,
+      UNSUPPORTED_PROPS,
+    ) as Partial<typeof rest>;
+    const restRecord = sanitizedProps as Record<string, unknown>;
+
+    return (
+      <WithReadOnlyWrapper
+        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}
+        readOnly={readOnly && !!readOnlyComponent}
+        readOnlyComponent={readOnlyComponent}
+        emptyValueComponent={emptyValueComponent}
+        readOnlyType="text"
+        readOnlyValue={value !== undefined ? value : defaultValue}
+        readOnlyNativeProps={props}
+        activeComponent={
+          <MantineRadio.Group
+            ref={ref}
+            /* Natively bind local disabled lock dynamically */
+            {...(sanitizedProps as unknown as MantineRadioGroupProps)}
+            disabled={readOnly || (restRecord as any).disabled}
+            value={value as any}
+            defaultValue={defaultValue as any}
+          >
+            <div className={styles.groupRoot} data-layout={formLayout}>
+              {children}
+            </div>
+          </MantineRadio.Group>
+        }
+      />
+    );
+  },
+);
+
+RadioGroup.displayName = "RadioGroup";

package/src/components/Radio/USAGE.md

@@ -0,0 +1,36 @@
+# Radio - Usage Guide
+
+This document describes how to integrate and use the `Radio` component in your projects using `@recursica/adapter-mantine-v8`.
+
+---
+
+## 1. Import Reference
+
+```tsx
+import { Radio } from "@recursica/adapter-mantine-v8";
+```
+
+---
+
+## 2. Basic Example
+
+```tsx
+import React from "react";
+import { Radio } from "@recursica/adapter-mantine-v8";
+
+export default function Demo() {
+  return <Radio label="Option 1" name="radio-group" value="1" defaultChecked />;
+}
+```
+
+---
+
+## 3. Design System Integration
+
+All Recursica components in the `@recursica/adapter-mantine-v8` package adhere strictly to design system spacing, scaling, and behavior patterns.
+
+> [!IMPORTANT]
+>
+> - **Anti-override protection**: Rogues style injections (like inline `style` or arbitrary `className`) are automatically blocked by our prop layer unless `overStyled={true}` is explicitly provided.
+> - **No Direct Layers**: Do not pass a `layer` prop to this component. To place it on a specific visual layer, wrap it in a `<Layer layer={0|1|2|3}>` component natively.
+> - **Variables and Theming**: Styling is entirely determined by local CSS variables defined in `recursica_variables_scoped.css` and mapped in the component's CSS module.

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/ReadOnlyBooleanField.tsx

@@ -0,0 +1,21 @@
+import React from "react";
+import { Box } from "@mantine/core";
+import styles from "./ReadOnlyField.module.css";
+
+export const ReadOnlyBooleanField: React.FC<{
+  checked: boolean;
+  label?: React.ReactNode;
+}> = ({ checked, label }) => {
+  return (
+    <Box
+      component="span"
+      className={styles.textField}
+      style={{ display: "inline-flex", gap: "8px", alignItems: "baseline" }}
+    >
+      {label && <span style={{ fontWeight: 500 }}>{label}:</span>}
+      <span>{checked ? "True" : "False"}</span>
+    </Box>
+  );
+};
+
+ReadOnlyBooleanField.displayName = "ReadOnlyBooleanField";

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

@@ -0,0 +1,54 @@
+/* LAYOUT SPACING OVERRIDES:
+   - Sets the --form-control-margin-bottom spacing hook to map component-specific layout tokens. */
+.layoutOverride {
+  --form-control-margin-bottom: var(
+    --recursica_ui-kit_components_read-only-field_variants_layouts_stacked_properties_top-bottom-margin
+  );
+}
+
+.layoutOverride[data-form-layout="side-by-side"] {
+  --form-control-margin-bottom: var(
+    --recursica_ui-kit_components_read-only-field_variants_layouts_side-by-side_properties_top-bottom-margin
+  );
+}
+
+/* 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
+  );
+  font-size: var(
+    --recursica_ui-kit_components_read-only-field_properties_text_font-size
+  );
+  font-weight: var(
+    --recursica_ui-kit_components_read-only-field_properties_text_font-weight
+  );
+  letter-spacing: var(
+    --recursica_ui-kit_components_read-only-field_properties_text_letter-spacing
+  );
+  line-height: var(
+    --recursica_ui-kit_components_read-only-field_properties_text_line-height
+  );
+  font-style: var(
+    --recursica_ui-kit_components_read-only-field_properties_text_font-style
+  );
+  text-decoration: var(
+    --recursica_ui-kit_components_read-only-field_properties_text_text-decoration
+  );
+  text-transform: var(
+    --recursica_ui-kit_components_read-only-field_properties_text_text-transform
+  );
+  color: var(
+    --recursica_ui-kit_components_read-only-field_properties_colors_text-color
+  );
+  min-height: var(
+    --recursica_ui-kit_components_read-only-field_properties_min-height
+  );
+}

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

@@ -0,0 +1,163 @@
+/* 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",
+  },
+};
+
+/**
+ * Demonstrates how the generic ReadOnlyField handles mapping different internal data types.
+ * Currently, all types safely default to string extraction mapping into the text renderer natively.
+ */
+export const DataTypes: Story = {
+  args: {},
+  render: () => (
+    <div style={{ display: "flex", flexDirection: "column", gap: "24px" }}>
+      <ReadOnlyField
+        label="Text Mapping"
+        type="text"
+        value="Standard string output"
+      />
+      <ReadOnlyField label="Number Mapping" type="number" value={1234567.89} />
+      <ReadOnlyField
+        label="Date Mapping"
+        type="date"
+        value={new Date("2026-04-28T12:00:00Z").toLocaleDateString()}
+      />
+      <ReadOnlyField
+        label="Boolean Mapping (True)"
+        type="boolean"
+        value={true}
+      />
+      <ReadOnlyField
+        label="Boolean Mapping (False)"
+        type="boolean"
+        value={false}
+      />
+      <ReadOnlyField
+        label="Switch Mapping (True -> On)"
+        type="switch"
+        value={true}
+      />
+      <ReadOnlyField
+        label="Switch Mapping (False -> Off)"
+        type="switch"
+        value={false}
+      />
+    </div>
+  ),
+};

package/src/components/ReadOnlyField/ReadOnlyField.test.tsx

@@ -0,0 +1 @@
+// Placeholder for future ReadOnlyField component tests. Add tests here if/when needed.

package/src/components/ReadOnlyField/ReadOnlyField.tsx

@@ -0,0 +1,114 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import React, { forwardRef } from "react";
+import {
+  EmptyValueRenderer,
+  type ReadOnlyControlProps,
+} from "@recursica/adapter-common";
+import {
+  filterStylingProps,
+  type RecursicaOverStyled,
+} from "../../utils/filterStylingProps";
+import {
+  type FormControlWrapperProps,
+  FormControlWrapper,
+} from "../FormControlWrapper/FormControlWrapper";
+import { ReadOnlyTextField } from "./ReadOnlyTextField";
+import styles from "./ReadOnlyField.module.css";
+
+import { type RecursicaReadOnlyFieldProps as BaseRecursicaReadOnlyFieldProps } from "@recursica/adapter-common";
+
+export interface RecursicaReadOnlyFieldProps
+  extends Omit<
+      FormControlWrapperProps,
+      "children" | "overStyled" | "controlMaxWidth" | "controlMinWidth"
+    >,
+    Pick<ReadOnlyControlProps, "emptyValueComponent">,
+    BaseRecursicaReadOnlyFieldProps {}
+
+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,
+      className,
+      style,
+      ...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 as any} />
+    ) : (
+      value
+    );
+
+    switch (type) {
+      case "boolean":
+        content = (
+          <ReadOnlyTextField
+            value={
+              value === true ? "True" : value === false ? "False" : displayValue
+            }
+            overStyled={overStyled as true}
+          />
+        );
+        break;
+      case "switch":
+        content = (
+          <ReadOnlyTextField
+            value={
+              value === true ? "On" : value === false ? "Off" : displayValue
+            }
+            overStyled={overStyled as true}
+          />
+        );
+        break;
+      case "text":
+      default:
+        content = (
+          <ReadOnlyTextField
+            value={displayValue}
+            overStyled={overStyled as true}
+          />
+        );
+        break;
+    }
+
+    const wrapperClass = className
+      ? `${styles.layoutOverride} ${className}`
+      : styles.layoutOverride;
+
+    return (
+      <FormControlWrapper
+        ref={ref}
+        {...(sanitizedProps as any)}
+        overStyled={overStyled as true}
+        className={wrapperClass}
+        style={style}
+      >
+        {content}
+      </FormControlWrapper>
+    );
+  },
+);
+
+ReadOnlyField.displayName = "ReadOnlyField";

package/src/components/ReadOnlyField/ReadOnlySwitchField.tsx

@@ -0,0 +1,21 @@
+import React from "react";
+import { Box } from "@mantine/core";
+import styles from "./ReadOnlyField.module.css";
+
+export const ReadOnlySwitchField: React.FC<{
+  checked: boolean;
+  label?: React.ReactNode;
+}> = ({ checked, label }) => {
+  return (
+    <Box
+      component="span"
+      className={styles.textField}
+      style={{ display: "inline-flex", gap: "8px", alignItems: "baseline" }}
+    >
+      {label && <span style={{ fontWeight: 500 }}>{label}:</span>}
+      <span>{checked ? "On" : "Off"}</span>
+    </Box>
+  );
+};
+
+ReadOnlySwitchField.displayName = "ReadOnlySwitchField";

package/src/components/ReadOnlyField/ReadOnlyTextField.tsx

@@ -0,0 +1,48 @@
+/* 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"
+      {...sanitizedProps}
+      className={
+        classNameProp
+          ? `${styles.textField} ${classNameProp}`
+          : styles.textField
+      }
+    >
+      {value != null
+        ? React.isValidElement(value)
+          ? value
+          : Array.isArray(value)
+            ? value.join(", ")
+            : String(value)
+        : ""}
+    </Box>
+  );
+};
+
+ReadOnlyTextField.displayName = "ReadOnlyTextField";

package/src/components/ReadOnlyField/USAGE.md

@@ -0,0 +1,44 @@
+# ReadOnlyField - Usage Guide
+
+This document describes how to integrate and use the `ReadOnlyField` component in your projects using `@recursica/adapter-mantine-v8`.
+
+---
+
+## 1. Import Reference
+
+```tsx
+import { ReadOnlyField } from "@recursica/adapter-mantine-v8";
+```
+
+---
+
+## 2. Basic Example
+
+```tsx
+import React from "react";
+import { ReadOnlyField } from "@recursica/adapter-mantine-v8";
+
+export default function Demo() {
+  return <ReadOnlyField label="API Key" value="sk_test_123456789" copyable />;
+}
+```
+
+---
+
+## 3. Design System Integration
+
+All Recursica components in the `@recursica/adapter-mantine-v8` package adhere strictly to design system spacing, scaling, and behavior patterns.
+
+> [!IMPORTANT]
+>
+> - **Anti-override protection**: Rogues style injections (like inline `style` or arbitrary `className`) are automatically blocked by our prop layer unless `overStyled={true}` is explicitly provided.
+> - **No Direct Layers**: Do not pass a `layer` prop to this component. To place it on a specific visual layer, wrap it in a `<Layer layer={0|1|2|3}>` component natively.
+> - **Variables and Theming**: Styling is entirely determined by local CSS variables defined in `recursica_variables_scoped.css` and mapped in the component's CSS module.
+
+---
+
+## 4. Key Integration Features & Constraints
+
+### Editable Mode
+
+If an edit action (e.g. via `labelActionArea`) is used to let a user switch a field from read-only to editable, that switch is one-directional in the UI — there is no built-in control (such as blurring the input) that switches it back to read-only. To revert to read-only, the parent must pass an updated `readOnly` value.