@recursica/mantine-adapter 0.9.4 → 0.11.0

package/src/components/FormControlWrapper/FormControlWrapper.tsx

@@ -0,0 +1,157 @@
+import React, { forwardRef, useId } from "react";
+import { type InputWrapperProps } from "@mantine/core";
+import {
+  filterStylingProps,
+  type RecursicaOverStyled,
+} from "../../utils/filterStylingProps";
+import { Label, type RecursicaLabelProps } from "../Label/Label";
+import { FormControlLayout } from "../FormControlLayout/FormControlLayout";
+import { AssistiveElement } from "../AssistiveElement/AssistiveElement";
+import styles from "./FormControlWrapper.module.css";
+
+export interface RecursicaFormControlWrapperProps extends RecursicaLabelProps {
+  /** Overall structural flow mapping the Form Control natively cascading down to Label and Input logic. */
+  formLayout?: "stacked" | "side-by-side";
+  /** Securely replaces standard Mantine descriptions safely providing standard Assistive properties. */
+  assistiveText?: React.ReactNode;
+  /** Explicit toggle to suppress the Info icon rendering natively alongside the assistiveText. Defaults to true. */
+  assistiveWithIcon?: boolean;
+  /** Custom action area to render alongside the label instead of the default edit icon. */
+  labelActionArea?: React.ReactNode;
+  /** Pass the native maximum width design variable dynamically bounding the specific wrapper width exclusively. */
+  controlMaxWidth: string | undefined;
+  /** Pass the native minimum width design variable dynamically bounding the specific wrapper width exclusively. */
+  controlMinWidth: string | undefined;
+}
+
+export type FormControlWrapperProps = RecursicaOverStyled<
+  Omit<InputWrapperProps, "labelProps" | "inputWrapperOrder"> &
+    RecursicaFormControlWrapperProps
+>;
+
+export const FormControlWrapper = forwardRef<
+  HTMLDivElement,
+  FormControlWrapperProps
+>(function FormControlWrapper(
+  {
+    formLayout,
+    labelSize,
+    labelAlignment,
+    labelOptionalText,
+    labelWithEditIcon,
+    labelActionArea,
+    onLabelEditClick,
+
+    label,
+    description,
+    assistiveText,
+    assistiveWithIcon = true,
+    controlMaxWidth,
+    controlMinWidth,
+    error,
+    required,
+    withAsterisk,
+    id: userProvidedId,
+    children,
+    className,
+    overStyled = false,
+    labelElement, // Extracted safely preventing bleeding into HTML domains
+    ...rest
+  },
+  ref,
+) {
+  // Generate a reliable ID to map the Label's HTML context down to the component array natively.
+  const generatedId = useId();
+  const id = userProvidedId || `recursica-fc-${generatedId}`;
+
+  // Evaluate explicit assistive fallbacks ensuring assistiveText correctly prioritizes natively over underlying Mantine configurations!
+  const resolvedAssistive = assistiveText || description;
+  const assistiveId = resolvedAssistive ? `${id}-assistive` : undefined;
+  const errorId = error ? `${id}-error` : undefined;
+
+  const sanitizedProps = filterStylingProps(rest, overStyled);
+  const restRecord = sanitizedProps as Record<string, unknown>;
+
+  const classNameProp =
+    className || (restRecord.className as string | undefined);
+  const rootClass = styles.root;
+  const finalClass = classNameProp
+    ? `${rootClass} ${classNameProp}`
+    : rootClass;
+
+  // Clone ARIA identifiers directly back down into the nested children wrapper so screen-readers natively hook the external strings
+  const content = React.isValidElement(children)
+    ? React.cloneElement(
+        children as React.ReactElement<Record<string, unknown>>,
+        {
+          ...(resolvedAssistive &&
+          !(children.props as Record<string, unknown>)["aria-describedby"]
+            ? { "aria-describedby": assistiveId }
+            : {}),
+          ...(error &&
+          !(children.props as Record<string, unknown>)["aria-errormessage"]
+            ? { "aria-errormessage": errorId }
+            : {}),
+        },
+      )
+    : children;
+
+  const labelNode = label ? (
+    <Label
+      id={id} // Directly binds ARIA references down
+      labelAlignment={labelAlignment}
+      labelOptionalText={labelOptionalText}
+      labelWithEditIcon={labelWithEditIcon}
+      labelActionArea={labelActionArea}
+      onLabelEditClick={onLabelEditClick}
+      required={withAsterisk ?? required}
+      // Manually propagate relevant structural logic if underlying groups dictate Label to act as generic wrapper
+      {...(labelElement === "div" ? { as: "div" } : {})}
+    >
+      {label}
+    </Label>
+  ) : undefined;
+
+  return (
+    <FormControlLayout
+      ref={ref}
+      className={finalClass}
+      formLayout={formLayout}
+      labelSize={labelSize}
+      controlMaxWidth={controlMaxWidth}
+      controlMinWidth={controlMinWidth}
+      leftSection={labelNode}
+      {...restRecord}
+    >
+      {/*
+        The Core Input Wrapper & Controls
+        Nakedly inject the actual field elements alongside natively bridged Assistive components mapped dynamically.
+      */}
+      <div className={styles.inputSection}>
+        {content}
+
+        {error && (
+          <AssistiveElement
+            id={errorId}
+            assistiveVariant="error"
+            assistiveWithIcon={assistiveWithIcon}
+          >
+            {error}
+          </AssistiveElement>
+        )}
+
+        {!error && resolvedAssistive && (
+          <AssistiveElement
+            id={assistiveId}
+            assistiveVariant="help"
+            assistiveWithIcon={assistiveWithIcon}
+          >
+            {resolvedAssistive}
+          </AssistiveElement>
+        )}
+      </div>
+    </FormControlLayout>
+  );
+});
+
+FormControlWrapper.displayName = "FormControlWrapper";

