@recursica/adapter-mui-v7 1.0.0

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

@@ -0,0 +1,169 @@
+.root {
+  /* Prevent default MUI absolute positioning logic */
+  position: relative;
+  transform: none;
+  pointer-events: auto;
+  white-space: normal;
+
+  /* Reset MUI structural overrides */
+  margin: 0;
+  padding: 0;
+  display: flex;
+  width: 100%;
+
+  /* Recursica Font Map */
+  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-style: var(
+    --recursica_ui-kit_components_label_properties_label-text_font-style
+  );
+  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
+  );
+  text-decoration: var(
+    --recursica_ui-kit_components_label_properties_label-text_text-decoration
+  );
+  text-transform: var(
+    --recursica_ui-kit_components_label_properties_label-text_text-transform
+  );
+
+  color: var(--recursica_ui-kit_components_label_properties_colors_text-color);
+}
+
+.innerLayout {
+  display: flex;
+  flex-wrap: wrap;
+  align-items: center;
+  gap: var(
+    --recursica_ui-kit_components_label_properties_label-optional-text-gap
+  );
+  width: 100%;
+}
+
+.root[data-alignment="right"] .innerLayout {
+  justify-content: flex-end;
+  text-align: right;
+}
+
+.text {
+  /* Natively intercepts MUI asterisk rendering securely wrapping inline with typography */
+  display: inline;
+}
+
+.required {
+  /* Override the `.MuiInputLabel-asterisk` natively */
+  color: var(
+    --recursica_ui-kit_components_label_properties_colors_asterisk-color
+  );
+  margin-left: var(
+    --recursica_ui-kit_components_label_properties_required-indicator-gap
+  );
+}
+
+.root :global(.MuiFormLabel-asterisk) {
+  display: none !important;
+}
+
+/* MUI propagates .Mui-error to the label automatically on FormControl error.
+   We explicitly override this bleed to prevent the main label text from turning red,
+   while allowing the asterisk to take the error color! */
+.root:global(.Mui-error) {
+  color: var(--recursica_ui-kit_components_label_properties_colors_text-color);
+}
+.root:global(.Mui-error) .required {
+  color: var(
+    --recursica_ui-kit_components_assistive-element_variants_types_error_properties_colors_text-color
+  );
+}
+
+/* Same bleed, different trigger: MUI's FormControl propagates .Mui-focused to this label
+   whenever any descendant form control (e.g. a grouped Switch/Checkbox) receives focus,
+   turning the whole label MUI's primary blue via InputLabel's own default styling. No
+   Recursica design calls for a focus-reactive label color, so it's reset here — same fix as
+   the .Mui-error case above, just for the focused trigger instead of the error one. */
+.root:global(.Mui-focused) {
+  color: var(--recursica_ui-kit_components_label_properties_colors_text-color);
+}
+
+.endNodes {
+  display: flex;
+  align-items: center;
+  gap: var(
+    --recursica_ui-kit_components_label_properties_label-optional-text-gap
+  );
+}
+
+.optionalText {
+  /* Forces the optional text onto its own row below the label text/end nodes,
+     mirroring mantine-adapter's flex-basis: 100% wrap behavior. */
+  flex-basis: 100%;
+  color: inherit;
+  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-style: var(
+    --recursica_ui-kit_components_label_properties_optional-text_font-style
+  );
+  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
+  );
+  text-decoration: var(
+    --recursica_ui-kit_components_label_properties_optional-text_text-decoration
+  );
+  text-transform: var(
+    --recursica_ui-kit_components_label_properties_optional-text_text-transform
+  );
+  opacity: var(
+    --recursica_ui-kit_components_label_properties_optional-text-opacity
+  );
+}
+
+.actionArea {
+  display: flex;
+  align-items: center;
+  margin-left: var(
+    --recursica_ui-kit_components_label_properties_edit-icon-gap
+  );
+}
+
+.editIcon {
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  cursor: pointer;
+  background: none;
+  border: none;
+  padding: 0;
+  margin-left: var(
+    --recursica_ui-kit_components_label_properties_edit-icon-gap
+  );
+
+  width: 16px;
+  height: 16px;
+  color: inherit;
+}
+
+.editIcon :global(svg) {
+  width: 100%;
+  height: 100%;
+  stroke-width: 2px;
+}

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

