@recursica/mantine-adapter 0.6.0 → 0.7.0

package/src/components/ReadOnlyField/ReadOnlyField.stories.tsx

@@ -0,0 +1,120 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import type { Meta, StoryObj } from "@storybook/react";
+import { ReadOnlyField } from "./ReadOnlyField";
+import { EmptyValueRenderer } from "@recursica/adapter-common";
+
+const meta: Meta<typeof ReadOnlyField> = {
+  title: "UI Kit/ReadOnlyField",
+  component: ReadOnlyField,
+  tags: ["autodocs"],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          "The ReadOnlyField safely natively wraps data sets bypassing active HTML interaction hooks while natively retaining exact bounding visual layouts defined by internal Design System Tokens. Useful for creating strict data-review profiles or conditional form read-overs.",
+      },
+    },
+  },
+  args: {
+    label: "Read Only Label",
+    value: "Fixed Data Set Value",
+    assistiveText: "Helper description text beneath the node.",
+    type: "text",
+  },
+  argTypes: {
+    type: {
+      control: "select",
+      options: ["text", "number"], // Add more as we support them
+    },
+    labelWithEditIcon: {
+      control: "boolean",
+    },
+    // We cannot natively control a React.ElementType through standard primitive storybook panels.
+  },
+};
+
+export default meta;
+
+type Story = StoryObj<typeof ReadOnlyField>;
+
+/**
+ * Playground story demonstrating standard structural blocks of the ReadOnlyField module dynamically.
+ */
+export const Default: Story = {
+  args: {},
+};
+
+/**
+ * Shows the default handler replacing missing mapping data directly with 'N/A'.
+ */
+export const EmptyValue: Story = {
+  args: {
+    value: "",
+    label: "Empty String Evaluated Automatically (Default 'N/A')",
+  },
+};
+
+const CustomEmptyTextRenderer: React.FC<{ value?: any }> & {
+  check?: (v: any) => boolean;
+} = (props) => <EmptyValueRenderer {...props} emptyText="No Data Found" />;
+CustomEmptyTextRenderer.check = EmptyValueRenderer.check;
+
+/**
+ * Demonstrates overriding the baseline verbiage internally utilizing the exported `EmptyValueRenderer` while inheriting default evaluation checks.
+ */
+export const CustomEmptyText: Story = {
+  args: {
+    value: null,
+    label: "Custom Empty Text Default",
+    emptyValueComponent: CustomEmptyTextRenderer,
+  },
+};
+
+const CustomEmptyCheckRenderer: React.FC<{ value?: any }> & {
+  check?: (v: any) => boolean;
+} = () => {
+  return <i>Custom HTML Markup Provided</i>;
+};
+CustomEmptyCheckRenderer.check = (val) => val === "EMPTY_MOCK";
+
+/**
+ * Validates a fully overridden emptyValueComponent injecting custom rendering boundaries alongside explicitly tailored validation rules evaluating datasets dynamically.
+ */
+export const CustomEmptyRenderer: Story = {
+  args: {
+    value: "EMPTY_MOCK",
+    label: "Custom Logic Evaluation Binding",
+    emptyValueComponent: CustomEmptyCheckRenderer,
+  },
+};
+
+/**
+ * Validates the core read-only label execution and base default spacing bindings globally.
+ */
+export const StackedDefault: Story = {
+  args: {
+    formLayout: "stacked",
+    value: "Some fixed readable text",
+  },
+};
+
+/**
+ * Binds side-by-side structures globally maintaining correct inline gutter layouts.
+ */
+export const SideBySide: Story = {
+  args: {
+    formLayout: "side-by-side",
+    value: "Some fixed readable text mapping horizontally",
+  },
+};
+
+/**
+ * Tests the fallback structural logic when Edit icon natively overrides required bindings.
+ */
+export const WithEditIcon: Story = {
+  args: {
+    labelWithEditIcon: true,
+    required: true,
+    value: "Editable fixed structure",
+  },
+};

