@recursica/mui-adapter 0.5.0 → 0.6.0

package/src/components/TextArea/TextArea.tsx

@@ -1,8 +1,158 @@
-import React from "react";
-import "./TextArea.module.css";
+import React, { forwardRef } from "react";
+import {
+  TextField as MuiTextarea,
+  type TextFieldProps as MuiTextareaProps,
+} from "@mui/material";
+import { type ReadOnlyControlProps } from "@recursica/adapter-common";
+import { TextField } from "@mui/material";
+import {
+  filterStylingProps,
+  type RecursicaOverStyled,
+} from "../../utils/filterStylingProps";
+import { type RecursicaFormControlWrapperProps } from "../FormControlWrapper/FormControlWrapper";
+import { WithReadOnlyWrapper } from "../ReadOnlyField/WithReadOnlyWrapper";
+import styles from "./TextArea.module.css";
 
-export type TextAreaProps = React.HTMLAttributes<HTMLDivElement>;
+export interface RecursicaTextAreaProps
+  extends Omit<
+      MuiTextareaProps,
+      "size" | "variant" | "radius" | "wrapperProps"
+    >,
+    Pick<
+      RecursicaFormControlWrapperProps,
+      | "assistiveText"
+      | "assistiveWithIcon"
+      | "formLayout"
+      | "labelSize"
+      | "labelAlignment"
+      | "labelOptionalText"
+      | "labelWithEditIcon"
+      | "onLabelEditClick"
+    >,
+    ReadOnlyControlProps {
+  /** Maximum rows for autosize textarea to grow */
+  maxRows?: number;
+  /** Minimum rows of autosize textarea */
+  minRows?: number;
+  /** If set, enables textarea height growing with its content */
+  autosize?: boolean;
+}
 
