@recursica/adapter-mantine-v8 1.0.0

package/src/components/Tabs/Tabs.stories.tsx

@@ -0,0 +1,154 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { Tabs } from "./Tabs";
+import { Flex } from "../Flex/Flex";
+
+const meta: Meta<typeof Tabs> = {
+  title: "UI-Kit/Tabs",
+  component: Tabs,
+  tags: ["autodocs"],
+  parameters: {
+    layout: "centered",
+  },
+  argTypes: {
+    variant: {
+      control: "radio",
+      options: ["default", "outline", "pills"],
+    },
+    orientation: {
+      control: "radio",
+      options: ["horizontal", "vertical"],
+    },
+    // @ts-expect-error Custom prop not in native TabsProps
+    disabled: {
+      control: "boolean",
+    },
+    defaultChecked: {
+      table: {
+        disable: true,
+      },
+    },
+  },
+};
+
+export default meta;
+type Story = StoryObj<typeof Tabs>;
+
+const InteractiveTabs = (
+  args: React.ComponentProps<typeof Tabs> & { disabled?: boolean },
+) => {
+  return (
+    <Flex w={600} h={300}>
+      <Tabs defaultValue="gallery" {...args}>
+        <Tabs.List>
+          <Tabs.Tab
+            value="gallery"
+            disabled={args.disabled}
+            leftSection={
+              <svg
+                xmlns="http://www.w3.org/2000/svg"
+                viewBox="0 0 24 24"
+                fill="none"
+                stroke="currentColor"
+                strokeWidth="2"
+                strokeLinecap="round"
+                strokeLinejoin="round"
+              >
+                <rect x="3" y="3" width="18" height="18" rx="2" ry="2"></rect>
+                <circle cx="8.5" cy="8.5" r="1.5"></circle>
+                <polyline points="21 15 16 10 5 21"></polyline>
+              </svg>
+            }
+          >
+            Gallery
+          </Tabs.Tab>
+          <Tabs.Tab
+            value="messages"
+            disabled={args.disabled}
+            leftSection={
+              <svg
+                xmlns="http://www.w3.org/2000/svg"
+                viewBox="0 0 24 24"
+                fill="none"
+                stroke="currentColor"
+                strokeWidth="2"
+                strokeLinecap="round"
+                strokeLinejoin="round"
+              >
+                <path d="M21 15a2 2 0 0 1-2 2H7l-4 4V5a2 2 0 0 1 2-2h14a2 2 0 0 1 2 2z"></path>
+              </svg>
+            }
+          >
+            Messages
+          </Tabs.Tab>
+          <Tabs.Tab
+            value="settings"
+            disabled={args.disabled}
+            leftSection={
+              <svg
+                xmlns="http://www.w3.org/2000/svg"
+                viewBox="0 0 24 24"
+                fill="none"
+                stroke="currentColor"
+                strokeWidth="2"
+                strokeLinecap="round"
+                strokeLinejoin="round"
+              >
+                <circle cx="12" cy="12" r="3"></circle>
+                <path d="M19.4 15a1.65 1.65 0 0 0 .33 1.82l.06.06a2 2 0 0 1 0 2.83 2 2 0 0 1-2.83 0l-.06-.06a1.65 1.65 0 0 0-1.82-.33 1.65 1.65 0 0 0-1 1.51V21a2 2 0 0 1-2 2 2 2 0 0 1-2-2v-.09A1.65 1.65 0 0 0 9 19.4a1.65 1.65 0 0 0-1.82.33l-.06.06a2 2 0 0 1-2.83 0 2 2 0 0 1 0-2.83l.06-.06a1.65 1.65 0 0 0 .33-1.82 1.65 1.65 0 0 0-1.51-1H3a2 2 0 0 1-2-2 2 2 0 0 1 2-2h.09A1.65 1.65 0 0 0 4.6 9a1.65 1.65 0 0 0-.33-1.82l-.06-.06a2 2 0 0 1 0-2.83 2 2 0 0 1 2.83 0l.06.06a1.65 1.65 0 0 0 1.82.33H9a1.65 1.65 0 0 0 1-1.51V3a2 2 0 0 1 2-2 2 2 0 0 1 2 2v.09a1.65 1.65 0 0 0 1 1.51 1.65 1.65 0 0 0 1.82-.33l.06-.06a2 2 0 0 1 2.83 0 2 2 0 0 1 0 2.83l-.06.06a1.65 1.65 0 0 0-.33 1.82V9a1.65 1.65 0 0 0 1.51 1H21a2 2 0 0 1 2 2 2 2 0 0 1-2 2h-.09a1.65 1.65 0 0 0-1.51 1z"></path>
+              </svg>
+            }
+          >
+            Settings
+          </Tabs.Tab>
+        </Tabs.List>
+
+        <Tabs.Panel value="gallery">Gallery tab content</Tabs.Panel>
+
+        <Tabs.Panel value="messages">Messages tab content</Tabs.Panel>
+
+        <Tabs.Panel value="settings">Settings tab content</Tabs.Panel>
+      </Tabs>
+    </Flex>
+  );
+};
+
+export const Default: Story = {
+  render: (args) => <InteractiveTabs {...args} />,
+  args: {
+    variant: "default",
+    orientation: "horizontal",
+  },
+};
+
+export const Outline: Story = {
+  render: (args) => <InteractiveTabs {...args} />,
+  args: {
+    variant: "outline",
+    orientation: "horizontal",
+  },
+};
+
+export const Pills: Story = {
+  render: (args) => <InteractiveTabs {...args} />,
+  args: {
+    variant: "pills",
+    orientation: "horizontal",
+  },
+};
+
+export const Vertical: Story = {
+  render: (args) => <InteractiveTabs {...args} />,
+  args: {
+    variant: "default",
+    orientation: "vertical",
+  },
+};
+
+export const Inverted: Story = {
+  render: (args) => <InteractiveTabs {...args} />,
+  args: {
+    variant: "default",
+    orientation: "horizontal",
+    inverted: true,
+  },
+};