package/src/components/ReadOnlyField/ReadOnlyField.tsx

@@ -0,0 +1,75 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import React, { forwardRef } from "react";
+import {
+  ReadOnlyFieldType,
+  EmptyValueRenderer,
+} from "@recursica/adapter-common";
+import {
+  filterStylingProps,
+  type RecursicaOverStyled,
+} from "../../utils/filterStylingProps";
+import {
+  type FormControlWrapperProps,
+  FormControlWrapper,
+} from "../FormControlWrapper/FormControlWrapper";
+import { ReadOnlyTextField } from "./ReadOnlyTextField";
+
+export interface RecursicaReadOnlyFieldProps
+  extends Omit<FormControlWrapperProps, "children" | "overStyled"> {
+  /** The specific value to be rendered in read-only mode explicitly matching the original field input */
+  value?: any;
+  /** The data type formatting rules bounding how the string is presented to the user */
+  type?: ReadOnlyFieldType;
+  /** Custom renderer explicitly responsible for formatting missing/empty value mappings (overriding default 'N/A') */
+  emptyValueComponent?: React.ElementType<{ value?: any }>;
+}
+
+export type ReadOnlyFieldProps =
+  RecursicaOverStyled<RecursicaReadOnlyFieldProps>;
+
+/**
+ * A native generic form control wrapper exclusively responsible for displaying fixed data.
+ * Internally maps to structural ReadOnly primitive blocks bridging standard `FormControlWrapper` layouts natively.
+ */
+export const ReadOnlyField = forwardRef<HTMLDivElement, ReadOnlyFieldProps>(
+  function ReadOnlyField(
+    { value, type = "text", emptyValueComponent, overStyled = false, ...rest },
+    ref,
+  ) {
+    let content: React.ReactNode = null;
+
+    // We still pass sanitized properties (like className/style/etc) strictly down.
+    const sanitizedProps = filterStylingProps(rest, overStyled);
+
+    const Renderer = emptyValueComponent || EmptyValueRenderer;
+    const isValueEmpty = (Renderer as any).check
+      ? (Renderer as any).check(value)
+      : EmptyValueRenderer.check(value);
+
+    const displayValue = isValueEmpty ? <Renderer value={value} /> : value;
+
+    switch (type) {
+      case "text":
+      default:
+        content = (
+          <ReadOnlyTextField
+            value={displayValue}
+            overStyled={overStyled as true}
+          />
+        );
+        break;
+    }
+
+    return (
+      <FormControlWrapper
+        ref={ref}
+        overStyled={overStyled as true}
+        {...(sanitizedProps as any)}
+      >
+        {content}
+      </FormControlWrapper>
+    );
+  },
+);
+
+ReadOnlyField.displayName = "ReadOnlyField";

package/src/components/ReadOnlyField/ReadOnlyTextField.tsx

@@ -0,0 +1,46 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import React from "react";
+import { Box } from "@mantine/core";
+import {
+  filterStylingProps,
+  type RecursicaOverStyled,
+} from "../../utils/filterStylingProps";
+import styles from "./ReadOnlyField.module.css";
+
+export interface RecursicaReadOnlyTextFieldProps {
+  /** The value strictly rendered as text output */
+  value?: any;
+}
+
+export type ReadOnlyTextFieldProps =
+  RecursicaOverStyled<RecursicaReadOnlyTextFieldProps>;
+
+export const ReadOnlyTextField: React.FC<ReadOnlyTextFieldProps> = ({
+  value,
+  overStyled = false,
+  ...rest
+}) => {
+  const sanitizedProps = filterStylingProps(rest, overStyled);
+  const classNameProp = (sanitizedProps as Record<string, unknown>)
+    .className as string | undefined;
+
+  return (
+    <Box
+      component="p"
+      className={
+        classNameProp
+          ? `${styles.textField} ${classNameProp}`
+          : styles.textField
+      }
+      {...sanitizedProps}
+    >
+      {value != null
+        ? React.isValidElement(value)
+          ? value
+          : String(value)
+        : ""}
+    </Box>
+  );
+};
+
+ReadOnlyTextField.displayName = "ReadOnlyTextField";

