@recursica/mui-adapter 0.4.0 → 0.6.0

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

@@ -1,35 +1,194 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import React from "react";
 import type { Meta, StoryObj } from "@storybook/react";
 import { ReadOnlyField } from "./ReadOnlyField";
-import { ComingSoon } from "@recursica/storybook-template";
+import { EmptyValueRenderer } from "@recursica/adapter-common";
+import { formControlArgTypes } from "../../../.storybook/commonArgTypes";
 
 const meta: Meta<typeof ReadOnlyField> = {
-  title: "UI-Kit/🚧 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.",
+      },
+    },
     controls: {
       include: [
-        "layer",
-        "withLayer",
-        "children",
-        "component",
-        "variant",
-        "size",
-        "icon",
-        "disabled",
-        "href",
-        "onClick",
-        "onChange",
-        "value",
-        "checked",
+        "type",
+        "labelWithEditIcon",
+        "formLayout",
+        "labelSize",
+        "labelAlignment",
+        "labelOptionalText",
+        "required",
       ],
     },
   },
+  args: {
+    label: "Read Only Label",
+    value: "Fixed Data Set Value",
+    assistiveText: "Helper description text beneath the node.",
+    type: "text",
+  },
+  argTypes: {
+    ...formControlArgTypes,
+    type: {
+      control: "select",
+      options: ["text", "number", "boolean", "switch", "date"], // Add more as we support them
+    },
+    labelWithEditIcon: {
+      control: "boolean",
+    },
+  },
 };
 
 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: {},