@@ -0,0 +1,131 @@
+import React from "react";
+import type { Meta, StoryObj } from "@storybook/react";
+import { Label } from "./Label";
+import { Button } from "../Button/Button";
+
+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\nThis component only renders the label itself — layout concerns like `stacked` vs `side-by-side` positioning relative to an input live on `FormControlLayout`/`FormControlWrapper`, not here. Render this `Label` in isolation to verify its own states, or see `UI-Kit/FormControlLayout` for how it composes into a full form field.",
+      },
+    },
+  },
+  argTypes: {
+    labelSize: {
+      control: "inline-radio",
+      options: ["default", "small"],
+      description:
+        "Sizing metrics for the Label. Only visually distinguishable once composed inside a `side-by-side` FormControlLayout, which is where the resulting width constraint applies.",
+    },
+    labelAlignment: {
+      control: "inline-radio",
+      options: ["left", "right"],
+      description: "Text alignment of the label content.",
+    },
+    required: {
+      control: "boolean",
+      description:
+        "Renders the required asterisk (suppressed automatically when `labelWithEditIcon` is set, and mutually exclusive with `labelOptionalText`).",
+    },
+    labelOptionalText: {
+      control: "text",
+      description:
+        "Secondary text rendered beneath the label. Pass `true` for the default '(Optional)' string, or a custom node/string. Suppressed when `required` is true.",
+    },
+    labelWithEditIcon: {
+      control: "boolean",
+      description:
+        "Replaces the default edit icon slot with an interactive edit affordance; replaces the required asterisk visually when both are set.",
+    },
+    labelActionArea: {
+      table: { disable: true },
+    },
+    onLabelEditClick: {
+      table: { disable: true },
+    },
+  },
+};
+
+export default meta;
+
+type Story = StoryObj<LabelStoryProps>;
+
+export const Default: Story = {
+  args: {
+    children: "Label",
+    labelSize: "default",
+    labelAlignment: "left",
+    required: false,
+    labelOptionalText: "",
+    labelWithEditIcon: false,
+  },
+};
+
+export const Required: Story = {
+  args: {
+    children: "Required Field",
+    required: true,
+  },
+};
+
+export const RequiredSuppressesOptionalText: Story = {
+  args: {
+    children: "Full Name",
+    required: true,
+    labelOptionalText: "This should not render",
+  },
+};
+
+export const WithOptionalText: Story = {
+  args: {
+    children: "Bio",
+    labelOptionalText: "Max 100 characters",
+  },
+};
+
+export const BooleanOptionalText: Story = {
+  args: {
+    children: "Middle Initial",
+    labelOptionalText: true,
+  },
+};
+
+export const WithEditIcon: Story = {
+  args: {
+    children: "Shipping Address",
+    labelWithEditIcon: true,
+  },
+};
+
+export const RequiredWithEditIcon: Story = {
+  args: {
+    children: "Primary Network Node",
+    required: true,
+    labelWithEditIcon: true,
+  },
+};
+
+export const RightAligned: Story = {
+  args: {
+    children: "Status",
+    labelAlignment: "right",
+  },
+};
+
+export const WithActionArea: Story = {
+  args: {
+    children: "Configuration",
+    labelActionArea: (
+      <Button variant="text" size="small">
+        Edit
+      </Button>
+    ),
+  },
+};

package/src/components/Label/Label.test.tsx

@@ -0,0 +1 @@
+// Placeholder for future Label component tests. Add tests here if/when needed.

package/src/components/Label/Label.tsx

