@recursica/mantine-adapter 0.6.0 → 0.7.0

package/src/components/Accordion/Accordion.tsx

@@ -0,0 +1,200 @@
+import React, { forwardRef } from "react";
+import {
+  Accordion as MantineAccordion,
+  type AccordionProps as MantineAccordionProps,
+  type AccordionItemProps,
+  type AccordionControlProps,
+  type AccordionPanelProps,
+} from "@mantine/core";
+import {
+  filterStylingProps,
+  type RecursicaOverStyled,
+} from "../../utils/filterStylingProps";
+import styles from "./Accordion.module.css";
+
+// ==== ACCORDION CONTAINER ====
+export type AccordionProps = RecursicaOverStyled<MantineAccordionProps>;
+
+const AccordionBase = function Accordion({
+  variant = "unstyled",
+  overStyled = false,
+  ...rest
+}: AccordionProps) {
+  const sanitizedProps = filterStylingProps(rest, overStyled);
+
+  // Bind all deep CSS module references natively into the global class mapping schema
+  const mergedClassNames: Partial<Record<string, string>> = {
+    root: styles.root,
+    item: styles.item,
+    control: styles.control,
+    label: styles.label,
+    chevron: styles.chevron,
+    panel: styles.panel,
+    content: styles.content,
+  };
+
+  const classNamesProp = (sanitizedProps as Record<string, unknown>).classNames;
+  if (
+    classNamesProp &&
+    typeof classNamesProp === "object" &&
+    !Array.isArray(classNamesProp)
+  ) {
+    const o = classNamesProp as Record<string, string>;
+    Object.keys(o).forEach((key) => {
+      if (mergedClassNames[key]) {
+        mergedClassNames[key] = `${mergedClassNames[key]} ${o[key]}`;
+      } else {
+        mergedClassNames[key] = o[key];
+      }
+    });
+  }
+
+  const classNameProp = (sanitizedProps as Record<string, unknown>)
+    .className as string | undefined;
+
+  return (
+    <MantineAccordion
+      variant={variant}
+      className={classNameProp}
+      classNames={mergedClassNames}
+      {...(sanitizedProps as unknown as MantineAccordionProps)}
+    />
+  );
+};
+AccordionBase.displayName = "Accordion";
+
+// ==== ACCORDION ITEM ====
+// eslint-disable-next-line @typescript-eslint/no-empty-object-type
+export interface RecursicaAccordionItemProps
+  extends Omit<AccordionItemProps, "className"> {}
+// We need to omit and re-merge native props like in Badge
+export type AccordionItemWrapperProps = RecursicaOverStyled<
+  AccordionItemProps & {
+    /**
+     * When provided alongside `leftIcon` or independently, this auto-generates the Accordion Control and Panel DOM layers natively.
+     */
+    title?: React.ReactNode;
+
+    /**
+     * Leading icon explicitly mapped into the Mantine `Accordion.Control` leftSection boundary natively.
+     */
+    leftIcon?: React.ReactNode;
+
+    /**
+     * Toggles the presence of the bottom trailing divider native to AccordionItems.
+     * @default true
+     */
+    divider?: boolean;
+  }
+>;
+
+export const AccordionItem = forwardRef<
+  HTMLDivElement,
+  AccordionItemWrapperProps
+>(function AccordionItem(
+  { title, leftIcon, divider = true, children, overStyled = false, ...rest },
+  ref,
+) {
+  const sanitizedProps = filterStylingProps(rest, overStyled);
+  const classNameProp = (sanitizedProps as Record<string, unknown>)
+    .className as string | undefined;
+
+  const finalClass =
+    [divider ? undefined : styles.noDivider, classNameProp]
+      .filter(Boolean)
+      .join(" ") || undefined;
+
+  // If the user utilizes the explicit 'title' prop from Recursica, we securely auto-construct the Mantine sub-hierarchy natively!
+  // If not, we defer to raw composable children (meaning the integrator maps `<Accordion.Control>` manually).
+  return (
+    <MantineAccordion.Item
+      ref={ref}
+      className={finalClass}
+      {...(sanitizedProps as unknown as AccordionItemProps)}
+    >
+      {title ? (
+        <>
+          <AccordionControl leftIcon={leftIcon}>{title}</AccordionControl>
+          <AccordionPanel>{children}</AccordionPanel>
+        </>
+      ) : (
+        children
+      )}
+    </MantineAccordion.Item>
+  );
+});
+AccordionItem.displayName = "AccordionItem";
+
+// ==== ACCORDION CONTROL ====
+export type AccordionControlWrapperProps = RecursicaOverStyled<
+  AccordionControlProps & {
+    /**
+     * Leading icon explicitly mapped into the Mantine `Accordion.Control` leftSection boundary natively.
+     */
+    leftIcon?: React.ReactNode;
+  }
+>;
+
+export const AccordionControl = forwardRef<
+  HTMLButtonElement,
+  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;
+
+  return (
+    <MantineAccordion.Control
+      ref={ref}
+      className={classNameProp}
+      icon={
+        leftIcon ? (
+          <span className={styles.iconLeftWrapper} aria-hidden>
+            {leftIcon}
+          </span>
+        ) : undefined
+      }
+      {...(sanitizedProps as unknown as AccordionControlProps)}
+    >
+      {children}
+    </MantineAccordion.Control>
+  );
+});
+AccordionControl.displayName = "AccordionControl";
+
+// ==== ACCORDION PANEL ====
+export type AccordionPanelWrapperProps =
+  RecursicaOverStyled<AccordionPanelProps>;
+
+export const AccordionPanel = forwardRef<
+  HTMLDivElement,
+  AccordionPanelWrapperProps
+>(function AccordionPanel({ overStyled = false, ...rest }, ref) {
+  const sanitizedProps = filterStylingProps(rest, overStyled);
+  const classNameProp = (sanitizedProps as Record<string, unknown>)
+    .className as string | undefined;
+
+  return (
+    <MantineAccordion.Panel
+      ref={ref}
+      className={classNameProp}
+      {...(sanitizedProps as unknown as AccordionPanelProps)}
+    />
+  );
+});
+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/index.ts

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

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

