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 = { + title: 'General/Layout/Stack', + component: Stack, + decorators: [withCenteredStory], + parameters: { + docs: { + page: mdx, + }, + }, +}; + +const Item = ({ children }: { children: ReactNode }) => ( +
{children}
+); + +export const Basic: StoryFn = ({ direction = 'column', gap = 2 }) => { + return ( + + Item 1 + Item 2 + Item 3 + + ); +}; + +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'; + + + +# 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. + + 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) => { + return ( + + {children} + + ); +}; 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';