package/src/components/ReadOnlyField/WithReadOnlyWrapper.tsx

@@ -0,0 +1,85 @@
+/* eslint-disable @typescript-eslint/no-explicit-any */
+import React, { forwardRef } from "react";
+import { type ReadOnlyFieldType } from "@recursica/adapter-common";
+import {
+  FormControlWrapper,
+  type FormControlWrapperProps,
+} from "../FormControlWrapper/FormControlWrapper";
+import { ReadOnlyField } from "./ReadOnlyField";
+
+export interface WithReadOnlyWrapperProps
+  extends Omit<FormControlWrapperProps, "children" | "overStyled"> {
+  /** Injects whether the field defaults to reading mode natively */
+  readOnly?: boolean;
+  /** Explicit React component directly overtaking the baseline text renderer when read-only mode is active */
+  readOnlyComponent?: React.ReactNode;
+  /** Instructs the underlying generic ReadOnlyField which raw visual structure to bridge automatically */
+  readOnlyType?: ReadOnlyFieldType;
+  /** The isolated raw data value intercepted explicitly into the ReadOnly formatters */
+  readOnlyValue?: any;
+  /** Safely enables deep Mantine overrides transparently bypassing block filters */
+  overStyled?: boolean;
+  /** The nested active node dynamically exposed exclusively when read-only bounds are disabled */
+  activeComponent: React.ReactNode;
+}
+
+/**
+ * Universal execution barrier trapping readOnly states globally.
+ * Natively delegates active logic down avoiding duplicative internal component bindings dynamically.
+ */
+export const WithReadOnlyWrapper = forwardRef<
+  HTMLDivElement,
+  WithReadOnlyWrapperProps
+>(function WithReadOnlyWrapper(
+  {
+    readOnly,
+    readOnlyComponent,
+    readOnlyType = "text",
+    readOnlyValue,
+    activeComponent,
+    overStyled,
+    onLabelEditClick,
+    ...wrapperProps
+  },
+  ref,
+) {
+  if (readOnly) {
+    if (readOnlyComponent) {
+      return (
+        <FormControlWrapper
+          ref={ref}
+          {...wrapperProps}
+          onLabelEditClick={onLabelEditClick}
+          overStyled={overStyled as true}
+        >
+          {readOnlyComponent}
+        </FormControlWrapper>
+      );
+    }
+
+    return (
+      <ReadOnlyField
+        ref={ref}
+        type={readOnlyType}
+        value={readOnlyValue}
+        onLabelEditClick={onLabelEditClick}
+        overStyled={overStyled as true}
+        {...wrapperProps}
+      />
+    );
+  }
+
+  // Active Standard Execution natively forwarding bound children implicitly
+  return (
+    <FormControlWrapper
+      ref={ref}
+      {...wrapperProps}
+      onLabelEditClick={onLabelEditClick}
+      overStyled={overStyled as true}
+    >
+      {activeComponent}
+    </FormControlWrapper>
+  );
+});
+
+WithReadOnlyWrapper.displayName = "WithReadOnlyWrapper";

package/src/components/ReadOnlyField/index.ts

@@ -0,0 +1,3 @@
+export * from "./ReadOnlyField";
+export * from "./WithReadOnlyWrapper";
+export * from "./ReadOnlyTextField";

package/src/components/Search/Search.stories.tsx

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

package/src/components/Search/Search.tsx

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

package/src/components/SegmentedControl/SegmentedControl.stories.tsx

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

package/src/components/SegmentedControl/SegmentedControl.tsx

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

package/src/components/Slider/Slider.stories.tsx

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

package/src/components/Slider/Slider.tsx

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

package/src/components/Stepper/Stepper.stories.tsx

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

package/src/components/Stepper/Stepper.tsx

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

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

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

package/src/components/Switch/Switch.tsx

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

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";