package/src/components/Tabs/Tabs.test.tsx

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

package/src/components/Tabs/Tabs.tsx

@@ -0,0 +1,114 @@
+import { forwardRef } from "react";
+import {
+  Tabs as MantineTabs,
+  type TabsProps as MantineTabsProps,
+  type TabsListProps as MantineTabsListProps,
+  type TabsTabProps as MantineTabsTabProps,
+  type TabsPanelProps as MantineTabsPanelProps,
+} from "@mantine/core";
+import {
+  filterStylingProps,
+  mergeClassNames,
+  type RecursicaOverStyled,
+} from "../../utils/filterStylingProps";
+import styles from "./Tabs.module.css";
+
+import { type RecursicaTabsProps } from "@recursica/adapter-common";
+
+export interface RecursicaTabsPropsExtended
+  extends Omit<MantineTabsProps, "variant">,
+    RecursicaTabsProps {}
+
+export type TabsProps = RecursicaOverStyled<RecursicaTabsPropsExtended>;
+
+const _Tabs = forwardRef<HTMLDivElement, TabsProps>(function Tabs(props, ref) {
+  const {
+    variant = "default",
+    orientation = "horizontal",
+    overStyled = false,
+    className,
+    ...rest
+  } = props;
+
+  const sanitizedProps = filterStylingProps(rest, overStyled);
+  const restRecord = sanitizedProps as Record<string, unknown>;
+
+  const mergedClassNames = mergeClassNames(
+    {
+      list: styles.list,
+      tab: styles.tab,
+      panel: styles.panel,
+    },
+    restRecord.classNames as Partial<Record<string, string>> | undefined,
+  );
+
+  return (
+    <MantineTabs
+      ref={ref}
+      {...(sanitizedProps as MantineTabsProps)}
+      variant={variant}
+      orientation={orientation}
+      className={`${styles.root} ${className || ""}`}
+      data-variant={variant}
+      data-orientation={orientation}
+      classNames={mergedClassNames}
+    />
+  );
+});
+
+_Tabs.displayName = "Tabs";
+
+export type TabsListProps = RecursicaOverStyled<MantineTabsListProps>;
+
+const _TabsList = forwardRef<HTMLDivElement, TabsListProps>(
+  function TabsList(props, ref) {
+    const { overStyled = false, ...rest } = props;
+    return (
+      <MantineTabs.List
+        ref={ref}
+        {...(filterStylingProps(rest, overStyled) as MantineTabsListProps)}
+      />
+    );
+  },
+);
+_TabsList.displayName = "Tabs.List";
+
+export type TabsTabProps = RecursicaOverStyled<MantineTabsTabProps>;
+
+const _TabsTab = forwardRef<HTMLButtonElement, TabsTabProps>(
+  function TabsTab(props, ref) {
+    const { overStyled = false, ...rest } = props;
+    return (
+      <MantineTabs.Tab
+        ref={ref}
+        {...(filterStylingProps(rest, overStyled) as MantineTabsTabProps)}
+      />
+    );
+  },
+);
+_TabsTab.displayName = "Tabs.Tab";
+
+export type TabsPanelProps = RecursicaOverStyled<MantineTabsPanelProps>;
+
+const _TabsPanel = forwardRef<HTMLDivElement, TabsPanelProps>(
+  function TabsPanel(props, ref) {
+    const { overStyled = false, ...rest } = props;
+    return (
+      <MantineTabs.Panel
+        ref={ref}
+        {...(filterStylingProps(rest, overStyled) as MantineTabsPanelProps)}
+      />
+    );
+  },
+);
+_TabsPanel.displayName = "Tabs.Panel";
+
+export const Tabs: typeof _Tabs & {
+  List: typeof _TabsList;
+  Tab: typeof _TabsTab;
+  Panel: typeof _TabsPanel;
+} = Object.assign(_Tabs, {
+  List: _TabsList,
+  Tab: _TabsTab,
+  Panel: _TabsPanel,
+});