@@ -0,0 +1,111 @@
+/**
+ * AssistiveElement.module.css
+ * 
+ * HARDCODED VALUES:
+ * - margin / padding: 0 — Structural resets.
+ * - display: flex / align-items: flex-start — layout alignment.
+ */
+
+.root {
+  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 */
+
+  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
+  );
+}
+
+.textWrapper {
+  /* Text properties securely governed via layout mappings */
+  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
+  );
+
+  /* Fallback text wrap structures */
+  overflow-wrap: break-word;
+  white-space: normal;
+}
+
+.iconWrapper {
+  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 */
+}
+
+.iconWrapper 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;
+}
+
+/* 
+ * VARIANT MAPPINGS 
+ * Inherits colors natively mapped per variant. 
+ */
+
+.root[data-variant="help"] .textWrapper {
+  color: var(
+    --recursica_ui-kit_components_assistive-element_variants_types_help_properties_colors_text-color
+  ) !important;
+}
+.root[data-variant="help"] .iconWrapper svg {
+  color: var(
+    --recursica_ui-kit_components_assistive-element_variants_types_help_properties_colors_icon-color
+  ) !important;
+}
+
+.root[data-variant="error"] .textWrapper {
+  color: var(
+    --recursica_ui-kit_components_assistive-element_variants_types_error_properties_colors_text-color
+  ) !important;
+}
+.root[data-variant="error"] .iconWrapper svg {
+  color: var(
+    --recursica_ui-kit_components_assistive-element_variants_types_error_properties_colors_icon-color
+  ) !important;
+}

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

@@ -0,0 +1,73 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { AssistiveElement } from "./AssistiveElement";
+import { Layer } from "@recursica/adapter-common";
+import React from "react";
+
+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,
+  },
+  render: (args) => (
+    <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,
+  },
+  render: (args) => (
+    <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,
+  },
+  render: (args) => (
+    <Layer layer={0} style={{ padding: "48px" }}>
+      <AssistiveElement {...args} />
+    </Layer>
+  ),
+};

