@recursica/mantine-adapter 0.9.4 → 0.10.0

package/src/components/Switch/Switch.stories.tsx

@@ -0,0 +1,96 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { Switch } from "./Switch";
+
+const meta: Meta<typeof Switch> = {
+  title: "UI-Kit/Switch",
+  component: Switch,
+  tags: ["autodocs"],
+  parameters: {
+    docs: {
+      description: {
+        component: `
+The \`Switch\` component is an atomic form primitive representing boolean states, natively aligned to the Recursica design system.
+
+> [!IMPORTANT]  
+> Unlike \`Checkbox\`, the \`Switch\` is typically used for standalone settings toggles. It fully supports the universal \`ReadOnlyField\` boundaries when passed the \`readOnly\` attribute.
+
+### Usage
+To render a standard switch:
+\`\`\`tsx
+<Switch label="Enable Notifications" defaultChecked />
+\`\`\`
+`,
+      },
+    },
+  },
+  argTypes: {
+    disabled: {
+      control: "boolean",
+    },
+    checked: {
+      control: "boolean",
+    },
+    required: {
+      control: "boolean",
+    },
+    error: {
+      control: "boolean",
+    },
+    defaultChecked: {
+      control: "boolean",
+    },
+    readOnly: {
+      control: "boolean",
+      description:
+        "Toggles structural read-only data presentation bypassing interaction boundaries completely.",
+    },
+  },
+};
+
+export default meta;
+
+type Story = StoryObj<typeof Switch>;
+
+export const Default: Story = {
+  args: {
+    disabled: false,
+    label: "Standard Switch",
+  },
+};
+
+export const StaticVariations: Story = {
+  args: {},
+  render: () => (
+    <div
+      style={{
+        display: "flex",
+        flexDirection: "column",
+        gap: "24px",
+      }}
+    >
+      <Switch label="Default Unchecked State" />
+      <Switch label="Checked State" defaultChecked />
+      <Switch label="Disabled Unchecked" disabled />
+      <Switch label="Disabled Checked" defaultChecked disabled />
+    </div>
+  ),
+};
+
+export const StaticReadOnly: Story = {
+  args: {},
+  render: () => (
+    <div
+      style={{
+        display: "flex",
+        flexDirection: "column",
+        gap: "24px",
+      }}
+    >
+      <Switch
+        label="Read Only Switch"
+        readOnly
+        readOnlyComponent={<span>Enabled</span>}
+      />
+    </div>
+  ),
+};

package/src/components/Switch/Switch.tsx

