@recursica/mantine-adapter 0.6.0 → 0.7.0

package/src/components/Label/Label.stories.tsx

@@ -0,0 +1,123 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import React from "react";
+import type { Meta, StoryObj } from "@storybook/react";
+import { Label } from "./Label";
+import { TextField } from "../TextField/TextField";
+import { formControlArgTypes } from "../../../.storybook/commonArgTypes";
+
+type LabelStoryProps = React.ComponentProps<typeof Label>;
+
+const meta: Meta<LabelStoryProps> = {
+  title: "UI-Kit/Label",
+  component: Label,
+  tags: ["autodocs"],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          "The `Label` component is a strict Recursica-styled wrapper around Mantine's native `Input.Label`. It serves as the primary compositional primitive for all form fields, preserving Mantine's accessibility associations and context while strictly enforcing the Recursica atomic design system.\n\n### Usage with Form Inputs\nWhen working with form structures, render this `Label` component directly above your inputs or supply it to a component's overriding properties. The component automatically maps structural layout dimensions, dynamic alignment (`left` vs `right`), custom indicator gaps, and integrates a customized `optionalText` and `withEditIcon` flow that safely bypasses Mantine's native required asterisk mechanisms.",
+      },
+    },
+  },
+  argTypes: {
+    ...formControlArgTypes,
+  },
+};
+
+export default meta;
+
+type Story = StoryObj<LabelStoryProps>;
+
+// Utility mapping to pipe raw Label args structurally into TextField accurately
+const renderWithTextField = ({ children, ...args }: LabelStoryProps) => (
+  <TextField
+    label={children as React.ReactNode}
+    placeholder="Form Control primitive mapped..."
+    {...(args as any)}
+  />
+);
+
+export const Default: Story = {
+  args: {
+    children: "Dynamic Label (Controls)",
+    formLayout: "stacked",
+    labelSize: "default",
+    labelAlignment: "left",
+    required: false,
+    labelOptionalText: "",
+    labelWithEditIcon: false,
+  },
+  render: renderWithTextField,
+};
+
+export const StackedDefault: Story = {
+  args: {
+    children: "Email Address",
+    formLayout: "stacked",
+  },
+  render: renderWithTextField,
+};
+
+export const StackedRequired: Story = {
+  args: {
+    children: "Primary Network Node",
+    formLayout: "stacked",
+    required: true,
+  },
+  render: renderWithTextField,
+};
+
+export const StackedWithEditIcon: Story = {
+  args: {
+    children: "Environment Variables",
+    formLayout: "stacked",
+    labelWithEditIcon: true,
+  },
+  render: renderWithTextField,
+};
+
+export const SideBySideDefault: Story = {
+  args: {
+    children: "Status",
+    formLayout: "side-by-side",
+    labelSize: "default",
+  },
+  render: renderWithTextField,
+};
+
+export const RequiredSuppressesOptionalText: Story = {
+  args: {
+    children: "Full Name",
+    formLayout: "stacked",
+    required: true,
+    labelOptionalText: "This should not render",
+  },
+  render: renderWithTextField,
+};
+
+export const BooleanOptionalText: Story = {
+  args: {
+    children: "Middle Initial",
+    formLayout: "side-by-side",
+    labelOptionalText: true,
+  },
+  render: renderWithTextField,
+};
+
+export const WithEditIcon: Story = {
+  args: {
+    children: "Shipping Address",
+    formLayout: "side-by-side",
+    labelWithEditIcon: true,
+  },
+  render: renderWithTextField,
+};
+
+export const LayerOneSideBySide: Story = {
+  args: {
+    children: "Configuration",
+    formLayout: "side-by-side",
+    labelWithEditIcon: true,
+  },
+  render: renderWithTextField,
+};

package/src/components/Label/Label.tsx

