@recursica/adapter-mui-v7 1.0.0

package/src/components/Radio/RadioGroup.tsx

@@ -0,0 +1,122 @@
+import React, { forwardRef } from "react";
+import {
+  // Removed unused Radio import
+  RadioGroup as MuiRadioGroup,
+  type RadioGroupProps as MuiRadioGroupProps,
+} from "@mui/material";
+import { type ReadOnlyControlProps } from "@recursica/adapter-common";
+import {
+  filterStylingProps,
+  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<
+      MuiRadioGroupProps,
+      "size" | "labelProps" | "classes" | "ref" | "value" | "defaultValue"
+    >,
+    Omit<
+      RecursicaFormControlWrapperProps,
+      | "controlMaxWidth"
+      | "controlMinWidth"
+      | "classes"
+      | "onChange"
+      | keyof MuiRadioGroupProps
+    >,
+    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 Mui Extracted Attributes
+      label,
+      description,
+      assistiveText,
+      assistiveWithIcon,
+      error,
+      // eslint-disable-next-line @typescript-eslint/no-unused-vars
+      required,
+      // Removed withAsterisk as it is not supported natively in this interface
+      id,
+      className,
+      style,
+      children,
+      readOnly,
+      readOnlyComponent,
+      emptyValueComponent,
+      value,
+      defaultValue,
+      ...rest
+    } = props;
+    // NOTE: MuiRadioGroupProps (via FormGroupProps) has no native "size" (or other
+    // Recursica-unsupported) prop to leak through here — nothing to add to an UNSUPPORTED_PROPS
+    // list beyond what filterStylingProps already blocks.
+    const sanitizedProps = filterStylingProps(rest, overStyled);
+
+    return (
+      <WithReadOnlyWrapper
+        className={className}
+        style={style as React.CSSProperties}
+        // Not the group's own row width: this token caps a single radio+its own label (applied
+        // per-item in Radio.module.css's `.root`). The group has no max-width token of its own
+        // in the schema, so this must stay undefined or FormControlLayout caps the whole
+        // label+items row (including the group's own label) at 400px in side-by-side layout.
+        controlMaxWidth={undefined}
+        controlMinWidth={undefined}
+        overStyled={overStyled as true}
+        // 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}
+        id={id}
+        readOnly={readOnly && !!readOnlyComponent}
+        readOnlyComponent={readOnlyComponent}
+        emptyValueComponent={emptyValueComponent}
+        readOnlyType="text"
+        readOnlyValue={value !== undefined ? value : defaultValue}
+        readOnlyNativeProps={props}
+        activeComponent={
+          <MuiRadioGroup
+            ref={ref}
+            /* Natively bind local disabled lock dynamically */
+            {...(sanitizedProps as unknown as MuiRadioGroupProps)}
+            value={value}
+            defaultValue={defaultValue}
+            className={styles.groupRoot}
+            data-layout={formLayout}
+          >
+            {children}
+          </MuiRadioGroup>
+        }
+      />
+    );
+  },
+);
+
+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-mui-v7`.
+
+---
+
+## 1. Import Reference
+
+```tsx
+import { Radio } from "@recursica/adapter-mui-v7";
+```
+
+---
+
+## 2. Basic Example
+
+```tsx
+import React from "react";
+import { Radio } from "@recursica/adapter-mui-v7";
+
+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-mui-v7` 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/Radio/index.ts

@@ -0,0 +1,2 @@
+export * from "./Radio";
+export * from "./RadioGroup";

package/src/components/ReadOnlyField/ReadOnlyBooleanField.tsx

@@ -0,0 +1,21 @@
+import React from "react";
+import { Box } from "@mui/material";
+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. */
+.root {
+  width: 100%;
+  --form-control-margin-bottom: var(
+    --recursica_ui-kit_components_read-only-field_variants_layouts_stacked_properties_top-bottom-margin
+  );
+}
+
+.root[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
+  );
+}
+
+.text {
+  margin: 0;
+  padding: 0;
+  display: flex;
+  align-items: center;
+  word-break: break-word;
+
+  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-style: var(
+    --recursica_ui-kit_components_read-only-field_properties_text_font-style
+  );
+  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
+  );
+  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,108 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import React from "react";
+import { type ReadOnlyControlProps } from "@recursica/adapter-common";
+import {
+  FormControlWrapper,
+  type RecursicaFormControlWrapperProps,
+} from "../FormControlWrapper/FormControlWrapper";
+import styles from "./ReadOnlyField.module.css";
+
+import { type RecursicaReadOnlyFieldProps as BaseRecursicaReadOnlyFieldProps } from "@recursica/adapter-common";
+
+export type ReadOnlyFieldProps = Omit<
+  RecursicaFormControlWrapperProps,
+  "error" | "focused" | "controlMaxWidth" | "controlMinWidth"
+> &
+  ReadOnlyControlProps &
+  BaseRecursicaReadOnlyFieldProps;
+
+export const ReadOnlyField = React.forwardRef<
+  HTMLDivElement,
+  ReadOnlyFieldProps
+>(function ReadOnlyField(props, ref) {
+  const {
+    value,
+    type = "text",
+    readOnlyComponent,
+    emptyValueComponent,
+    className,
+    ...wrapperProps
+  } = props;
+
+  // Custom empty component bypass map handling dynamically explicitly
+  if (emptyValueComponent && typeof emptyValueComponent !== "string") {
+    const CustomEmptyRenderer = emptyValueComponent as React.FC<any> & {
+      check?: (val: any) => boolean;
+    };
+    if (CustomEmptyRenderer.check && CustomEmptyRenderer.check(value)) {
+      return (
+        <FormControlWrapper
+          ref={ref}
+          className={`${styles.root} ${className || ""}`}
+          {...wrapperProps}
+        >
+          <CustomEmptyRenderer value={value} />
+        </FormControlWrapper>
+      );
+    }
+  }
+
+  // Value missing check mapping Default 'N/A' behavior mapping natively
+  const isMissing =
+    value === undefined ||
+    value === null ||
+    value === "" ||
+    (Array.isArray(value) && value.length === 0);
+
+  if (isMissing) {
+    return (
+      <FormControlWrapper
+        ref={ref}
+        className={`${styles.root} ${className || ""}`}
+        {...wrapperProps}
+      >
+        <p className={styles.text}>N/A</p>
+      </FormControlWrapper>
+    );
+  }
+
+  // Override execution mapping securely
+  if (readOnlyComponent) {
+    const CustomReadOnlyRenderer = readOnlyComponent as React.ElementType;
+    return (
+      <FormControlWrapper
+        ref={ref}
+        className={`${styles.root} ${className || ""}`}
+        {...wrapperProps}
+      >
+        <CustomReadOnlyRenderer value={value as any} />
+      </FormControlWrapper>
+    );
+  }
+
+  // Type coercions securely bounding the output values cleanly explicitly.
+  let displayValue: React.ReactNode = value as any;
+
+  if (type === "boolean" || type === "switch") {
+    displayValue = value ? "True" : "False";
+    if (type === "switch") {
+      displayValue = value ? "On" : "Off";
+    }
+  } else if (Array.isArray(value)) {
+    displayValue = value.join(", ");
+  } else {
+    displayValue = String(value);
+  }
+
+  return (
+    <FormControlWrapper
+      ref={ref}
+      className={`${styles.root} ${className || ""}`}
+      {...wrapperProps}
+    >
+      <p className={styles.text}>{displayValue}</p>
+    </FormControlWrapper>
+  );
+});
+
+ReadOnlyField.displayName = "ReadOnlyField";

package/src/components/ReadOnlyField/ReadOnlySwitchField.tsx

@@ -0,0 +1,21 @@
+import React from "react";
+import { Box } from "@mui/material";
+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 "@mui/material";
+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,36 @@
+# ReadOnlyField - Usage Guide
+
+This document describes how to integrate and use the `ReadOnlyField` component in your projects using `@recursica/adapter-mui-v7`.
+
+---
+
+## 1. Import Reference
+
+```tsx
+import { ReadOnlyField } from "@recursica/adapter-mui-v7";
+```
+
+---
+
+## 2. Basic Example
+
+```tsx
+import React from "react";
+import { ReadOnlyField } from "@recursica/adapter-mui-v7";
+
+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-mui-v7` 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.