@recursica/mui-adapter 0.5.0 → 0.7.0

package/src/components/Accordion/Accordion.tsx

@@ -1,8 +1,263 @@
-import React from "react";
-import "./Accordion.module.css";
+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>;
+import {
+  type RecursicaAccordionProps,
+  type RecursicaAccordionItemProps,
+  type RecursicaAccordionControlProps,
+} from "@recursica/adapter-common";
 
-export const Accordion: React.FC<AccordionProps> = (props) => {
-  return <div {...props}>Accordion</div>;
+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>
+);
+
+const AccordionContext = createContext<{
+  value: string | string[] | null;
+  onChange: (val: string) => void;
+} | null>(null);
+
+// ==== ACCORDION CONTAINER ====
+export type AccordionProps = RecursicaOverStyled<
+  React.HTMLAttributes<HTMLDivElement> & RecursicaAccordionProps
+>;
+
+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";
+
+export type AccordionItemWrapperProps = RecursicaOverStyled<
+  Omit<MuiAccordionProps, "children" | "value"> & {
+    children?: React.ReactNode;
+    value: string;
+  } & RecursicaAccordionItemProps
+>;
+
+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
+        )) as any
+      }
+    </MuiAccordion>
+  );
+});
+AccordionItem.displayName = "AccordionItem";
+
+// ==== ACCORDION CONTROL ====
+export type AccordionControlWrapperProps = RecursicaOverStyled<
+  MuiAccordionSummaryProps & RecursicaAccordionControlProps
+>;
+
+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