package/src/components/Group/GROUP_IMPLEMENTATION_NOTES.md

@@ -0,0 +1,4 @@
+# Group Implementation Notes
+
+The `Group` component is a generic flex layout wrapper mapped directly to Mantine's `Group`.
+It currently does not require any custom logical layouts or CSS workarounds since it serves only to organize layout structure, and doesn't enforce any strict design-system token styling itself. All gap, align, wrap, and justify properties pass safely through via the `filterStylingProps` layout-property allowance.

package/src/components/Group/Group.module.css

@@ -0,0 +1,7 @@
+/* HARDCODED VALUES:
+ * None. This is a generic flex layout wrapper.
+ */
+
+.root {
+  /* Mantine handles flex, gap, align, justify. No intrinsic design-system styles required for pure layout wrappers. */
+}

package/src/components/Group/Group.stories.tsx

@@ -0,0 +1,120 @@
+import React from "react";
+import type { Meta, StoryObj } from "@storybook/react";
+import { Group } from "./Group";
+import { Button } from "../Button";
+import { Text } from "../Text/Text";
+
+type GroupStoryProps = React.ComponentProps<typeof Group>;
+
+const meta: Meta<GroupStoryProps> = {
+  title: "UI-Kit/Group",
+  component: Group,
+  tags: ["autodocs"],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          "Group is a flex horizontal layout container that maps directly to Mantine's Group component allowing safe layout property passing.",
+      },
+    },
+  },
+  args: {
+    gap: "rec-default",
+    align: "center",
+    justify: "flex-start",
+    wrap: "wrap",
+  },
+  argTypes: {
+    gap: {
+      control: "select",
+      options: [
+        "rec-none",
+        "rec-sm",
+        "rec-default",
+        "rec-md",
+        "rec-lg",
+        "rec-xl",
+        "rec-2xl",
+        "xs",
+        "sm",
+        "md",
+        "lg",
+        "xl",
+      ],
+      description: "Gap between elements",
+    },
+    align: {
+      control: "select",
+      options: ["flex-start", "center", "flex-end", "stretch"],
+      description: "Align-items property",
+    },
+    justify: {
+      control: "select",
+      options: [
+        "flex-start",
+        "center",
+        "flex-end",
+        "space-between",
+        "space-around",
+      ],
+      description: "Justify-content property",
+    },
+    wrap: {
+      control: "select",
+      options: ["wrap", "nowrap", "wrap-reverse"],
+      description: "Flex-wrap property",
+    },
+    defaultChecked: {
+      table: { disable: true },
+    },
+    rowGap: {
+      table: { disable: true },
+    },
+    columnGap: {
+      table: { disable: true },
+    },
+  },
+};
+
+export default meta;
+
+type Story = StoryObj<GroupStoryProps>;
+
+export const Default: Story = {
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars, @typescript-eslint/no-explicit-any
+  render: ({ withLayer, layer, ...args }: any) => (
+    <Group {...args}>
+      <Button variant="solid">Primary</Button>
+      <Button variant="outline">Secondary</Button>
+      <Text>Text element within Group</Text>
+    </Group>
+  ),
+};
+
+export const StaticGapSmall: Story = {
+  args: {
+    gap: "rec-sm",
+  },
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars, @typescript-eslint/no-explicit-any
+  render: ({ withLayer, layer, ...args }: any) => (
+    <Group {...args}>
+      <Button variant="solid">Item 1</Button>
+      <Button variant="solid">Item 2</Button>
+      <Button variant="solid">Item 3</Button>
+    </Group>
+  ),
+};
+
+export const StaticGapLarge: Story = {
+  args: {
+    gap: "rec-xl",
+  },
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars, @typescript-eslint/no-explicit-any
+  render: ({ withLayer, layer, ...args }: any) => (
+    <Group {...args}>
+      <Button variant="solid">Item 1</Button>
+      <Button variant="solid">Item 2</Button>
+      <Button variant="solid">Item 3</Button>
+    </Group>
+  ),
+};