@@ -0,0 +1,119 @@
+import { forwardRef } from "react";
+import {
+  Switch as MantineSwitch,
+  type SwitchProps as MantineSwitchProps,
+  CheckIcon,
+  CloseIcon,
+} from "@mantine/core";
+import { type ReadOnlyControlProps } from "@recursica/adapter-common";
+
+import {
+  filterStylingProps,
+  type RecursicaOverStyled,
+} from "../../utils/filterStylingProps";
+import styles from "./Switch.module.css";
+
+import { SwitchGroup } from "./SwitchGroup";
+
+export type RecursicaSwitchProps = Omit<
+  MantineSwitchProps,
+  "size" | "color" | "radius" | "variant"
+> &
+  ReadOnlyControlProps;
+
+export type SwitchProps = RecursicaOverStyled<RecursicaSwitchProps>;
+
+type SwitchComponent = React.ForwardRefExoticComponent<
+  SwitchProps & React.RefAttributes<HTMLInputElement>
+> & {
+  Group: typeof SwitchGroup;
+};
+
+export const Switch = forwardRef<HTMLInputElement, SwitchProps>(function Switch(
+  {
+    overStyled = false,
+    readOnly,
+    readOnlyComponent,
+    disabled,
+    thumbIcon,
+    ...rest
+  },
+  ref,
+) {
+  const sanitizedProps = filterStylingProps(rest, overStyled);
+  const restRecord = sanitizedProps as Record<string, unknown>;
+
+  // Actively delete dimension bindings that bypass the abstraction
+  delete restRecord["size"];
+  delete restRecord["color"];
+  delete restRecord["radius"];
+  delete restRecord["variant"];
+
+  if (readOnly && readOnlyComponent) {
+    // Safely fallback explicitly returning mapped elements natively without macro wrappers
+    return <>{readOnlyComponent}</>;
+  }
+
+  const mergedClassNames: Partial<Record<string, string>> = {
+    root: styles.root,
+    body: styles.body,
+    track: styles.track,
+    thumb: styles.thumb,
+    trackLabel: styles.trackLabel,
+    labelWrapper: styles.labelWrapper,
+    label: styles.label,
+  };
+
+  const classNamesProp = restRecord.classNames;
+  if (
+    classNamesProp &&
+    typeof classNamesProp === "object" &&
+    !Array.isArray(classNamesProp)
+  ) {
+    const o = classNamesProp as Partial<Record<string, string>>;
+    mergedClassNames.root = o.root ? `${styles.root} ${o.root}` : styles.root;
+    mergedClassNames.body = o.body ? `${styles.body} ${o.body}` : styles.body;
+    mergedClassNames.track = o.track
+      ? `${styles.track} ${o.track}`
+      : styles.track;
+    mergedClassNames.thumb = o.thumb
+      ? `${styles.thumb} ${o.thumb}`
+      : styles.thumb;
+    mergedClassNames.trackLabel = o.trackLabel
+      ? `${styles.trackLabel} ${o.trackLabel}`
+      : styles.trackLabel;
+    mergedClassNames.labelWrapper = o.labelWrapper
+      ? `${styles.labelWrapper} ${o.labelWrapper}`
+      : styles.labelWrapper;
+    mergedClassNames.label = o.label
+      ? `${styles.label} ${o.label}`
+      : styles.label;
+  }
+
+  const classNameProp = restRecord.className as string | undefined;
+  const finalClass = classNameProp
+    ? `${styles.root} ${classNameProp}`
+    : styles.root;
+
+  const FinalThumbIcon = (
+    <div className={styles.thumbIconWrapper}>
+      <CheckIcon className={styles.checkIcon} />
+      <CloseIcon className={styles.closeIcon} />
+    </div>
+  );
+
+  // We omit Mantine's sizing/coloring so we rely strictly on variables from Switch.module.css
+  return (
+    <MantineSwitch
+      ref={ref}
+      className={finalClass}
+      classNames={mergedClassNames}
+      disabled={readOnly || disabled}
+      thumbIcon={thumbIcon ?? FinalThumbIcon}
+      {...(sanitizedProps as unknown as MantineSwitchProps)}
+    />
+  );
+}) as SwitchComponent;
+
+Switch.displayName = "Switch";
+Switch.Group = SwitchGroup;

package/src/components/Switch/SwitchGroup.stories.tsx