@@ -1,20 +1,114 @@
-/* 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_assistive-element_properties_icon-size */
-/* recursica-ignore: --recursica_ui-kit_components_assistive-element_properties_icon-text-gap */
-/* recursica-ignore: --recursica_ui-kit_components_assistive-element_properties_max-width */
-/* recursica-ignore: --recursica_ui-kit_components_assistive-element_properties_text_font-family */
-/* recursica-ignore: --recursica_ui-kit_components_assistive-element_properties_text_font-size */
-/* recursica-ignore: --recursica_ui-kit_components_assistive-element_properties_text_font-style */
-/* recursica-ignore: --recursica_ui-kit_components_assistive-element_properties_text_font-weight */
-/* recursica-ignore: --recursica_ui-kit_components_assistive-element_properties_text_letter-spacing */
-/* recursica-ignore: --recursica_ui-kit_components_assistive-element_properties_text_line-height */
-/* recursica-ignore: --recursica_ui-kit_components_assistive-element_properties_text_text-decoration */
-/* recursica-ignore: --recursica_ui-kit_components_assistive-element_properties_text_text-transform */
-/* recursica-ignore: --recursica_ui-kit_components_assistive-element_properties_top-margin */
-/* recursica-ignore: --recursica_ui-kit_components_assistive-element_variants_types_error_properties_colors_icon-color */
-/* recursica-ignore: --recursica_ui-kit_components_assistive-element_variants_types_error_properties_colors_text-color */
-/* recursica-ignore: --recursica_ui-kit_components_assistive-element_variants_types_help_properties_colors_icon-color */
-/* recursica-ignore: --recursica_ui-kit_components_assistive-element_variants_types_help_properties_colors_text-color */
+/*
+  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 !important;
+  align-items: flex-start !important; /* Forces the icon to align with the first line of text */
+  margin: 0 !important; /* HARDCODE: structural reset */
+  padding: 0 !important; /* HARDCODE: structural reset */
+  width: 100%;
+
+  gap: var(
+    --recursica_ui-kit_components_assistive-element_properties_icon-text-gap
+  );
+  margin-top: var(
+    --recursica_ui-kit_components_assistive-element_properties_top-margin
+  ) !important;
+  max-width: var(
+    --recursica_ui-kit_components_assistive-element_properties_max-width
+  );
+
+  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 {
+  overflow-wrap: break-word;
+  white-space: normal;
+}
+
+/* Base Icon Architecture */
+.icon {
+  flex-shrink: 0 !important; /* Prevent squishing */
+  display: flex !important;
+  align-items: center !important;
+  justify-content: center !important;
+
+  width: var(
+    --recursica_ui-kit_components_assistive-element_properties_icon-size
+  ) !important;
+  height: calc(
+    var(
+        --recursica_ui-kit_components_assistive-element_properties_text_line-height
+      ) *
+      var(
+        --recursica_ui-kit_components_assistive-element_properties_text_font-size
+      )
+  ) !important; /* Forces exact centering bounds within the first text line vertically */
+}
+
+.icon :global(svg) {
+  width: var(
+    --recursica_ui-kit_components_assistive-element_properties_icon-size
+  ) !important;
+  height: var(
+    --recursica_ui-kit_components_assistive-element_properties_icon-size
+  ) !important;
+}
+
+/* =========================================
+   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,75 @@
 import type { Meta, StoryObj } from "@storybook/react";
 import { AssistiveElement } from "./AssistiveElement";
-import { ComingSoon } from "@recursica/storybook-template";
+import { Layer } from "@recursica/adapter-common";
 
 const meta: Meta<typeof AssistiveElement> = {
-  title: "UI-Kit/🚧 AssistiveElement",
+  title: "UI-Kit/AssistiveElement",
   component: AssistiveElement,
   tags: ["autodocs"],
   parameters: {
-    controls: {
-      include: [
-        "layer",
-        "withLayer",
-        "children",
-        "component",
-        "variant",
-        "size",
-        "icon",
-        "disabled",
-        "href",
-        "onClick",
-        "onChange",
-        "value",
-        "checked",
-      ],
+    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.",
+      },
+    },
+  },
+  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: ({ withLayer, layer, ...args }: any) => (
+    <Layer layer={0} style={{ padding: "48px" }}>
+      <AssistiveElement {...args} />
+    </Layer>
+  ),
+};
+
+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: ({ withLayer, layer, ...args }: any) => (
+    <Layer layer={0} style={{ padding: "48px" }}>
+      <AssistiveElement {...args} />
+    </Layer>
+  ),
+};
+
+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: ({ withLayer, layer, ...args }: any) => (
+    <Layer layer={0} style={{ padding: "48px" }}>
+      <AssistiveElement {...args} />
+    </Layer>
+  ),
 };

package/src/components/AssistiveElement/AssistiveElement.tsx

@@ -1,8 +1,84 @@
 import React from "react";
-import "./AssistiveElement.module.css";
+import { FormHelperText, type FormHelperTextProps } from "@mui/material";
+import { filterStylingProps } from "../../utils/filterStylingProps";
+import styles from "./AssistiveElement.module.css";
 
-export type AssistiveElementProps = React.HTMLAttributes<HTMLDivElement>;
+import { type RecursicaAssistiveElementProps } from "@recursica/adapter-common";
 
-export const AssistiveElement: React.FC<AssistiveElementProps> = (props) => {
-  return <div {...props}>AssistiveElement</div>;
-};
+export interface AssistiveElementProps
+  extends FormHelperTextProps,
+    RecursicaAssistiveElementProps {
+  overStyled?: boolean;
+}
+
+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"
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="2"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+    >
+      <circle cx="12" cy="12" r="10" />
+      <path d="M12 16v-4" />
+      <path d="M12 8h.01" />
+    </svg>
+  );
+
+  const ErrorIcon = () => (
+    <svg
+      xmlns="http://www.w3.org/2000/svg"
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="2"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+    >
+      <path d="m21.73 18-8-14a2 2 0 0 0-3.48 0l-8 14A2 2 0 0 0 4 21h16a2 2 0 0 0 1.73-3Z" />
+      <path d="M12 9v4" />
+      <path d="M12 17h.01" />
+    </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";