package/src/components/Group/Group.tsx

@@ -0,0 +1,68 @@
+import React, { forwardRef } from "react";
+import {
+  Group as MantineGroup,
+  type GroupProps as MantineGroupProps,
+} from "@mantine/core";
+import {
+  filterStylingProps,
+  type RecursicaOverStyled,
+  type RecursicaSpacing,
+} from "../../utils/filterStylingProps";
+import styles from "./Group.module.css";
+
+export interface RecursicaGroupProps {
+  /**
+   * Children components inside the group
+   */
+  children?: React.ReactNode;
+  gap?: MantineGroupProps["gap"] | RecursicaSpacing;
+  rowGap?: MantineGroupProps["gap"] | RecursicaSpacing;
+  columnGap?: MantineGroupProps["gap"] | RecursicaSpacing;
+}
+
+/**
+ * Group flex layout wrapper
+ */
+export type GroupProps = RecursicaOverStyled<
+  MantineGroupProps & RecursicaGroupProps
+>;
+
+export const Group = forwardRef<HTMLDivElement, GroupProps>(function Group(
+  { children, overStyled = false, gap = "rec-default", ...rest },
+  ref,
+) {
+  const sanitizedProps = filterStylingProps({ ...rest, gap }, overStyled);
+  const restRecord = sanitizedProps as Record<string, unknown>;
+
+  const mergedClassNames: Partial<Record<string, string>> = {
+    root: styles.root,
+  };
+
+  const classNamesProp = restRecord.classNames;
+  if (
+    classNamesProp &&
+    typeof classNamesProp === "object" &&
+    !Array.isArray(classNamesProp)
+  ) {
+    const o = classNamesProp as Partial<Record<string, string>>;
+    mergedClassNames.root = o.root ? `${styles.root} ${o.root}` : styles.root;
+  }
+
+  const classNameProp = restRecord.className as string | undefined;
+  const finalClass = classNameProp
+    ? `${styles.root} ${classNameProp}`
+    : styles.root;
+
+  return (
+    <MantineGroup
+      ref={ref}
+      className={finalClass}
+      classNames={mergedClassNames}
+      {...sanitizedProps}
+    >
+      {children}
+    </MantineGroup>
+  );
+});
+
+Group.displayName = "Group";

package/src/components/HoverCard/HoverCard.stories.tsx

@@ -0,0 +1,17 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { HoverCard } from "./HoverCard";
+import { ComingSoon } from "@recursica/storybook-template";
+
+const meta: Meta<typeof HoverCard> = {
+  title: "UI-Kit/🚧 HoverCard",
+  component: HoverCard,
+  tags: ["autodocs"],
+};
+
+export default meta;
+
+type Story = StoryObj<typeof HoverCard>;
+
+export const Default: Story = {
+  render: () => <ComingSoon componentName="HoverCard" />,
+};

package/src/components/HoverCard/HoverCard.tsx

@@ -0,0 +1,7 @@
+import React from "react";
+
+export type HoverCardProps = React.HTMLAttributes<HTMLDivElement>;
+
+export const HoverCard: React.FC<HoverCardProps> = (props) => {
+  return <div {...props}>HoverCard</div>;
+};

