@recursica/adapter-mui-v7 1.0.0

package/src/components/Badge/Badge.module.css

@@ -0,0 +1,115 @@
+/* HARDCODED VALUES:
+   - border-style: solid (needs a token if we support other border styles)
+   - box-sizing: border-box
+   - display: inline-flex
+   - align-items: center
+   - justify-content: center
+   - text-transform: uppercase (Mantine does this, but our tokens also specify it so we map it)
+ */
+
+.root {
+  /* HARDCODE: Basic structural assumptions */
+  box-sizing: border-box;
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  border-style: solid;
+
+  /* Base style resets to fully clear Mantine's defaults before applying ours */
+  background-color: transparent;
+  color: inherit;
+  border-color: transparent;
+
+  /* Apply global badge properties */
+  border-radius: var(
+    --recursica_ui-kit_components_badge_properties_border-radius
+  );
+  border-width: var(--recursica_ui-kit_components_badge_properties_border-size);
+  box-shadow: var(--recursica_ui-kit_components_badge_properties_elevation);
+
+  padding-left: var(
+    --recursica_ui-kit_components_badge_properties_padding-horizontal
+  );
+  padding-right: var(
+    --recursica_ui-kit_components_badge_properties_padding-horizontal
+  );
+  padding-top: var(
+    --recursica_ui-kit_components_badge_properties_padding-vertical
+  );
+  padding-bottom: var(
+    --recursica_ui-kit_components_badge_properties_padding-vertical
+  );
+
+  font-family: var(
+    --recursica_ui-kit_components_badge_properties_text_font-family
+  );
+  font-size: var(--recursica_ui-kit_components_badge_properties_text_font-size);
+  font-weight: var(
+    --recursica_ui-kit_components_badge_properties_text_font-weight
+  );
+  font-style: var(
+    --recursica_ui-kit_components_badge_properties_text_font-style
+  );
+  letter-spacing: var(
+    --recursica_ui-kit_components_badge_properties_text_letter-spacing
+  );
+  line-height: var(
+    --recursica_ui-kit_components_badge_properties_text_line-height
+  );
+  text-decoration: var(
+    --recursica_ui-kit_components_badge_properties_text_text-decoration
+  );
+  text-transform: var(
+    --recursica_ui-kit_components_badge_properties_text_text-transform
+  );
+}
+
+/* Variant Definitions */
+
+.root[data-variant="alert"] {
+  background-color: var(
+    --recursica_ui-kit_components_badge_variants_styles_alert_properties_colors_background-color
+  );
+  border-color: var(
+    --recursica_ui-kit_components_badge_variants_styles_alert_properties_colors_border-color
+  );
+  color: var(
+    --recursica_ui-kit_components_badge_variants_styles_alert_properties_colors_text-color
+  );
+}
+
+.root[data-variant="primary-color"] {
+  background-color: var(
+    --recursica_ui-kit_components_badge_variants_styles_primary-color_properties_colors_background-color
+  );
+  border-color: var(
+    --recursica_ui-kit_components_badge_variants_styles_primary-color_properties_colors_border-color
+  );
+  color: var(
+    --recursica_ui-kit_components_badge_variants_styles_primary-color_properties_colors_text-color
+  );
+}
+
+.root[data-variant="success"] {
+  background-color: var(
+    --recursica_ui-kit_components_badge_variants_styles_success_properties_colors_background-color
+  );
+  border-color: var(
+    --recursica_ui-kit_components_badge_variants_styles_success_properties_colors_border-color
+  );
+  color: var(
+    --recursica_ui-kit_components_badge_variants_styles_success_properties_colors_text-color
+  );
+}
+
+.root[data-variant="warning"] {
+  background-color: var(
+    --recursica_ui-kit_components_badge_variants_styles_warning_properties_colors_background-color
+  );
+  border-color: var(
+    --recursica_ui-kit_components_badge_variants_styles_warning_properties_colors_border-color
+  );
+  color: var(
+    --recursica_ui-kit_components_badge_variants_styles_warning_properties_colors_text-color
+  );
+}

package/src/components/Badge/Badge.stories.tsx