@@ -0,0 +1,112 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { Switch } from "./Switch";
+import { SwitchGroup } from "./SwitchGroup";
+import { useState } from "react";
+import { formControlArgTypes } from "../../../.storybook/commonArgTypes";
+
+const meta: Meta<typeof SwitchGroup> = {
+  title: "UI-Kit/SwitchGroup",
+  component: SwitchGroup,
+  tags: ["autodocs"],
+  parameters: {
+    docs: {
+      description: {
+        component: `
+The \`SwitchGroup\` component is the mandatory organizational wrapper for orchestrating \`Switch\` primitives into macro form layouts. It inherently leverages the \`FormControlWrapper\`, granting native access to structural alignments, assistive descriptions, and strict flex arrays.
+
+### Supported Layout Vectors
+- **\`formLayout="stacked"\`**: Top-to-bottom layout cascading the Label bounding box down vertically into a standard stacked switch array.
+- **\`formLayout="side-by-side"\`**: Flow architecture pulling the grouping Label dynamically to the left while structurally organizing the internal switches cleanly alongside it horizontally.
+
+> [!IMPORTANT]  
+> If you require a solitary \`Switch\` field to natively accept an overarching form label, assistive text, or align with other side-by-side components in a form column, you must wrap it inside a \`Switch.Group\` to trigger the \`FormControlWrapper\` mapping.
+`,
+      },
+    },
+  },
+  argTypes: {
+    ...formControlArgTypes,
+    readOnly: {
+      control: "boolean",
+      description:
+        "Passes read-only lock natively down mapping inner switches into explicitly disabled states.",
+    },
+  },
+};
+
+export default meta;
+
+type Story = StoryObj<typeof SwitchGroup>;
+
+export const Default: Story = {
+  args: {
+    formLayout: "stacked",
+    label: "Notification Settings",
+    description: "Manage your preferences.",
+    assistiveText: "We recommend turning these on.",
+    error: "",
+    required: true,
+  },
+  render: function DefaultRender(args) {
+    const [value, setValue] = useState<string[]>(["email"]);
+    return (
+      <SwitchGroup {...args} value={value} onChange={setValue}>
+        <Switch value="email" label="Email Alerts" />
+        <Switch value="push" label="Push Notifications" />
+        <Switch value="sms" label="SMS Messages" />
+      </SwitchGroup>
+    );
+  },
+};
+
+export const SideBySideLayout: Story = {
+  args: {
+    ...Default.args,
+    formLayout: "side-by-side",
+    labelSize: "default",
+    labelAlignment: "left",
+  },
+  render: function SideBySideRender(args) {
+    const [value, setValue] = useState<string[]>([]);
+    return (
+      <SwitchGroup {...args} value={value} onChange={setValue}>
+        <Switch value="weekly" label="Weekly Digest" />
+        <Switch value="marketing" label="Marketing Emails" />
+      </SwitchGroup>
+    );
+  },
+};
+
+export const SolitaryFormControl: Story = {
+  args: {
+    formLayout: "side-by-side",
+    label: "Enable Backups",
+    description: "Automatically back up your data nightly.",
+  },
+  render: function SolitaryRender(args) {
+    const [value, setValue] = useState<string[]>(["auto"]);
+    return (
+      <SwitchGroup {...args} value={value} onChange={setValue}>
+        <Switch value="auto" label="Auto-backup" />
+      </SwitchGroup>
+    );
+  },
+};
+
+export const GroupReadOnly: Story = {
+  args: {
+    ...Default.args,
+    readOnly: true,
+    readOnlyComponent: <span>2 Notifications Enabled</span>,
+  },
+  render: function ReadOnlyRender(args) {
+    const [value, setValue] = useState<string[]>(["email", "sms"]);
+    return (
+      <SwitchGroup {...args} value={value} onChange={setValue}>
+        <Switch value="email" label="Email Alerts" />
+        <Switch value="push" label="Push Notifications" />
+        <Switch value="sms" label="SMS Messages" />
+      </SwitchGroup>
+    );
+  },
+};

package/src/components/Switch/SwitchGroup.tsx