+  render: ({ ...args }: any) => <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')",
+  },
+  render: ({ ...args }: any) => <ReadOnlyField {...args} />,
+};
+
+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,
+  },
+  render: ({ ...args }: any) => <ReadOnlyField {...args} />,
+};
+
+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,
+  },
+  render: ({ ...args }: any) => <ReadOnlyField {...args} />,
+};
+
+/**
+ * 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",
+  },
+  render: ({ ...args }: any) => <ReadOnlyField {...args} />,
+};
+
+/**
+ * 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",
+  },
+  render: ({ ...args }: any) => <ReadOnlyField {...args} />,
+};
+
+/**
+ * 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",
+  },
+  render: ({ ...args }: any) => <ReadOnlyField {...args} />,
+};
+
+/**
+ * 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: ({ ...args }: any) => (
+    <div style={{ display: "flex", flexDirection: "column", gap: "24px" }}>
+      <ReadOnlyField
+        {...args}
+        label="Text Mapping"
+        type="text"
+        value="Standard string output"
+      />
+      <ReadOnlyField
+        {...args}
+        label="Number Mapping"
+        type="number"
+        value={1234567.89}
+      />
+      <ReadOnlyField
+        {...args}
+        label="Date Mapping"
+        type="date"
+        value={new Date("2026-04-28T12:00:00Z").toLocaleDateString()}
+      />
+      <ReadOnlyField
+        {...args}
+        label="Boolean Mapping (True)"
+        type="boolean"
+        value={true}
+      />
+      <ReadOnlyField
+        {...args}
+        label="Boolean Mapping (False)"
+        type="boolean"
+        value={false}
+      />
+      <ReadOnlyField
+        {...args}
+        label="Switch Mapping (True -> On)"
+        type="switch"
+        value={true}
+      />
+      <ReadOnlyField
+        {...args}
+        label="Switch Mapping (False -> Off)"
+        type="switch"
+        value={false}
+      />
+    </div>
+  ),
 };

package/src/components/ReadOnlyField/ReadOnlyField.tsx

@@ -1,7 +1,112 @@
+/* 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";
 
-export type ReadOnlyFieldProps = React.HTMLAttributes<HTMLDivElement>;
+export type ReadOnlyFieldProps = Omit<
+  RecursicaFormControlWrapperProps,
+  "error" | "focused"
+> &
+  ReadOnlyControlProps & {
+    value?: any;
+    type?: "text" | "boolean" | "number" | "switch" | "date";
+  };
 
-export const ReadOnlyField: React.FC<ReadOnlyFieldProps> = (props) => {
-  return <div {...props}>ReadOnlyField</div>;
-};
+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}
+      >
+        <span className={styles.text}>N/A</span>
+      </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 (typeof value === "object") {
+    try {
+      displayValue = JSON.stringify(value);
+    } catch {
+      displayValue = String(value);
+    }
+  } else {
+    displayValue = String(value);
+  }
+
+  return (
+    <FormControlWrapper
+      ref={ref}
+      className={`${styles.root} ${className || ""}`}
+      {...wrapperProps}
+    >
+      <span className={styles.text}>{displayValue}</span>
+    </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"
+      className={
+        classNameProp
+          ? `${styles.textField} ${classNameProp}`
+          : styles.textField
+      }
+      {...sanitizedProps}
+    >
+      {value != null
+        ? React.isValidElement(value)
+          ? value
+          : Array.isArray(value)
+            ? value.join(", ")
+            : String(value)
+        : ""}
+    </Box>
+  );
+};
+
+ReadOnlyTextField.displayName = "ReadOnlyTextField";

package/src/components/ReadOnlyField/WithReadOnlyWrapper.tsx

@@ -0,0 +1,93 @@
+/* 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.ElementType<any>;
+  /** Custom renderer explicitly responsible for formatting missing/empty value mappings (overriding default 'N/A') */
+  emptyValueComponent?: React.ElementType<{ value?: any }>;
+  /** The full native props dictionary securely forwarded into the custom readOnlyComponent if active */
+  readOnlyNativeProps?: any;
+  /** 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 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,
+    readOnlyNativeProps,
+    emptyValueComponent,
+    activeComponent,
+    overStyled,
+    onLabelEditClick,
+    ...wrapperProps
+  },
+  ref,
+) {
+  if (readOnly) {
+    if (readOnlyComponent) {
+      const ReadOnlyComponent = readOnlyComponent;
+      return (
+        <FormControlWrapper
+          ref={ref}
+          {...wrapperProps}
+          onLabelEditClick={onLabelEditClick}
+          overStyled={overStyled as true}
+        >
+          <ReadOnlyComponent {...readOnlyNativeProps} />
+        </FormControlWrapper>
+      );
+    }
+
+    return (
+      <ReadOnlyField
+        ref={ref}
+        type={readOnlyType}
+        value={readOnlyValue}
+        emptyValueComponent={emptyValueComponent}
+        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

@@ -1 +1,2 @@
 export * from "./ReadOnlyField";
+export * from "./WithReadOnlyWrapper";

package/src/components/SegmentedControl/SegmentedControl.module.css

@@ -0,0 +1,203 @@
+/* HARDCODED VALUES:
+   - border-style: solid; on container and indicator
+   - background-color: transparent; on label hover (overriding Mantine)
+   - Scope prefix .root to enforce Figma tokens over Mantine's inline calculation without using !important
+*/
+
+.root {
+  background-color: var(
+    --recursica_ui-kit_components_segmented-control_properties_colors_background
+  );
+  border: var(
+      --recursica_ui-kit_components_segmented-control_properties_border-size
+    )
+    solid
+    var(
+      --recursica_ui-kit_components_segmented-control_properties_colors_border-color
+    );
+  border-radius: var(
+    --recursica_ui-kit_components_segmented-control_properties_border-radius
+  );
+  padding: var(
+      --recursica_ui-kit_components_segmented-control_properties_padding-vertical
+    )
+    var(
+      --recursica_ui-kit_components_segmented-control_properties_padding-horizontal
+    );
+  box-shadow: var(
+    --recursica_ui-kit_components_segmented-control_properties_elevation,
+    none
+  );
+  gap: var(--recursica_ui-kit_components_segmented-control_properties_item-gap);
+}
+
+.root .label {
+  padding-left: var(
+    --recursica_ui-kit_components_segmented-control-item_properties_item_padding-horizontal
+  );
+  padding-right: var(
+    --recursica_ui-kit_components_segmented-control-item_properties_item_padding-horizontal
+  );
+  height: var(
+    --recursica_ui-kit_components_segmented-control-item_properties_item_height
+  );
+  border-radius: var(
+    --recursica_ui-kit_components_segmented-control-item_properties_unselected_border-radius,
+    var(
+      --recursica_ui-kit_components_segmented-control-item_properties_item_border-radius
+    )
+  );
+
+  border: var(
+      --recursica_ui-kit_components_segmented-control-item_properties_unselected_border-size
+    )
+    solid
+    var(
+      --recursica_ui-kit_components_segmented-control-item_properties_unselected_colors_border-color
+    );
+  background-color: var(
+    --recursica_ui-kit_components_segmented-control-item_properties_unselected_colors_background
+  );
+  box-shadow: var(
+    --recursica_ui-kit_components_segmented-control-item_properties_unselected_elevation
+  );
+
+  font-family: var(
+    --recursica_ui-kit_components_segmented-control-item_properties_unselected-text_font-family,
+    inherit
+  );
+  font-size: var(
+    --recursica_ui-kit_components_segmented-control-item_properties_unselected-text_font-size,
+    inherit
+  );
+  font-style: var(
+    --recursica_ui-kit_components_segmented-control-item_properties_unselected-text_font-style,
+    inherit
+  );
+  font-weight: var(
+    --recursica_ui-kit_components_segmented-control-item_properties_unselected-text_font-weight,
+    inherit
+  );
+  letter-spacing: var(
+    --recursica_ui-kit_components_segmented-control-item_properties_unselected-text_letter-spacing,
+    inherit
+  );
+  line-height: var(
+    --recursica_ui-kit_components_segmented-control-item_properties_unselected-text_line-height,
+    inherit
+  );
+  text-decoration: var(
+    --recursica_ui-kit_components_segmented-control-item_properties_unselected-text_text-decoration,
+    inherit
+  );
+  text-transform: var(
+    --recursica_ui-kit_components_segmented-control-item_properties_unselected-text_text-transform,
+    inherit
+  );
+
+  color: var(
+    --recursica_ui-kit_components_segmented-control-item_properties_unselected_colors_text-color,
+    inherit
+  );
+
+  display: flex;
+  align-items: center;
+  justify-content: center;
+}
+
+/* Mantine natively wraps label contents in an innerLabel span */
+.root .label :global(.mantine-SegmentedControl-innerLabel) {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  gap: var(
+    --recursica_ui-kit_components_segmented-control-item_properties_item_icon-text-gap
+  );
+}
+
+.root .label svg {
+  width: var(
+    --recursica_ui-kit_components_segmented-control-item_properties_item_icon-size
+  );
+  height: var(
+    --recursica_ui-kit_components_segmented-control-item_properties_item_icon-size
+  );
+  flex-shrink: 0;
+}
+
+/* Mantine adds a background on hover, we must strictly strip it */
+.root .label:hover {
+  background-color: transparent;
+}
+
+/* Mantine adds separators via ::before on the .control */
+.root .control::before {
+  background-color: var(
+    --recursica_ui-kit_components_segmented-control_properties_colors_divider-color
+  );
+  width: var(
+    --recursica_ui-kit_components_segmented-control_properties_divider-size
+  );
+}
+
+/* Indicator (the moving selected block) */
+.root .indicator {
+  background-color: var(
+    --recursica_ui-kit_components_segmented-control-item_properties_selected_colors_background
+  );
+  border: var(
+      --recursica_ui-kit_components_segmented-control-item_properties_selected_border-size
+    )
+    solid
+    var(
+      --recursica_ui-kit_components_segmented-control-item_properties_selected_colors_border-color
+    );
+  box-shadow: var(
+    --recursica_ui-kit_components_segmented-control-item_properties_selected_elevation
+  );
+  border-radius: var(
+    --recursica_ui-kit_components_segmented-control-item_properties_selected_border-radius,
+    var(
+      --recursica_ui-kit_components_segmented-control-item_properties_item_border-radius
+    )
+  );
+}
+
+/* Selected label text color override */
+.root .control[data-active] .label {
+  color: var(
+    --recursica_ui-kit_components_segmented-control-item_properties_selected_colors_text-color
+  );
+  font-family: var(
+    --recursica_ui-kit_components_segmented-control-item_properties_selected-text_font-family,
+    inherit
+  );
+  font-size: var(
+    --recursica_ui-kit_components_segmented-control-item_properties_selected-text_font-size,
+    inherit
+  );
+  font-style: var(
+    --recursica_ui-kit_components_segmented-control-item_properties_selected-text_font-style,
+    inherit
+  );
+  font-weight: var(
+    --recursica_ui-kit_components_segmented-control-item_properties_selected-text_font-weight,
+    inherit
+  );
+  letter-spacing: var(
+    --recursica_ui-kit_components_segmented-control-item_properties_selected-text_letter-spacing,
+    inherit
+  );
+  line-height: var(
+    --recursica_ui-kit_components_segmented-control-item_properties_selected-text_line-height,
+    inherit
+  );
+  text-decoration: var(
+    --recursica_ui-kit_components_segmented-control-item_properties_selected-text_text-decoration,
+    inherit
+  );
+  text-transform: var(
+    --recursica_ui-kit_components_segmented-control-item_properties_selected-text_text-transform,
+    inherit
+  );
+}