@recursica/adapter-mui-v7 1.0.0

package/src/components/Accordion/Accordion.tsx

@@ -0,0 +1,285 @@
+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";
+
+import {
+  type RecursicaAccordionProps,
+  type RecursicaAccordionItemProps,
+  type RecursicaAccordionControlProps,
+  type RecursicaAccordionPanelProps,
+} from "@recursica/adapter-common";
+
+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;
+  chevron?: React.ReactNode;
+} | null>(null);
+
+// ==== ACCORDION CONTAINER ====
+export type AccordionProps = RecursicaOverStyled<
+  React.HTMLAttributes<HTMLDivElement> &
+    RecursicaAccordionProps & {
+      // MUI has no native multi-panel accordion group to match (its own `Accordion` is a
+      // single controlled item) — this signature is Recursica's own, same as TransferList.
+      onChange?: (value: string | string[] | null) => void;
+    }
+>;
+
+const AccordionBase = forwardRef<HTMLDivElement, AccordionProps>(
+  function Accordion(
+    {
+      variant = "default",
+      overStyled = false,
+      value,
+      defaultValue,
+      onChange,
+      multiple = false,
+      chevron,
+      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, chevron }}
+      >
+        <div
+          ref={ref}
+          {...(sanitizedProps as React.HTMLAttributes<HTMLDivElement>)}
+          className={finalClass}
+          data-variant={variant}
+        >
+          {children}
+        </div>
+      </AccordionContext.Provider>
+    );
+  },
+);
+AccordionBase.displayName = "Accordion";
+
+export type AccordionItemWrapperProps = RecursicaOverStyled<
+  // `expanded`/`onChange` are computed internally from the group context — omitted so a
+  // caller can't silently detach this item from the controlled state. `defaultExpanded` has
+  // no meaning here since expansion is always driven by the group's `value`. `disabled` is
+  // shared as-is with `RecursicaAccordionItemProps.disabled` — same name, same shape, no
+  // reshaping needed; see ACCORDION_IMPLEMENTATION_NOTES.md.
+  Omit<
+    MuiAccordionProps,
+    "children" | "value" | "expanded" | "onChange" | "defaultExpanded"
+  > & {
+    children?: React.ReactNode;
+    value: string;
+  } & RecursicaAccordionItemProps
+>;
+
+export const AccordionItem = forwardRef<
+  HTMLDivElement,
+  AccordionItemWrapperProps
+>(function AccordionItem(
+  {
+    title,
+    leftIcon,
+    divider = true,
+    children,
+    value,
+    disabled = false,
+    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}
+      {...(sanitizedProps as unknown as Omit<
+        MuiAccordionProps,
+        "expanded" | "onChange" | "defaultExpanded" | "disabled"
+      >)}
+      className={finalClass}
+      disableGutters
+      elevation={0}
+      square
+      expanded={isExpanded}
+      onChange={handleChange}
+      disabled={disabled}
+      data-disabled={disabled || undefined}
+      style={mergedStyle}
+    >
+      {
+        (title ? (
+          <>
+            <AccordionControl leftIcon={leftIcon}>{title}</AccordionControl>
+            <AccordionPanel>{children}</AccordionPanel>
+          </>
+        ) : (
+          children
+          // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        )) as any
+      }
+    </MuiAccordion>
+  );
+});
+AccordionItem.displayName = "AccordionItem";
+
+// ==== ACCORDION CONTROL ====
+export type AccordionControlWrapperProps = RecursicaOverStyled<
+  // `expandIcon` is resolved internally from the container's `chevron` (via context) —
+  // omitted so a caller can't silently override it with MUI's native chevron slot.
+  Omit<MuiAccordionSummaryProps, "expandIcon"> & 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;
+
+  const ctx = useContext(AccordionContext);
+  const resolvedChevron = ctx?.chevron ?? <ChevronIcon />;
+
+  return (
+    <MuiAccordionSummary
+      ref={ref}
+      {...(sanitizedProps as unknown as MuiAccordionSummaryProps)}
+      className={finalClass}
+      expandIcon={<span className={styles.chevron}>{resolvedChevron}</span>}
+    >
+      {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 & RecursicaAccordionPanelProps
+>;
+
+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}
+      {...(sanitizedProps as unknown as MuiAccordionDetailsProps)}
+      className={finalClass}
+    >
+      <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/Accordion/USAGE.md

@@ -0,0 +1,43 @@
+# Accordion - Usage Guide
+
+This document describes how to integrate and use the `Accordion` component in your projects using `@recursica/adapter-mui-v7`.
+
+---
+
+## 1. Import Reference
+
+```tsx
+import { Accordion } from "@recursica/adapter-mui-v7";
+```
+
+---
+
+## 2. Basic Example
+
+```tsx
+import React from "react";
+import { Accordion } from "@recursica/adapter-mui-v7";
+
+export default function Demo() {
+  return (
+    <Accordion>
+      <Accordion.Item value="item-1">
+        <Accordion.Control>Section 1</Accordion.Control>
+        <Accordion.Panel>Section 1 content</Accordion.Panel>
+      </Accordion.Item>
+    </Accordion>
+  );
+}
+```
+
+---
+
+## 3. Design System Integration
+
+All Recursica components in the `@recursica/adapter-mui-v7` package adhere strictly to design system spacing, scaling, and behavior patterns.
+
+> [!IMPORTANT]
+>
+> - **Anti-override protection**: Rogues style injections (like inline `style` or arbitrary `className`) are automatically blocked by our prop layer unless `overStyled={true}` is explicitly provided.
+> - **No Direct Layers**: Do not pass a `layer` prop to this component. To place it on a specific visual layer, wrap it in a `<Layer layer={0|1|2|3}>` component natively.
+> - **Variables and Theming**: Styling is entirely determined by local CSS variables defined in `recursica_variables_scoped.css` and mapped in the component's CSS module.

package/src/components/Accordion/index.ts

@@ -0,0 +1 @@
+export * from "./Accordion";

package/src/components/AssistiveElement/ASSISTIVEELEMENT_IMPLEMENTATION_NOTES.md

@@ -0,0 +1,59 @@
+# AssistiveElement – implementation notes
+
+Decisions and design tweaks specific to the UI Kit's AssistiveElement wrapped against
+`@mui/material`.
+
+---
+
+## 1. Forced `component="div"` trades away `FormHelperText`'s default semantics
+
+**Decision:** `FormHelperText` renders a `<p>` by default — a reasonable semantic choice for
+standalone helper/error text. This adapter forces `component="div"` instead, purely so the
+icon + text can sit side by side in a flex row; `<p>` can't contain the flex layout the same
+way without other tradeoffs.
+**Implementation:** `component="div"` and `error={isError}` (derived from `assistiveVariant`)
+are both computed internally and omitted from `AssistiveElementProps` (`Omit<FormHelperTextProps,
+"error" | "component">`) so a caller can't silently override either via spread.
+`aria-describedby`/`aria-errormessage` association with a field is a different story: this
+component has no reference to any sibling field, so it can't wire that itself. It's already
+handled one layer up, in `FormControlWrapper` — which generates the ids, passes them down via
+this component's own `id` prop, and clones `aria-describedby`/`aria-errormessage` onto the
+field. Only a fully standalone `<AssistiveElement>` used outside `FormControlWrapper` still
+needs that wiring done by hand. `role="alert"` for the error variant is handled here instead
+(see §4) — that piece genuinely belongs at this component's own level.
+
+---
+
+## 2. CSS specificity tie against MUI's own `.Mui-error` color
+
+**Decision:** MUI's `FormHelperText` sets its own error color via `.MuiFormHelperText-root.Mui-error`
+(two classes) whenever `error` is set. Our own `.root[data-variant="error"]` (one class + one
+attribute) lands at the _same_ specificity — without help, whichever rule loads later in the
+merged stylesheet wins, which is import-order luck rather than a deterministic override.
+**Implementation:** `!important` on that one rule's `color` guarantees ours wins regardless of
+load order (same reasoning as the focus-ring override in the Accordion adapter). Not needed for
+the `help` variant — MUI's unconditional base `color` on `.root` alone already has lower
+specificity than our attribute-qualified rule there.
+
+---
+
+## 3. Native passthrough capabilities, left unblocked and undocumented
+
+**Decision:** `FormHelperText`'s own `disabled`/`filled`/`focused`/`margin`/`required`/`variant`/
+`classes`/`sx` all pass straight through today (none of them are omitted, and none are
+computed internally so there's nothing for them to silently override). They're also not added
+to `RecursicaAssistiveElementProps` — same "accidental passthrough" class as Accordion's
+`disabled` was before it got formalized. Known asymmetry: MUI callers can reach for these
+today, Mantine callers can't (Mantine's `AssistiveElement` wraps no native component at all).
+Revisit if a real use case shows up for any of them.
+
+---
+
+## 4. `role="alert"` defaults on for the error variant
+
+**Decision:** Error text needs to be announced by assistive tech as it appears or changes;
+static help text doesn't. Rather than requiring every integrator to remember `role="alert"`,
+`assistiveVariant="error"` defaults it automatically.
+**Implementation:** `role` is destructured out and resolved as `role ?? (isError ? "alert" :
+undefined)` before rendering — an explicit caller-supplied `role` always wins over the default,
+and `"help"` gets no default at all.

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

@@ -0,0 +1,121 @@
+/*
+  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
+   ========================================= */
+
+/* MUI's own `FormHelperText` sets its error color via `.MuiFormHelperText-root.Mui-error`
+   (two classes) whenever `error` is set — the exact same specificity as our own
+   `.root[data-variant="error"]` (one class + one attribute), so whichever rule loads later
+   in the merged stylesheet would otherwise win. `!important` makes ours win deterministically
+   regardless of CSS import order (same reasoning as the focus-ring override elsewhere in this
+   codebase). Not needed for the `help` variant above — MUI's unconditional base `color` on
+   `.root` alone has lower specificity than ours there already. */
+.root[data-variant="error"] {
+  color: var(
+    --recursica_ui-kit_components_assistive-element_variants_types_error_properties_colors_text-color
+  ) !important;
+}
+
+.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

@@ -0,0 +1,68 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { AssistiveElement } from "./AssistiveElement";
+
+const meta: Meta<typeof 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.",
+      },
+    },
+  },
+  argTypes: {
+    assistiveVariant: {
+      control: "radio",
+      options: ["help", "error"],
+    },
+    assistiveWithIcon: {
+      control: "boolean",
+    },
+  },
+};
+
+export default meta;
+
+type Story = StoryObj<typeof 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) => (
+    <AssistiveElement {...args} />
+  ),
+};
+
+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) => (
+    <AssistiveElement {...args} />
+  ),
+};
+
+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) => (
+    <AssistiveElement {...args} />
+  ),
+};

