@recursica/adapter-mantine-v8 1.3.4 → 1.3.6

package/src/components/HoverCard/HoverCard.stories.tsx

@@ -0,0 +1,172 @@
+import type { Meta, StoryObj } from "@storybook/react";
+import { HoverCard } from "./HoverCard";
+import { Button } from "../Button";
+import { Text } from "../Text/Text";
+import { Group } from "../Group/Group";
+import { Stack } from "../Stack/Stack";
+import { Avatar } from "../Avatar";
+
+/**
+ * HoverCard story axes:
+ * - position: dropdown alignment relative to target
+ * - withArrow: arrow indicator on the dropdown
+ * - openDelay / closeDelay: hover timing controls
+ * - content variations: plain text, rich content (avatar + text + actions)
+ * - layer: tested via the global Layer decorator (withLayer/layer args)
+ */
+
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+type HoverCardStoryArgs = Record<string, any>;
+
+const meta: Meta = {
+  title: "UI-Kit/HoverCard",
+  component: HoverCard,
+  tags: ["autodocs"],
+  argTypes: {
+    position: {
+      control: "select",
+      options: [
+        "bottom",
+        "bottom-start",
+        "bottom-end",
+        "top",
+        "top-start",
+        "top-end",
+        "left",
+        "left-start",
+        "left-end",
+        "right",
+        "right-start",
+        "right-end",
+      ],
+      description: "The position of the dropdown relative to the target.",
+    },
+    withBeak: {
+      control: "boolean",
+      description:
+        "Whether to display a beak (arrow) pointing to the target. Recursica equivalent of Mantine's withArrow.",
+    },
+    offset: {
+      control: "number",
+      description:
+        "Distance in px between the dropdown and the target element.",
+    },
+    openDelay: {
+      control: "number",
+      description: "Delay in ms before the dropdown opens on hover.",
+    },
+    closeDelay: {
+      control: "number",
+      description: "Delay in ms before the dropdown closes when hover ends.",
+    },
+    disabled: {
+      control: "boolean",
+      description: "If set, the hover card dropdown will not be rendered.",
+    },
+  },
+  parameters: {
+    layout: "centered",
+    docs: {
+      description: {
+        component: `
+The \`HoverCard\` component displays a popover-style dropdown when the user hovers over a target element. It wraps Mantine's composable \`HoverCard\` while enforcing strict Recursica design token styling.
+
+### Composable API
+
+HoverCard uses a dot-notation composition pattern:
+- \`<HoverCard>\` — Root container managing open/close state on hover
+- \`<HoverCard.Target>\` — Wrapper for the trigger element (must be a single element supporting ref)
+- \`<HoverCard.Dropdown>\` — The popup panel displaying content on hover
+
+### Key Behaviors
+- The dropdown opens when the user hovers over the target and closes when they move away
+- \`openDelay\` and \`closeDelay\` control the timing of open/close transitions
+- The dropdown stays open while the user hovers over it, allowing interaction with its content
+        `,
+      },
+    },
+  },
+};
+
+export default meta;
+
+type Story = StoryObj<HoverCardStoryArgs>;
+
+export const Default: Story = {
+  args: {
+    position: "top",
+    withBeak: true,
+    offset: 5,
+    openDelay: 0,
+    closeDelay: 150,
+  },
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  render: ({ withLayer, layer, ...args }: HoverCardStoryArgs) => {
+    return (
+      <HoverCard {...args}>
+        <HoverCard.Target>
+          <Button variant="solid">Hover me</Button>
+        </HoverCard.Target>
+
+        <HoverCard.Dropdown>
+          <Text>
+            This is a hover card with informational content that appears when
+            you hover over the target element.
+          </Text>
+        </HoverCard.Dropdown>
+      </HoverCard>
+    );
+  },
+};
+
+export const WithoutBeak: Story = {
+  args: {
+    position: "top",
+    withBeak: false,
+    offset: 5,
+  },
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  render: ({ withLayer, layer, ...args }: HoverCardStoryArgs) => {
+    return (
+      <HoverCard {...args}>
+        <HoverCard.Target>
+          <Button variant="outline">Without Beak</Button>
+        </HoverCard.Target>
+
+        <HoverCard.Dropdown>
+          <Text>
+            This hover card has the beak disabled, showing a clean dropdown
+            without the pointing indicator.
+          </Text>
+        </HoverCard.Dropdown>
+      </HoverCard>
+    );
+  },
+};
+
+export const RichContent: Story = {
+  args: {
+    position: "top",
+    offset: 5,
+  },
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars
+  render: ({ withLayer, layer, ...args }: HoverCardStoryArgs) => {
+    return (
+      <HoverCard {...args}>
+        <HoverCard.Target>
+          <Button variant="solid">User Profile</Button>
+        </HoverCard.Target>
+
+        <HoverCard.Dropdown>
+          <Group>
+            <Avatar src={null} alt="User avatar" />
+            <Stack>
+              <Text>Jane Doe</Text>
+              <Text>Software Engineer at Recursica</Text>
+            </Stack>
+          </Group>
+        </HoverCard.Dropdown>
+      </HoverCard>
+    );
+  },
+};

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/LayoutGrid/LayoutGrid.stories.tsx

