@recursica/mui-adapter 0.4.0 → 0.6.0

package/src/components/Accordion/Accordion.tsx

@@ -1,7 +1,267 @@
-import React from "react";
+import React, { forwardRef, createContext, useContext, useState } from "react";
+import {
+  Accordion as MuiAccordion,
+  AccordionSummary as MuiAccordionSummary,
+  AccordionDetails as MuiAccordionDetails,
+  type AccordionProps as MuiAccordionProps,
+  type AccordionSummaryProps as MuiAccordionSummaryProps,
+  type AccordionDetailsProps as MuiAccordionDetailsProps,
+} from "@mui/material";
+import {
+  filterStylingProps,
+  type RecursicaOverStyled,
+} from "../../utils/filterStylingProps";
+import styles from "./Accordion.module.css";
 
-export type AccordionProps = React.HTMLAttributes<HTMLDivElement>;
+const ChevronIcon = () => (
+  <svg
+    viewBox="0 0 24 24"
+    fill="none"
+    xmlns="http://www.w3.org/2000/svg"
+    stroke="currentColor"
+    strokeWidth="2"
+    strokeLinecap="round"
+    strokeLinejoin="round"
+    style={{ width: "100%", height: "100%" }}
+  >
+    <polyline points="6 9 12 15 18 9"></polyline>
+  </svg>
+);
 