@@ -0,0 +1,96 @@
+import React from "react";
+import { InputLabel, type InputLabelProps } from "@mui/material";
+import { filterStylingProps } from "../../utils/filterStylingProps";
+import styles from "./Label.module.css";
+
+import { type RecursicaLabelProps } from "@recursica/adapter-common";
+
+export interface LabelProps extends InputLabelProps, RecursicaLabelProps {
+  overStyled?: boolean;
+}
+
+export const Label = React.forwardRef<HTMLLabelElement, LabelProps>(
+  function Label(props, ref) {
+    const {
+      overStyled = false,
+      required = false,
+      labelAlignment,
+      labelOptionalText = "",
+      labelWithEditIcon = false,
+      onLabelEditClick,
+      labelActionArea,
+      children,
+      className,
+      ...rest
+    } = props;
+
+    const resolvedAlignment = labelAlignment || "left";
+
+    const sanitizedProps = filterStylingProps(rest, overStyled);
+
+    const PenIcon = () => (
+      <svg
+        xmlns="http://www.w3.org/2000/svg"
+        width="24"
+        height="24"
+        viewBox="0 0 24 24"
+        fill="none"
+        stroke="currentColor"
+        strokeWidth="2"
+        strokeLinecap="round"
+        strokeLinejoin="round"
+      >
+        <path d="M12 20h9"></path>
+        <path d="M16.5 3.5a2.121 2.121 0 0 1 3 3L7 19l-4 1 1-4L16.5 3.5z"></path>
+      </svg>
+    );
+
+    // Bypassing MUI's floating functionality by forcing shrink=true to static inline positioning.
+    return (
+      <InputLabel
+        ref={ref}
+        {...(sanitizedProps as InputLabelProps)}
+        shrink={true}
+        data-alignment={resolvedAlignment}
+        className={className ? `${styles.root} ${className}` : styles.root}
+      >
+        <div className={styles.innerLayout}>
+          <span className={styles.textWrapper}>
+            <span className={styles.text}>{children}</span>
+            {required && <span className={styles.required}> *</span>}
+          </span>
+
+          <div className={styles.endNodes}>
+            {labelActionArea && (
+              <span className={styles.actionArea}>{labelActionArea}</span>
+            )}
+            {labelWithEditIcon && (
+              <button
+                type="button"
+                className={styles.editIcon}
+                onClick={onLabelEditClick}
+                aria-label="Edit label"
+              >
+                <PenIcon />
+              </button>
+            )}
+          </div>
+
+          {!required && labelOptionalText && !labelActionArea && (
+            <span className={styles.optionalText}>
+              {(() => {
+                const resolved =
+                  labelOptionalText === true ? "optional" : labelOptionalText;
+                return typeof resolved === "string"
+                  ? `(${resolved})`
+                  : resolved;
+              })()}
+            </span>
+          )}
+        </div>
+      </InputLabel>
+    );
+  },
+);
+
+Label.displayName = "Label";

package/src/components/Label/USAGE.md

@@ -0,0 +1,36 @@
+# Label - Usage Guide
+
+This document describes how to integrate and use the `Label` component in your projects using `@recursica/adapter-mui-v7`.
+
+---
+
+## 1. Import Reference
+
+```tsx
+import { Label } from "@recursica/adapter-mui-v7";
+```
+
+---
+
+## 2. Basic Example
+
+```tsx
+import React from "react";
+import { Label } from "@recursica/adapter-mui-v7";
+
+export default function Demo() {
+  return <Label required>Field Label</Label>;
+}
+```
+
+---
+
+## 3. Design System Integration
+
+All Recursica components in the `@recursica/adapter-mui-v7` package adhere strictly to design system spacing, scaling, and behavior patterns.
+
+> [!IMPORTANT]
+>
+> - **Anti-override protection**: Rogues style injections (like inline `style` or arbitrary `className`) are automatically blocked by our prop layer unless `overStyled={true}` is explicitly provided.
+> - **No Direct Layers**: Do not pass a `layer` prop to this component. To place it on a specific visual layer, wrap it in a `<Layer layer={0|1|2|3}>` component natively.
+> - **Variables and Theming**: Styling is entirely determined by local CSS variables defined in `recursica_variables_scoped.css` and mapped in the component's CSS module.

package/src/components/Label/index.ts

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

package/src/components/Layer/USAGE.md