@@ -0,0 +1,61 @@
+import React from "react";
+import type { Meta, StoryObj } from "@storybook/react";
+import { useRecursicaManifest } from "@recursica/adapter-common";
+import { LayoutGrid } from "./LayoutGrid";
+
+type LayoutGridStoryProps = React.ComponentProps<typeof LayoutGrid>;
+
+const meta: Meta<LayoutGridStoryProps> = {
+  title: "UI-Kit/LayoutGrid",
+  component: LayoutGrid,
+  tags: ["autodocs"],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          "LayoutGrid is the Recursica layout grid. Its column count, column-gutter, row-gutter and margin come from the design system's layout-grid tokens, which Forge defines per breakpoint, so they respond to the viewport and are not integrator-configurable.",
+      },
+    },
+  },
+};
+
+export default meta;
+
+type Story = StoryObj<LayoutGridStoryProps>;
+
+// Plain bordered cell: Card has a token min-width wider than one column, which would overflow it.
+const Swatch = ({ children }: { children: React.ReactNode }) => (
+  <div
+    style={{
+      border: "1px dashed currentColor",
+      padding: "8px",
+      textAlign: "center",
+    }}
+  >
+    {children}
+  </div>
+);
+
+// Reads the default layout grid from the manifest (brand.layout-grids.default) and fills two full
+// rows of single-column cells, so the story shows exactly the design system's column count.
+const DefaultGrid = () => {
+  const manifest = useRecursicaManifest() as {
+    brand: {
+      "layout-grids": { default: { columns: { $value: number } } };
+    };
+  };
+  const columns = manifest.brand["layout-grids"].default.columns.$value;
+  return (
+    <LayoutGrid>
+      {Array.from({ length: columns * 2 }, (_, i) => (
+        <LayoutGrid.Col key={i} span={1}>
+          <Swatch>{(i % columns) + 1}</Swatch>
+        </LayoutGrid.Col>
+      ))}
+    </LayoutGrid>
+  );
+};
+
+export const Default: Story = {
+  render: () => <DefaultGrid />,
+};

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/Loader/Loader.stories.tsx

@@ -0,0 +1,123 @@
+import React from "react";
+import type { Meta, StoryObj } from "@storybook/react";
+import { Loader } from "./Loader";
+import { Layer } from "@recursica/adapter-common";
+
+type LoaderStoryArgs = React.ComponentProps<typeof Loader> & {
+  layer?: 0 | 1 | 2 | 3;
+};
+
+const meta: Meta<LoaderStoryArgs> = {
+  title: "UI-Kit/Loader",
+  component: Loader as React.ComponentType<LoaderStoryArgs>,
+  tags: ["autodocs"],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          "The Loader bridges the Recursica UI-Kit `loader` variables to the generic primitive, rendering deterministic sizes and variants visually mapped strictly from the explicit design boundary tokens.",
+      },
+    },
+  },
+  argTypes: {
+    variant: {
+      control: "select",
+      options: ["oval", "bars", "dots"],
+      description: "The structural layout variant of the loading indicator",
+    },
+    size: {
+      control: "select",
+      options: ["sm", "md", "lg", "small", "default", "large"],
+      description:
+        "Scales the dimensional and thickness layout constrained to the explicit UI variables",
+    },
+    color: {
+      control: "color",
+      description:
+        "Optional inline dynamic color override spanning the token defaults",
+    },
+    layer: {
+      control: { type: "range", min: 0, max: 3, step: 1 },
+      description:
+        "Applies a wrapping context to observe rendering logic externally",
+    },
+    animate: {
+      control: "boolean",
+      description:
+        "Freezes the CSS animation when false — deterministic, for visual regression",
+    },
+  },
+};
+
+export default meta;
+
+type Story = StoryObj<LoaderStoryArgs>;
+
+/**
+ * Animated — excluded from visual regression (`adapter-tester.config.json`),
+ * since a moving animation diffs differently every run. See the `Static*`
+ * stories below for the deterministic, visual-regression-covered equivalents.
+ */
+export const Default: Story = {
+  args: {
+    variant: "oval",
+    size: "default",
+    layer: 0,
+  },
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars, @typescript-eslint/no-explicit-any
+  render: ({ withLayer, layer, ...args }: any) => (
+    <Layer layer={layer ?? 0} style={{ padding: "24px" }}>
+      <Loader {...args} />
+    </Layer>
+  ),
+};
+
+/** `animate: false` freezes the spin — deterministic for visual regression. */
+export const StaticOvalDefault: Story = {
+  args: {
+    variant: "oval",
+    size: "default",
+    animate: false,
+  },
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars, @typescript-eslint/no-explicit-any
+  render: ({ withLayer, layer, ...args }: any) => <Loader {...args} />,
+};
+
+/** `animate: false` freezes the bars — deterministic for visual regression. */
+export const StaticBarsLarge: Story = {
+  args: {
+    variant: "bars",
+    size: "large",
+    animate: false,
+  },
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars, @typescript-eslint/no-explicit-any
+  render: ({ withLayer, layer, ...args }: any) => <Loader {...args} />,
+};
+
+/** `animate: false` freezes the dots — deterministic for visual regression. */
+export const StaticDotsSmall: Story = {
+  args: {
+    variant: "dots",
+    size: "sm",
+    animate: false,
+  },
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars, @typescript-eslint/no-explicit-any
+  render: ({ withLayer, layer, ...args }: any) => <Loader {...args} />,
+};
+
+/**
+ * Animated — excluded from visual regression, same as `Default`; this one
+ * additionally demonstrates rendering inside a `layer={2}` context.
+ */
+export const LayerTwoOval: Story = {
+  args: {
+    variant: "oval",
+    size: "default",
+  },
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars, @typescript-eslint/no-explicit-any
+  render: ({ withLayer, layer, ...args }: any) => (
+    <Layer layer={2} style={{ padding: "24px" }}>
+      <Loader {...args} />
+    </Layer>
+  ),
+};