From 1442f626335e30e3a8d74e4e13e561c41f073ef8 Mon Sep 17 00:00:00 2001
From: undergroundwires <git@undergroundwires.dev>
Date: Thu, 23 Nov 2023 07:39:11 +0100
Subject: [PATCH] Fix spacing in documentation for readability

This commit improves the readability of the script/category
documentations by refining the vertical and horizontal spacing. The
adjustments aim to create more visually consistent layout.

Styling changes include:

- Add more and consistent spacing between text parts (such as lists,
  tables, paragraphs etc.).
- Remove top/bottom spacing at the start and end of the text.
- Add more horizontal spacing (padding on left) for lists.
- Improve blockquote styling with a border and similar spacing as other
  parts.
---
 .../Documentation/DocumentationText.vue       | 84 ++++++++++++-------
 1 file changed, 56 insertions(+), 28 deletions(-)

diff --git a/src/presentation/components/Scripts/View/Tree/NodeContent/Documentation/DocumentationText.vue b/src/presentation/components/Scripts/View/Tree/NodeContent/Documentation/DocumentationText.vue
index e3105a1b..3dcdc08c 100644
--- a/src/presentation/components/Scripts/View/Tree/NodeContent/Documentation/DocumentationText.vue
+++ b/src/presentation/components/Scripts/View/Tree/NodeContent/Documentation/DocumentationText.vue
@@ -55,6 +55,8 @@ function renderAsMarkdownListItem(content: string): string {
 
 <style lang="scss"> /* Not scoped due to element styling such as "a". */
 @use "@/presentation/assets/styles/main" as *;
+@use 'sass:math';
+
 $text-color: $color-on-primary;
 $text-size: 0.75em; // Lower looks bad on Firefox
 
@@ -86,7 +88,7 @@ $text-size: 0.75em; // Lower looks bad on Firefox
         height: $text-size;
 
         background-color: $text-color;
-        margin-left: calc($text-size / 4);
+        margin-left: math.div($text-size, 4);
       }
       /*
         Match color of global hover behavior. We need to do it manually because global hover sets
@@ -101,46 +103,72 @@ $text-size: 0.75em; // Lower looks bad on Firefox
       }
     }
   }
-  h1, h2, h3, h4, h5, h6 {
-    &:first-child {
-      /*
-        Remove default browser margin, if they're the first element.
-        Just like `<p>`, it ensures that the visible texts start with top spacing.
-      */
-      margin-top: 0;
+
+  @mixin no-margin($selectors) {
+    #{$selectors} {
+      margin: 0;
     }
   }
 
-  @mixin set-paragraph-vertical-gap($paragraph-vertical-gap) {
-    p {
-      /*
-        Remove default browser margin on paragraphs to ensure:
-          1. A markdown text represented as a list (e.g. <ul>, <ol>) has same vertical spacing as a standalone paragraph (</p>).
-          2. The first paragraph in a sequence (first `<p>` usage) does not introduce top spacing.
-          3. Uniformity, so margin can be set consistently across browsers.
-      */
-      margin: 0;
+  @mixin no-padding($selectors) {
+    #{$selectors} {
+      padding: 0;
     }
-    /*
-      Introduce spacing between successive elements and paragraphs.
-      E.g., spacing between two paragraphs (`p`), paragraphs after lists (<ul>, <ol>)...
-    */
-    * {
-      + p {
-        margin-top: $paragraph-vertical-gap;
+  }
+
+  @mixin left-padding($selectors, $horizontal-gap) {
+    #{$selectors} {
+      padding-inline-start: $horizontal-gap;
+    }
+  }
+
+  @mixin bottom-margin($selectors, $vertical-gap) {
+    #{$selectors} {
+      &:not(:last-child) {
+        margin-bottom: $vertical-gap;
       }
     }
   }
-  @include set-paragraph-vertical-gap($text-size);
-  ul {
-    // CSS default is 40px, if the text is a bulletpoint, it leads to unexpected padding.
-    padding-inline-start: 1em;
 
+  @mixin apply-uniform-vertical-spacing($vertical-gap) {
+    /* Reset default top/bottom margins added by browser. */
+    @include no-margin('p');
+    @include no-margin('h1, h2, h3, h4, h5, h6');
+    @include no-margin('blockquote');
+
+    /* Add spacing between elements using `margin-bottom` only (bottom-out instead of top-down strategy). */
+    $small-gap: math.div($vertical-gap, 2);
+    @include bottom-margin('p', $vertical-gap);
+    @include bottom-margin('h1, h2, h3, h4, h5, h6', $vertical-gap);
+    @include bottom-margin('ul, ol', $vertical-gap);
+    @include bottom-margin('li', $small-gap);
+    @include bottom-margin('table', $vertical-gap);
+    @include bottom-margin('blockquote', $vertical-gap);
+  }
+
+  @mixin apply-uniform-horizontal-spacing($horizontal-gap) {
+    /* Reset default left/right paddings added by browser. */
+    @include no-padding('ul, ol');
+
+    /* Add spacing for list items. */
+    $list-spacing: $horizontal-gap * 2;
+    @include left-padding('ul, ol', $list-spacing);
+  }
+
+  @include apply-uniform-vertical-spacing($text-size);
+  @include apply-uniform-horizontal-spacing($text-size);
+
+  ul {
     /*
       Set list style explicitly, because otherwise it changes based on parent <ul>s in tree view.
       We reset the style from here.
     */
     list-style: square;
   }
+
+  blockquote {
+    padding: 0 1em;
+    border-left: .25em solid $color-primary;
+  }
 }
 </style>