@recursica/mui-adapter 0.5.0 → 0.7.0

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

@@ -0,0 +1,117 @@
+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 Default: Story = {
+  args: {
+    formLayout: "stacked",
+    label: "Standard Group",
+  },
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars, @typescript-eslint/no-explicit-any
+  render: function StoryRender({ withLayer, layer, ...args }: any) {
+    const [value, setValue] = useState<string>("");
+    return (
+      <RadioGroup {...args} value={value} onChange={setValue}>
+        <Radio value="1" label="Option 1" />
+        <Radio value="2" label="Option 2" />
+      </RadioGroup>
+    );
+  },
+};
+
+export const StackedLayout: Story = {
+  args: {
+    formLayout: "stacked",
+    required: true,
+    label: "Hosting Provider",
+    error: "You must select a deployment provider.",
+  },
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars, @typescript-eslint/no-explicit-any
+  render: function StoryRender({ withLayer, layer, ...args }: any) {
+    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 SideBySideLayout: Story = {
+  args: {
+    formLayout: "side-by-side",
+    labelOptionalText: "Recommended",
+    labelWithEditIcon: true,
+    label: "Deployment Region",
+    assistiveText: "Select the data center closest to your user base.",
+  },
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars, @typescript-eslint/no-explicit-any
+  render: function StoryRender({ withLayer, layer, ...args }: any) {
+    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 ReadOnly: Story = {
+  args: {
+    readOnly: true,
+    formLayout: "stacked",
+    required: true,
+    label: "Selected Framework",
+    assistiveText: "This selection cannot be changed after initialization.",
+  },
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars, @typescript-eslint/no-explicit-any
+  render: function StoryRender({ withLayer, layer, ...args }: any) {
+    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,125 @@
+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"
+      | "onChange"
+      | "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;
+    const sanitizedProps = filterStylingProps(rest, overStyled);
+    const restRecord = sanitizedProps as Record<string, unknown>;
+
+    // Delete prohibited sizing hooks from bypassing the variables
+    delete restRecord["size"];
+
+    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}
+        // 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/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

@@ -1,16 +1,54 @@
-/* EXEMPTIONS:
-   This component is a placeholder stub. Once fully implemented, its specific
-   tokens will be fully wired up to direct styles. */
+/* 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
+  );
+}
 
-/* recursica-ignore: --recursica_ui-kit_components_read-only-field_properties_colors_text */
-/* recursica-ignore: --recursica_ui-kit_components_read-only-field_properties_min-height */
-/* recursica-ignore: --recursica_ui-kit_components_read-only-field_properties_text_font-family */
-/* recursica-ignore: --recursica_ui-kit_components_read-only-field_properties_text_font-size */
-/* recursica-ignore: --recursica_ui-kit_components_read-only-field_properties_text_font-style */
-/* recursica-ignore: --recursica_ui-kit_components_read-only-field_properties_text_font-weight */
-/* recursica-ignore: --recursica_ui-kit_components_read-only-field_properties_text_letter-spacing */
-/* recursica-ignore: --recursica_ui-kit_components_read-only-field_properties_text_line-height */
-/* recursica-ignore: --recursica_ui-kit_components_read-only-field_properties_text_text-decoration */
-/* recursica-ignore: --recursica_ui-kit_components_read-only-field_properties_text_text-transform */
-/* recursica-ignore: --recursica_ui-kit_components_read-only-field_variants_layouts_side-by-side_properties_top-bottom-margin */
-/* recursica-ignore: --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
+  );
+
+  min-height: var(
+    --recursica_ui-kit_components_read-only-field_properties_min-height
+  );
+}

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

@@ -1,35 +1,163 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
 import type { Meta, StoryObj } from "@storybook/react";
 import { ReadOnlyField } from "./ReadOnlyField";
-import { ComingSoon } from "@recursica/storybook-template";
+import { EmptyValueRenderer } from "@recursica/adapter-common";
 
 const meta: Meta<typeof ReadOnlyField> = {
-  title: "UI-Kit/🚧 ReadOnlyField",
+  title: "UI Kit/ReadOnlyField",
   component: ReadOnlyField,
   tags: ["autodocs"],
   parameters: {
-    controls: {
-      include: [
-        "layer",
-        "withLayer",
-        "children",
-        "component",
-        "variant",
-        "size",
-        "icon",
-        "disabled",
-        "href",
-        "onClick",
-        "onChange",
-        "value",
-        "checked",
-      ],
+    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 = {
-  render: () => <ComingSoon componentName="ReadOnlyField" />,
+  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.tsx

@@ -1,8 +1,108 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
 import React from "react";
-import "./ReadOnlyField.module.css";
+import { type ReadOnlyControlProps } from "@recursica/adapter-common";
+import {
+  FormControlWrapper,
+  type RecursicaFormControlWrapperProps,
+} from "../FormControlWrapper/FormControlWrapper";
+import styles from "./ReadOnlyField.module.css";
 
-export type ReadOnlyFieldProps = React.HTMLAttributes<HTMLDivElement>;
+import { type RecursicaReadOnlyFieldProps as BaseRecursicaReadOnlyFieldProps } from "@recursica/adapter-common";
 
-export const ReadOnlyField: React.FC<ReadOnlyFieldProps> = (props) => {
-  return <div {...props}>ReadOnlyField</div>;
-};
+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;
+
+  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";