@@ -0,0 +1,50 @@
+# Layer - Usage Guide
+
+This document describes how to integrate and use the `Layer` component in your projects using `@recursica/adapter-mui-v7`.
+
+> [!NOTE] > `Layer` is defined once in `@recursica/adapter-common` and re-exported here so it shares the exact same behavior across every Recursica adapter.
+
+---
+
+## 1. Import Reference
+
+```tsx
+import { Layer } from "@recursica/adapter-mui-v7";
+```
+
+---
+
+## 2. Basic Example
+
+`Layer` sets `data-recursica-layer` on its root element, which is what makes the theme+layer scoped CSS variables (surface color, border, elevation, padding) in `recursica_variables_scoped.css` actually apply. [`RecursicaThemeProvider`](../RecursicaThemeProvider/USAGE.md) automatically wraps your app in a `layer={0}` `Layer` by default (via its `initLayer0` prop), so you don't need to add one yourself for the base page. You still add `Layer`s manually for anything visually elevated above the page background:
+
+```tsx
+import { RecursicaThemeProvider, Layer, Card } from "@recursica/adapter-mui-v7";
+
+function App() {
+  return (
+    <RecursicaThemeProvider theme="light">
+      {/* Page background/surface already uses layer 0, applied automatically */}
+      <Layer layer={1}>
+        <Card>Elevated content sits on layer 1</Card>
+      </Layer>
+    </RecursicaThemeProvider>
+  );
+}
+```
+
+---
+
+## 3. Design System Integration
+
+> [!IMPORTANT]
+>
+> - **Layer 0 is automatic**: `RecursicaThemeProvider` applies it for you by default. Only opt out (`initLayer0={false}`) if you need to control exactly where layer 0 starts in the tree, or need `contentsOnly` on the base layer — see [RecursicaThemeProvider usage](../RecursicaThemeProvider/USAGE.md).
+> - **Layers 1–3 are manual**: Wrap any content that's visually elevated above the page background (a Card, Modal, Popover, etc.) in its own `<Layer layer={1|2|3}>`. Nesting `Layer`s is how Recursica communicates elevation to descendant components — do **not** pass a `layer` prop directly to other components; wrap them in a `Layer` instead (every other component's `USAGE.md` repeats this rule).
+> - **`contentsOnly`**: When `true`, `Layer` renders with `display: contents` and omits `data-recursica-layer` entirely — use this when you need a layer boundary in your component tree without adding an extra DOM box or applying layer styling (e.g. a purely structural wrapper).
+
+---
+
+## 4. Key Integration Features & Constraints
+
+`Layer` has no visual variants of its own — its entire purpose is to bind a subtree to a numbered layer's design tokens. It does not accept `overStyled`; instead, if you find yourself needing to override a layer's surface styling, that's a signal you may want a different layer number rather than an escape hatch.

package/src/components/Link/LINK_IMPLEMENTATION_NOTES.md

@@ -0,0 +1,9 @@
+# Link Component Implementation Notes
+
+## Focus State
+
+There's no per-component `focus` token for Link in the design tokens. Like every other
+interactive component (see Button), `.root:focus-visible` in `Link.module.css` replaces the
+native browser focus outline with the global `--recursica_brand_states_focus_*` ring instead of
+leaving it to the browser default. This was previously missing here — Link (and anything composing
+it, e.g. Breadcrumb) fell back to the browser's native focus outline instead of Recursica's.

package/src/components/Link/Link.module.css