-export const TextArea: React.FC<TextAreaProps> = (props) => {
-  return <div {...props}>TextArea</div>;
-};
+export type TextAreaProps = RecursicaOverStyled<RecursicaTextAreaProps>;
+
+export const TextArea = forwardRef<HTMLTextAreaElement, TextAreaProps>(
+  function TextArea(props, ref) {
+    const {
+      overStyled = false,
+      formLayout = "stacked",
+
+      // Label & Wrapper Maps
+      labelSize,
+      labelAlignment,
+      labelOptionalText,
+      labelWithEditIcon,
+      onLabelEditClick,
+
+      label,
+      assistiveText,
+      assistiveWithIcon,
+      error,
+      required,
+      withAsterisk,
+      id,
+      className,
+      style,
+      disabled,
+      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 variables natively
+    delete restRecord["size"];
+    delete restRecord["variant"];
+    delete restRecord["radius"];
+
+    // Securely map core native blocks down ensuring nested CSS modules map precisely
+    const mergedClassNames: Partial<Record<string, string>> = {
+      wrapper: styles.root, // The nested Input internal relative wrapper bounding box
+      input: styles.input,
+    };
+
+    const classNamesProp = restRecord.classNames;
+    if (
+      classNamesProp &&
+      typeof classNamesProp === "object" &&
+      !Array.isArray(classNamesProp)
+    ) {
+      const o = classNamesProp as Partial<Record<string, string>>;
+      mergedClassNames.wrapper = o.wrapper
+        ? `${styles.root} ${o.wrapper}`
+        : styles.root;
+      mergedClassNames.input = o.input
+        ? `${styles.input} ${o.input}`
+        : styles.input;
+    }
+
+    const wrapperClass = className
+      ? `${styles.layoutOverride} ${className}`
+      : styles.layoutOverride;
+
+    return (
+      <WithReadOnlyWrapper
+        className={wrapperClass}
+        style={style as React.CSSProperties}
+        controlMaxWidth="var(--recursica_ui-kit_components_textarea_properties_max-width)"
+        controlMinWidth="var(--recursica_ui-kit_components_textarea_properties_min-width)"
+        overStyled={overStyled as true}
+        formLayout={formLayout}
+        labelSize={labelSize}
+        labelAlignment={labelAlignment}
+        labelOptionalText={labelOptionalText}
+        labelWithEditIcon={labelWithEditIcon}
+        onLabelEditClick={onLabelEditClick}
+        label={label}
+        assistiveText={assistiveText}
+        assistiveWithIcon={assistiveWithIcon}
+        error={error}
+        required={required}
+        withAsterisk={withAsterisk}
+        id={id}
+        readOnly={readOnly}
+        readOnlyComponent={readOnlyComponent}
+        emptyValueComponent={emptyValueComponent}
+        readOnlyType="text"
+        readOnlyValue={value !== undefined ? value : defaultValue}
+        readOnlyNativeProps={props}
+        activeComponent={
+          /* Naked Input execution safely decoupled from Mui's macro Input.Wrapper DOM hooks */
+          <MuiTextarea
+            multiline
+            ref={ref}
+            classes={mergedClassNames}
+            disabled={disabled}
+            value={value}
+            defaultValue={defaultValue}
+            label={undefined}
+            description={undefined}
+            error={undefined}
+            required={undefined}
+            withAsterisk={undefined}
+            wrapperProps={{
+              "data-disabled": disabled ? "true" : undefined,
+              "data-error": error ? "true" : undefined,
+            }}
+            {...(sanitizedProps as unknown as MuiTextareaProps)}
+          />
+        }
+      />
+    );
+  },
+);
+
+TextArea.displayName = "TextArea";

package/src/components/TextField/TextField.module.css

@@ -1,47 +1,266 @@
 /* EXEMPTIONS:
-   This component is a placeholder stub. Once fully implemented, its specific
-   tokens will be fully wired up to direct styles. */
-
-/* recursica-ignore: --recursica_ui-kit_components_text-field_properties_border-radius */
-/* recursica-ignore: --recursica_ui-kit_components_text-field_properties_horizontal-padding */
-/* recursica-ignore: --recursica_ui-kit_components_text-field_properties_icon-size */
-/* recursica-ignore: --recursica_ui-kit_components_text-field_properties_icon-text-gap */
-/* recursica-ignore: --recursica_ui-kit_components_text-field_properties_max-width */
-/* recursica-ignore: --recursica_ui-kit_components_text-field_properties_min-height */
-/* recursica-ignore: --recursica_ui-kit_components_text-field_properties_min-width */
-/* recursica-ignore: --recursica_ui-kit_components_text-field_properties_placeholder-opacity */
-/* recursica-ignore: --recursica_ui-kit_components_text-field_properties_text_font-family */
-/* recursica-ignore: --recursica_ui-kit_components_text-field_properties_text_font-size */
-/* recursica-ignore: --recursica_ui-kit_components_text-field_properties_text_font-style */
-/* recursica-ignore: --recursica_ui-kit_components_text-field_properties_text_font-weight */
-/* recursica-ignore: --recursica_ui-kit_components_text-field_properties_text_letter-spacing */
-/* recursica-ignore: --recursica_ui-kit_components_text-field_properties_text_line-height */
-/* recursica-ignore: --recursica_ui-kit_components_text-field_properties_text_text-decoration */
-/* recursica-ignore: --recursica_ui-kit_components_text-field_properties_text_text-transform */
-/* recursica-ignore: --recursica_ui-kit_components_text-field_properties_vertical-padding */
-/* recursica-ignore: --recursica_ui-kit_components_text-field_variants_layouts_side-by-side_properties_top-bottom-margin */
-/* recursica-ignore: --recursica_ui-kit_components_text-field_variants_layouts_stacked_properties_top-bottom-margin */
+   - state-specific border-size variables are ignored because a uniform 1px border is applied globally to prevent 
+     unexpected layout shift or flickering during focus, disabled, or error state transitions. */
 /* recursica-ignore: --recursica_ui-kit_components_text-field_variants_states_default_properties_border-size */
-/* recursica-ignore: --recursica_ui-kit_components_text-field_variants_states_default_properties_colors_background */
-/* recursica-ignore: --recursica_ui-kit_components_text-field_variants_states_default_properties_colors_border-color */
-/* recursica-ignore: --recursica_ui-kit_components_text-field_variants_states_default_properties_colors_leading-icon */
-/* recursica-ignore: --recursica_ui-kit_components_text-field_variants_states_default_properties_colors_text */
-/* recursica-ignore: --recursica_ui-kit_components_text-field_variants_states_default_properties_colors_trailing-icon */
 /* recursica-ignore: --recursica_ui-kit_components_text-field_variants_states_disabled_properties_border-size */
-/* recursica-ignore: --recursica_ui-kit_components_text-field_variants_states_disabled_properties_colors_background */
-/* recursica-ignore: --recursica_ui-kit_components_text-field_variants_states_disabled_properties_colors_border-color */
-/* recursica-ignore: --recursica_ui-kit_components_text-field_variants_states_disabled_properties_colors_leading-icon */
-/* recursica-ignore: --recursica_ui-kit_components_text-field_variants_states_disabled_properties_colors_text */
-/* recursica-ignore: --recursica_ui-kit_components_text-field_variants_states_disabled_properties_colors_trailing-icon */
 /* recursica-ignore: --recursica_ui-kit_components_text-field_variants_states_error_properties_border-size */
-/* recursica-ignore: --recursica_ui-kit_components_text-field_variants_states_error_properties_colors_background */
-/* recursica-ignore: --recursica_ui-kit_components_text-field_variants_states_error_properties_colors_border-color */
-/* recursica-ignore: --recursica_ui-kit_components_text-field_variants_states_error_properties_colors_leading-icon */
-/* recursica-ignore: --recursica_ui-kit_components_text-field_variants_states_error_properties_colors_text */
-/* recursica-ignore: --recursica_ui-kit_components_text-field_variants_states_error_properties_colors_trailing-icon */
 /* recursica-ignore: --recursica_ui-kit_components_text-field_variants_states_focus_properties_border-size */
-/* recursica-ignore: --recursica_ui-kit_components_text-field_variants_states_focus_properties_colors_background */
-/* recursica-ignore: --recursica_ui-kit_components_text-field_variants_states_focus_properties_colors_border-color */
-/* recursica-ignore: --recursica_ui-kit_components_text-field_variants_states_focus_properties_colors_leading-icon */
-/* recursica-ignore: --recursica_ui-kit_components_text-field_variants_states_focus_properties_colors_text */
-/* recursica-ignore: --recursica_ui-kit_components_text-field_variants_states_focus_properties_colors_trailing-icon */
+
+/* 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_text-field_variants_layouts_stacked_properties_top-bottom-margin
+  );
+}
+
+.layoutOverride[data-form-layout="side-by-side"] {
+  --form-control-margin-bottom: var(
+    --recursica_ui-kit_components_text-field_variants_layouts_side-by-side_properties_top-bottom-margin
+  );
+}
+
+/* HARDCODED VALUES:
+   - border-width: 1px. Native geometric boundary for the input box.
+   - border-style: solid. Native structural rendering rule.
+   - outline: none. Bypassing browser focus rings to rely strictly on Recursica focus states natively.
+   - flex/layout: display: flex on the root wrapper safely encapsulating internal section rendering.
+*/
+
+.root {
+  display: flex;
+  position: relative;
+  width: 100%;
+  min-height: var(
+    --recursica_ui-kit_components_text-field_properties_min-height
+  );
+
+  /* Strict Typography Unification placed on root for MUI InputBase inheritance */
+  font-family: var(
+    --recursica_ui-kit_components_text-field_properties_text_font-family
+  );
+  font-size: var(
+    --recursica_ui-kit_components_text-field_properties_text_font-size
+  );
+  font-style: var(
+    --recursica_ui-kit_components_text-field_properties_text_font-style
+  );
+  font-weight: var(
+    --recursica_ui-kit_components_text-field_properties_text_font-weight
+  );
+  letter-spacing: var(
+    --recursica_ui-kit_components_text-field_properties_text_letter-spacing
+  );
+  line-height: var(
+    --recursica_ui-kit_components_text-field_properties_text_line-height
+  );
+  text-decoration: var(
+    --recursica_ui-kit_components_text-field_properties_text_text-decoration
+  );
+  text-transform: var(
+    --recursica_ui-kit_components_text-field_properties_text_text-transform
+  );
+
+  /* Box Geometry placed on root so MUI InputBase boundary executes */
+  border-radius: var(
+    --recursica_ui-kit_components_text-field_properties_border-radius
+  );
+  border-width: 1px;
+  border-style: solid;
+
+  /* Base State Default Execution */
+  background-color: var(
+    --recursica_ui-kit_components_text-field_variants_states_default_properties_colors_background
+  );
+  border-color: var(
+    --recursica_ui-kit_components_text-field_variants_states_default_properties_colors_border-color
+  );
+  color: var(
+    --recursica_ui-kit_components_text-field_variants_states_default_properties_colors_text
+  );
+
+  /* Override MUI/Mantine native Input variables governing section spacing padding mathematics safely */
+  --input-left-section-size: calc(
+    var(
+        --recursica_ui-kit_components_text-field_properties_horizontal-padding
+      ) +
+      var(--recursica_ui-kit_components_text-field_properties_icon-size) +
+      var(--recursica_ui-kit_components_text-field_properties_icon-text-gap)
+  );
+  --input-right-section-size: calc(
+    var(
+        --recursica_ui-kit_components_text-field_properties_horizontal-padding
+      ) +
+      var(--recursica_ui-kit_components_text-field_properties_icon-size) +
+      var(--recursica_ui-kit_components_text-field_properties_icon-text-gap)
+  );
+}
+
+.input {
+  /* Structural Overrides */
+  width: 100%;
+  box-sizing: border-box;
+  margin: 0;
+
+  /* Box Geometry Padding */
+  min-height: var(
+    --recursica_ui-kit_components_text-field_properties_min-height
+  );
+  padding-top: var(
+    --recursica_ui-kit_components_text-field_properties_vertical-padding
+  );
+  padding-bottom: var(
+    --recursica_ui-kit_components_text-field_properties_vertical-padding
+  );
+  padding-left: var(
+    --recursica_ui-kit_components_text-field_properties_horizontal-padding
+  );
+  padding-right: var(
+    --recursica_ui-kit_components_text-field_properties_horizontal-padding
+  );
+
+  outline: none;
+  border: none; /* Because root handles border in MUI */
+  background: transparent;
+  color: inherit;
+  height: auto; /* overrides MUI's 1.1876em */
+}
+
+.input::placeholder {
+  opacity: var(
+    --recursica_ui-kit_components_text-field_properties_placeholder-opacity
+  );
+  color: inherit;
+}
+
+/* Dynamic Padding Overrides */
+.root[data-with-left-section="true"] .input {
+  padding-left: var(--input-left-section-size);
+}
+
+.root[data-with-right-section="true"] .input {
+  padding-right: var(--input-right-section-size);
+}
+
+/* Flexible End-Caps (Icons, actions) */
+.section {
+  display: flex;
+  align-items: center;
+  height: 100%;
+  position: absolute;
+}
+
+.section[data-position="left"] {
+  justify-content: flex-start;
+  left: 0;
+  padding-left: var(
+    --recursica_ui-kit_components_text-field_properties_horizontal-padding
+  );
+}
+
+.section[data-position="right"] {
+  justify-content: flex-end;
+  right: 0;
+  padding-right: var(
+    --recursica_ui-kit_components_text-field_properties_horizontal-padding
+  );
+}
+
+.section :global(svg) {
+  width: var(--recursica_ui-kit_components_text-field_properties_icon-size);
+  height: var(--recursica_ui-kit_components_text-field_properties_icon-size);
+  color: var(
+    --recursica_ui-kit_components_text-field_variants_states_default_properties_colors_leading-icon
+  );
+}
+
+.section[data-position="right"] :global(svg) {
+  color: var(
+    --recursica_ui-kit_components_text-field_variants_states_default_properties_colors_trailing-icon
+  );
+}
+
+/* -------------------------------------
+   STATE CASCADE ARCHITECTURE
+-------------------------------------- */
+
+/* Focus State Mapping (Triggered internally via browser pseudo-pseudo-class) */
+.root:focus-within,
+.root:focus {
+  border-color: var(
+    --recursica_ui-kit_components_text-field_variants_states_focus_properties_colors_border-color
+  );
+  background-color: var(
+    --recursica_ui-kit_components_text-field_variants_states_focus_properties_colors_background
+  );
+  color: var(
+    --recursica_ui-kit_components_text-field_variants_states_focus_properties_colors_text
+  );
+}
+
+.root:focus-within .section[data-position="left"] :global(svg) {
+  color: var(
+    --recursica_ui-kit_components_text-field_variants_states_focus_properties_colors_leading-icon
+  );
+}
+
+.root:focus-within .section[data-position="right"] :global(svg) {
+  color: var(
+    --recursica_ui-kit_components_text-field_variants_states_focus_properties_colors_trailing-icon
+  );
+}
+
+/* Error State Mapping (Propagated strictly down from the wrapper DOM context) */
+.root[data-error="true"] {
+  border-color: var(
+    --recursica_ui-kit_components_text-field_variants_states_error_properties_colors_border-color
+  );
+  background-color: var(
+    --recursica_ui-kit_components_text-field_variants_states_error_properties_colors_background
+  );
+  color: var(
+    --recursica_ui-kit_components_text-field_variants_states_error_properties_colors_text
+  );
+}
+
+.root[data-error="true"] .section[data-position="left"] :global(svg) {
+  color: var(
+    --recursica_ui-kit_components_text-field_variants_states_error_properties_colors_leading-icon
+  );
+}
+
+.root[data-error="true"] .section[data-position="right"] :global(svg) {
+  color: var(
+    --recursica_ui-kit_components_text-field_variants_states_error_properties_colors_trailing-icon
+  );
+}
+
+/* Disabled State Mapping (Propagated strictly down from the wrapper DOM context) */
+.root[data-disabled="true"] {
+  border-color: var(
+    --recursica_ui-kit_components_text-field_variants_states_disabled_properties_colors_border-color
+  );
+  background-color: var(
+    --recursica_ui-kit_components_text-field_variants_states_disabled_properties_colors_background
+  );
+  color: var(
+    --recursica_ui-kit_components_text-field_variants_states_disabled_properties_colors_text
+  );
+  cursor: not-allowed;
+}
+
+.root[data-disabled="true"] .input {
+  cursor: not-allowed;
+}
+
+.root[data-disabled="true"] .section[data-position="left"] :global(svg) {
+  color: var(
+    --recursica_ui-kit_components_text-field_variants_states_disabled_properties_colors_leading-icon
+  );
+}
+
+.root[data-disabled="true"] .section[data-position="right"] :global(svg) {
+  color: var(
+    --recursica_ui-kit_components_text-field_variants_states_disabled_properties_colors_trailing-icon
+  );
+}

package/src/components/TextField/TextField.stories.tsx

@@ -1,35 +1,188 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import React from "react";
 import type { Meta, StoryObj } from "@storybook/react";
 import { TextField } from "./TextField";
-import { ComingSoon } from "@recursica/storybook-template";
+import { formControlArgTypes } from "../../../.storybook/commonArgTypes";
 
 const meta: Meta<typeof TextField> = {
-  title: "UI-Kit/🚧 TextField",
+  title: "UI-Kit/TextField",
   component: TextField,
   tags: ["autodocs"],
   parameters: {
+    docs: {
+      description: {
+        component: `
+The \`TextField\` primitive functions as a universal text entry input natively integrated directly into the unified \`FormControlWrapper\` architecture.
+
+### Architectural Decoupling
+Recursica forcibly overrides the internal MUI \`InputBase\` defaults injecting an untamed input layout primitive perfectly mapped back into our rigid design systems. State modifiers (e.g. Focus, Errors) hook flawlessly back onto our CSS module mapping variable colors strictly accurately.
+
+### Examples
+Always structure horizontal architectures via the generic \`formLayout\` parameter.
+\`\`\`tsx
+<TextField 
+  label="Primary Network Socket" 
+  assistiveText="Ensure connections resolve seamlessly." 
+  formLayout="stacked" 
+/>
+\`\`\`
+`,
+      },
+    },
     controls: {
       include: [
-        "layer",
-        "withLayer",
-        "children",
-        "component",
-        "variant",
-        "size",
-        "icon",
         "disabled",
-        "href",
-        "onClick",
-        "onChange",
-        "value",
-        "checked",
+        "error",
+        "required",
+        "label",
+        "assistiveText",
+        "readOnly",
+        "formLayout",
+        "labelSize",
+        "labelAlignment",
+        "labelOptionalText",
+        "labelWithEditIcon",
       ],
     },
   },
+  argTypes: {
+    ...formControlArgTypes,
+    disabled: {
+      control: "boolean",
+      description:
+        "Maps the formal disabled variable states structurally to the input core.",
+    },
+    error: {
+      control: "text",
+      description:
+        "Applies the strict error string boundary rendering invalid structures seamlessly.",
+    },
+    required: {
+      control: "boolean",
+    },
+    label: {
+      control: "text",
+    },
+    assistiveText: {
+      control: "text",
+    },
+    readOnly: {
+      control: "boolean",
+      description:
+        "Toggles structural read-only data presentation explicitly blocking standard component bindings.",
+    },
+  },
 };
 
 export default meta;
+
 type Story = StoryObj<typeof TextField>;
 
 export const Default: Story = {
-  render: () => <ComingSoon componentName="TextField" />,
+  args: {
+    disabled: false,
+    label: "Authentication Token",
+    placeholder: "Enter validation hash...",
+    assistiveText:
+      "Tokens are stored identically locally and strictly ephemeral.",
+  },
+  render: ({ ...args }: any) => <TextField {...args} />,
+};
+
+export const FormsSideBySide: Story = {
+  args: {
+    label: "Distributed Access Control",
+    placeholder: "admin@node.local",
+    assistiveText:
+      "Specify the exact cluster administrative credentials enforcing strict domain policies. This violently long string tests native textual wrapping safely mapping alongside inputs.",
+    formLayout: "side-by-side",
+  },
+  render: ({ ...args }: any) => <TextField {...args} />,
+};
+
+export const WithLeadingIcon: Story = {
+  args: {
+    label: "Search Global Context",
+    placeholder: "Search for repositories...",
+    leftSection: (
+      <svg
+        width="24"
+        height="24"
+        viewBox="0 0 24 24"
+        fill="none"
+        stroke="currentColor"
+        strokeWidth="2"
+        strokeLinecap="round"
+        strokeLinejoin="round"
+      >
+        <circle cx="11" cy="11" r="8"></circle>
+        <line x1="21" y1="21" x2="16.65" y2="16.65"></line>
+      </svg>
+    ),
+  },
+  render: ({ ...args }: any) => <TextField {...args} />,
+};
+
+export const WithTrailingIcon: Story = {
+  args: {
+    label: "Validation URL",
+    placeholder: "https://recursica.dev",
+    rightSection: (
+      <svg
+        width="24"
+        height="24"
+        viewBox="0 0 24 24"
+        fill="none"
+        stroke="currentColor"
+        strokeWidth="2"
+        strokeLinecap="round"
+        strokeLinejoin="round"
+      >
+        <polyline points="20 6 9 17 4 12"></polyline>
+      </svg>
+    ),
+  },
+  render: ({ ...args }: any) => <TextField {...args} />,
+};
+
+export const Disabled: Story = {
+  args: {
+    label: "Disabled Deployment Node",
+    placeholder: "Disabled primitive map...",
+    disabled: true,
+  },
+  render: ({ ...args }: any) => <TextField {...args} />,
+};
+
+export const ErrorState: Story = {
+  args: {
+    label: "Cluster Failure",
+    placeholder: "Failing component instance...",
+    defaultValue: "Invalid Execution Plan",
+    error:
+      "Critical runtime node disconnect detected traversing DOM architecture.",
+    required: true,
+  },
+  render: ({ ...args }: any) => <TextField {...args} />,
+};
+
+export const StaticReadOnly: Story = {
+  args: {
+    label: "Static ReadOnly Review",
+    placeholder: "Ignored...",
+    value: "Explicitly Uneditable Bound Output",
+    readOnly: true,
+  },
+  render: ({ ...args }: any) => <TextField {...args} />,
+};
+
+export const EditableReadOnly: Story = {
+  args: {
+    label: "Editable ReadOnly Review",
+    placeholder: "Ignored until active...",
+    defaultValue: "Waiting for Edit Execution",
+    readOnly: true,
+    labelWithEditIcon: true,
+  },
+  render: ({ ...args }: any) => <TextField {...args} />,
 };