@@ -0,0 +1,78 @@
+import React from "react";
+import type { Meta, StoryObj } from "@storybook/react";
+import { Badge } from "./Badge";
+import { Layer } from "@recursica/adapter-common";
+
+type BadgeStoryProps = React.ComponentProps<typeof Badge>;
+
+const meta: Meta<BadgeStoryProps> = {
+  title: "UI-Kit/Badge",
+  component: Badge,
+  tags: ["autodocs"],
+  argTypes: {
+    variant: {
+      control: "select",
+      options: ["alert", "primary-color", "success", "warning"],
+      description: "The style / intent mapping for the badge",
+    },
+  },
+};
+
+export default meta;
+
+type Story = StoryObj<BadgeStoryProps>;
+
+export const Default: Story = {
+  args: {
+    children: "Badge Label",
+    variant: "primary-color",
+  },
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars, @typescript-eslint/no-explicit-any
+  render: ({ withLayer, layer, ...args }: any) => {
+    return <Badge {...args} />;
+  },
+};
+
+export const StaticAlert: Story = {
+  args: {
+    children: "Alert Badge",
+    variant: "alert",
+  },
+  render: (args: BadgeStoryProps) => <Badge {...args} />,
+};
+
+export const StaticPrimary: Story = {
+  args: {
+    children: "Primary Badge",
+    variant: "primary-color",
+  },
+  render: (args: BadgeStoryProps) => <Badge {...args} />,
+};
+
+export const StaticSuccess: Story = {
+  args: {
+    children: "Success Badge",
+    variant: "success",
+  },
+  render: (args: BadgeStoryProps) => <Badge {...args} />,
+};
+
+export const StaticWarning: Story = {
+  args: {
+    children: "Warning Badge",
+    variant: "warning",
+  },
+  render: (args: BadgeStoryProps) => <Badge {...args} />,
+};
+
+export const LayerOneAlert: Story = {
+  args: {
+    children: "Layer 1 Alert",
+    variant: "alert",
+  },
+  render: (args: BadgeStoryProps) => (
+    <Layer layer={1} style={{ padding: "24px" }}>
+      <Badge {...args} />
+    </Layer>
+  ),
+};

package/src/components/Badge/Badge.test.tsx

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

package/src/components/Badge/Badge.tsx

@@ -0,0 +1,61 @@
+import { forwardRef } from "react";
+import {
+  Badge as MuiBadge,
+  type BadgeProps as MuiBadgeProps,
+} from "@mui/material";
+import {
+  filterStylingProps,
+  mergeClassNames,
+  type RecursicaOverStyled,
+} from "../../utils/filterStylingProps";
+import styles from "./Badge.module.css";
+
+import { type RecursicaBadgeProps } from "@recursica/adapter-common";
+
+export type BadgeProps = RecursicaOverStyled<
+  Omit<MuiBadgeProps, "variant" | "size" | "color" | "radius"> &
+    RecursicaBadgeProps
+>;
+
+const _Badge = forwardRef<HTMLDivElement, BadgeProps>(function Badge(
+  { variant = "primary-color", overStyled = false, ...rest },
+  ref,
+) {
+  // Strip all visual override injections unless developer has specifically opted into overStyling.
+  // External layout props like margins are safely preserved.
+  const sanitizedProps = filterStylingProps(rest, overStyled);
+
+  // Note MUI's actual prop is "classes", not "classNames" (that's Mantine's naming) — this
+  // used to read the wrong key, silently no-op-ing any caller-supplied classes.
+  const mergedClassNames = mergeClassNames(
+    { root: styles.root },
+    (sanitizedProps as Record<string, unknown>).classes as
+      | Partial<Record<string, string>>
+      | undefined,
+  );
+
+  const classNameProp = (sanitizedProps as Record<string, unknown>)
+    .className as string | undefined;
+  const finalClass = classNameProp
+    ? `${styles.root} ${classNameProp}`
+    : styles.root;
+
+  return (
+    <MuiBadge
+      ref={ref}
+      variant="standard" // We manage visual style purely through our CSS variables mapping
+      data-variant={variant}
+      {...sanitizedProps}
+      className={finalClass}
+      classes={mergedClassNames}
+    />
+  );
+});
+_Badge.displayName = "Badge";
+
+/**
+ * Recursica Badge component wrapping Mui's Badge.
+ *
+ * Supports polymorphism via the `component` prop or `renderRoot` for custom element rendering.
+ */
+export const Badge = _Badge;

package/src/components/Badge/USAGE.md