package/src/components/Label/LABEL_IMPLEMENTATION_NOTES.md

@@ -0,0 +1,48 @@
+# Label Implementation Notes
+
+## Architecture Overview
+
+The `Label` component is fundamentally built as a strict, localized wrapper around Mantine's native `Input.Label`. The core goal is to preserve context, ref-forwarding, and native accessibility links, while completely overriding visual behaviors via Recursica design variables in scoped CSS.
+
+## Key Design Decisions
+
+### **Layout Architecture**
+
+- Because Recursica dictates complex alignments between primary label text, asterisks, edit icons, and optional strings, Mantine's rigid form label flow could not be used out-of-the-box.
+- Implemented `display: flex; flex-wrap: wrap;` directly on `.root`.
+- Injected strict integer-based flex `order` properties (e.g. `order: 1` for text, `order: 2` for `required`, `order: 5` for `optionalText`) to physically decouple DOM rendering from markup flow.
+- Because `optionalText` often acts as secondary contextual detail, it forces `flex-basis: 100%`, securely wrapping to a secondary line underneath the primary label properties and transforming the horizontal gap spacing seamlessly into a `margin-top` vector.
+
+### **Optional Text & Required Mutually Exclusive Parsing**
+
+- By design standards, a component cannot logically be both "Required" and mapped as "Optional".
+- To bulletproof implementations natively, the adapter forcibly suppresses rendering of the `resolvedOptionalText` strings if the parent wrapper invokes `required={true}`.
+- `optionalText` can operate as dynamic data or specifically as a boolean `true`, which forces the adapter to natively render the formal `(Optional)` string map.
+
+### **The "Edit Icon" Replacer Logic**
+
+- Passing `withEditIcon={true}` evaluates it as fundamentally mutually exclusive to the standard required indicator asterisk.
+- `required={required && !withEditIcon}` is passed to the underlying Mantine structure so the native `*` is entirely suppressed.
+- Added localized styling via `data-replaces-asterisk={required ? "true" : undefined}` onto the `.editIconWrapper` element. If an editable instance is simultaneously designated as required, the edit icon functionally assumes the indicator role natively, overriding its default icon metrics explicitly to match `--recursica_ui-kit_components_label_properties_colors_asterisk`.
+
+### **Bypassing `Input.Wrapper` Integrations**
+
+- By decoupling from Mantine's standard `Input.Wrapper`, the `Label` component is exclusively mapped manually through `FormControlWrapper`. This grants us exact visual sync regarding where the label renders based on `formLayout="stacked"` or `formLayout="side-by-side"`, without fighting internal Mantine positional hooks that assume vertical stacking by default.
+
+### **Label Size Container Constraints**
+
+- The `labelSize` parameter (mapping values like `"small"`) internally **does not scale typographic font metrics**. Instead, it dynamically defines the explicit horizontal bounding width limit of the block container itself.
+- **Architectural Rule:** `labelSize` modifications are strictly designed to execute exclusively when `formLayout="side-by-side"` is active. It acts as an optical grid threshold ensuring left-aligned string wrappers constrain correctly uniformly down a column without bleeding into the physical input arrays alongside them.
+
+## Outstanding Technical Debt / Issues
+
+### **Description Property Omission**
+
+- **Issue:** Currently, the adapter `Label` does not natively parse or support a structured `description` node directly attached beneath it.
+- **Context:** Standard forms often attach subtext beneath inputs, but mapping a description purely within the `<Label>` (distinct from an overall form-control description) is omitted structurally until subsequent UI Kit requirements mandate dedicated `description` styles locally on the label component itself.
+
+### **Global Interactive Hover Mappings**
+
+- **Issue:** Currently, the `editIconWrapper` lacks a dedicated hover background layer.
+- **Context:** While the global theme abstracts interactive hover environments deeply using layered variable syntax (e.g., `--recursica_brand_layer_1_elements_interactive_hover-color`), Recursica's token generation framework natively fails to expose a universally generic placeholder token (e.g., `--recursica_elements_interactive_hover-color`) which downstream wrappers can map their `<Layer>` injections directly into safely.
+- **Resolution Path:** We are explicitly ignoring the `.editIconWrapper:hover` background color assignment until the raw Figma token exports directly scaffold a generic token placeholder that we can interface cleanly with across arbitrary `<Layer>` contexts, avoiding manually mapping statically hardcoded depths (`layer-0`, `layer-1`).

