From a9dc16625d25d45c0ae99ca28e8f22b3e0b63f43 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Julien=20D=C3=A9ramond?= <julien.deramond@orange.com>
Date: Wed, 7 Aug 2024 08:12:12 +0200
Subject: [PATCH] docs(helpers): add 'Stacks' page

---
 site/content/docs/0.0/helpers/stacks.md | 85 ++++++++++++++++++++++++-
 site/data/sidebar.yml                   |  1 -
 2 files changed, 84 insertions(+), 2 deletions(-)

diff --git a/site/content/docs/0.0/helpers/stacks.md b/site/content/docs/0.0/helpers/stacks.md
index 834fc7390c..d80d4cbe9b 100644
--- a/site/content/docs/0.0/helpers/stacks.md
+++ b/site/content/docs/0.0/helpers/stacks.md
@@ -8,4 +8,87 @@ aliases:
 toc: true
 ---
 
-{{< callout-soon "helper" >}}
+Stacks offer a shortcut for applying a number of flexbox properties to quickly and easily create layouts in OUDS Web. All credit for the concept and implementation goes to the open source [Pylon project](https://almonk.github.io/pylon/).
+
+{{< callout warning >}}
+**Heads up!** Support for gap utilities with flexbox was recently added to Safari, so consider verifying your intended browser support. Grid layout should have no issues. [Read more](https://caniuse.com/flexbox-gap).
+{{< /callout >}}
+
+## Vertical
+
+Use `.vstack` to create vertical layouts. Stacked items are full-width by default. Use `.gap-*` utilities to add space between items.
+
+{{< example class="bd-example-flex" >}}
+<div class="vstack gap-3">
+  <div class="p-2">First item</div>
+  <div class="p-2">Second item</div>
+  <div class="p-2">Third item</div>
+</div>
+{{< /example >}}
+
+## Horizontal
+
+Use `.hstack` for horizontal layouts. Stacked items are vertically centered by default and only take up their necessary width. Use `.gap-*` utilities to add space between items.
+
+{{< example class="bd-example-flex" >}}
+<div class="hstack gap-3">
+  <div class="p-2">First item</div>
+  <div class="p-2">Second item</div>
+  <div class="p-2">Third item</div>
+</div>
+{{< /example >}}
+
+Using horizontal margin utilities like `.ms-auto` as spacers:
+
+{{< example class="bd-example-flex" >}}
+<div class="hstack gap-3">
+  <div class="p-2">First item</div>
+  <div class="p-2 ms-auto">Second item</div>
+  <div class="p-2">Third item</div>
+</div>
+{{< /example >}}
+
+<!--And with [vertical rules]({{< docsref "/helpers/vertical-rule" >}}):
+
+{{< example class="bd-example-flex" >}}
+<div class="hstack gap-3">
+  <div class="p-2">First item</div>
+  <div class="p-2 ms-auto">Second item</div>
+  <div class="vr"></div>
+  <div class="p-2">Third item</div>
+</div>
+{{< /example >}}-->
+
+<!--## Examples
+
+Use `.vstack` to stack buttons and other elements:
+
+{{< example >}}
+<div class="vstack gap-2 col-md-5 mx-auto">
+  <button type="button" class="btn btn-primary">Save changes</button>
+  <button type="button" class="btn btn-outline-secondary">Cancel</button>
+</div>
+{{< /example >}}
+
+Create an inline form with `.hstack`:
+
+<details>
+<summary>See Bootstrap examples that are incompatible with Orange Design System.</summary>
+<br>
+{{< design-callout-alert >}}
+This variant with an **horizontal layout** (i.e. labels not above the input fields) should not be used because it does not respect the Orange Design System specifications.
+{{< /design-callout-alert >}}
+
+{{< example >}}
+<div class="hstack gap-3">
+  <input class="form-control me-auto" type="text" placeholder="Add your item here..." aria-label="Add your item here...">
+  <button type="button" class="btn btn-primary">Submit</button>
+  <div class="vr"></div>
+  <button type="button" class="btn btn-outline-secondary">Reset</button>
+</div>
+{{< /example >}}
+</details>-->
+
+## CSS
+
+{{< scss-docs name="stacks" file="scss/helpers/_stacks.scss" >}}
diff --git a/site/data/sidebar.yml b/site/data/sidebar.yml
index faa6c29e63..d7c1203e64 100644
--- a/site/data/sidebar.yml
+++ b/site/data/sidebar.yml
@@ -196,7 +196,6 @@
     - title: Ratio
       draft: true
     - title: Stacks
-      draft: true
     - title: Stretched link
       draft: true
     - title: Text truncation