@@ -0,0 +1,132 @@
+import React, { forwardRef } from "react";
+import { Input, type InputLabelProps } from "@mantine/core";
+import {
+  filterStylingProps,
+  type RecursicaOverStyled,
+} from "../../utils/filterStylingProps";
+import styles from "./Label.module.css";
+
+export interface RecursicaLabelProps {
+  /** Overall structural flow mapping the Form Control natively cascading down to Label and Input logic. */
+  formLayout?: "stacked" | "side-by-side";
+  /** Specifies the sizing metrics natively mapping the Label boundaries. */
+  labelSize?: "default" | "small";
+  /** Overall alignment directive for the label strings natively forcing Left/Right justification. */
+  labelAlignment?: "left" | "right";
+  /** Injects an indicator text block alongside the label. Can be boolean (`true` maps to '(Optional)') or custom React nodes. */
+  labelOptionalText?: boolean | React.ReactNode;
+  /** When true, forces the native Edit Icon to replace the standard asterisk visually. */
+  labelWithEditIcon?: boolean;
+  /** Custom action area to render alongside the label instead of the default edit icon. */
+  labelActionArea?: React.ReactNode;
+  /** Interaction hook invoked whenever a generated edit icon block natively triggers a click event. */
+  onLabelEditClick?: React.MouseEventHandler<HTMLButtonElement>;
+}
+
+export type LabelProps = RecursicaOverStyled<
+  Omit<InputLabelProps, "size"> & RecursicaLabelProps
+>;
+
+export const Label = forwardRef<HTMLLabelElement, LabelProps>(function Label(
+  {
+    formLayout = "stacked",
+    labelSize = "default",
+    labelAlignment,
+    required = false,
+    labelOptionalText,
+    labelWithEditIcon,
+    labelActionArea,
+    onLabelEditClick,
+    children,
+    overStyled = false,
+    ...rest
+  },
+  ref,
+) {
+  const resolvedAlignment =
+    labelAlignment || (formLayout === "side-by-side" ? "right" : "left");
+
+  let resolvedOptionalText: React.ReactNode | undefined;
+  if (!required) {
+    if (labelOptionalText === true) resolvedOptionalText = "optional";
+    else if (labelOptionalText) resolvedOptionalText = labelOptionalText;
+  }
+
+  const sanitizedProps = filterStylingProps(rest, overStyled);
+  const restRecord = sanitizedProps as Record<string, unknown>;
+
+  const mergedClassNames: Partial<Record<string, string>> = {
+    label: styles.root,
+    required: styles.required,
+  };
+
+  const classNamesProp = restRecord.classNames;
+  if (
+    classNamesProp &&
+    typeof classNamesProp === "object" &&
+    !Array.isArray(classNamesProp)
+  ) {
+    const o = classNamesProp as Partial<Record<string, string>>;
+    mergedClassNames.label = o.label
+      ? `${styles.root} ${o.label}`
+      : styles.root;
+    mergedClassNames.required = o.required
+      ? `${styles.required} ${o.required}`
+      : styles.required;
+  }
+
+  const classNameProp = restRecord.className as string | undefined;
+  const finalClass = classNameProp
+    ? `${styles.root} ${classNameProp}`
+    : styles.root;
+
+  return (
+    <Input.Label
+      ref={ref}
+      className={finalClass}
+      classNames={mergedClassNames}
+      data-layout={formLayout}
+      data-size={labelSize}
+      data-alignment={resolvedAlignment}
+      required={required && !labelWithEditIcon}
+      {...sanitizedProps}
+    >
+      <span className={styles.labelText}>{children}</span>
+      {resolvedOptionalText && (
+        <span className={styles.optionalText}>
+          {typeof resolvedOptionalText === "string"
+            ? `(${resolvedOptionalText})`
+            : resolvedOptionalText}
+        </span>
+      )}
+      {labelActionArea ? (
+        <span className={styles.actionAreaWrapper}>{labelActionArea}</span>
+      ) : labelWithEditIcon ? (
+        <button
+          type="button"
+          className={styles.editIconWrapper}
+          data-replaces-asterisk={required ? "true" : undefined}
+          onClick={onLabelEditClick}
+          aria-label="Edit"
+        >
+          <svg
+            width="16"
+            height="16"
+            viewBox="0 0 16 16"
+            fill="none"
+            xmlns="http://www.w3.org/2000/svg"
+          >
+            <path
+              d="M11.5303 2.46967C11.8232 2.17678 12.2981 2.17678 12.591 2.46967L13.5303 3.40898C13.8232 3.70188 13.8232 4.17675 13.5303 4.46964L5.61288 12.3871C5.45268 12.5473 5.24434 12.6483 5.01809 12.6766L2.39534 13.0044C2.10091 13.0412 1.83856 12.7789 1.87538 12.4845L2.2032 9.86175C2.23147 9.63551 2.3325 9.42716 2.4927 9.26696L11.5303 2.46967Z"
+              stroke="currentColor"
+              strokeLinecap="round"
+              strokeLinejoin="round"
+            />
+          </svg>
+        </button>
+      ) : null}
+    </Input.Label>
+  );
+});
+
+Label.displayName = "Label";

