@recursica/mantine-adapter 0.5.0 → 0.7.0

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.

package/src/components/Avatar/Avatar.module.css

@@ -0,0 +1,340 @@
+/*
+HARDCODED VALUES:
+- justify-content, align-items, display: Center content for custom internal spans
+- Mantine overrides (--avatar-bd, --avatar-bg, --avatar-color): Remove default static themes
+- Default object-fit for image
+- Transitions and standard flex layouts
+- Image has no explicit size tokens other than root size, assume it scales 100%
+*/
+
+.root {
+  box-sizing: border-box;
+  margin: 0;
+  border-style: solid;
+  overflow: hidden;
+  position: relative;
+  transition: all 0.2s ease;
+
+  /* HARDCODE: Remove internal Mantine custom props that interfere */
+  --avatar-bd: none;
+  --avatar-bg: transparent;
+  --avatar-color: inherit;
+}
+
+/* ==== SIZES ==== */
+.root[data-size="small"] {
+  width: var(
+    --recursica_ui-kit_components_avatar_variants_sizes_small_properties_width
+  );
+  height: var(
+    --recursica_ui-kit_components_avatar_variants_sizes_small_properties_height
+  );
+  border-width: var(
+    --recursica_ui-kit_components_avatar_variants_sizes_small_properties_border-size
+  );
+}
+
+.root[data-size="small"] .iconWrapper {
+  width: var(
+    --recursica_ui-kit_components_avatar_variants_sizes_small_properties_icon-size
+  );
+  height: var(
+    --recursica_ui-kit_components_avatar_variants_sizes_small_properties_icon-size
+  );
+}
+
+.root[data-size="small"] .textWrapper {
+  font-family: var(
+    --recursica_ui-kit_components_avatar_variants_sizes_small_properties_text_font-family
+  );
+  font-size: var(
+    --recursica_ui-kit_components_avatar_variants_sizes_small_properties_text_font-size
+  );
+  font-style: var(
+    --recursica_ui-kit_components_avatar_variants_sizes_small_properties_text_font-style
+  );
+  font-weight: var(
+    --recursica_ui-kit_components_avatar_variants_sizes_small_properties_text_font-weight
+  );
+  letter-spacing: var(
+    --recursica_ui-kit_components_avatar_variants_sizes_small_properties_text_letter-spacing
+  );
+  line-height: var(
+    --recursica_ui-kit_components_avatar_variants_sizes_small_properties_text_line-height
+  );
+  text-decoration: var(
+    --recursica_ui-kit_components_avatar_variants_sizes_small_properties_text_text-decoration
+  );
+  text-transform: var(
+    --recursica_ui-kit_components_avatar_variants_sizes_small_properties_text_text-transform
+  );
+}
+
+.root[data-size="default"] {
+  width: var(
+    --recursica_ui-kit_components_avatar_variants_sizes_default_properties_width
+  );
+  height: var(
+    --recursica_ui-kit_components_avatar_variants_sizes_default_properties_height
+  );
+  border-width: var(
+    --recursica_ui-kit_components_avatar_variants_sizes_default_properties_border-size
+  );
+}
+
+.root[data-size="default"] .iconWrapper {
+  width: var(
+    --recursica_ui-kit_components_avatar_variants_sizes_default_properties_icon-size
+  );
+  height: var(
+    --recursica_ui-kit_components_avatar_variants_sizes_default_properties_icon-size
+  );
+}
+
+.root[data-size="default"] .textWrapper {
+  font-family: var(
+    --recursica_ui-kit_components_avatar_variants_sizes_default_properties_text_font-family
+  );
+  font-size: var(
+    --recursica_ui-kit_components_avatar_variants_sizes_default_properties_text_font-size
+  );
+  font-style: var(
+    --recursica_ui-kit_components_avatar_variants_sizes_default_properties_text_font-style
+  );
+  font-weight: var(
+    --recursica_ui-kit_components_avatar_variants_sizes_default_properties_text_font-weight
+  );
+  letter-spacing: var(
+    --recursica_ui-kit_components_avatar_variants_sizes_default_properties_text_letter-spacing
+  );
+  line-height: var(
+    --recursica_ui-kit_components_avatar_variants_sizes_default_properties_text_line-height
+  );
+  text-decoration: var(
+    --recursica_ui-kit_components_avatar_variants_sizes_default_properties_text_text-decoration
+  );
+  text-transform: var(
+    --recursica_ui-kit_components_avatar_variants_sizes_default_properties_text_text-transform
+  );
+}
+
+.root[data-size="large"] {
+  width: var(
+    --recursica_ui-kit_components_avatar_variants_sizes_large_properties_width
+  );
+  height: var(
+    --recursica_ui-kit_components_avatar_variants_sizes_large_properties_height
+  );
+  border-width: var(
+    --recursica_ui-kit_components_avatar_variants_sizes_large_properties_border-size
+  );
+}
+
+.root[data-size="large"] .iconWrapper {
+  width: var(
+    --recursica_ui-kit_components_avatar_variants_sizes_large_properties_icon-size
+  );
+  height: var(
+    --recursica_ui-kit_components_avatar_variants_sizes_large_properties_icon-size
+  );
+}
+
+.root[data-size="large"] .textWrapper {
+  font-family: var(
+    --recursica_ui-kit_components_avatar_variants_sizes_large_properties_text_font-family
+  );
+  font-size: var(
+    --recursica_ui-kit_components_avatar_variants_sizes_large_properties_text_font-size
+  );
+  font-style: var(
+    --recursica_ui-kit_components_avatar_variants_sizes_large_properties_text_font-style
+  );
+  font-weight: var(
+    --recursica_ui-kit_components_avatar_variants_sizes_large_properties_text_font-weight
+  );
+  letter-spacing: var(
+    --recursica_ui-kit_components_avatar_variants_sizes_large_properties_text_letter-spacing
+  );
+  line-height: var(
+    --recursica_ui-kit_components_avatar_variants_sizes_large_properties_text_line-height
+  );
+  text-decoration: var(
+    --recursica_ui-kit_components_avatar_variants_sizes_large_properties_text_text-decoration
+  );
+  text-transform: var(
+    --recursica_ui-kit_components_avatar_variants_sizes_large_properties_text_text-transform
+  );
+}
+
+/* ==== STYLES & VARIANTS ==== */
+
+/* 1. IMAGE */
+.root[data-style="image"] {
+  border-radius: var(
+    --recursica_ui-kit_components_avatar_variants_styles_image_properties_border-radius
+  );
+  border-width: var(
+    --recursica_ui-kit_components_avatar_variants_styles_image_properties_border-size
+  );
+  padding: var(
+    --recursica_ui-kit_components_avatar_variants_styles_image_properties_padding
+  );
+
+  /* Missing specific standard variant tokens so hardcoding typical resets */
+  background-color: transparent;
+  border-color: transparent;
+}
+
+/* Base styles for Internal Nodes */
+.image {
+  object-fit: cover;
+  width: 100%;
+  height: 100%;
+}
+
+.placeholder {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  width: 100%;
+  height: 100%;
+  color: inherit;
+  background-color: transparent;
+}
+
+.iconWrapper {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  flex-shrink: 0;
+}
+.iconWrapper > * {
+  width: 100%;
+  height: 100%;
+  object-fit: contain;
+}
+
+.textWrapper {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+}
+
+/* 2. ICON */
+.root[data-style="icon"] {
+  border-radius: var(
+    --recursica_ui-kit_components_avatar_variants_styles_icon_properties_border-radius
+  );
+  padding: var(
+    --recursica_ui-kit_components_avatar_variants_styles_icon_properties_padding
+  );
+}
+
+.root[data-style="icon"][data-variant="solid"] {
+  border-width: var(
+    --recursica_ui-kit_components_avatar_variants_styles_icon_variants_solid_properties_border-size
+  );
+  background-color: var(
+    --recursica_ui-kit_components_avatar_variants_styles_icon_variants_solid_properties_colors_background
+  );
+  border-color: var(
+    --recursica_ui-kit_components_avatar_variants_styles_icon_variants_solid_properties_colors_border-color
+  );
+  color: var(
+    --recursica_ui-kit_components_avatar_variants_styles_icon_variants_solid_properties_colors_icon-color,
+    var(
+      --recursica_ui-kit_components_avatar_variants_styles_icon_variants_solid_properties_colors_text-color
+    )
+  );
+}
+
+.root[data-style="icon"][data-variant="outline"] {
+  border-width: var(
+    --recursica_ui-kit_components_avatar_variants_styles_icon_variants_outline_properties_border-size
+  );
+  background-color: var(
+    --recursica_ui-kit_components_avatar_variants_styles_icon_variants_outline_properties_colors_background
+  );
+  border-color: var(
+    --recursica_ui-kit_components_avatar_variants_styles_icon_variants_outline_properties_colors_border-color
+  );
+  color: var(
+    --recursica_ui-kit_components_avatar_variants_styles_icon_variants_outline_properties_colors_icon-color,
+    var(
+      --recursica_ui-kit_components_avatar_variants_styles_icon_variants_outline_properties_colors_text-color
+    )
+  );
+}
+
+.root[data-style="icon"][data-variant="ghost"] {
+  border-width: var(
+    --recursica_ui-kit_components_avatar_variants_styles_icon_variants_ghost_properties_border-size
+  );
+  background-color: var(
+    --recursica_ui-kit_components_avatar_variants_styles_icon_variants_ghost_properties_colors_background
+  );
+  border-color: var(
+    --recursica_ui-kit_components_avatar_variants_styles_icon_variants_ghost_properties_colors_border-color
+  );
+  color: var(
+    --recursica_ui-kit_components_avatar_variants_styles_icon_variants_ghost_properties_colors_icon-color,
+    var(
+      --recursica_ui-kit_components_avatar_variants_styles_icon_variants_ghost_properties_colors_text-color
+    )
+  );
+}
+
+/* 3. TEXT */
+.root[data-style="text"] {
+  border-radius: var(
+    --recursica_ui-kit_components_avatar_variants_styles_text_properties_border-radius
+  );
+  padding: var(
+    --recursica_ui-kit_components_avatar_variants_styles_text_properties_padding
+  );
+}
+
+.root[data-style="text"][data-variant="solid"] {
+  border-width: var(
+    --recursica_ui-kit_components_avatar_variants_styles_text_variants_solid_properties_border-size
+  );
+  background-color: var(
+    --recursica_ui-kit_components_avatar_variants_styles_text_variants_solid_properties_colors_background
+  );
+  border-color: var(
+    --recursica_ui-kit_components_avatar_variants_styles_text_variants_solid_properties_colors_border-color
+  );
+  color: var(
+    --recursica_ui-kit_components_avatar_variants_styles_text_variants_solid_properties_colors_text-color
+  );
+}
+
+.root[data-style="text"][data-variant="outline"] {
+  border-width: var(
+    --recursica_ui-kit_components_avatar_variants_styles_text_variants_outline_properties_border-size
+  );
+  background-color: var(
+    --recursica_ui-kit_components_avatar_variants_styles_text_variants_outline_properties_colors_background
+  );
+  border-color: var(
+    --recursica_ui-kit_components_avatar_variants_styles_text_variants_outline_properties_colors_border-color
+  );
+  color: var(
+    --recursica_ui-kit_components_avatar_variants_styles_text_variants_outline_properties_colors_text-color
+  );
+}
+
+.root[data-style="text"][data-variant="ghost"] {
+  border-width: var(
+    --recursica_ui-kit_components_avatar_variants_styles_text_variants_ghost_properties_border-size
+  );
+  background-color: var(
+    --recursica_ui-kit_components_avatar_variants_styles_text_variants_ghost_properties_colors_background
+  );
+  border-color: var(
+    --recursica_ui-kit_components_avatar_variants_styles_text_variants_ghost_properties_colors_border-color
+  );
+  color: var(
+    --recursica_ui-kit_components_avatar_variants_styles_text_variants_ghost_properties_colors_text-color
+  );
+}