@@ -0,0 +1,40 @@
+# Badge - Usage Guide
+
+This document describes how to integrate and use the `Badge` component in your projects using `@recursica/adapter-mui-v7`.
+
+---
+
+## 1. Import Reference
+
+```tsx
+import { Badge } from "@recursica/adapter-mui-v7";
+```
+
+---
+
+## 2. Basic Example
+
+```tsx
+import React from "react";
+import { Badge } from "@recursica/adapter-mui-v7";
+
+export default function Demo() {
+  return (
+    <Badge variant="filled" size="md">
+      Active
+    </Badge>
+  );
+}
+```
+
+---
+
+## 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/Badge/index.ts

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

package/src/components/Breadcrumb/BREADCRUMB_IMPLEMENTATION_NOTES.md

@@ -0,0 +1,51 @@
+# Breadcrumb Implementation Notes
+
+## Missing Variants and Sizes
+
+The `Breadcrumb` currently does not establish any size (`xs`, `sm`, etc.) or variant variables in the underlying design tokens (`recursica_ui-kit.json`). Only basic structural definitions for `padding` and `item-gap` exist. Because of this, the `size` and `variant` properties have been explicitly omitted from the passed MUI props.
+
+## Gap Styling
+
+MUI renders items/separators inside the `<ol>`, not directly under the `<nav>` root — `gap` lives on `.ol` in `.module.css` so it lands uniformly between item/separator/item, matching mantine-adapter.
+
+## Composition and Separators
+
+MUI natively accepts typical anchor tags as children, wrapping each in its own `<li>` internally — Breadcrumb.tsx doesn't add any structural spans of its own, allowing developers to utilize `Link` wrappers as needed contextually.
+The separator character is inherited natively from MUI's default configuration (`/`) unless overridden by passing `separator={<Icon />}` to the component props.
+
+## Current-page Crumb: Best-effort Enforcement, Not a Guarantee
+
+**The last crumb should always be plain, non-interactive text — a `<span>`, not a `Link`.** It
+represents the current page; per standard breadcrumb UX and the ARIA breadcrumb pattern, it
+shouldn't be clickable. Passing a `Link` (or an anchor) for the last item is a misuse of the
+component, even though `Breadcrumb.tsx` tries to correct for it — see below.
+
+Breadcrumb intentionally keeps the flexible MUI `children`-as-anchors interface (unlike BEAM's
+`Breadcrumb.Item`, which renders its own `Link` internally and can't accept a caller-supplied
+router-aware Link or `onClick`). That flexibility means Breadcrumb.tsx can't fully own what the
+last item renders as, so it does what it can via `markCurrentPageItem` (`@recursica/adapter-common`):
+
+- Adds `aria-current="page"` to the last child, always.
+- If that child looks interactive (has `href` or `onClick`), strips both and sets `tabIndex={-1}`.
+- In dev, warns to the console when it had to strip anything — a signal the caller should switch
+  that item to plain text instead of relying on this fallback.
+
+Backed up by a CSS rule targeting `[aria-current="page"]` (Breadcrumb.module.css) that resets
+color/text-decoration and sets `pointer-events: none`, and sets `font-family`/`font-size` to Link's own tokens
+(per product decision: the current item should typographically match Link, just without Link's
+color/decoration/interactivity).
+
+**Why this isn't a real guarantee:** `cloneElement` can only override props an element actually
+reads. A custom Link component (e.g. React Router's `<Link to="...">`) that navigates from its own
+internal handler, independent of a passed-through `onClick`, will still navigate — stripping
+`onClick`/`href` here doesn't touch that internal logic, and `pointer-events: none` only blocks
+mouse activation, not keyboard/Enter on a focusable custom element. Treat all of the above as a
+safety net for the common case (plain anchors, our own `Link`), not a substitute for callers doing
+the right thing and passing plain text for the last crumb.
+
+The story's `items` convenience prop demonstrates the correct pattern: every crumb except the last
+is wrapped in `Link`, and the last is a plain `<span>`.
+
+This logic is shared with mantine-adapter — `markCurrentPageItem` lives once in
+`@recursica/adapter-common` (`components/Breadcrumb/markCurrentPageItem.ts`) and is unit-tested
+there via mantine-adapter's test suite (`markCurrentPageItem.test.ts`), not duplicated here.

package/src/components/Breadcrumb/Breadcrumb.module.css

@@ -0,0 +1,51 @@
+/* HARDCODED VALUES:
+   - align-items: center
+*/
+
+.root {
+  /* Base style resets */
+  background-color: transparent;
+  color: inherit;
+
+  /* Apply global breadcrumb properties */
+  padding: var(--recursica_ui-kit_components_breadcrumb_properties_padding);
+}
+
+/* MUI renders items/separators inside the <ol>, not directly under <nav> (.root) — the
+   gap must live here to land uniformly between item/separator/item, matching Mantine. */
+.ol {
+  /* HARDCODE: Basic structural flex layout for breadcrumbs */
+  display: flex;
+  align-items: center;
+
+  gap: var(--recursica_ui-kit_components_breadcrumb_properties_item-gap);
+}
+
+.separator {
+  /* Separator base resets if needed */
+  display: flex;
+  align-items: center;
+  justify-content: center;
+  /* Neutralize MUI's built-in 8px marginLeft/marginRight so .ol's gap alone controls spacing */
+  margin: 0;
+}
+
+/* Current-page item (last crumb): Breadcrumb.tsx (via markCurrentPageItem) marks it
+   aria-current="page". This is a style-layer backstop in case that item still renders as a Link
+   despite having its href/onClick stripped — see BREADCRUMB_IMPLEMENTATION_NOTES.md. Two classes'
+   worth of specificity beats Link's single .root color/text-decoration rule regardless of module
+   load order. pointer-events only blocks mouse activation, not a router Link's own internal
+   handler — the last crumb should really just be plain text. */
+.ol [aria-current="page"] {
+  color: inherit;
+  text-decoration: none;
+  pointer-events: none;
+
+  /* Per product decision: the current-page item should match Link's font-family/size (it's
+     typically rendered as plain text, with no font styling of its own — otherwise it falls back
+     to MUI's default Typography font-size) but not any of Link's other styling. */
+  font-family: var(
+    --recursica_ui-kit_components_link_properties_text_font-family
+  );
+  font-size: var(--recursica_ui-kit_components_link_properties_text_font-size);
+}

package/src/components/Breadcrumb/Breadcrumb.stories.tsx

@@ -0,0 +1,114 @@
+import React from "react";
+import type { Meta, StoryObj } from "@storybook/react";
+import { Breadcrumb } from "./Breadcrumb";
+import { Link } from "../Link";
+
+type BreadcrumbStoryProps = React.ComponentProps<typeof Breadcrumb> & {
+  items?: string[];
+};
+
+const meta: Meta<BreadcrumbStoryProps> = {
+  title: "UI-Kit/Breadcrumb",
+  component: Breadcrumb,
+  tags: ["autodocs"],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          "**Proper usage** (see `Default`): every crumb except the last is a `Link`; the last " +
+          "crumb — the current page — is plain text (e.g. a `<span>`), not a link. `Breadcrumb` " +
+          "does its best to neutralize a `Link` passed as the last item anyway (see " +
+          "`LastItemAsLink`), but that's a safety net, not something to rely on — see " +
+          "BREADCRUMB_IMPLEMENTATION_NOTES.md.",
+      },
+    },
+  },
+  argTypes: {
+    children: {
+      table: {
+        disable: true,
+      },
+    },
+    items: {
+      control: "object",
+      description:
+        "Array of string labels used to dynamically generate the interactive Breadcrumb nodes.",
+      table: {
+        category: "Story Controls",
+      },
+    },
+    separator: {
+      control: "text",
+      description: "Custom separator between items",
+    },
+  },
+  args: {
+    items: ["Home", "Components", "Breadcrumbs"],
+  },
+  render: ({ items, children, ...args }) => {
+    const mappedChildren = items
+      ? items.map((label, index) =>
+          // The last crumb represents the current page, so it's plain text,
+          // not a link — matches standard breadcrumb UX.
+          index === items.length - 1 ? (
+            <span key={index}>{label}</span>
+          ) : (
+            <Link href="#" key={index}>
+              {label}
+            </Link>
+          ),
+        )
+      : children;
+
+    return <Breadcrumb children={mappedChildren} {...args} />;
+  },
+};
+
+export default meta;
+
+type Story = StoryObj<BreadcrumbStoryProps>;
+
+export const Default: Story = {
+  args: {
+    items: ["Dashboard", "Settings", "Security"],
+  },
+};
+
+export const CustomSeparator: Story = {
+  args: {
+    items: ["Root", "Branch", "Leaf"],
+    separator: "→",
+  },
+};
+
+export const LastItemAsLink: Story = {
+  name: "Last Item As Link (Incorrect Usage)",
+  args: {
+    // Bypass the `items` convenience prop (which always renders the last crumb as a span) to
+    // demonstrate what happens if a caller wraps every crumb, including the last, in a `Link`.
+    items: undefined,
+    children: [
+      <Link href="#" key="dashboard">
+        Dashboard
+      </Link>,
+      <Link href="#" key="settings">
+        Settings
+      </Link>,
+      <Link href="#" key="security">
+        Security
+      </Link>,
+    ],
+  },
+  parameters: {
+    docs: {
+      description: {
+        story:
+          "Incorrect usage, kept as a story to prove Breadcrumb still handles it: the last " +
+          'crumb is a `Link`, but Breadcrumb adds `aria-current="page"`, strips its `href`/' +
+          "`onClick`, drops it from the tab order, and the CSS reset removes Link's color/" +
+          "underline — it renders identically to `Default`'s plain-text current item. Don't " +
+          "rely on this; pass plain text for the last crumb instead.",
+      },
+    },
+  },
+};