package/src/components/AssistiveElement/AssistiveElement.test.tsx

@@ -0,0 +1 @@
+// Placeholder for future AssistiveElement component tests. Add tests here if/when needed.

package/src/components/AssistiveElement/AssistiveElement.tsx

@@ -0,0 +1,94 @@
+import React from "react";
+import { FormHelperText, type FormHelperTextProps } from "@mui/material";
+import {
+  filterStylingProps,
+  type RecursicaOverStyled,
+} from "../../utils/filterStylingProps";
+import styles from "./AssistiveElement.module.css";
+
+import { type RecursicaAssistiveElementProps } from "@recursica/adapter-common";
+
+// `error`/`component` are computed internally (from `assistiveVariant`, and forced to "div"
+// for layout) — omitted so a caller can't silently override either via spread.
+export type AssistiveElementProps = RecursicaOverStyled<
+  Omit<FormHelperTextProps, "error" | "component"> &
+    RecursicaAssistiveElementProps
+>;
+
+export const AssistiveElement = React.forwardRef<
+  HTMLParagraphElement,
+  AssistiveElementProps
+>(function AssistiveElement(props, ref) {
+  const {
+    assistiveVariant = "help",
+    assistiveWithIcon = true,
+    overStyled = false,
+    className,
+    children,
+    role,
+    ...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";
+
+  // Announce error text as it appears/changes; a caller-supplied `role` always wins. No
+  // default for `help` — static descriptive text doesn't need a live region.
+  const resolvedRole = role ?? (isError ? "alert" : undefined);
+
+  // Force component = "div" so flex layouts execute correctly inside HelperText
+  return (
+    <FormHelperText
+      ref={ref}
+      {...(sanitizedProps as Omit<FormHelperTextProps, "error" | "component">)}
+      component="div"
+      error={isError}
+      role={resolvedRole}
+      data-variant={assistiveVariant}
+      className={className ? `${styles.root} ${className}` : styles.root}
+    >
+      {assistiveWithIcon && (
+        <div className={styles.icon}>
+          {assistiveVariant === "error" ? <ErrorIcon /> : <HelpIcon />}
+        </div>
+      )}
+      <span className={styles.text}>{children}</span>
+    </FormHelperText>
+  );
+});
+
+AssistiveElement.displayName = "AssistiveElement";