@recursica/mantine-adapter 0.6.0 → 0.7.0

package/src/components/FormControlWrapper/FormControlWrapper.module.css

@@ -0,0 +1,46 @@
+/* FormControlWrapper.module.css */
+
+.root {
+  display: flex;
+  margin: 0; /* Hardcoded structural reset */
+  padding: 0; /* Hardcoded structural reset */
+  max-width: var(--form-control-max-width, 100%);
+  min-width: var(--form-control-min-width, auto);
+}
+
+/* Base Structural Stacked Layout */
+.root[data-form-layout="stacked"] {
+  flex-direction: column;
+}
+
+/* Base Structural Grid Layout */
+.root[data-form-layout="side-by-side"] {
+  flex-direction: row;
+  align-items: flex-start;
+  flex-wrap: wrap; /* Allows collapse if screen is too thin, though standard flex width should hold */
+}
+
+/* Left structural justification defaults (push input mapping) */
+.root[data-form-alignment="left"] {
+  /* Inherited naturally via row/column flows */
+}
+
+/* Right structural justification defaults */
+.root[data-form-alignment="right"] {
+  /* To justify entire form control components to the right */
+  justify-content: flex-end;
+}
+
+.labelSection {
+  /* Width dimensions are strictly governed natively inside Label.module.css's sizing variant mapping */
+  flex-shrink: 0;
+  display: flex;
+  flex-direction: column;
+}
+
+.inputSection {
+  display: flex; /* Groups internal field alongside subsequent errors/descriptions */
+  flex-direction: column;
+  flex: 1; /* Consumes the remaining x-axis in grid columns natively */
+  min-width: 0; /* Break boundary preventing internal flex explosion */
+}

package/src/components/FormControlWrapper/FormControlWrapper.stories.tsx

@@ -0,0 +1,116 @@
+import React from "react";
+import type { Meta, StoryObj } from "@storybook/react";
+import {
+  FormControlWrapper,
+  type FormControlWrapperProps,
+} from "./FormControlWrapper";
+import { TextField } from "../TextField/TextField";
+import { formControlArgTypes } from "../../../.storybook/commonArgTypes";
+
+type WrapperStoryProps = FormControlWrapperProps;
+
+const meta: Meta<WrapperStoryProps> = {
+  title: "UI-Kit/FormControlWrapper",
+  component: FormControlWrapper,
+  tags: ["autodocs"],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          "The `FormControlWrapper` is the ultimate structural replacement for Mantine's built-in `Input.Wrapper`. By abandoning Mantine's opinionated wrappers entirely, we centralize all label tracking, error rendering, ARIA generation, and grid layouts natively inside this single component.\n\n### Usage with Naked Primitives\nThis component wraps 'naked' elements like `<Input>` directly. The demonstration stories below utilize `<TextField>` as a native display vehicle, since `<TextField>` natively pipes all its properties structurally back into this wrapper.",
+      },
+    },
+  },
+  argTypes: {
+    ...formControlArgTypes,
+    error: {
+      control: "text",
+      description:
+        "Error string driving native assistive component and validation markers.",
+    },
+    assistiveText: {
+      control: "text",
+      description:
+        "Helper instructions safely dynamically anchored below the input box.",
+    },
+    assistiveWithIcon: {
+      control: "boolean",
+    },
+    required: {
+      control: "boolean",
+    },
+  },
+};
+
+export default meta;
+
+type Story = StoryObj<WrapperStoryProps>;
+
+const renderWithTextField = (args: WrapperStoryProps) => (
+  <TextField placeholder="Form Control primitive mapped..." {...args} />
+);
+
+export const Default: Story = {
+  args: {
+    label: "Account Username",
+    formLayout: "stacked",
+    assistiveText: "Validation occurs immediately natively.",
+  },
+  render: renderWithTextField,
+};
+
+export const VisualErrorState: Story = {
+  args: {
+    label: "Encryption Protocol",
+    formLayout: "stacked",
+    error: "Strict validation limits reached. Handshake rejected securely.",
+  },
+  render: renderWithTextField,
+};
+
+export const RequiredArchitecture: Story = {
+  args: {
+    label: "Root Password",
+    formLayout: "side-by-side",
+    required: true,
+    assistiveText: "Bypass string structure required to initiate protocol.",
+  },
+  render: renderWithTextField,
+};
+
+export const WithoutAssistiveIcons: Story = {
+  args: {
+    label: "Server Domain",
+    assistiveText:
+      "A standard text boundary without default native icon parameters bounding.",
+    assistiveWithIcon: false,
+  },
+  render: renderWithTextField,
+};
+
+export const NativeChildrenDirectly: Story = {
+  description:
+    "Bypassing the TextField map to show exactly how native `<input>` hooks execute inside the raw wrapper natively perfectly.",
+  args: {
+    label: "Raw HTML Checkbox",
+    formLayout: "side-by-side",
+    assistiveText: "This wraps a raw HTML input tag mapping correctly.",
+  },
+  render: (args) => (
+    <div
+      style={{
+        display: "flex",
+        gap: "10px",
+        alignItems: "center",
+      }}
+    >
+      {/* We can cleanly wrap even un-styled HTML primitives! */}
+      <FormControlWrapper {...args}>
+        <input
+          type="checkbox"
+          style={{ margin: 0, width: "16px", height: "16px" }}
+        />
+      </FormControlWrapper>
+    </div>
+  ),
+};