package/src/components/Tabs/USAGE.md

@@ -0,0 +1,45 @@
+# Tabs - Usage Guide
+
+This document describes how to integrate and use the `Tabs` component in your projects using `@recursica/adapter-mantine-v8`.
+
+---
+
+## 1. Import Reference
+
+```tsx
+import { Tabs } from "@recursica/adapter-mantine-v8";
+```
+
+---
+
+## 2. Basic Example
+
+```tsx
+import React from "react";
+import { Tabs } from "@recursica/adapter-mantine-v8";
+
+export default function Demo() {
+  return (
+    <Tabs defaultValue="home">
+      <Tabs.List>
+        <Tabs.Tab value="home">Home</Tabs.Tab>
+        <Tabs.Tab value="profile">Profile</Tabs.Tab>
+      </Tabs.List>
+      <Tabs.Panel value="home">Home content</Tabs.Panel>
+      <Tabs.Panel value="profile">Profile content</Tabs.Panel>
+    </Tabs>
+  );
+}
+```
+
+---
+
+## 3. Design System Integration
+
+All Recursica components in the `@recursica/adapter-mantine-v8` 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/Text/TEXT_IMPLEMENTATION_NOTES.md

@@ -0,0 +1,12 @@
+# Text – Implementation Notes
+
+## `.root` `text-wrap: balance` (Matt Massey, 2026-08-28)
+
+**Decision:** Added `text-wrap: balance` via a new `Text.module.css` `.root` class, merged onto the
+typography class alongside the caller's own `className`.
+
+**Implementation:** UX asked for more evenly balanced multi-line wrapping instead of a ragged last
+line. Not a design token — it's a layout algorithm choice, so it's hardcoded rather than pulled
+from `recursica_variables_scoped.css`. Chromium/Firefox only balance up to ~6 lines; longer
+paragraphs silently fall back to normal wrapping past that point. No fallback needed — browsers
+that don't support the value just ignore the declaration.

package/src/components/Text/Text.module.css

@@ -0,0 +1,13 @@
+/*
+ * HARDCODED VALUES
+ * - `.root` `text-wrap: balance` — not a design token; a layout algorithm choice requested by
+ *   UX (Matt Massey, 2026-08-28) to even out wrapped line lengths. See TEXT_IMPLEMENTATION_NOTES.md.
+ */
+
+.root {
+  /* HARDCODE: balances wrapped line lengths instead of leaving a ragged short last line. Most
+     effective on short text; browsers cap balancing at ~6 lines, so long paragraphs silently
+     fall back to normal wrapping past that point — no fallback needed, unsupported browsers
+     just ignore the declaration. */
+  text-wrap: balance;
+}

package/src/components/Text/Text.stories.tsx

@@ -0,0 +1,75 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { Text } from "./Text";
+
+const meta: Meta<typeof Text> = {
+  title: "UI-Kit/Text",
+  component: Text,
+  tags: ["autodocs"],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          "The standard `<Text>` component controls common body sizing scales and implicit paragraphs governed by the active theme layer. For semantic headings (`h1` through `h6`), use `<Heading>` instead.",
+      },
+    },
+  },
+  argTypes: {
+    variant: {
+      control: "select",
+      options: [
+        "body",
+        "body-small",
+        "caption",
+        "overline",
+        "subtitle",
+        "subtitle-small",
+      ],
+      description:
+        "Controls the standard logical boundary definitions natively extracted from Figma.",
+    },
+    c: {
+      control: "text",
+      description:
+        "Standard Mantine color string mapped via internal boundaries. Example: `dimmed`",
+    },
+  },
+};
+
+export default meta;
+
+type Story = StoryObj<typeof Text>;
+
+export const Default: Story = {
+  args: {
+    variant: "body",
+    children:
+      "This is standard body typography controlled by the central UI-kit boundaries exclusively.",
+  },
+  render: ({ ...args }) => <Text {...args} />,
+};
+
+export const StaticVariations: Story = {
+  args: {},
+  render: () => (
+    <div style={{ display: "flex", flexDirection: "column", gap: "16px" }}>
+      <Text variant="body">
+        Body (Base paragraph and generic information flow)
+      </Text>
+      <Text variant="body-small">
+        Body Small (Compacted list items and helper blocks)
+      </Text>
+      <Text variant="caption">
+        Caption (Data table descriptions or micro-labels)
+      </Text>
+      <Text variant="overline">
+        Overline (Card contextual pre-headers and categorical tags)
+      </Text>
+      <Text variant="subtitle">
+        Subtitle (Minor sub-headers avoiding heavy display weights)
+      </Text>
+      <Text variant="subtitle-small">
+        Subtitle Small (Section anchors deep in hierarchy)
+      </Text>
+    </div>
+  ),
+};