@@ -0,0 +1,138 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import React, { forwardRef } from "react";
+import {
+  Switch as MantineSwitch,
+  type SwitchGroupProps as MantineSwitchGroupProps,
+} from "@mantine/core";
+import { type ReadOnlyControlProps } from "@recursica/adapter-common";
+import {
+  filterStylingProps,
+  type RecursicaOverStyled,
+} from "../../utils/filterStylingProps";
+import {
+  FormControlWrapper,
+  type RecursicaFormControlWrapperProps,
+} from "../FormControlWrapper/FormControlWrapper";
+import styles from "./Switch.module.css";
+
+export interface RecursicaSwitchGroupProps
+  extends Omit<MantineSwitchGroupProps, "size" | "labelProps">,
+    Omit<
+      RecursicaFormControlWrapperProps,
+      "controlMaxWidth" | "controlMinWidth"
+    >,
+    ReadOnlyControlProps {}
+
+export type SwitchGroupProps = RecursicaOverStyled<RecursicaSwitchGroupProps>;
+
+export const SwitchGroup = forwardRef<HTMLDivElement, SwitchGroupProps>(
+  function SwitchGroup(
+    {
+      overStyled = false,
+      formLayout = "stacked",
+
+      // Label Wrappers
+      labelSize,
+      labelAlignment,
+      labelOptionalText,
+      labelWithEditIcon,
+      onLabelEditClick,
+
+      // Base Mantine Extracted Attributes
+      label,
+      description,
+      assistiveText,
+      assistiveWithIcon,
+      error,
+      required,
+      withAsterisk,
+      id,
+      className,
+      style,
+      children,
+      readOnly,
+      readOnlyComponent,
+      ...rest
+    },
+    ref,
+  ) {
+    const sanitizedProps = filterStylingProps(rest, overStyled);
+    const restRecord = sanitizedProps as Record<string, unknown>;
+
+    // Delete prohibited sizing hooks from bypassing the variables
+    delete restRecord["size"];
+
+    if (readOnly && readOnlyComponent) {
+      return (
+        <FormControlWrapper
+          className={className}
+          style={style as React.CSSProperties}
+          controlMaxWidth="var(--recursica_ui-kit_components_switch_properties_max-width)"
+          controlMinWidth={undefined}
+          overStyled={overStyled as true}
+          labelElement="div"
+          formLayout={formLayout}
+          labelSize={labelSize}
+          labelAlignment={labelAlignment}
+          labelOptionalText={labelOptionalText}
+          labelWithEditIcon={labelWithEditIcon}
+          onLabelEditClick={onLabelEditClick}
+          label={label}
+          description={description}
+          assistiveText={assistiveText}
+          assistiveWithIcon={assistiveWithIcon}
+          error={error}
+          required={required}
+          withAsterisk={withAsterisk}
+          id={id}
+        >
+          {readOnlyComponent}
+        </FormControlWrapper>
+      );
+    }
+
+    return (
+      <FormControlWrapper
+        className={className}
+        style={style as React.CSSProperties}
+        controlMaxWidth="var(--recursica_ui-kit_components_switch_properties_max-width)"
+        controlMinWidth={undefined}
+        overStyled={overStyled as true}
+        labelElement="div" // Strictly override. ARIA grouping prohibits interactive switches nested natively inside <label>.
+        formLayout={formLayout}
+        labelSize={labelSize}
+        labelAlignment={labelAlignment}
+        labelOptionalText={labelOptionalText}
+        labelWithEditIcon={labelWithEditIcon}
+        onLabelEditClick={onLabelEditClick}
+        label={label}
+        description={description}
+        assistiveText={assistiveText}
+        assistiveWithIcon={assistiveWithIcon}
+        error={error}
+        required={required}
+        withAsterisk={withAsterisk}
+        id={id}
+      >
+        <MantineSwitch.Group
+          ref={ref}
+          /* Natively bind local disabled lock dynamically */
+          {...(sanitizedProps as unknown as MantineSwitchGroupProps)}
+        >
+          <div className={styles.groupRoot} data-layout={formLayout}>
+            {React.Children.map(children, (child) => {
+              if (React.isValidElement(child)) {
+                return React.cloneElement(child as React.ReactElement<any>, {
+                  disabled: readOnly || (child.props as any).disabled,
+                });
+              }
+              return child;
+            })}
+          </div>
+        </MantineSwitch.Group>
+      </FormControlWrapper>
+    );
+  },
+);
+
+SwitchGroup.displayName = "SwitchGroup";

package/src/components/Table/Table.stories.tsx

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

package/src/components/Table/Table.tsx

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

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

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

package/src/components/Tabs/Tabs.tsx

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

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

@@ -0,0 +1,88 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { Text } from "./Text";
+import { Layer } from "@recursica/adapter-common";
+
+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 `<Title>` 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 }) => (
+    <Layer layer={0} style={{ padding: "48px" }}>
+      <Text {...args} />
+    </Layer>
+  ),
+};
+
+export const StaticVariations: Story = {
+  args: {},
+  render: () => (
+    <Layer
+      layer={0}
+      style={{
+        padding: "48px",
+        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>
+    </Layer>
+  ),
+};

package/src/components/Text/Text.tsx

@@ -0,0 +1,54 @@
+import { forwardRef, type ReactNode } from "react";
+import {
+  Text as MantineText,
+  type TextProps as MantineTextProps,
+} from "@mantine/core";
+import {
+  filterStylingProps,
+  type RecursicaOverStyled,
+} from "../../utils/filterStylingProps";
+
+export type TextVariant =
+  | "body"
+  | "body-small"
+  | "caption"
+  | "overline"
+  | "subtitle"
+  | "subtitle-small";
+
+export type RecursicaTextProps = Omit<MantineTextProps, "variant"> & {
+  /**
+   * The explicit typography hierarchy dictated by Recursica's global design tokens.
+   */
+  variant?: TextVariant;
+  children?: ReactNode;
+};
+
+export type TextProps = RecursicaOverStyled<RecursicaTextProps>;
+
+/**
+ * A generalized typographical wrapper limiting text properties to bounded Recursica UI-kit tokens inherently.
+ * Do not use for semantic headings; use the explicit `<Title>` component for `<h1>` - `<h6>`.
+ */
+export 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 = classNameProp
+    ? `${typographyClass} ${classNameProp}`
+    : typographyClass;
+
+  return (
+    <MantineText
+      ref={ref}
+      className={mergedClassName}
+      {...(sanitizedProps as unknown as MantineTextProps)}
+    />
+  );
+});
+Text.displayName = "Text";

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.