-export const Accordion: React.FC<AccordionProps> = (props) => {
-  return <div {...props}>Accordion</div>;
+const AccordionContext = createContext<{
+  value: string | string[] | null;
+  onChange: (val: string) => void;
+} | null>(null);
+
+// ==== ACCORDION CONTAINER ====
+export type AccordionProps = RecursicaOverStyled<
+  React.HTMLAttributes<HTMLDivElement> & {
+    variant?: string;
+    value?: string | string[];
+    defaultValue?: string | string[];
+    onChange?: (value: string | string[] | null) => void;
+    multiple?: boolean;
+  }
+>;
+
+const AccordionBase = forwardRef<HTMLDivElement, AccordionProps>(
+  function Accordion(
+    {
+      variant = "unstyled",
+      overStyled = false,
+      value,
+      defaultValue,
+      onChange,
+      multiple = false,
+      children,
+      ...rest
+    },
+    ref,
+  ) {
+    const sanitizedProps = filterStylingProps(rest, overStyled);
+    const classNameProp = (sanitizedProps as Record<string, unknown>)
+      .className as string | undefined;
+
+    const finalClass =
+      [styles.root, classNameProp].filter(Boolean).join(" ") || undefined;
+
+    const [uncontrolledValue, setUncontrolledValue] = useState<
+      string | string[] | null
+    >(defaultValue !== undefined ? defaultValue : multiple ? [] : null);
+    const activeValue = value !== undefined ? value : uncontrolledValue;
+
+    const handleItemChange = (itemValue: string) => {
+      let newValue: string | string[] | null;
+      if (multiple) {
+        const arr = Array.isArray(activeValue)
+          ? activeValue
+          : activeValue
+            ? [activeValue as string]
+            : [];
+        newValue = arr.includes(itemValue)
+          ? arr.filter((v) => v !== itemValue)
+          : [...arr, itemValue];
+      } else {
+        newValue = activeValue === itemValue ? null : itemValue;
+      }
+      setUncontrolledValue(newValue);
+      onChange?.(newValue);
+    };
+
+    return (
+      <AccordionContext.Provider
+        value={{ value: activeValue, onChange: handleItemChange }}
+      >
+        <div
+          ref={ref}
+          className={finalClass}
+          data-variant={variant}
+          {...(sanitizedProps as React.HTMLAttributes<HTMLDivElement>)}
+        >
+          {children}
+        </div>
+      </AccordionContext.Provider>
+    );
+  },
+);
+AccordionBase.displayName = "Accordion";
+
+// ==== ACCORDION ITEM ====
+export type AccordionItemWrapperProps = RecursicaOverStyled<
+  Omit<MuiAccordionProps, "children" | "value"> & {
+    children?: React.ReactNode;
+    title?: React.ReactNode;
+    leftIcon?: React.ReactNode;
+    divider?: boolean;
+    value: string;
+  }
+>;
+
+export const AccordionItem = forwardRef<
+  HTMLDivElement,
+  AccordionItemWrapperProps
+>(function AccordionItem(
+  {
+    title,
+    leftIcon,
+    divider = true,
+    children,
+    value,
+    overStyled = false,
+    style,
+    ...rest
+  },
+  ref,
+) {
+  const sanitizedProps = filterStylingProps(rest, overStyled);
+  const classNameProp = (sanitizedProps as Record<string, unknown>)
+    .className as string | undefined;
+
+  const finalClass =
+    [styles.item, divider ? undefined : styles.noDivider, classNameProp]
+      .filter(Boolean)
+      .join(" ") || undefined;
+
+  const ctx = useContext(AccordionContext);
+  const isExpanded = ctx
+    ? Array.isArray(ctx.value)
+      ? ctx.value.includes(value)
+      : ctx.value === value
+    : undefined;
+
+  const handleChange = () => {
+    ctx?.onChange(value);
+  };
+
+  // background-color: transparent allows Layer overrides to naturally penetrate
+  const mergedStyle = { backgroundColor: "transparent", ...style };
+
+  return (
+    <MuiAccordion
+      ref={ref}
+      className={finalClass}
+      disableGutters
+      elevation={0}
+      square
+      expanded={isExpanded}
+      onChange={handleChange}
+      style={mergedStyle}
+      {...(sanitizedProps as unknown as Omit<
+        MuiAccordionProps,
+        "expanded" | "onChange"
+      >)}
+    >
+      {title ? (
+        <>
+          <AccordionControl leftIcon={leftIcon}>{title}</AccordionControl>
+          <AccordionPanel>{children}</AccordionPanel>
+        </>
+      ) : (
+        children
+      )}
+    </MuiAccordion>
+  );
+});
+AccordionItem.displayName = "AccordionItem";
+
+// ==== ACCORDION CONTROL ====
+export type AccordionControlWrapperProps = RecursicaOverStyled<
+  MuiAccordionSummaryProps & {
+    leftIcon?: React.ReactNode;
+  }
+>;
+
+export const AccordionControl = forwardRef<
+  HTMLDivElement,
+  AccordionControlWrapperProps
+>(function AccordionControl(
+  { leftIcon, children, overStyled = false, ...rest },
+  ref,
+) {
+  const sanitizedProps = filterStylingProps(rest, overStyled);
+  const classNameProp = (sanitizedProps as Record<string, unknown>)
+    .className as string | undefined;
+
+  const finalClass =
+    [styles.control, classNameProp].filter(Boolean).join(" ") || undefined;
+
+  return (
+    <MuiAccordionSummary
+      ref={ref}
+      className={finalClass}
+      expandIcon={
+        <span className={styles.chevron}>
+          <ChevronIcon />
+        </span>
+      }
+      {...(sanitizedProps as unknown as MuiAccordionSummaryProps)}
+    >
+      {leftIcon && (
+        <span className={styles.iconLeftWrapper} aria-hidden>
+          {leftIcon}
+        </span>
+      )}
+      <div className={styles.label}>{children}</div>
+    </MuiAccordionSummary>
+  );
+});
+AccordionControl.displayName = "AccordionControl";
+
+// ==== ACCORDION PANEL ====
+export type AccordionPanelWrapperProps =
+  RecursicaOverStyled<MuiAccordionDetailsProps>;
+
+export const AccordionPanel = forwardRef<
+  HTMLDivElement,
+  AccordionPanelWrapperProps
+>(function AccordionPanel({ overStyled = false, children, ...rest }, ref) {
+  const sanitizedProps = filterStylingProps(rest, overStyled);
+  const classNameProp = (sanitizedProps as Record<string, unknown>)
+    .className as string | undefined;
+
+  const finalClass =
+    [styles.panel, classNameProp].filter(Boolean).join(" ") || undefined;
+
+  return (
+    <MuiAccordionDetails
+      ref={ref}
+      className={finalClass}
+      {...(sanitizedProps as unknown as MuiAccordionDetailsProps)}
+    >
+      <div className={styles.content}>{children}</div>
+    </MuiAccordionDetails>
+  );
+});
+AccordionPanel.displayName = "AccordionPanel";
+
+// ==== DOT NOTATION EXPORT ====
+type AccordionComponent = typeof AccordionBase & {
+  Item: typeof AccordionItem;
+  Control: typeof AccordionControl;
+  Panel: typeof AccordionPanel;
 };
+
+export const Accordion = AccordionBase as AccordionComponent;
+Accordion.Item = AccordionItem;
+Accordion.Control = AccordionControl;
+Accordion.Panel = AccordionPanel;

package/src/components/AssistiveElement/AssistiveElement.module.css

@@ -0,0 +1,111 @@
+/*
+  ASSISTIVE ELEMENT ARCHITECTURE
+  This component strictly standardizes FormHelperText logic dynamically natively decoupled from the overarching input blocks.
+*/
+
+.root {
+  /* Override MUI FormHelperText native resets structurally safely */
+  display: flex;
+  align-items: flex-start; /* Forces the icon to align with the first line of text */
+  margin: 0; /* HARDCODE: structural reset */
+  padding: 0; /* HARDCODE: structural reset */
+  width: 100%;
+
+  gap: var(
+    --recursica_ui-kit_components_assistive-element_properties_icon-text-gap
+  );
+
+  font-family: var(
+    --recursica_ui-kit_components_assistive-element_properties_text_font-family
+  );
+  font-size: var(
+    --recursica_ui-kit_components_assistive-element_properties_text_font-size
+  );
+  font-style: var(
+    --recursica_ui-kit_components_assistive-element_properties_text_font-style
+  );
+  font-weight: var(
+    --recursica_ui-kit_components_assistive-element_properties_text_font-weight
+  );
+  letter-spacing: var(
+    --recursica_ui-kit_components_assistive-element_properties_text_letter-spacing
+  );
+  line-height: var(
+    --recursica_ui-kit_components_assistive-element_properties_text_line-height
+  );
+  text-decoration: var(
+    --recursica_ui-kit_components_assistive-element_properties_text_text-decoration
+  );
+  text-transform: var(
+    --recursica_ui-kit_components_assistive-element_properties_text_text-transform
+  );
+}
+
+.text {
+  flex: 1; /* Consume remaining space causing native flex wrap */
+}
+
+/* Base Icon Architecture */
+.icon {
+  flex-shrink: 0; /* Prevent squishing */
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  width: var(
+    --recursica_ui-kit_components_assistive-element_properties_icon-size
+  );
+  height: var(
+    --recursica_ui-kit_components_assistive-element_properties_icon-size
+  );
+
+  /* Mathematical vertical centering bounds to the first line of typography explicitly */
+  margin-top: calc(
+    (
+        var(
+            --recursica_ui-kit_components_assistive-element_properties_text_line-height
+          ) -
+          var(
+            --recursica_ui-kit_components_assistive-element_properties_icon-size
+          )
+      ) /
+      2
+  ); /* Forces exact centering bounds within the first text line vertically */
+}
+
+.icon :global(svg) {
+  width: 100%;
+  height: 100%;
+  stroke-width: 2px;
+}
+
+/* =========================================
+   VARIANTS: Default / Help
+   ========================================= */
+
+.root[data-variant="help"] {
+  color: var(
+    --recursica_ui-kit_components_assistive-element_variants_types_help_properties_colors_text-color
+  );
+}
+
+.root[data-variant="help"] .icon {
+  color: var(
+    --recursica_ui-kit_components_assistive-element_variants_types_help_properties_colors_icon-color
+  );
+}
+
+/* =========================================
+   VARIANTS: Error
+   ========================================= */
+
+.root[data-variant="error"] {
+  color: var(
+    --recursica_ui-kit_components_assistive-element_variants_types_error_properties_colors_text-color
+  );
+}
+
+.root[data-variant="error"] .icon {
+  color: var(
+    --recursica_ui-kit_components_assistive-element_variants_types_error_properties_colors_icon-color
+  );
+}

package/src/components/AssistiveElement/AssistiveElement.stories.tsx

@@ -1,35 +1,92 @@
+import React from "react";
 import type { Meta, StoryObj } from "@storybook/react";
 import { AssistiveElement } from "./AssistiveElement";
-import { ComingSoon } from "@recursica/storybook-template";
 
 const meta: Meta<typeof AssistiveElement> = {
-  title: "UI-Kit/🚧 AssistiveElement",
+  title: "UI-Kit/AssistiveElement",
   component: AssistiveElement,
   tags: ["autodocs"],
   parameters: {
+    docs: {
+      description: {
+        component:
+          "The `AssistiveElement` is a semantic structural primitive designed to standardize Helper and Error descriptive blocks natively beneath form components globally. By explicitly wiring to the `--recursica_ui-kit_components_assistive-element` layout tokens, this component safely injects custom SVGs (Alerts vs Info circles) alongside constrained flex-wrapping typography strings, preserving flawless line-height and alignment logic entirely decoupled from underlying input engine frameworks.",
+      },
+    },
     controls: {
-      include: [
-        "layer",
-        "withLayer",
-        "children",
-        "component",
-        "variant",
-        "size",
-        "icon",
-        "disabled",
-        "href",
-        "onClick",
-        "onChange",
-        "value",
-        "checked",
-      ],
+      include: ["assistiveVariant", "assistiveWithIcon", "children"],
+    },
+  },
+  argTypes: {
+    assistiveVariant: {
+      control: "radio",
+      options: ["help", "error"],
+    },
+    assistiveWithIcon: {
+      control: "boolean",
     },
   },
 };
 
 export default meta;
+
 type Story = StoryObj<typeof AssistiveElement>;
 
-export const Default: Story = {
-  render: () => <ComingSoon componentName="AssistiveElement" />,
+export const DefaultHelp: Story = {
+  args: {
+    children:
+      "This is a standard assistive layout explaining specific configurations.",
+    assistiveVariant: "help",
+    assistiveWithIcon: true,
+  },
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars, @typescript-eslint/no-explicit-any
+  render: ({ ...args }: any) => (
+    <div style={{ padding: "48px" }}>
+      <AssistiveElement {...args} />
+    </div>
+  ),
+};
+
+export const ErrorState: Story = {
+  args: {
+    children:
+      "Invalid property. You must satisfy the constraints outlined above.",
+    assistiveVariant: "error",
+    assistiveWithIcon: true,
+  },
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars, @typescript-eslint/no-explicit-any
+  render: ({ ...args }: any) => (
+    <div style={{ padding: "48px" }}>
+      <AssistiveElement {...args} />
+    </div>
+  ),
+};
+
+export const NoIconHelp: Story = {
+  args: {
+    children:
+      "Fallback textual representation without visual injection targets.",
+    assistiveVariant: "help",
+    assistiveWithIcon: false,
+  },
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars, @typescript-eslint/no-explicit-any
+  render: ({ ...args }: any) => (
+    <div style={{ padding: "48px" }}>
+      <AssistiveElement {...args} />
+    </div>
+  ),
+};
+
+export const Docs: Story = {
+  args: {
+    children: "Docs explicitly mapped configuration.",
+    assistiveVariant: "help",
+    assistiveWithIcon: true,
+  },
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars, @typescript-eslint/no-explicit-any
+  render: ({ ...args }: any) => (
+    <div style={{ padding: "48px" }}>
+      <AssistiveElement {...args} />
+    </div>
+  ),
 };

package/src/components/AssistiveElement/AssistiveElement.tsx

@@ -1,7 +1,88 @@
 import React from "react";
+import { FormHelperText, type FormHelperTextProps } from "@mui/material";
+import { filterStylingProps } from "../../utils/filterStylingProps";
+import styles from "./AssistiveElement.module.css";
 
-export type AssistiveElementProps = React.HTMLAttributes<HTMLDivElement>;
+export interface AssistiveElementProps extends FormHelperTextProps {
+  /** Governs the semantic rendering block (changes icon and CSS structural hooks natively). */
+  assistiveVariant?: "help" | "error";
+  /** Renders the structural mapping icon inline beside the text natively. */
+  assistiveWithIcon?: boolean;
+  overStyled?: boolean;
+}
 
-export const AssistiveElement: React.FC<AssistiveElementProps> = (props) => {
-  return <div {...props}>AssistiveElement</div>;
-};
+export const AssistiveElement = React.forwardRef<
+  HTMLParagraphElement,
+  AssistiveElementProps
+>(function AssistiveElement(props, ref) {
+  const {
+    assistiveVariant = "help",
+    assistiveWithIcon = true,
+    overStyled = false,
+    className,
+    children,
+    ...rest
+  } = props;
+
+  const sanitizedProps = filterStylingProps(rest, overStyled);
+
+  const HelpIcon = () => (
+    <svg
+      xmlns="http://www.w3.org/2000/svg"
+      width="24"
+      height="24"
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="2"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+    >
+      <circle cx="12" cy="12" r="10"></circle>
+      <line x1="12" y1="16" x2="12" y2="12"></line>
+      <line x1="12" y1="8" x2="12.01" y2="8"></line>
+    </svg>
+  );
+
+  const ErrorIcon = () => (
+    <svg
+      xmlns="http://www.w3.org/2000/svg"
+      width="24"
+      height="24"
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="2"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+    >
+      <circle cx="12" cy="12" r="10"></circle>
+      <line x1="12" y1="8" x2="12" y2="12"></line>
+      <line x1="12" y1="16" x2="12.01" y2="16"></line>
+    </svg>
+  );
+
+  // Map to MUI's native error prop if it's explicitly an error state
+  const isError = assistiveVariant === "error";
+
+  // Force component = "div" so flex layouts execute correctly inside HelperText
+  return (
+    <FormHelperText
+      ref={ref}
+      component="div"
+      error={isError}
+      data-variant={assistiveVariant}
+      className={className ? `${styles.root} ${className}` : styles.root}
+      {...(sanitizedProps as FormHelperTextProps)}
+    >
+      {assistiveWithIcon && (
+        <div className={styles.icon}>
+          {assistiveVariant === "error" ? <ErrorIcon /> : <HelpIcon />}
+        </div>
+      )}
+      <div className={styles.text}>{children}</div>
+    </FormHelperText>
+  );
+});
+
+AssistiveElement.displayName = "AssistiveElement";