From 0cbed993118d72ddaa5cb5638a1328a9eb886d36 Mon Sep 17 00:00:00 2001
From: upsiflu <upsiflu@gmail.com>
Date: Fri, 20 Dec 2024 00:30:46 +0100
Subject: [PATCH] feat(ui-docs): improve layout documentation

---
 front/ui-docs/components/ui/layout.md         | 265 ++++--------------
 front/ui-docs/components/ui/layout/columns.md | 101 +++++++
 front/ui-docs/components/ui/layout/flex.md    |  58 ++++
 front/ui-docs/components/ui/layout/grid.md    |  78 ++++++
 front/ui-docs/components/ui/layout/stack.md   |  45 +++
 5 files changed, 343 insertions(+), 204 deletions(-)
 create mode 100644 front/ui-docs/components/ui/layout/columns.md
 create mode 100644 front/ui-docs/components/ui/layout/flex.md
 create mode 100644 front/ui-docs/components/ui/layout/grid.md
 create mode 100644 front/ui-docs/components/ui/layout/stack.md

diff --git a/front/ui-docs/components/ui/layout.md b/front/ui-docs/components/ui/layout.md
index 38ca0eca7..78d8d712f 100644
--- a/front/ui-docs/components/ui/layout.md
+++ b/front/ui-docs/components/ui/layout.md
@@ -1,4 +1,4 @@
-<script setup lang="ts">
+<script setup>
 import { ref } from 'vue'
 
 import Card from '~/components/ui/Card.vue'
@@ -18,214 +18,35 @@ const noGap = ref(true)
 
 The following containers are responsive. Change your window's size or select a device preset from your browser's dev tools to see how layouts are affected by available space.
 