@@ -0,0 +1,105 @@
+/* Brand-layer exemptions (recursica-allow-brand) — see recursica-token-analyzer README.md.
+ * Only source for link hover-underline; no per-component token exists (see IMPLEMENTATION_NOTES.md).
+ *   recursica-allow-brand: --recursica_brand_states_link_decoration
+ * Global focus-ring tokens (recursica_variables_scoped.css header, 'Hover & Focus states' —
+ * implicit rule for every interactive element; components must not define their own per-component
+ * treatment). Same pattern as Button.module.css.
+ *   recursica-allow-brand: --recursica_brand_states_focus_blur
+ *   recursica-allow-brand: --recursica_brand_states_focus_border-size
+ *   recursica-allow-brand: --recursica_brand_states_focus_color
+ *   recursica-allow-brand: --recursica_brand_states_focus_margin
+ */
+
+/*
+HARDCODED VALUES:
+- display: inline-flex; (Base layout to align icon and text correctly)
+- align-items: center;
+- cursor: pointer;
+- text-decoration: none; (Overridden by our design tokens instead of using Mantine's underline prop)
+- color: inherit; (Reset before applying token)
+*/
+
+.root {
+  /* HARDCODE: base layout */
+  display: inline;
+  cursor: pointer;
+
+  /* HARDCODE: Reset underline and color so we can explicitly use our tokens */
+  text-decoration: none;
+  color: inherit;
+
+  /* Typography Tokens */
+  font-family: var(
+    --recursica_ui-kit_components_link_properties_text_font-family
+  );
+  font-size: var(--recursica_ui-kit_components_link_properties_text_font-size);
+  font-style: var(
+    --recursica_ui-kit_components_link_properties_text_font-style
+  );
+  font-weight: var(
+    --recursica_ui-kit_components_link_properties_text_font-weight
+  );
+  letter-spacing: var(
+    --recursica_ui-kit_components_link_properties_text_letter-spacing
+  );
+  line-height: var(
+    --recursica_ui-kit_components_link_properties_text_line-height
+  );
+  text-decoration: var(
+    --recursica_ui-kit_components_link_properties_text_text-decoration
+  );
+  color: var(--recursica_ui-kit_components_link_properties_colors_text-color);
+}
+
+.root[data-has-icon] {
+  display: inline-flex;
+  align-items: center;
+  gap: var(--recursica_ui-kit_components_link_properties_icon-text-gap);
+}
+
+.root:visited {
+  color: var(
+    --recursica_ui-kit_components_link_variants_states_visited_properties_colors_text-color
+  );
+}
+
+.root:hover {
+  text-decoration: var(--recursica_brand_states_link_decoration);
+}
+
+/* Focus State Mapping (native browser focus outline replaced with the recursica focus ring).
+   Was previously unset here, so Link (and anything using it, e.g. Breadcrumb) fell back to the
+   browser's native focus outline instead of the recursica ring. */
+.root:focus-visible {
+  outline: none;
+  box-shadow:
+    0 0 0 var(--recursica_brand_states_focus_border-size)
+      var(--recursica_brand_states_focus_color),
+    0 0 var(--recursica_brand_states_focus_blur)
+      var(--recursica_brand_states_focus_margin)
+      var(--recursica_brand_states_focus_color);
+}
+
+/* Icon Support */
+.iconWrapper {
+  /* HARDCODE: maintain intrinsic icon bounds */
+  display: flex;
+  align-items: center;
+  justify-content: center;
+
+  width: var(--recursica_ui-kit_components_link_properties_icon-size);
+  height: var(--recursica_ui-kit_components_link_properties_icon-size);
+  color: var(--recursica_ui-kit_components_link_properties_colors_icon-color);
+}
+
+.root:visited .iconWrapper {
+  color: var(
+    --recursica_ui-kit_components_link_variants_states_visited_properties_colors_icon-color
+  );
+}
+
+/* Label text wrapper */
+.labelText {
+  /* HARDCODE: allows text truncation if bounded */
+  min-width: 0;
+}

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

@@ -0,0 +1,58 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+/* eslint-disable @typescript-eslint/no-unused-vars */
+import type { Meta, StoryObj } from "@storybook/react";
+import { Link } from "./Link";
+
+const meta: Meta<typeof Link> = {
+  title: "UI-Kit/Link",
+  component: Link,
+  tags: ["autodocs"],
+  args: {
+    children: "Link text",
+    href: "#",
+  },
+  render: ({ withLayer, layer, ...args }: any) => <Link {...args} />,
+};
+
+export default meta;
+
+type Story = StoryObj<typeof Link>;
+
+export const Default: Story = {};
+
+export const WithIcon: Story = {
+  args: {
+    icon: (
+      <svg
+        width="24"
+        height="24"
+        viewBox="0 0 24 24"
+        fill="none"
+        stroke="currentColor"
+        strokeWidth="2"
+        strokeLinecap="round"
+        strokeLinejoin="round"
+      >
+        <path d="M10 13a5 5 0 0 0 7.54.54l3-3a5 5 0 0 0-7.07-7.07l-1.72 1.71"></path>
+        <path d="M14 11a5 5 0 0 0-7.54-.54l-3 3a5 5 0 0 0 7.07 7.07l1.71-1.71"></path>
+      </svg>
+    ),
+    children: "Link with Icon",
+  },
+};
+
+export const Polymorphic: Story = {
+  args: {
+    component: "button",
+    onClick: () => alert("Button clicked!"),
+    children: "Rendered as <button>",
+  },
+};
+
+export const InlineText: Story = {
+  render: () => (
+    <p>
+      Here is some text with an <Link href="#">inline link</Link> inside it.
+    </p>
+  ),
+};

package/src/components/Link/Link.test.tsx

@@ -0,0 +1 @@
+// Placeholder for future Link component tests. Add tests here if/when needed.