package/src/components/FormControlWrapper/FormControlWrapper.tsx

@@ -0,0 +1,170 @@
+import React, { forwardRef, useId } from "react";
+import { type InputWrapperProps, Box } from "@mantine/core";
+import {
+  filterStylingProps,
+  type RecursicaOverStyled,
+} from "../../utils/filterStylingProps";
+import { Label, type RecursicaLabelProps } from "../Label/Label";
+import { AssistiveElement } from "../AssistiveElement/AssistiveElement";
+import styles from "./FormControlWrapper.module.css";
+
+export interface RecursicaFormControlWrapperProps extends RecursicaLabelProps {
+  /** 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;
+
+  return (
+    <Box
+      ref={ref}
+      className={finalClass}
+      data-form-layout={formLayout || "stacked"}
+      data-form-alignment={labelAlignment || "left"}
+      style={
+        {
+          ...((restRecord.style as React.CSSProperties) || {}),
+          ...(controlMaxWidth
+            ? { "--form-control-max-width": controlMaxWidth }
+            : {}),
+          ...(controlMinWidth
+            ? { "--form-control-min-width": controlMinWidth }
+            : {}),
+        } as React.CSSProperties
+      }
+      {...restRecord}
+    >
+      {/* 
+        Section 1: The Native Custom Label
+        Bypasses Mantine's built-in Input.Wrapper Label entirely in favor of explicit Recursica formatting.
+      */}
+      {label && (
+        <div className={styles.labelSection}>
+          <Label
+            id={id} // Directly binds ARIA references down
+            formLayout={formLayout}
+            labelSize={labelSize}
+            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>
+        </div>
+      )}
+
+      {/*
+        Section 2: 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>
+    </Box>
+  );
+});
+
+FormControlWrapper.displayName = "FormControlWrapper";

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,177 @@
+/* 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;
+}
+
+.root[data-layout="stacked"] {
+  padding-bottom: var(
+    --recursica_ui-kit_components_label_variants_layouts_stacked_properties_bottom-padding
+  );
+  min-height: var(
+    --recursica_ui-kit_components_label_variants_layouts_stacked_properties_min-height
+  );
+}
+
+.root[data-layout="side-by-side"] {
+  padding-top: var(
+    --recursica_ui-kit_components_label_variants_layouts_side-by-side_properties_vertical-padding
+  );
+  padding-bottom: var(
+    --recursica_ui-kit_components_label_variants_layouts_side-by-side_properties_vertical-padding
+  );
+  min-height: var(
+    --recursica_ui-kit_components_label_variants_layouts_side-by-side_properties_min-height
+  );
+  /* In side-by-side, the label exists to the left of its input, so we use the gutter gap here. */
+  margin-right: var(
+    --recursica_ui-kit_components_label_variants_layouts_side-by-side_properties_gutter
+  );
+}
+
+.root[data-layout="side-by-side"][data-size="default"] {
+  width: var(
+    --recursica_ui-kit_components_label_variants_layouts_side-by-side_variants_sizes_default_properties_width
+  );
+}
+
+.root[data-layout="side-by-side"][data-size="small"] {
+  width: var(
+    --recursica_ui-kit_components_label_variants_layouts_side-by-side_variants_sizes_small_properties_width
+  );
+}
+
+.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);
+}