package/src/components/AssistiveElement/AssistiveElement.tsx

@@ -0,0 +1,91 @@
+import React, { forwardRef } from "react";
+import {
+  filterStylingProps,
+  type RecursicaOverStyled,
+} from "../../utils/filterStylingProps";
+import styles from "./AssistiveElement.module.css";
+
+export interface RecursicaAssistiveElementProps {
+  /** The semantic variant driving the icon and text colors natively mapped across the UI Kit tokens. */
+  assistiveVariant?: "help" | "error";
+  /** Explicitly toggle the rendering of the variant-specific SVG bounding box. */
+  assistiveWithIcon?: boolean;
+}
+
+export type AssistiveElementProps = RecursicaOverStyled<
+  React.HTMLAttributes<HTMLDivElement> & RecursicaAssistiveElementProps
+>;
+
+const InfoIcon = () => (
+  <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 AlertIcon = () => (
+  <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>
+);
+
+export const AssistiveElement = forwardRef<
+  HTMLDivElement,
+  AssistiveElementProps
+>(function AssistiveElement(
+  {
+    assistiveVariant = "help",
+    assistiveWithIcon = true,
+    children,
+    className,
+    overStyled = false,
+    ...rest
+  },
+  ref,
+) {
+  const sanitizedProps = filterStylingProps(rest, overStyled);
+  const restRecord = sanitizedProps as Record<string, unknown>;
+
+  const rootClass = styles.root;
+  const finalClass = className ? `${rootClass} ${className}` : rootClass;
+
+  const IconComponent = assistiveVariant === "error" ? AlertIcon : InfoIcon;
+
+  return (
+    <div
+      ref={ref}
+      className={finalClass}
+      data-variant={assistiveVariant}
+      style={restRecord.style as React.CSSProperties}
+      {...restRecord} // Spread standard HTML attributes (like id, aria-*, role) natively.
+    >
+      {assistiveWithIcon && (
+        <span className={styles.iconWrapper}>
+          <IconComponent />
+        </span>
+      )}
+      <span className={styles.textWrapper}>{children}</span>
+    </div>
+  );
+});
+
+AssistiveElement.displayName = "AssistiveElement";

package/src/components/Avatar/AVATAR_IMPLEMENTATION_NOTES.md

@@ -0,0 +1,24 @@
+# Avatar Component Implementation Notes
+
+## Architecture Decisions
+
+The `Avatar` component is an adapter over Mantine's `Avatar`. To ensure adherence to the `COMPONENT_GUIDE_WALKTHROUGH.md`:
+
+- We do not wrap `MantineAvatar` in any custom standard `div` elements, preserving DOM structure.
+- All styles strictly pull from explicit `--recursica_ui-kit_components_avatar_*` CSS tokens.
+
+## Structural Workarounds
+
+### Implicit `data-style`
+
+Mantine's Avatar implicitly renders an image, an icon, or a text node based on the properties passed (`src`, `var`, `children`).
+Recursica Tokens split Avatar styling distinctly across three separate categories: `image`, `icon`, and `text`.
+To correctly map these variables, our React component observes standard prop states and manually injects a `data-style="image|icon|text"` onto the root. The `Avatar.module.css` explicitly gates padding and generic sizing modifiers under these `data-style` attributes.
+
+### Flex Layout & Internal Spans
+
+Since Avatar children (icons or initials) require robust centering that might differ heavily across Recursica size mappings, all child content defaults to being wrapped in `span` elements (either `.textWrapper` or `.iconWrapper`). These spans enforce 100% height and flex formatting independent of the Mantine container constraints.
+
+### CSS Reset Hacks
+
+Noticeable `/* HARDCODE: ... */` hacks are deployed within `.root` to completely zero-out Mantine's `--avatar-bg` and internal variables statically since Recursica handles background-colors inherently via the CSS variants cascade.