From cdf548cad09303869f88141fff445fcd2a0e60b8 Mon Sep 17 00:00:00 2001
From: Thomas Purchas <tpurchas@gmail.com>
Date: Mon, 8 Jul 2024 15:12:24 +0100
Subject: [PATCH] Add CSS to make top doc box have a fade, rather than hard
 cutoff (#570)

The current hard cutoff in the docs often results in people not
realising that the doc box can be expanded, and often resulting in
confusion because the most helpful examples are often in the module doc
box.

This change uses some simple CSS tweaks to replace the hard cut-off with
a visualfade, so it's obvious that there's content hidden out of view.
Doing this required removing the CSS transition, as it hard to correctly
transition the height property of CSS element of unknown target height.
But the improved discoverablility of the doc content seems like a
worthwhile tradeoff.
---
 .../main/resources/org/pkl/doc/styles/pkldoc.css   | 14 ++++++++++++++
 .../DocGeneratorTest/output/styles/pkldoc.css      | 14 ++++++++++++++
 2 files changed, 28 insertions(+)

diff --git a/pkl-doc/src/main/resources/org/pkl/doc/styles/pkldoc.css b/pkl-doc/src/main/resources/org/pkl/doc/styles/pkldoc.css
index 1bebe2ff..2c3632a3 100644
--- a/pkl-doc/src/main/resources/org/pkl/doc/styles/pkldoc.css
+++ b/pkl-doc/src/main/resources/org/pkl/doc/styles/pkldoc.css
@@ -518,6 +518,20 @@ because the entire .member.with-page-link is effectively a link (via JS).
   display: none;
 }
 
+#_declaration .expandable {
+  transform: none;
+  transition: none;
+}
+
+#_declaration .expandable.collapsed {
+  mask: linear-gradient(rgb(0 0 0), transparent) content-box;
+  height: 100px;
+}
+
+#_declaration .expandable.hidden {
+  display: block;
+}
+
 /* show an otherwise hidden inherited member if it's a link target */
 .anchor:target + .expandable.collapsed.hidden {
   display: inherit;
diff --git a/pkl-doc/src/test/files/DocGeneratorTest/output/styles/pkldoc.css b/pkl-doc/src/test/files/DocGeneratorTest/output/styles/pkldoc.css
index 1bebe2ff..2c3632a3 100644
--- a/pkl-doc/src/test/files/DocGeneratorTest/output/styles/pkldoc.css
+++ b/pkl-doc/src/test/files/DocGeneratorTest/output/styles/pkldoc.css
@@ -518,6 +518,20 @@ because the entire .member.with-page-link is effectively a link (via JS).
   display: none;
 }
 
+#_declaration .expandable {
+  transform: none;
+  transition: none;
+}
+
+#_declaration .expandable.collapsed {
+  mask: linear-gradient(rgb(0 0 0), transparent) content-box;
+  height: 100px;
+}
+
+#_declaration .expandable.hidden {
+  display: block;
+}
+
 /* show an otherwise hidden inherited member if it's a link target */
 .anchor:target + .expandable.collapsed.hidden {
   display: inherit;