From 43be03a2d85f31e5c77f89fda496375798b63a24 Mon Sep 17 00:00:00 2001
From: Tobias Skarhed <1438972+tskarhed@users.noreply.github.com>
Date: Tue, 29 Aug 2023 13:59:13 +0200
Subject: [PATCH] Grafana UI: Stack component (#73593)

* Add Stack component and sotry

* Add item

* Add MDX and story

* Add forwardRef

* Add usage instructions

* Remove story

* Update docs

* Add unstable export

* Fix story

* Update default values and mdx

* Change export
---
 .../components/Stack/Stack.internal.story.tsx | 34 +++++++++++++++++++
 .../grafana-ui/src/components/Stack/Stack.mdx | 34 +++++++++++++++++++
 .../grafana-ui/src/components/Stack/Stack.tsx | 18 ++++++++++
 packages/grafana-ui/src/unstable.ts           |  2 ++
 4 files changed, 88 insertions(+)
 create mode 100644 packages/grafana-ui/src/components/Stack/Stack.internal.story.tsx
 create mode 100644 packages/grafana-ui/src/components/Stack/Stack.mdx
 create mode 100644 packages/grafana-ui/src/components/Stack/Stack.tsx

diff --git a/packages/grafana-ui/src/components/Stack/Stack.internal.story.tsx b/packages/grafana-ui/src/components/Stack/Stack.internal.story.tsx
new file mode 100644
index 00000000000..820aeed700d
--- /dev/null
+++ b/packages/grafana-ui/src/components/Stack/Stack.internal.story.tsx
@@ -0,0 +1,34 @@
+import { Meta, StoryFn } from '@storybook/react';
+import React, { ReactNode } from 'react';
+
+import { withCenteredStory } from '../../utils/storybook/withCenteredStory';
+
+import { Stack } from './Stack';
+import mdx from './Stack.mdx';
+
+const meta: Meta<typeof Stack> = {
+  title: 'General/Layout/Stack',
+  component: Stack,
+  decorators: [withCenteredStory],
+  parameters: {
+    docs: {
+      page: mdx,
+    },
+  },
+};
+
+const Item = ({ children }: { children: ReactNode }) => (
+  <div style={{ backgroundColor: 'lightgrey', width: '100px', height: '50px' }}>{children}</div>
+);
+
+export const Basic: StoryFn<typeof Stack> = ({ direction = 'column', gap = 2 }) => {
+  return (
+    <Stack direction={direction} gap={gap}>
+      <Item>Item 1</Item>
+      <Item>Item 2</Item>
+      <Item>Item 3</Item>
+    </Stack>
+  );
+};
+
+export default meta;
diff --git a/packages/grafana-ui/src/components/Stack/Stack.mdx b/packages/grafana-ui/src/components/Stack/Stack.mdx
new file mode 100644
index 00000000000..a956ea5eb5e
--- /dev/null
+++ b/packages/grafana-ui/src/components/Stack/Stack.mdx
@@ -0,0 +1,34 @@
+import { Meta, ArgTypes, Canvas } from '@storybook/blocks';
+import { Stack } from './Stack';
+import * as Stories from './Stack.internal.story';
+
+<Meta title="MDX|Stack" component={Stack} />
+
+# Stack
+
+The `Stack` component is designed to assist with layout and positioning of elements within a container, offering a simple and flexible way to stack elements vertically or horizontally. This documentation outlines the proper usage of the Stack component and provides guidance on when to use it over the Grid or Flex components.
+
+### Usage
+
+#### When to use
+
+Use the Stack component when you need to arrange elements in a linear format, either vertically or horizontally. It's particularly useful when you want to maintain consistent spacing between items.
+
+Use the Stack component when:
+
+- You need a simple way to stack elements with predictable spacing.
+- You want to ensure consistent alignment.
+
+#### When not to use
+
+Use the `Grid` component instead for these use cases:
+
+- **Intricate Layouts:** Grids are ideal for complex dashboard and magazine-style designs with rows and columns.
+- **Structured Grid:** Use Grids when items need to span multiple rows/columns, creating structured layouts.
+
+Use the `Flex` component instead for these use cases:
+
+- **Centering:** Perfect for centering elements both vertically and horizontally.
+- **Dynamic Order:** Easily reorder elements for responsive layouts without changing code.
+
+<ArgTypes of={Stack} />
diff --git a/packages/grafana-ui/src/components/Stack/Stack.tsx b/packages/grafana-ui/src/components/Stack/Stack.tsx
new file mode 100644
index 00000000000..c2b0120568c
--- /dev/null
+++ b/packages/grafana-ui/src/components/Stack/Stack.tsx
@@ -0,0 +1,18 @@
+import React from 'react';
+
+import { ThemeSpacingTokens } from '@grafana/data';
+
+import { Direction, Flex } from '../Flex/Flex';
+
+interface StackProps {
+  direction?: Direction;
+  gap?: ThemeSpacingTokens;
+}
+
+export const Stack = ({ gap = 1, direction = 'column', children }: React.PropsWithChildren<StackProps>) => {
+  return (
+    <Flex gap={gap} direction={direction}>
+      {children}
+    </Flex>
+  );
+};
diff --git a/packages/grafana-ui/src/unstable.ts b/packages/grafana-ui/src/unstable.ts
index f882d5a8a34..f1a9f2aac04 100644
--- a/packages/grafana-ui/src/unstable.ts
+++ b/packages/grafana-ui/src/unstable.ts
@@ -10,3 +10,5 @@
  */
 
 export * from './components/Flex/Flex';
+
+export { Stack } from './components/Stack/Stack';