-<Tabs class="solid" style="border: 32px solid var(--background-color);border-radius: 8px;outline: 1px solid var(--border-color);margin: 0 -32px;">
-<Tab title="Flex (default)" icon="⠖">
-
-Items are laid out in a row and wrapped as they overflow the container.
-By default, all items in a row assume the same (maximum) height.
-
-```vue-html
-<Layout flex>
-  <Card title="A" style="width:100px; min-width:100px"></Card>
-  <Card title="B" :tags="['funk', 'dunk', 'punk']"></Card>
-  <Card title="C" style="width:100px; min-width:100px"></Card>
-  <Card title="D"></Card>
-</Layout>
-```
-
-<div class="preview">
-<Layout flex>
-  <Card title="A" style="width:100px; min-width:100px"></Card>
-  <Card title="B" :tags="['funk', 'dunk', 'punk']"></Card>
-  <Card title="C" style="width:100px; min-width:100px"></Card>
-  <Card title="D"></Card>
-</Layout>
-</div>
-
-::: info Use additional `flexbox` properties
-
-Find a list of all styles here: [Flexbox guide on css-tricks.com](https://css-tricks.com/snippets/css/a-guide-to-flexbox/)
-
-<Layout flex>
-  <div class="preview" style="font-size:11px; font-weight:bold; mix-blend-mode:luminosity;">
-    <Layout flex style="--gap: 4px;"> --gap: 4px
-      <Alert red style="align-self: flex-end">align-self: flex-end</Alert>
-      <Alert red style="flex-grow: 1">flex-grow: 1</Alert>
-      <Alert red style="height: 5rem;">height: 5rem</Alert>
-      <Alert red style="width: 100%">width: 100%</Alert>
+<Layout grid="auto / repeat(auto-fit, minmax(min-content, 163px))" style="--gap:8px">
+  <Card auto title="flex" to="layout/flex" >
+    <Layout flex>
+      <Button primary icon="bi-eye" />
+      <Button secondary icon="bi-eye" />
+      <Button destructive icon="bi-eye" />
     </Layout>
-  </div>
-</Layout>
-
-:::
-
-</Tab>
-<Tab title="Grid" icon="ꖛ">
-
-Align items both vertically and horizontally
-
-##### Override the `:column-width` (in px):
-
-<Layout flex>
-
-```vue-html{1}
-<Layout grid :column-width=90>
-  <Alert>A</Alert>
-  <Alert>B</Alert>
-  ...
-</Layout>
-```
-
-<Layout grid :column-width="90" class="preview" :style="`width:${2 * 90 + 32}px`">
-  <Alert>A</Alert>
-  <Alert>B</Alert>
-  <Alert>C</Alert>
-  <Alert>D</Alert>
-  <Alert>E</Alert>
-  <Alert>F</Alert>
-  <Alert>G</Alert>
-</Layout>
-
-</Layout>
-
-##### Let elements span multiple rows or columns:
-
-```vue-html{2,4}
-<Layout grid>
-  <Card title="A" class="span-2-columns"></Card>
-  <Card title="B"></Card>
-  <Card title="C" class="span-2-rows"></Card>
-  <Card title="D"></Card>
-</Layout>
-```
-
-<Layout grid>
-  <Card title="A" class="span-2-columns">
-
-    ```vue
-    <Card class="span-2-columns"></Card>
-    ```
-
   </Card>
-  <Card title="B"></Card>
-  <Card title="C" class="span-2-rows">
-
-    ```vue
-    <Card class="span-2-rows"></Card>
-    ```
-
+  <Card auto title="grid" to="layout/grid" >
+    <Layout grid column-width="40">
+      <Button primary icon="bi-eye" />
+      <Button secondary icon="bi-eye" style="grid-row: span 2; height: 100%;"  />
+      <Button destructive icon="bi-eye" />
+    </Layout>
   </Card>
-  <Card title="D"></Card>
+  <Card auto title="stack" to="layout/stack" >
+    <Layout stack style="--gap:0; margin:-8px;">
+      <Button primary icon="bi-eye" />
+      <Button secondary icon="bi-eye" />
+      <Button destructive icon="bi-eye" />
+    </Layout></Card>
+  <Card auto title="columns" to="layout/columns" >
+    <Layout columns column-width="40">
+      <Button primary icon="bi-eye" />
+      <Button secondary icon="bi-eye" />
+      <Button destructive icon="bi-eye" />
+    </Layout></Card>
 </Layout>
 
-</Tab>
-
-<Tab title="Stack" icon="𝌆">
-
-Add space between vertically stacked items
-
-<Layout flex>
-
-```vue-html
-<Layout stack>
-  <Card title="A"></Card>
-  <Card title="B"></Card>
-  <Card title="C"></Card>
-  <Card title="D"></Card>
-  <Card title="E"></Card>
-</Layout>
-```
-
-<div class="preview">
-<Layout stack>
-  <Card title="A"></Card>
-  <Card title="B"></Card>
-  <Card title="C"></Card>
-  <Card title="D"></Card>
-  <Card title="E"></Card>
-</Layout>
-</div>
-
-</Layout>
-
-</Tab>
-
-<Tab title="Columns" icon="𝌆">
-
-Let items flow like words on a printed newspaper, Great for very long lists of buttons or links.
-
-<Layout stack no-gap>
-
-```vue-html
-<Layout columns :column-width="120">
-  <Button icon="bi-star"/>
-  <Button icon="bi-star"/>
-  <Button icon="bi-star"/>
-
-Normal paragraph. Text flows like in a newspaper. Set the column width in px. Columns will be equally distributed over the width of the container.
-
-  <Card small title="Cards...">...break over columns...</Card>
-
-  <Button icon="bi-star"/>
-  <Button icon="bi-star"/>
-  <Button icon="bi-star"/>
-</Layout>
-```
-
-<div class="preview">
-<Layout columns :column-width="120">
-  <Button icon="bi-star"/>
-  <Button icon="bi-star"/>
-  <Button icon="bi-star"/>
-
----
-
-Normal paragraph. Text flows like in a newspaper. Set the column width in px. Columns will be equally distributed over the width of the container.
-
----
-
-<Card small title="Cards...">...break over columns...</Card>
-
----
-
-  <Button icon="bi-star"/>
-  <Button icon="bi-star"/>
-  <Button icon="bi-star"/>
-</Layout>
-</div>
-
-</Layout>
-
-### `no-rule`: Remove the rule (thin line) between columns
-
-<Layout grid>
-
-```vue-html
-<Layout columns colummn-width>
-  <div>Lorem ipsum dolor sit amet.</div>
-</Layout>
-
-<Layout columns no-rule>
-  <div>Lorem ipsum dolor sit amet.</div>
-</Layout>
-```
-
-<Layout class="preview">
-  <Layout columns :column-width="120">
-    <div>Lorem ipsum dolor sit amet.</div>
-  </Layout>
-
-  <Layout columns no-rule :column-width="120">
-    <div>Lorem ipsum dolor sit amet.</div>
-  </Layout>
-</Layout>
-
-</Layout>
-
-</Tab>
-
-</Tabs>
-
 ## Common props
 
 ### `no-gap`: Remove the gap between items
@@ -346,3 +167,39 @@ Note that you can set the minimum space occupied by the `Spacer` with its `size`
 </div>
 
 </Layout>
+
+---
+
+<Tabs class="solid" style="border: 32px solid var(--background-color);border-radius: 8px;outline: 1px solid var(--border-color);margin: 0 -32px;">
+<Tab title="Flex (default)" icon="⠖">
+
+Items are laid out in a row and wrapped as they overflow the container
+
+[Layout flex](./layout/flex)
+
+</Tab>
+<Tab title="Grid" icon="ꖛ">
+
+Align items both vertically and horizontally
+
+[Layout grid](./layout/grid)
+
+</Tab>
+
+<Tab title="Stack" icon="𝌆">
+
+Add space between vertically stacked items
+
+[Layout stack](./layout/stack)
+
+</Tab>
+
+<Tab title="Columns" icon="ꔖ">
+
+Let text and items flow like on a printed newspaper
+
+[Layout columns](./layout/columns)
+
+</Tab>
+
+</Tabs>
diff --git a/front/ui-docs/components/ui/layout/columns.md b/front/ui-docs/components/ui/layout/columns.md
new file mode 100644
index 000000000..3b6a84faf
--- /dev/null
+++ b/front/ui-docs/components/ui/layout/columns.md
@@ -0,0 +1,101 @@
+<script setup>
+import { ref } from 'vue'
+
+import Card from '~/components/ui/Card.vue'
+import Alert from '~/components/ui/Alert.vue'
+import Layout from '~/components/ui/Layout.vue'
+import Spacer from '~/components/ui/layout/Spacer.vue'
+import Tab from '~/components/ui/Tab.vue'
+import Tabs from '~/components/ui/Tabs.vue'
+import Toggle from '~/components/ui/Toggle.vue'
+import Button from '~/components/ui/Button.vue'
+
+const isGrowing = ref(true)
+const noGap = ref(true)
+</script>
+
+🡔 [Layout](../layout)
+
+# Layout `columns`
+
+Let items flow like words on a printed newspaper, Great for very long lists of buttons or links.
+
+<Layout stack no-gap>
+
+```vue-html
+<Layout columns :column-width="120">
+  <Button icon="bi-star"/>
+  <Button icon="bi-star"/>
+  <Button icon="bi-star"/>
+
+Normal paragraph. Text flows like in a newspaper. Set the column width in px. Columns will be equally distributed over the width of the container.
+
+  <Card small title="Cards...">...break over columns...</Card>
+
+  <Button icon="bi-star"/>
+  <Button icon="bi-star"/>
+  <Button icon="bi-star"/>
+</Layout>
+```
+
+<div class="preview">
+<Layout columns :column-width="120">
+  <Button icon="bi-star"/>
+  <Button icon="bi-star"/>
+  <Button icon="bi-star"/>
+
+---
+
+Normal paragraph. Text flows like in a newspaper. Set the column width in px. Columns will be equally distributed over the width of the container.
+
+---
+
+<Card small title="Cards...">...break over columns...</Card>
+
+---
+
+  <Button icon="bi-star"/>
+  <Button icon="bi-star"/>
+  <Button icon="bi-star"/>
+</Layout>
+</div>
+
+</Layout>
+
+Make sure that all elements fit the column width, else they will leak into the neighboring columns.
+
+### `no-rule`: Remove the rule (thin line) between columns
+
+<Layout grid>
+
+```vue-html
+<Layout columns :colummn-width="50">
+  <div>Lorem ipsum dolor sit amet.</div>
+</Layout>
+
+<Layout columns :colummn-width="50" no-rule>
+  <div>Lorem ipsum dolor sit amet.</div>
+</Layout>
+```
+
+<Layout class="preview">
+  <Layout columns :column-width="40">
+    <div>Lorem ipsum dolor sit amet.</div>
+  </Layout>
+
+  <Layout columns no-rule :column-width="40">
+    <div>Lorem ipsum dolor sit amet.</div>
+  </Layout>
+</Layout>
+
+</Layout>
+
+### Tricks
+
+#### Prevent column breaks
+
+Add the following style to the element that you want to preserve whole:
+
+```css
+style="break-inside: avoid;"
+```
diff --git a/front/ui-docs/components/ui/layout/flex.md b/front/ui-docs/components/ui/layout/flex.md
new file mode 100644
index 000000000..fbd8149ce
--- /dev/null
+++ b/front/ui-docs/components/ui/layout/flex.md
@@ -0,0 +1,58 @@
+<script setup>
+import { ref } from 'vue'
+
+import Card from '~/components/ui/Card.vue'
+import Alert from '~/components/ui/Alert.vue'
+import Layout from '~/components/ui/Layout.vue'
+import Spacer from '~/components/ui/layout/Spacer.vue'
+import Tab from '~/components/ui/Tab.vue'
+import Tabs from '~/components/ui/Tabs.vue'
+import Toggle from '~/components/ui/Toggle.vue'
+import Button from '~/components/ui/Button.vue'
+
+const isGrowing = ref(true)
+const noGap = ref(true)
+</script>
+
+🡔 [Layout](../layout)
+
+# Layout `flex`
+
+Items are laid out in a row and wrapped as they overflow the container.
+By default, all items in a row assume the same (maximum) height.
+
+```vue-html
+<Layout flex>
+  <Card title="A" style="width:100px; min-width:100px"></Card>
+  <Card title="B" :tags="['funk', 'dunk', 'punk']"></Card>
+  <Card title="C" style="width:100px; min-width:100px"></Card>
+  <Card title="D"></Card>
+</Layout>
+```
+
+<div class="preview">
+<Layout flex>
+  <Card title="A" style="width:100px; min-width:100px"></Card>
+  <Card title="B" :tags="['funk', 'dunk', 'punk']"></Card>
+  <Card title="C" style="width:100px; min-width:100px"></Card>
+  <Card title="D"></Card>
+</Layout>
+</div>
+
+## Use additional `flexbox` properties
+
+<Layout flex
+class="preview"
+style="font-size:11px; font-weight:bold; --gap: 4px;"
+
+>
+
+--gap: 4px
+
+<Alert red style="align-self: flex-end;">align-self: flex-end</Alert>
+<Alert green style="flex-grow: 1;">flex-grow: 1</Alert>
+<Alert yellow style="height: 5rem;">height: 5rem</Alert>
+<Alert purple style="width: 100%;">width: 100%</Alert>
+</Layout>
+
+Find a list of all styles here: [Flexbox guide on css-tricks](https://css-tricks.com/snippets/css/a-guide-to-flexbox/).
diff --git a/front/ui-docs/components/ui/layout/grid.md b/front/ui-docs/components/ui/layout/grid.md
new file mode 100644
index 000000000..98930ff40
--- /dev/null
+++ b/front/ui-docs/components/ui/layout/grid.md
@@ -0,0 +1,78 @@
+<script setup>
+import { ref } from 'vue'
+
+import Card from '~/components/ui/Card.vue'
+import Alert from '~/components/ui/Alert.vue'
+import Layout from '~/components/ui/Layout.vue'
+import Spacer from '~/components/ui/layout/Spacer.vue'
+import Tab from '~/components/ui/Tab.vue'
+import Tabs from '~/components/ui/Tabs.vue'
+import Toggle from '~/components/ui/Toggle.vue'
+import Button from '~/components/ui/Button.vue'
+
+const isGrowing = ref(true)
+const noGap = ref(true)
+</script>
+
+🡔 [Layout](../layout)
+
+# Layout `grid`
+
+Align items both vertically and horizontally.
+You can either specify the column width (default: 320px) or set the desired number of columns.
+
+### Override the `:column-width` (in px):
+
+<Layout flex>
+
+```vue-html{1}
+<Layout grid :column-width="90"
+  :style="`width:${2 * 90 + 32}px`"
+>
+  <Alert yellow />
+  <Card small title="brown" />
+  <Alert blue />
+</Layout>
+```
+
+<Layout grid :column-width="90" class="preview" :style="`width:${2 * 90 + 32}px`">
+  <Alert yellow />
+  <Card small title="brown" />
+  <Alert blue />
+</Layout>
+
+</Layout>
+
+### Let elements span multiple rows or columns:
+
+```vue-html{1,2}
+  <Alert purple style="grid-column: span 2;" />
+  <Card title="2" style="grid-row: span 2;" />
+  <Alert green />
+  <Card title="1" />
+```
+
+<Layout grid>
+  <Alert purple style="grid-column: span 2;" />
+  <Card title="2" style="grid-row: span 2;" />
+  <Alert green />
+  <Card title="1" />
+</Layout>
+
+### Custom grid configuration
+
+You can pass any valid CSS `grid` value to the `grid` prop:
+
+```vue-html
+<Layout grid="auto / repeat(auto-fit, minmax(min-content, 100px))">
+  <Alert red />
+  <Alert green />
+  <Alert blue />
+</Layout>
+```
+
+<Layout class="preview" grid="auto / repeat(auto-fit, minmax(min-content, 100px))">
+  <Alert red />
+  <Alert green />
+  <Alert blue />
+</Layout>
diff --git a/front/ui-docs/components/ui/layout/stack.md b/front/ui-docs/components/ui/layout/stack.md
new file mode 100644
index 000000000..f6935027e
--- /dev/null
+++ b/front/ui-docs/components/ui/layout/stack.md
@@ -0,0 +1,45 @@
+<script setup>
+import { ref } from 'vue'
+
+import Card from '~/components/ui/Card.vue'
+import Alert from '~/components/ui/Alert.vue'
+import Layout from '~/components/ui/Layout.vue'
+import Spacer from '~/components/ui/layout/Spacer.vue'
+import Tab from '~/components/ui/Tab.vue'
+import Tabs from '~/components/ui/Tabs.vue'
+import Toggle from '~/components/ui/Toggle.vue'
+import Button from '~/components/ui/Button.vue'
+
+const isGrowing = ref(true)
+const noGap = ref(true)
+</script>
+
+🡔 [Layout](../layout)
+
+# Layout `stack`
+
+Add space between vertically stacked items
+
+<Layout flex>
+
+```vue-html
+<Layout stack>
+  <Card title="A"></Card>
+  <Card title="B"></Card>
+  <Card title="C"></Card>
+  <Card title="D"></Card>
+  <Card title="E"></Card>
+</Layout>
+```
+
+<div class="preview">
+<Layout stack>
+  <Card title="A"></Card>
+  <Card title="B"></Card>
+  <Card title="C"></Card>
+  <Card title="D"></Card>
+  <Card title="E"></Card>
+</Layout>
+</div>
+
+</Layout>