package/src/components/Label/Label.module.css

@@ -0,0 +1,140 @@
+/* HARDCODED VALUES:
+   - display: flex helps us leverage flex 'order' to perfectly position Mantine's injected asterisk.
+   - align-items: baseline ensures text logic lines up nicely if font sizes differ slightly.
+   - margin/padding resets.
+*/
+
+.root {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: baseline;
+  box-sizing: border-box;
+  margin: 0;
+  color: var(--recursica_ui-kit_components_label_properties_colors_text);
+}
+
+.root[data-alignment="left"] {
+  justify-content: flex-start;
+  text-align: left;
+}
+
+.root[data-alignment="right"] {
+  justify-content: flex-end;
+  text-align: right;
+}
+
+.labelText {
+  order: 1;
+  font-family: var(
+    --recursica_ui-kit_components_label_properties_label-text_font-family
+  );
+  font-size: var(
+    --recursica_ui-kit_components_label_properties_label-text_font-size
+  );
+  font-weight: var(
+    --recursica_ui-kit_components_label_properties_label-text_font-weight
+  );
+  letter-spacing: var(
+    --recursica_ui-kit_components_label_properties_label-text_letter-spacing
+  );
+  line-height: var(
+    --recursica_ui-kit_components_label_properties_label-text_line-height
+  );
+  font-style: var(
+    --recursica_ui-kit_components_label_properties_label-text_font-style,
+    normal
+  );
+  text-decoration: var(
+    --recursica_ui-kit_components_label_properties_label-text_text-decoration,
+    none
+  );
+  text-transform: var(
+    --recursica_ui-kit_components_label_properties_label-text_text-transform,
+    none
+  );
+}
+
+.required {
+  order: 2;
+  margin-left: var(
+    --recursica_ui-kit_components_label_properties_required-indicator-gap
+  );
+  color: var(--recursica_ui-kit_components_label_properties_colors_asterisk);
+
+  /* Inherit identical typography bounds to prevent flex row line-height stretching */
+  font-family: var(
+    --recursica_ui-kit_components_label_properties_label-text_font-family
+  );
+  font-size: var(
+    --recursica_ui-kit_components_label_properties_label-text_font-size
+  );
+  line-height: var(
+    --recursica_ui-kit_components_label_properties_label-text_line-height
+  );
+}
+
+.optionalText {
+  order: 5;
+  flex-basis: 100%;
+  margin-top: var(
+    --recursica_ui-kit_components_label_properties_label-optional-text-gap
+  );
+  margin-left: 0;
+  font-family: var(
+    --recursica_ui-kit_components_label_properties_optional-text_font-family
+  );
+  font-size: var(
+    --recursica_ui-kit_components_label_properties_optional-text_font-size
+  );
+  font-weight: var(
+    --recursica_ui-kit_components_label_properties_optional-text_font-weight
+  );
+  letter-spacing: var(
+    --recursica_ui-kit_components_label_properties_optional-text_letter-spacing
+  );
+  line-height: var(
+    --recursica_ui-kit_components_label_properties_optional-text_line-height
+  );
+  font-style: normal;
+  text-decoration: var(
+    --recursica_ui-kit_components_label_properties_optional-text_text-decoration,
+    none
+  );
+  text-transform: var(
+    --recursica_ui-kit_components_label_properties_optional-text_text-transform,
+    none
+  );
+  color: inherit;
+  opacity: var(
+    --recursica_ui-kit_components_label_properties_colors_optional-text-opacity
+  );
+}
+
+.actionAreaWrapper {
+  order: 4;
+  margin-left: var(
+    --recursica_ui-kit_components_label_properties_edit-icon-gap
+  );
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+}
+
+.editIconWrapper {
+  order: 4;
+  margin-left: var(
+    --recursica_ui-kit_components_label_properties_edit-icon-gap
+  );
+  background: none;
+  border: none;
+  padding: 0;
+  cursor: pointer;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  color: inherit;
+}
+
+.editIconWrapper[data-replaces-asterisk="true"] {
+  color: var(--recursica_ui-kit_components_label_properties_colors_asterisk);
+}