package/src/components/Breadcrumb/Breadcrumb.test.tsx

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

package/src/components/Breadcrumb/Breadcrumb.tsx

@@ -0,0 +1,70 @@
+import { forwardRef } from "react";
+import {
+  Breadcrumbs as MuiBreadcrumbs,
+  type BreadcrumbsProps as MuiBreadcrumbsProps,
+} from "@mui/material";
+import {
+  filterStylingProps,
+  mergeClassNames,
+  type RecursicaOverStyled,
+} from "../../utils/filterStylingProps";
+import styles from "./Breadcrumb.module.css";
+
+import {
+  markCurrentPageItem,
+  type RecursicaBreadcrumbProps,
+} from "@recursica/adapter-common";
+
+export type BreadcrumbProps = RecursicaOverStyled<
+  Omit<MuiBreadcrumbsProps, "variant" | "size"> & RecursicaBreadcrumbProps
+>;
+
+/**
+ * The last child should always be plain, non-interactive text (e.g. a `<span>`) — it represents
+ * the current page and shouldn't be a link. Breadcrumb tries to correct for a Link/anchor passed
+ * there anyway via `markCurrentPageItem` (aria-current, stripped href/onClick, CSS reset in
+ * Breadcrumb.module.css), but that's a best-effort safety net, not a guarantee — it can't stop a
+ * custom Link component (e.g. a router Link) that navigates from its own internal handler. See
+ * BREADCRUMB_IMPLEMENTATION_NOTES.md.
+ */
+export const Breadcrumb = forwardRef<HTMLDivElement, BreadcrumbProps>(
+  function Breadcrumb(
+    { overStyled = false, separator = ">", children, ...rest },
+    ref,
+  ) {
+    const sanitizedProps = filterStylingProps(
+      { separator, children: markCurrentPageItem(children), ...rest },
+      overStyled,
+    );
+
+    // Note MUI's actual prop is "classes", not "classNames" (that's Mantine's naming) — this
+    // used to read the wrong key, silently no-op-ing any caller-supplied classes.
+    const mergedClassNames = mergeClassNames(
+      {
+        root: styles.root,
+        ol: styles.ol,
+        separator: styles.separator,
+      },
+      (sanitizedProps as Record<string, unknown>).classes as
+        | Partial<Record<string, string>>
+        | undefined,
+    );
+
+    const classNameProp = (sanitizedProps as Record<string, unknown>)
+      .className as string | undefined;
+    const finalClass = classNameProp
+      ? `${styles.root} ${classNameProp}`
+      : styles.root;
+
+    return (
+      <MuiBreadcrumbs
+        ref={ref}
+        {...(sanitizedProps as unknown as MuiBreadcrumbsProps)}
+        className={finalClass}
+        classes={mergedClassNames}
+      />
+    );
+  },
+);
+
+Breadcrumb.displayName = "Breadcrumb";

package/src/components/Breadcrumb/USAGE.md

@@ -0,0 +1,42 @@
+# Breadcrumb - Usage Guide
+
+This document describes how to integrate and use the `Breadcrumb` component in your projects using `@recursica/adapter-mui-v7`.
+
+---
+
+## 1. Import Reference
+
+```tsx
+import { Breadcrumb } from "@recursica/adapter-mui-v7";
+```
+
+---
+
+## 2. Basic Example
+
+```tsx
+import React from "react";
+import { Breadcrumb } from "@recursica/adapter-mui-v7";
+
+export default function Demo() {
+  return (
+    <Breadcrumb>
+      <Link href="/">Home</Link>
+      <Link href="/components">Components</Link>
+      <Text>Button</Text>
+    </Breadcrumb>
+  );
+}
+```
+
+---
+
+## 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/Breadcrumb/index.ts

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