@recursica/adapter-mantine-v8 1.0.0

package/src/components/FileUpload/FileUpload.tsx

@@ -0,0 +1,354 @@
+import React, { forwardRef, useEffect, useRef, useState } from "react";
+import { type InputWrapperProps } from "@mantine/core";
+import {
+  filterStylingProps,
+  type RecursicaOverStyled,
+} from "../../utils/filterStylingProps";
+import { Button } from "../Button/Button";
+import { Chip } from "../Chip/Chip";
+import {
+  FormControlWrapper,
+  type RecursicaFormControlWrapperProps,
+} from "../FormControlWrapper/FormControlWrapper";
+import styles from "./FileUpload.module.css";
+
+import {
+  fileMatchesAccept,
+  type RecursicaFileUploadItem,
+  type RecursicaFileUploadProps as BaseRecursicaFileUploadProps,
+} from "@recursica/adapter-common";
+export type { RecursicaFileUploadItem };
+
+export interface RecursicaFileUploadProps
+  extends Omit<
+      React.HTMLAttributes<HTMLDivElement>,
+      "children" | "onDrop" | "onChange"
+    >,
+    Pick<
+      InputWrapperProps,
+      "label" | "error" | "required" | "withAsterisk" | "id"
+    >,
+    Omit<
+      RecursicaFormControlWrapperProps,
+      "controlMaxWidth" | "controlMinWidth"
+    >,
+    BaseRecursicaFileUploadProps {}
+
+export type FileUploadProps = RecursicaOverStyled<RecursicaFileUploadProps>;
+
+function UploadIcon() {
+  return (
+    <svg
+      xmlns="http://www.w3.org/2000/svg"
+      viewBox="0 0 24 24"
+      fill="none"
+      stroke="currentColor"
+      strokeWidth="2"
+      strokeLinecap="round"
+      strokeLinejoin="round"
+      aria-hidden
+    >
+      <path d="M12 3v12" />
+      <path d="M7 8l5-5 5 5" />
+      <path d="M4 21h16" />
+    </svg>
+  );
+}
+
+/**
+ * A dropzone for uploading files, with a native browse-button fallback and a
+ * removable-chip list of the currently selected files.
+ *
+ * @example
+ * <FileUpload
+ *   label="Upload Files"
+ *   assistiveText="Max file size 5MB"
+ *   files={files}
+ *   onFilesAdded={(added) => setFiles((f) => [...f, ...added.map((file) => ({ file }))])}
+ *   onFileRemove={(id) => setFiles((f) => f.filter((item) => (item.id ?? item.file.name) !== id))}
+ * />
+ */
+export const FileUpload = forwardRef<HTMLDivElement, FileUploadProps>(
+  function FileUpload(props, ref) {
+    const {
+      overStyled = false,
+      formLayout = "stacked",
+
+      // Label & Wrapper Maps
+      labelSize,
+      labelAlignment,
+      labelOptionalText,
+      labelWithEditIcon,
+      labelActionArea,
+      onLabelEditClick,
+
+      label,
+      assistiveText,
+      assistiveWithIcon,
+      error,
+      required,
+      withAsterisk,
+      id,
+      className,
+      style,
+      disabled,
+      readOnly,
+
+      files,
+      onFilesAdded,
+      onFileRemove,
+      accept,
+      multiple = true,
+      maxSize,
+      maxFiles,
+      onFilesRejected,
+      invalidFileTypeMessage = "File type not accepted",
+      maxFilesMessage = `Maximum of ${maxFiles} files allowed`,
+      icon,
+      dropzoneLabel = "Drag and drop files here to upload",
+      browseButtonLabel = "Browse files",
+      removeFileLabel = "Remove",
+      ...rest
+    } = props;
+
+    const sanitizedProps = filterStylingProps(rest, overStyled);
+    const restRecord = sanitizedProps as Record<string, unknown>;
+
+    const inputRef = useRef<HTMLInputElement>(null);
+
+    // Whether the most recent drop/pick attempt included a file that failed the `accept` check —
+    // surfaced as the control's error state (see `effectiveError` below) rather than left for the
+    // integrator to wire up themselves.
+    const [invalidTypeRejected, setInvalidTypeRejected] = useState(false);
+    // Whether the most recent drop/pick attempt included a file that would have pushed the total
+    // past `maxFiles` — surfaced the same way as `invalidTypeRejected` (see `effectiveError`).
+    const [tooManyFilesRejected, setTooManyFilesRejected] = useState(false);
+
+    const handleFiles = (incoming: FileList | File[]) => {
+      if (disabled) return;
+      const list = Array.from(incoming);
+      if (list.length === 0) return;
+
+      const currentCount = files?.length ?? 0;
+      const accepted: File[] = [];
+      const rejected: File[] = [];
+      let hasInvalidType = false;
+      let hasTooMany = false;
+      for (const file of list) {
+        const isInvalidType = !fileMatchesAccept(file, accept);
+        if (isInvalidType) hasInvalidType = true;
+        const isTooLarge = maxSize !== undefined && file.size > maxSize;
+        const wouldExceedMax =
+          maxFiles !== undefined && currentCount + accepted.length >= maxFiles;
+        if (wouldExceedMax) hasTooMany = true;
+        const isRejected = isInvalidType || isTooLarge || wouldExceedMax;
+        (isRejected ? rejected : accepted).push(file);
+      }
+      setInvalidTypeRejected(hasInvalidType);
+      setTooManyFilesRejected(hasTooMany);
+      if (accepted.length > 0) onFilesAdded?.(accepted);
+      if (rejected.length > 0) onFilesRejected?.(rejected);
+    };
+
+    // Counts nested dragenter/dragleave pairs (they fire for every child element the pointer
+    // crosses, not just the dropzone itself) so the drag-over visual state only clears once the
+    // pointer has actually left the dropzone, not just moved between its children.
+    const dragCounterRef = useRef(0);
+    const [isDragging, setIsDragging] = useState(false);
+
+    const handleDragEnter = (event: React.DragEvent<HTMLDivElement>) => {
+      event.preventDefault();
+      dragCounterRef.current += 1;
+      setIsDragging(true);
+    };
+
+    const handleDragLeave = (event: React.DragEvent<HTMLDivElement>) => {
+      event.preventDefault();
+      dragCounterRef.current -= 1;
+      if (dragCounterRef.current <= 0) {
+        dragCounterRef.current = 0;
+        setIsDragging(false);
+      }
+    };
+
+    const handleDragOver = (event: React.DragEvent<HTMLDivElement>) => {
+      // Required so the browser treats this element as a valid drop target.
+      event.preventDefault();
+    };
+
+    const handleDrop = (event: React.DragEvent<HTMLDivElement>) => {
+      event.preventDefault();
+      dragCounterRef.current = 0;
+      setIsDragging(false);
+      handleFiles(event.dataTransfer.files);
+    };
+
+    const openFilePicker = () => {
+      if (disabled) return;
+      inputRef.current?.click();
+    };
+
+    const handleInputChange = (event: React.ChangeEvent<HTMLInputElement>) => {
+      if (event.target.files) handleFiles(event.target.files);
+      // Reset so picking the same file again still fires a change event.
+      event.target.value = "";
+    };
+
+    // Roving tabindex across the file chip list: only the "active" chip's delete icon is a tab
+    // stop (Tab lands on the first chip), and Left/Right/Up/Down move it — see
+    // FILEUPLOAD_IMPLEMENTATION_NOTES.md.
+    const [activeChipIndex, setActiveChipIndex] = useState(0);
+    const deleteIconRefs = useRef<Array<HTMLSpanElement | null>>([]);
+    const prevFileCountRef = useRef(files?.length ?? 0);
+
+    useEffect(() => {
+      const count = files?.length ?? 0;
+      // A chip was removed (via keyboard or otherwise) — keep focus in the list, clamped to the
+      // new length, rather than letting it fall back to the document body.
+      if (count > 0 && count < prevFileCountRef.current) {
+        const nextIndex = Math.min(activeChipIndex, count - 1);
+        setActiveChipIndex(nextIndex);
+        deleteIconRefs.current[nextIndex]?.focus();
+      }
+      prevFileCountRef.current = count;
+      // Only react to the file list itself shrinking/growing, not to activeChipIndex changes.
+      // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [files]);
+
+    const handleFileListKeyDown = (
+      event: React.KeyboardEvent<HTMLDivElement>,
+    ) => {
+      const count = files?.length ?? 0;
+      if (count === 0) return;
+      let nextIndex: number | undefined;
+      if (event.key === "ArrowRight" || event.key === "ArrowDown") {
+        nextIndex = (activeChipIndex + 1) % count;
+      } else if (event.key === "ArrowLeft" || event.key === "ArrowUp") {
+        nextIndex = (activeChipIndex - 1 + count) % count;
+      }
+      if (nextIndex === undefined) return;
+      event.preventDefault();
+      setActiveChipIndex(nextIndex);
+      deleteIconRefs.current[nextIndex]?.focus();
+    };
+
+    // The built-in `accept`-mismatch message is only shown when the integrator hasn't supplied
+    // their own `error` — an explicit error always wins.
+    const effectiveError =
+      error ??
+      (invalidTypeRejected
+        ? invalidFileTypeMessage
+        : tooManyFilesRejected
+          ? maxFilesMessage
+          : undefined);
+
+    const wrapperClass = className
+      ? `${styles.layoutOverride} ${className}`
+      : styles.layoutOverride;
+
+    return (
+      <FormControlWrapper
+        overStyled={overStyled as true}
+        className={wrapperClass}
+        style={style}
+        formLayout={formLayout}
+        labelSize={labelSize}
+        labelAlignment={labelAlignment}
+        labelOptionalText={labelOptionalText}
+        labelWithEditIcon={labelWithEditIcon}
+        labelActionArea={labelActionArea}
+        onLabelEditClick={onLabelEditClick}
+        label={label}
+        assistiveText={assistiveText}
+        assistiveWithIcon={assistiveWithIcon}
+        error={effectiveError}
+        required={required}
+        withAsterisk={withAsterisk}
+        id={id}
+      >
+        <div
+          ref={ref}
+          {...restRecord}
+          className={styles.root}
+          data-disabled={disabled ? "true" : undefined}
+          data-error={effectiveError ? "true" : undefined}
+        >
+          {!readOnly && (
+            <div
+              className={styles.dropzone}
+              data-dragging={isDragging ? "true" : undefined}
+              onDragEnter={disabled ? undefined : handleDragEnter}
+              onDragLeave={disabled ? undefined : handleDragLeave}
+              onDragOver={disabled ? undefined : handleDragOver}
+              onDrop={disabled ? undefined : handleDrop}
+            >
+              <span className={styles.uploadIcon}>
+                {icon ?? <UploadIcon />}
+              </span>
+              <span className={styles.dropzoneText}>{dropzoneLabel}</span>
+              <Button
+                variant="outline"
+                disabled={disabled}
+                onClick={openFilePicker}
+              >
+                {browseButtonLabel}
+              </Button>
+              <input
+                ref={inputRef}
+                type="file"
+                hidden
+                accept={accept}
+                multiple={multiple}
+                disabled={disabled}
+                onChange={handleInputChange}
+              />
+            </div>
+          )}
+
+          {files &&
+            files.length > 0 &&
+            (readOnly ? (
+              <div className={styles.fileList}>
+                {files.map((item: RecursicaFileUploadItem) => {
+                  const itemId = item.id ?? item.file.name;
+                  return (
+                    <Chip key={itemId} checked={false} tabIndex={-1}>
+                      {item.file.name}
+                    </Chip>
+                  );
+                })}
+              </div>
+            ) : (
+              <div
+                className={styles.fileList}
+                onKeyDown={handleFileListKeyDown}
+              >
+                {files.map((item: RecursicaFileUploadItem, index) => {
+                  const itemId = item.id ?? item.file.name;
+                  return (
+                    <Chip
+                      key={itemId}
+                      checked={false}
+                      tabIndex={-1}
+                      deleteLabel={removeFileLabel}
+                      deleteTabIndex={index === activeChipIndex ? 0 : -1}
+                      deleteIconRef={(el) => {
+                        deleteIconRefs.current[index] = el;
+                      }}
+                      onDelete={
+                        disabled ? undefined : () => onFileRemove?.(itemId)
+                      }
+                    >
+                      {item.file.name}
+                    </Chip>
+                  );
+                })}
+              </div>
+            ))}
+        </div>
+      </FormControlWrapper>
+    );
+  },
+);
+
+FileUpload.displayName = "FileUpload";

package/src/components/FileUpload/USAGE.md

@@ -0,0 +1,199 @@
+# FileUpload - Usage Guide
+
+This document describes how to integrate and use the `FileUpload` component in your projects using `@recursica/adapter-mantine-v8`.
+
+---
+
+## 1. Import Reference
+
+```tsx
+import { FileUpload } from "@recursica/adapter-mantine-v8";
+```
+
+---
+
+## 2. Basic Example
+
+`FileUpload` is a **controlled** component: it never stores the selected files itself. `onFilesAdded` reports newly dropped/picked files, `onFileRemove` reports which file was removed, and you own the `files` array in between.
+
+```tsx
+import React, { useState } from "react";
+import { FileUpload } from "@recursica/adapter-mantine-v8";
+import { type RecursicaFileUploadItem } from "@recursica/adapter-common";
+
+export default function Demo() {
+  const [files, setFiles] = useState<RecursicaFileUploadItem[]>([]);
+
+  return (
+    <FileUpload
+      label="Upload Files"
+      assistiveText="Max file size 5MB"
+      files={files}
+      onFilesAdded={(added) =>
+        setFiles((prev) => [...prev, ...added.map((file) => ({ file }))])
+      }
+      onFileRemove={(id) =>
+        setFiles((prev) =>
+          prev.filter((item) => (item.id ?? item.file.name) !== id),
+        )
+      }
+    />
+  );
+}
+```
+
+---
+
+## 3. Props Reference
+
+| Prop                     | Type                        | Description                                                                                                                                                                                                                          |
+| ------------------------ | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `files`                  | `RecursicaFileUploadItem[]` | Files currently selected, rendered as removable chips below the dropzone. Each item is `{ file: File; id?: string }`.                                                                                                                |
+| `onFilesAdded`           | `(files: File[]) => void`   | Called with newly dropped/picked files. Only the new files — merge them into `files` yourself.                                                                                                                                       |
+| `onFileRemove`           | `(id: string) => void`      | Called with a file's `id` (or `file.name` if no `id` was given) when its remove (X) icon is activated.                                                                                                                               |
+| `accept`                 | `string`                    | Native `accept` attribute (e.g. `".pdf,.png"` or `"image/*"`) — constrains the picker dialog, and is also enforced against dropped files (via `onFilesRejected`), since the browser never applies `accept` to a `drop` event itself. |
+| `multiple`               | `boolean`                   | Whether more than one file can be selected/dropped at once. Defaults to `true`.                                                                                                                                                      |
+| `maxSize`                | `number`                    | Maximum size per file, in bytes. Oversized files go to `onFilesRejected` instead of `onFilesAdded`.                                                                                                                                  |
+| `maxFiles`               | `number`                    | Maximum total number of files allowed in `files`. Files that would exceed it go to `onFilesRejected` instead of `onFilesAdded`.                                                                                                      |
+| `onFilesRejected`        | `(files: File[]) => void`   | Called with files rejected for exceeding `maxSize`/`maxFiles` or not matching `accept`.                                                                                                                                              |
+| `invalidFileTypeMessage` | `React.ReactNode`           | Error message shown when a file is rejected for not matching `accept`. Defaults to `"File type not accepted"`. An explicit `error` prop always takes priority over this.                                                             |
+| `maxFilesMessage`        | `React.ReactNode`           | Error message shown when a file is rejected for exceeding `maxFiles`. Defaults to `"Maximum of {maxFiles} files allowed"`. An explicit `error` prop always takes priority over this.                                                 |
+| `icon`                   | `React.ReactNode`           | Icon shown above the dropzone label. Defaults to the built-in upload icon.                                                                                                                                                           |
+| `dropzoneLabel`          | `React.ReactNode`           | Text shown inside the dropzone. Defaults to `"Drag and drop files here to upload"`.                                                                                                                                                  |
+| `browseButtonLabel`      | `React.ReactNode`           | Label for the button that opens the native file picker. Defaults to `"Browse files"`.                                                                                                                                                |
+| `removeFileLabel`        | `string`                    | Screen-reader label for each file chip's remove button. Defaults to `"Remove"`.                                                                                                                                                      |
+| `disabled`               | `boolean`                   | Disables the dropzone, browse button, and every file chip's remove icon.                                                                                                                                                             |
+| `readOnly`               | `boolean`                   | Renders `files` as a static chip list with no remove icon, and omits the dropzone/browse button entirely.                                                                                                                            |
+
+`FileUpload` also accepts the standard Recursica form-control props (`label`, `assistiveText`, `error`, `required`, `withAsterisk`, `formLayout`, `labelSize`, `labelAlignment`, `labelOptionalText`, `labelWithEditIcon`, `onLabelEditClick`) — see [FormControlWrapper's USAGE.md](../FormControlWrapper/USAGE.md) for how these behave.
+
+---
+
+## 4. Rejecting Oversized Files
+
+```tsx
+<FileUpload
+  label="Upload Files"
+  assistiveText="Max file size 5MB"
+  maxSize={5 * 1024 * 1024}
+  files={files}
+  onFilesAdded={(added) =>
+    setFiles((prev) => [...prev, ...added.map((file) => ({ file }))])
+  }
+  onFilesRejected={(rejected) =>
+    setError(`${rejected.length} file(s) exceeded the 5MB limit.`)
+  }
+  onFileRemove={(id) =>
+    setFiles((prev) =>
+      prev.filter((item) => (item.id ?? item.file.name) !== id),
+    )
+  }
+/>
+```
+
+---
+
+## 5. Rejecting Files by Extension/MIME Type
+
+```tsx
+<FileUpload
+  label="Upload Files"
+  assistiveText="Only .pdf and .png files are accepted"
+  accept=".pdf,.png"
+  files={files}
+  onFilesAdded={(added) =>
+    setFiles((prev) => [...prev, ...added.map((file) => ({ file }))])
+  }
+  onFileRemove={(id) =>
+    setFiles((prev) =>
+      prev.filter((item) => (item.id ?? item.file.name) !== id),
+    )
+  }
+/>
+```
+
+This applies equally to a file picked via "Browse files" and one dragged directly onto the
+dropzone — the browser's own `accept` filtering never covers drag-and-drop, so `FileUpload`
+re-validates it itself before calling `onFilesAdded`/`onFilesRejected`.
+
+A mismatched file automatically puts the control into its error state with the message
+`"File type not accepted"` — no need to wire `onFilesRejected` into your own `error` prop just to
+show something. Override the message with `invalidFileTypeMessage`, or pass your own `error` prop
+to take over the error state entirely:
+
+```tsx
+<FileUpload
+  label="Upload Files"
+  accept=".pdf,.png"
+  invalidFileTypeMessage="Only PDF and PNG files are supported"
+  files={files}
+  onFilesAdded={(added) =>
+    setFiles((prev) => [...prev, ...added.map((file) => ({ file }))])
+  }
+  onFileRemove={(id) =>
+    setFiles((prev) =>
+      prev.filter((item) => (item.id ?? item.file.name) !== id),
+    )
+  }
+/>
+```
+
+---
+
+## 6. Limiting the Number of Files
+
+```tsx
+<FileUpload
+  label="Upload Files"
+  assistiveText="Up to 2 files allowed"
+  maxFiles={2}
+  files={files}
+  onFilesAdded={(added) =>
+    setFiles((prev) => [...prev, ...added.map((file) => ({ file }))])
+  }
+  onFileRemove={(id) =>
+    setFiles((prev) =>
+      prev.filter((item) => (item.id ?? item.file.name) !== id),
+    )
+  }
+/>
+```
+
+Once `files` reaches `maxFiles`, further dropped/picked files are rejected the same way an
+`accept` mismatch is — automatically switching the control into its error state with the default
+`maxFilesMessage` ("Maximum of 2 files allowed" for the example above). Override the message with
+`maxFilesMessage`, or pass your own `error` prop to take over the error state entirely.
+
+---
+
+## 7. Read-only Mode
+
+```tsx
+<FileUpload label="Uploaded Files" readOnly files={files} />
+```
+
+Renders `files` as a plain, non-removable chip list with no dropzone or Browse button — for
+displaying files that were already submitted and can no longer be changed. `onFilesAdded`/
+`onFileRemove` aren't called in this mode since there's nothing to add or remove.
+
+---
+
+## 8. Keyboard Navigation of the File List
+
+Once files are selected, their chips form a single roving-tabindex group, not one tab stop per
+chip: `Tab` lands on the first chip's remove icon, `Enter`/`Space` removes the focused chip, and
+`ArrowLeft`/`ArrowRight`/`ArrowUp`/`ArrowDown` move focus between chips (wrapping at both ends).
+This is a group-level pattern, not an option on `Chip` used standalone elsewhere. (Not applicable
+in `readOnly` mode, which has no remove icons to navigate to.)
+
+---
+
+## 9. 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**: Rogue 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/Flex/FLEX_IMPLEMENTATION_NOTES.md

@@ -0,0 +1,4 @@
+# Flex Implementation Notes
+
+The `Flex` component is a generic unopinionated flex layout wrapper mapped directly to Mantine's `Flex`.
+It currently does not require any custom logical layouts or CSS workarounds since it serves only to provide absolute, raw manipulation of standard CSS flex properties. All spacing props (gap, align, justify, direction, wrap) pass safely through via the `filterStylingProps` layout-property allowance, with `rec-` dimension tokens scaling transparently mapped to standard gap limits.

package/src/components/Flex/Flex.module.css

@@ -0,0 +1,7 @@
+/* HARDCODED VALUES:
+ * None. This is a generic flex layout wrapper.
+ */
+
+.root {
+  /* Mantine handles flex, gap, align, justify. No intrinsic design-system styles required for pure layout wrappers. */
+}

package/src/components/Flex/Flex.stories.tsx

@@ -0,0 +1,128 @@
+import React from "react";
+import type { Meta, StoryObj } from "@storybook/react";
+import { Flex } from "./Flex";
+import { Button } from "../Button";
+import { Text } from "../Text/Text";
+
+type FlexStoryProps = React.ComponentProps<typeof Flex>;
+
+const meta: Meta<FlexStoryProps> = {
+  title: "UI-Kit/Flex",
+  component: Flex,
+  tags: ["autodocs"],
+  parameters: {
+    docs: {
+      description: {
+        component:
+          "Flex is a bare-metal flex container that maps directly to Mantine's Flex component, providing unopinionated control over direction, alignment, and wrapping.",
+      },
+    },
+  },
+  args: {
+    gap: "rec-default",
+    align: "center",
+    justify: "flex-start",
+    direction: "row",
+    wrap: "wrap",
+  },
+  argTypes: {
+    gap: {
+      control: "select",
+      options: [
+        "rec-none",
+        "rec-sm",
+        "rec-default",
+        "rec-md",
+        "rec-lg",
+        "rec-xl",
+        "rec-2xl",
+        "xs",
+        "sm",
+        "md",
+        "lg",
+        "xl",
+      ],
+      description: "Gap between elements",
+    },
+    direction: {
+      control: "select",
+      options: ["row", "column", "row-reverse", "column-reverse"],
+      description: "Flex-direction property",
+    },
+    align: {
+      control: "select",
+      options: ["flex-start", "center", "flex-end", "stretch"],
+      description: "Align-items property",
+    },
+    justify: {
+      control: "select",
+      options: [
+        "flex-start",
+        "center",
+        "flex-end",
+        "space-between",
+        "space-around",
+      ],
+      description: "Justify-content property",
+    },
+    wrap: {
+      control: "select",
+      options: ["wrap", "nowrap", "wrap-reverse"],
+      description: "Flex-wrap property",
+    },
+    defaultChecked: {
+      table: { disable: true },
+    },
+    rowGap: {
+      table: { disable: true },
+    },
+    columnGap: {
+      table: { disable: true },
+    },
+  },
+};
+
+export default meta;
+
+type Story = StoryObj<FlexStoryProps>;
+
+export const Default: Story = {
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars, @typescript-eslint/no-explicit-any
+  render: ({ withLayer, layer, ...args }: any) => (
+    <Flex {...args}>
+      <Button variant="solid">Block A</Button>
+      <Button variant="outline">Block B</Button>
+      <Text>Text inside Flex</Text>
+    </Flex>
+  ),
+};
+
+export const StaticGapSmallColumn: Story = {
+  args: {
+    gap: "rec-sm",
+    direction: "column",
+  },
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars, @typescript-eslint/no-explicit-any
+  render: ({ withLayer, layer, ...args }: any) => (
+    <Flex {...args}>
+      <Button variant="solid">Item 1</Button>
+      <Button variant="solid">Item 2</Button>
+      <Button variant="solid">Item 3</Button>
+    </Flex>
+  ),
+};
+
+export const StaticGapLargeRow: Story = {
+  args: {
+    gap: "rec-xl",
+    direction: "row",
+  },
+  // eslint-disable-next-line @typescript-eslint/no-unused-vars, @typescript-eslint/no-explicit-any
+  render: ({ withLayer, layer, ...args }: any) => (
+    <Flex {...args}>
+      <Button variant="solid">Item 1</Button>
+      <Button variant="solid">Item 2</Button>
+      <Button variant="solid">Item 3</Button>
+    </Flex>
+  ),
+};