package/src/components/Text/Text.test.tsx

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

package/src/components/Text/Text.tsx

@@ -0,0 +1,53 @@
+import { forwardRef } from "react";
+import {
+  Text as MantineText,
+  type TextProps as MantineTextProps,
+  createPolymorphicComponent,
+} from "@mantine/core";
+import {
+  filterStylingProps,
+  type RecursicaOverStyled,
+} from "../../utils/filterStylingProps";
+
+import { type RecursicaTextProps } from "@recursica/adapter-common";
+import styles from "./Text.module.css";
+
+export type TextProps = RecursicaOverStyled<
+  Omit<MantineTextProps, "variant"> & RecursicaTextProps
+>;
+
+const _Text = forwardRef<HTMLDivElement, TextProps>(function Text(
+  { overStyled = false, variant = "body", ...rest },
+  ref,
+) {
+  const sanitizedProps = filterStylingProps(rest, overStyled);
+  const classNameProp = (sanitizedProps as Record<string, unknown>)
+    .className as string | undefined;
+
+  const typographyClass = `recursica_brand_typography_${variant}`;
+  const mergedClassName = [typographyClass, styles.root, classNameProp]
+    .filter(Boolean)
+    .join(" ");
+
+  return (
+    <MantineText
+      ref={ref}
+      {...(sanitizedProps as unknown as MantineTextProps)}
+      className={mergedClassName}
+    />
+  );
+});
+_Text.displayName = "Text";
+
+/**
+ * A generalized typographical wrapper limiting text properties to bounded Recursica UI-kit tokens inherently.
+ * Do not use for semantic headings; use the explicit `<Heading>` component for `<h1>` - `<h6>`.
+ *
+ * Supports polymorphism via the `component` prop or `renderRoot` for custom element rendering.
+ * @example
+ * ```tsx
+ * <Text component="span">Inline text</Text>
+ * <Text component="label" htmlFor="input-id">Label text</Text>
+ * ```
+ */
+export const Text = createPolymorphicComponent<"p", TextProps>(_Text);

package/src/components/Text/USAGE.md

@@ -0,0 +1,40 @@
+# Text - Usage Guide
+
+This document describes how to integrate and use the `Text` component in your projects using `@recursica/adapter-mantine-v8`.
+
+---
+
+## 1. Import Reference
+
+```tsx
+import { Text } from "@recursica/adapter-mantine-v8";
+```
+
+---
+
+## 2. Basic Example
+
+```tsx
+import React from "react";
+import { Text } from "@recursica/adapter-mantine-v8";
+
+export default function Demo() {
+  return (
+    <Text size="md" color="dimmed">
+      This is some styled body text.
+    </Text>
+  );
+}
+```
+
+---
+
+## 3. Design System Integration
+
+All Recursica components in the `@recursica/adapter-mantine-v8` 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/TextArea/TEXTAREA_IMPLEMENTATION_NOTES.md

@@ -0,0 +1,7 @@
+# TextArea Implementation Notes
+
+The `TextArea` component is mapped explicitly to Mantine's `<Textarea>` following the same strict encapsulation rules as `TextField`.
+
+1. **Naked Primitive Mapping:** Mantine's `Textarea` natively executes macro-label generation. To decouple it, we explicitly disable internal labels (`label={undefined}`) and inject it purely inside our generic `FormControlWrapper`.
+2. **Text Field Token Re-Use:** Because text areas fundamentally share the same box-geometry, text, and state definitions as single-line inputs, it strictly implements the `--recursica_ui-kit_components_text-field_...` variables natively.
+3. **Autosize Handling:** The component supports Mantine's raw `autosize`, `minRows`, and `maxRows` parameters out of the box dynamically via property passthrough.