package/src/components/Label/index.ts

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

package/src/components/Link/Link.stories.tsx

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

package/src/components/Link/Link.tsx

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

package/src/components/Loader/Loader.stories.tsx

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

package/src/components/Loader/Loader.tsx

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

package/src/components/Menu/Menu.stories.tsx

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

package/src/components/Menu/Menu.tsx

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

package/src/components/Modal/Modal.stories.tsx

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

package/src/components/Modal/Modal.tsx

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

package/src/components/NumberInput/NumberInput.stories.tsx

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

package/src/components/NumberInput/NumberInput.tsx

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

package/src/components/Pagination/Pagination.stories.tsx

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

package/src/components/Pagination/Pagination.tsx

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

package/src/components/Panel/Panel.stories.tsx

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

package/src/components/Panel/Panel.tsx

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

package/src/components/Popover/Popover.stories.tsx

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

package/src/components/Popover/Popover.tsx

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

package/src/components/Radio/Radio.stories.tsx

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

package/src/components/Radio/Radio.tsx

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

package/src/components/ReadOnlyField/READ_ONLY_FIELD_IMPLEMENTATION_NOTES.md

@@ -0,0 +1,15 @@
+# ReadOnlyField Implementation Notes
+
+This document acts as a living record tracking edge cases and architectural choices made specific to the `ReadOnlyField` and its internal blocks (like `ReadOnlyTextField`).
+
+## 1. Stripping Mantine Assumptions
+
+Unlike standard input variables, standard HTML output `<p>` tags inherently carry margin and spacing assumptions from core browser stylesheets. To correctly map `ReadOnlyTextField` elements gracefully inside the generic `FormControlWrapper` bounded context, we hardcode resets:
+
+- `margin: 0` explicitly strips block flow gap so `FormControlWrapper` handles vertical rhythm.
+- `min-height`: Native `Input` boxes typically have baseline padding borders. We map directly to `var(--recursica_ui-kit_components_read-only-field_properties_min-height)` to ensure a side-by-side editable `TextField` and `ReadOnlyField` perfectly share roughly identical visual heights.
+
+## 2. Unidirectional Editable Mode
+
+The main wrapper intercepts `readOnly` boolean blocks, maintaining its own `isReadOnly` state. Natively, if a user clicks an exposed 'Edit' action (like our legacy SVG or custom `labelActionArea`), the context permanently switches to active.
+There is intentionally no built-in reverse toggle inside typical field bindings (like input "Blur") to revert state. Parents must pass external controls to `readOnly` forcing the internal hooks to reset via standard `useEffect` propagation.

package/src/components/ReadOnlyField/ReadOnlyField.module.css

@@ -0,0 +1,49 @@
+/* HARDCODED VALUES:
+   - margin: 0; padding: overrides native paragraph margins mapping back to form element flows.
+*/
+.textField {
+  margin: 0; /* HARDCODE: Reset paragraph margin; assume wrapper controls layout */
+  display: flex;
+  align-items: center;
+  word-break: break-word;
+  padding: 0; /* HARDCODE: read-only fields have no specific padding defined by tokens, zeroing it. */
+  font-family: var(
+    --recursica_ui-kit_components_read-only-field_properties_text_font-family,
+    inherit
+  );
+  font-size: var(
+    --recursica_ui-kit_components_read-only-field_properties_text_font-size,
+    1rem
+  );
+  font-weight: var(
+    --recursica_ui-kit_components_read-only-field_properties_text_font-weight,
+    normal
+  );
+  letter-spacing: var(
+    --recursica_ui-kit_components_read-only-field_properties_text_letter-spacing,
+    normal
+  );
+  line-height: var(
+    --recursica_ui-kit_components_read-only-field_properties_text_line-height,
+    1.5
+  );
+  font-style: var(
+    --recursica_ui-kit_components_read-only-field_properties_text_font-style,
+    normal
+  );
+  text-decoration: var(
+    --recursica_ui-kit_components_read-only-field_properties_text_text-decoration,
+    none
+  );
+  text-transform: var(
+    --recursica_ui-kit_components_read-only-field_properties_text_text-transform,
+    none
+  );
+  color: var(
+    --recursica_ui-kit_components_read-only-field_properties_colors_text
+  );
+  min-height: var(
+    --recursica_ui-kit_components_read-only-field_properties_min-height,
+    32px
+  );
+}