refa: improve <Container> and <Breakout> component

.changeset/kind-books-heal.md

@@ -0,0 +1,16 @@
+---
+"@marigold/docs": major
+"@marigold/components": major
+---
+
+refa: improve `<Container>` and `<Breakout>`  component
+
+**BREAKING CHANGE:** This PR includes breaking changes, because we removed and changed a lot ot the props API of `<Container>` and `<Breakout>`. The `<Container>` now only works with `<Text>` and `<Headline>` component. This allows for a smoother developer experience and prevents suprises.
+
+Make the `<Container>` and `<Breakout>` component more usable for real world scenarios.
+
+- `<Container>` supporst `space` style prop
+- simplify `<Container>` usage by removing unnecessary props
+- simplify ´<Breakout>` and make it composable with other layout components
+- make `<Text>` and `<Headline>` adhere to a `<Container>` content length
+

docs/content/components/form/slider/slider-form.demo.tsx

@@ -1,10 +1,9 @@
 import { FormEvent } from 'react';
 import {
   Button,
-  Container,
+  Center,
   FieldBase,
   FieldGroup,
-  Inline,
   Slider,
   Stack,
 } from '@marigold/components';
@@ -20,26 +19,26 @@ export default () => {
   };
 
   return (
-    <Container size={'large'}>
+    <Center>
       <Form onSubmit={handleSubmit}>
-        <FieldGroup labelWidth={'100px'}>
-          <Stack space={2}>
-            <FieldBase label="Age">
-              <Slider
-                defaultValue={[20, 30]}
-                maxValue={100}
-                thumbLabels={['start', 'end']}
-                width={60}
-              />
-            </FieldBase>
-          </Stack>
-        </FieldGroup>
-        <Inline space={4} alignX={'right'}>
+        <Stack alignX="right" space={4}>
+          <FieldGroup labelWidth={'100px'}>
+            <Stack space={2}>
+              <FieldBase label="Age">
+                <Slider
+                  defaultValue={[20, 30]}
+                  maxValue={100}
+                  thumbLabels={['start', 'end']}
+                  width={60}
+                />
+              </FieldBase>
+            </Stack>
+          </FieldGroup>
           <Button variant="primary" type="submit">
             Submit
           </Button>
-        </Inline>
+        </Stack>
       </Form>
-    </Container>
+    </Center>
   );
 };

docs/content/components/form/switch/switch-appearance.demo.tsx

@@ -1,7 +1,5 @@
-import { Container, Switch, SwitchProps } from '@marigold/components';
+import { Switch, SwitchProps } from '@marigold/components';
 
 export default (props: SwitchProps) => (
-  <Container size={'small'}>
-    <Switch {...props}>Default Switch</Switch>
-  </Container>
+  <Switch {...props}>Default Switch</Switch>
 );

docs/content/components/layout/breakout/breakout-appearance.demo.tsx

@@ -0,0 +1,32 @@
+import {
+  Aspect,
+  Breakout,
+  Container,
+  Headline,
+  Image,
+  Text,
+} from '@marigold/components';
+
+export default () => (
+  <Container align="center" alignItems="center" space={4}>
+    <Headline level="3">
+      Welcome to The Giggle Grounds - Laughville's New Comedy Hub!
+    </Headline>
+    <Breakout>
+      <Aspect ratio="ultrawide">
+        <Image src="/venues/comedy-show.webp" alt="" />
+      </Aspect>
+    </Breakout>
+    <Text>
+      Laughville, get ready to laugh! Introducing The Giggle Grounds, an outdoor
+      amphitheater for comedy under the stars. Located at 123 Main Street, this
+      venue blends natural charm with live entertainment for a perfect night
+      out. With a capacity of 500, The Giggle Grounds offers an intimate yet
+      lively experience, ideal for enjoying top comedians in an open-air
+      setting. Pricing ranges from $1000 to $5000, making it flexible for
+      various events and budgets. Join us at The Giggle Grounds for an
+      unforgettable comedy experience! For bookings or more information, visit
+      us at 123 Main Street, Laughville.
+    </Text>
+  </Container>
+);

docs/content/components/layout/breakout/breakout-complex.demo.tsx

@@ -0,0 +1,44 @@
+import {
+  Aspect,
+  Breakout,
+  Container,
+  Headline,
+  Image,
+  Inline,
+  Text,
+} from '@marigold/components';
+
+export default () => (
+  <Container space={6} align="center">
+    <Headline level="2">Upcoming Shows at The Guffaw Gardens</Headline>
+    <Breakout>
+      <Inline space={4} alignY="center" alignX="center">
+        <Aspect maxWidth="200px">
+          <Image src="/venues/petal-punchlines.webp" alt="" />
+        </Aspect>
+        <Aspect maxWidth="200px">
+          <Image src="/venues/chuckles-and-chill.webp" alt="" />
+        </Aspect>
+        <Aspect maxWidth="200px">
+          <Image src="/venues/botanical-banter.webp" alt="" />
+        </Aspect>
+      </Inline>
+    </Breakout>
+    <Text>
+      Get ready for a season of laughter at The Guffaw Gardens! This spring,
+      don't miss the Laugh Bloom Festival, featuring some of the best names in
+      comedy.
+    </Text>
+    <Text>
+      On May 5th, The Petal Punchlines will be hosted by comedian Rosie Petals,
+      known for her sharp wit. On May 12th, Chuckles & Chill will bring a
+      relaxed evening of comedy with Ivy Green and Marv "The Bloom" Thompson.
+      Finish the month with Botanical Banter on May 26th, headlined by Daisy
+      Bloom and Fern Tickles, promising a night full of laughs.
+    </Text>
+    <Text>
+      Whether with friends or for a special night out, The Guffaw Gardens is the
+      place to be for comedy and nature this season.
+    </Text>
+  </Container>
+);

docs/content/components/layout/breakout/breakout.mdx

@@ -1,40 +1,57 @@
 ---
 title: Breakout
-caption: Component that breaks out of a grid layout context.
+caption: When you need to break out of a grid layout.
+badge: updated
 ---
 
-`<Breakout>` is a layout component which lets you span the full row in a CSS grid context e.g. our [`<Container>`](container/) component.
+The `<Breakout>` component is designed to help elements break out of their current container layout, creating visual interest and giving content the space it needs to stand out. Combine `<Breakout>` with the `<Container>` component to maintain a cohesive design while effectively drawing attention to important elements.
 
-You need this component if you want to display something out of the context. It is also possible to put several components into the `<Breakout>`.
+## Usage
 
-You can use `alignX` or `alignY` to place the items inside the `<Breakout>` element.
+Use the `<Breakout>` component when you need elements to break out of their current container layout, adding visual interest and giving content the space it needs to stand out.
 
-## Import
+It is particularly useful for situations where extra emphasis is needed or when you want to create a more dynamic and engaging reading experience. `<Breakout>` is ideal for highlighting media elements or other key content.
 
-```tsx
-import { Breakout } from '@marigold/components';
-```
+<ComponentDemo file="./breakout-appearance.demo.tsx" />
 
-## Props
-
-<PropsTable component={title} />
-
-## Examples
+### Complex layouts
 
-### Vertical alignment
+You can create more complex layouts within the `<Breakout>` component by combining it with other layout components. By nesting `<Inline>`, `<Stack>`, or `<Columns>` inside `<Breakout>`, you can design advanced, responsive structures that go beyond simple content.
 
-In this case the `height` prop is necessary, if you haven't set it, the `alignY` has no impact.
+Note that the `<Text>` component will still adhere to the content length defined by the `<Container>`.
 
-<ComponentDemo file="./vertical-breakout.demo.tsx" />
+<ComponentDemo file="./breakout-complex.demo.tsx" />
 
-### Horizontal alignment
-
-Example to show how the `alignX` prop is to set. Options are `"left" | "center" | "right"`. The default value is `left`.
-
-<ComponentDemo file="./horizontal-breakout.demo.tsx" />
+## Props
 
-### Breakout iframe
+<StorybookHintMessage component={title} />
 
-This example shows how to use an `<iframe>` within a `<Breakout>`.
+<PropsTable component={title} />
 
-<ComponentDemo file="./iframe-breakout.demo.tsx" />
+## Related
+
+<TeaserList
+  items={[
+    {
+      title: 'Building layouts',
+      href: '../../foundations/layouts',
+      caption: 'Learn how to build layouts.',
+      icon: (
+        <svg
+          xmlns="http://www.w3.org/2000/svg"
+          fill="none"
+          viewBox="0 0 24 24"
+          strokeWidth={1.5}
+          stroke="currentColor"
+          className="size-6"
+        >
+          <path
+            strokeLinecap="round"
+            strokeLinejoin="round"
+            d="M2.25 7.125C2.25 6.504 2.754 6 3.375 6h6c.621 0 1.125.504 1.125 1.125v3.75c0 .621-.504 1.125-1.125 1.125h-6a1.125 1.125 0 0 1-1.125-1.125v-3.75ZM14.25 8.625c0-.621.504-1.125 1.125-1.125h5.25c.621 0 1.125.504 1.125 1.125v8.25c0 .621-.504 1.125-1.125 1.125h-5.25a1.125 1.125 0 0 1-1.125-1.125v-8.25ZM3.75 16.125c0-.621.504-1.125 1.125-1.125h5.25c.621 0 1.125.504 1.125 1.125v2.25c0 .621-.504 1.125-1.125 1.125h-5.25a1.125 1.125 0 0 1-1.125-1.125v-2.25Z"
+          />
+        </svg>
+      ),
+    },
+  ]}
+/>

docs/content/components/layout/container/container-alignment.demo.tsx

@@ -0,0 +1,36 @@
+import { Aspect, Container, Headline, Image, Text } from '@marigold/components';
+
+export default () => (
+  <Container space={4} contentLength="short" align="center" alignItems="center">
+    <Headline level="3">Taking care of Marigolds</Headline>
+    <Aspect maxWidth="250px" ratio="ultrawide">
+      <Image
+        src="/marigold-watering.webp"
+        alt="Watering a marigold flower"
+        fit="cover"
+      />
+    </Aspect>
+    <Text>
+      Caring for marigold flowers is straightforward, making them a popular
+      choice for many gardeners. Marigolds thrive best in full sunlight, so make
+      sure to plant them in a spot that receives at least six hours of direct
+      sunlight every day. They grow well in a variety of soils but prefer
+      well-drained, moderately fertile soil. Be sure to space them adequately,
+      as proper air circulation helps prevent disease.
+    </Text>
+    <Text>
+      Watering marigolds requires balance. They do best when their soil is kept
+      slightly moist but not overly wet. Water the plants deeply when the top
+      inch of soil feels dry, but avoid watering directly onto the flowers and
+      leaves to prevent mold and mildew. Mulching around the base can help
+      retain moisture and minimize weeds.
+    </Text>
+    <Text>
+      Deadheading, or removing spent flowers, will encourage marigolds to bloom
+      more vigorously. This not only keeps the plants looking tidy but also
+      redirects energy into producing new blooms. With proper sunlight,
+      watering, and a bit of pruning, marigold flowers can bring vibrant color
+      to your garden all season long.
+    </Text>
+  </Container>
+);

docs/content/components/layout/container/container-appearance.demo.tsx

@@ -0,0 +1,18 @@
+import { Container, Headline, Text } from '@marigold/components';
+
+export default () => (
+  <Container>
+    <Headline level="3">The marigold flower</Headline>
+    <Text>
+      The marigold flower, known for its bright orange and yellow hues, is more
+      than just a vibrant addition to gardens. Marigolds have been used for
+      centuries in traditional medicine for their anti-inflammatory properties.
+      In many cultures, they symbolize positive emotions like warmth and
+      creativity, and are often used in festivals and celebrations. The marigold
+      is also known for its ability to deter garden pests, making it a favorite
+      companion plant for vegetables. Beyond their beauty, these flowers play a
+      role in pollinator gardens, attracting bees and butterflies to enhance
+      biodiversity.
+    </Text>
+  </Container>
+);

docs/content/components/layout/container/container-complex.demo.tsx

@@ -0,0 +1,34 @@
+import { Columns, Container, Headline, Text } from '@marigold/components';
+
+export default () => (
+  <Container space={6} align="center" alignItems="center">
+    <Headline level="3">Sunny the marigold</Headline>
+    <Columns columns={[1, 1]} space={8}>
+      <Text>
+        In a cozy garden behind an old cottage, a marigold named Sunny grew
+        among daisies and tulips. Her petals were vibrant, glowing in deep
+        shades of orange and yellow. She loved feeling the warmth of the sun as
+        it touched her petals, and she enjoyed the company of her fellow
+        flowers. Butterflies would often visit her, and she would sway gently in
+        the breeze, feeling a sense of peace. Despite all of this, Sunny
+        sometimes felt small compared to the tall sunflowers nearby. They seemed
+        grand, while she was just a splash of color in the corner.
+      </Text>
+      <Text>
+        One morning, a little girl named Emma, who lived in the cottage,
+        wandered into the garden feeling sad. Her best friend had moved away,
+        and she needed comfort. When she saw Sunny's glowing petals, Emma smiled
+        for the first time in days. She knelt beside Sunny, touched her petals,
+        and whispered, "You're beautiful." Emma made a small bouquet with Sunny
+        at the center, finding a bit of joy even in her sadness.
+      </Text>
+    </Columns>
+    <Text>
+      After that day, Sunny understood her purpose. It wasn't about being the
+      biggest flower, but about bringing light to others. She had made Emma
+      smile, and that was more important than anything else. Sunny stood tall,
+      proud of her role in the garden—a reminder that even the smallest flowers
+      can have the biggest impact.
+    </Text>
+  </Container>
+);