#377: Optionally render details section as open

api/src/main/java/org/itsallcode/openfasttrace/api/DetailsSectionFolding.java

@@ -0,0 +1,13 @@
+package org.itsallcode.openfasttrace.api;
+
+/**
+ * Determines if the details sections for specification items in the HTML report
+ * are folded (i.e. hidden) or unfolded (i.e. visible) by default.
+ */
+public enum DetailsSectionFolding
+{
+    /** Hide details section by default. */
+    HIDE_DETAILS,
+    /** How details section by default. */
+    SHOW_DETAILS;
+}

api/src/main/java/org/itsallcode/openfasttrace/api/ReportSettings.java

@@ -1,11 +1,11 @@
 package org.itsallcode.openfasttrace.api;
 
+import java.util.Objects;
+
 import org.itsallcode.openfasttrace.api.core.Newline;
 import org.itsallcode.openfasttrace.api.report.ReportConstants;
 import org.itsallcode.openfasttrace.api.report.ReportVerbosity;
 
-import java.util.Objects;
-
 /**
  * This class implements a parameter object to control the settings of OFT's
  * report mode.
@@ -17,14 +17,16 @@ public class ReportSettings
     private final String outputFormat;
     private final Newline newline;
     private final ColorScheme colorScheme;
+    private final DetailsSectionFolding detailsSectionFolding;
 
     private ReportSettings(final Builder builder)
     {
         this.verbosity = builder.verbosity;
         this.showOrigin = builder.showOrigin;
         this.outputFormat = builder.outputFormat;
         this.newline = builder.newline;
-        this.colorScheme = Objects.requireNonNull(builder.colorScheme);
+        this.colorScheme = Objects.requireNonNull(builder.colorScheme, "colorScheme");
+        this.detailsSectionFolding = Objects.requireNonNull(builder.detailsSectionFolding, "detailsSectionFolding");
     }
 
     /**
@@ -72,10 +74,21 @@ public Newline getNewline()
      *
      * @return color scheme
      */
-    public ColorScheme getColorScheme() {
+    public ColorScheme getColorScheme()
+    {
         return this.colorScheme;
     }
 
+    /**
+     * Get the details section folding status.
+     * 
+     * @return folding status
+     */
+    public DetailsSectionFolding getDetailsSectionFolding()
+    {
+        return detailsSectionFolding;
+    }
+
     /**
      * Create default report settings
      * 
@@ -101,6 +114,7 @@ public static Builder builder()
      */
     public static class Builder
     {
+        private DetailsSectionFolding detailsSectionFolding = DetailsSectionFolding.HIDE_DETAILS;
         private Newline newline = Newline.UNIX;
         private String outputFormat = ReportConstants.DEFAULT_REPORT_FORMAT;
         private boolean showOrigin = false;
@@ -109,7 +123,7 @@ public static class Builder
 
         private Builder()
         {
-
+            // empty by intention
         }
 
         /**
@@ -123,11 +137,12 @@ public ReportSettings build()
         }
 
         /**
-         * Set the report verbosity
+         * Set the report verbosity. Default:
+         * {@link ReportVerbosity#FAILURE_DETAILS}.
          * 
          * @param verbosity
          *            report verbosity
-         * @return <code>this</code> for fluent programming
+         * @return {@code this} for fluent programming
          */
         public Builder verbosity(final ReportVerbosity verbosity)
         {
@@ -137,11 +152,11 @@ public Builder verbosity(final ReportVerbosity verbosity)
 
         /**
          * Set the whether the origin of specification items should be shown in
-         * the report
+         * the report. Default: {@code false}.
          * 
          * @param showOrigin
          *            set to {@code true} if the origin should be shown
-         * @return <code>this</code> for fluent programming
+         * @return {@code this} for fluent programming
          */
         public Builder showOrigin(final boolean showOrigin)
         {
@@ -150,11 +165,12 @@ public Builder showOrigin(final boolean showOrigin)
         }
 
         /**
-         * Set the output format
+         * Set the output format. Default:
+         * {@link ReportConstants#DEFAULT_REPORT_FORMAT}.
          * 
          * @param outputFormat
          *            output format
-         * @return <code>this</code> for fluent programming
+         * @return {@code this} for fluent programming
          */
         public Builder outputFormat(final String outputFormat)
         {
@@ -163,11 +179,11 @@ public Builder outputFormat(final String outputFormat)
         }
 
         /**
-         * Set the newline format
+         * Set the newline format. Default: {@link Newline#UNIX}.
          * 
          * @param newline
          *            newline format
-         * @return <code>this</code> for fluent programming
+         * @return {@code this} for fluent programming
          */
         public Builder newline(final Newline newline)
         {
@@ -176,13 +192,30 @@ public Builder newline(final Newline newline)
         }
 
         /**
-         * Set the desired color scheme
+         * Set the desired color scheme. Default:
+         * {@link ColorScheme#BLACK_AND_WHITE}.
+         *
+         * @param colorScheme
+         *            color scheme to use
+         * @return {@code this} for fluent programming
+         */
+        public Builder colorScheme(final ColorScheme colorScheme)
+        {
+            this.colorScheme = Objects.requireNonNull(colorScheme, "colorScheme");
+            return this;
+        }
+
+        /**
+         * Set the desired details section folding status. Default:
+         * {@link DetailsSectionFolding#HIDE_DETAILS}.
          *
-         * @param colorScheme color scheme to use
-         * @return <code>this</code> for fluent programming
+         * @param detailsSectionFolding
+         *            folding status to use
+         * @return {@code this} for fluent programming
          */
-        public Builder colorScheme(final ColorScheme colorScheme) {
-            this.colorScheme = Objects.requireNonNull(colorScheme);
+        public Builder detailsSectionFolding(final DetailsSectionFolding detailsSectionFolding)
+        {
+            this.detailsSectionFolding = Objects.requireNonNull(detailsSectionFolding, "detailsSectionFolding");
             return this;
         }
     }

api/src/test/java/org/itsallcode/openfasttrace/api/TestReportSettings.java

@@ -2,6 +2,7 @@
 
 import static org.hamcrest.CoreMatchers.equalTo;
 import static org.hamcrest.MatcherAssert.assertThat;
+import static org.junit.jupiter.api.Assertions.assertThrows;
 
 import org.itsallcode.openfasttrace.api.ReportSettings.Builder;
 import org.itsallcode.openfasttrace.api.core.Newline;
@@ -69,4 +70,26 @@ void testBuildWithNewline()
         assertThat(this.builder.newline(Newline.OLDMAC).build().getNewline(),
                 equalTo(Newline.OLDMAC));
     }
+
+    @Test
+    void testBuildDetailsFoldingStatusDefault()
+    {
+        assertThat(this.builder.build().getDetailsSectionFolding(),
+                equalTo(DetailsSectionFolding.HIDE_DETAILS));
+    }
+
+    @Test
+    void testBuildDetailsFoldingStatusNullNotAllowed()
+    {
+        assertThrows(NullPointerException.class, () -> this.builder.detailsSectionFolding(null));
+    }
+
+    @Test
+    void testBuildDetailsFoldingStatusCustom()
+    {
+        assertThat(
+                this.builder.detailsSectionFolding(DetailsSectionFolding.SHOW_DETAILS).build()
+                        .getDetailsSectionFolding(),
+                equalTo(DetailsSectionFolding.SHOW_DETAILS));
+    }
 }

core/src/main/java/org/itsallcode/openfasttrace/core/cli/CliArguments.java

@@ -5,6 +5,7 @@
 import java.util.*;
 
 import org.itsallcode.openfasttrace.api.ColorScheme;
+import org.itsallcode.openfasttrace.api.DetailsSectionFolding;
 import org.itsallcode.openfasttrace.api.cli.DirectoryService;
 import org.itsallcode.openfasttrace.api.core.Newline;
 import org.itsallcode.openfasttrace.api.report.ReportConstants;
@@ -38,6 +39,9 @@ public class CliArguments
     private final DirectoryService directoryService;
     private ColorScheme colorScheme;
 
+    // [impl->dsn~reporting.html.details-folding~1]
+    private DetailsSectionFolding detailsSectionFolding;
+
     /**
      * Create new {@link CliArguments}.
      * 
@@ -312,6 +316,19 @@ public ColorScheme getColorScheme()
         }
     }
 
+    /**
+     * Get the default folding status of HTML report details sections.
+     * <p>
+     * Defaults to {@link DetailsSectionFolding#HIDE_DETAILS}.
+     * </p>
+     * 
+     * @return folding status
+     */
+    public DetailsSectionFolding getDetailsSectionFolding()
+    {
+        return detailsSectionFolding == null ? DetailsSectionFolding.HIDE_DETAILS : detailsSectionFolding;
+    }
+
     /**
      * Set a list of tags to be applied as filter during import
      * 
@@ -388,4 +405,15 @@ public void setC(final ColorScheme colorScheme)
     {
         this.setColorScheme(colorScheme);
     }
+
+    /**
+     * Choose the details folding status.
+     *
+     * @param detailsSectionFolding
+     *            folding status
+     */
+    public void setDetailsSectionFolding(final DetailsSectionFolding detailsSectionFolding)
+    {
+        this.detailsSectionFolding = detailsSectionFolding;
+    }
 }

core/src/main/java/org/itsallcode/openfasttrace/core/cli/commands/TraceCommand.java

@@ -5,9 +5,7 @@
 import java.util.List;
 
 import org.itsallcode.openfasttrace.api.ReportSettings;
-import org.itsallcode.openfasttrace.api.core.LinkedSpecificationItem;
-import org.itsallcode.openfasttrace.api.core.SpecificationItem;
-import org.itsallcode.openfasttrace.api.core.Trace;
+import org.itsallcode.openfasttrace.api.core.*;
 import org.itsallcode.openfasttrace.core.Oft;
 import org.itsallcode.openfasttrace.core.cli.CliArguments;
 
@@ -72,6 +70,7 @@ private ReportSettings convertCommandLineArgumentsToReportSettings()
                 .newline(this.arguments.getNewline()) //
                 .showOrigin(this.arguments.getShowOrigin()) //
                 .colorScheme(this.arguments.getColorScheme()) //
+                .detailsSectionFolding(this.arguments.getDetailsSectionFolding()) //
                 .build();
     }
 }

core/src/test/java/org/itsallcode/openfasttrace/core/cli/TestCliArguments.java

@@ -8,6 +8,7 @@
 import java.util.List;
 
 import org.itsallcode.openfasttrace.api.ColorScheme;
+import org.itsallcode.openfasttrace.api.DetailsSectionFolding;
 import org.itsallcode.openfasttrace.api.core.Newline;
 import org.itsallcode.openfasttrace.api.report.ReportConstants;
 import org.itsallcode.openfasttrace.api.report.ReportVerbosity;
@@ -234,17 +235,17 @@ void testSetS()
         assertThat(this.arguments.getShowOrigin(), is(true));
     }
 
-    // [dsn~reporting.plain-text.ansi-color~1]
-    // [dsn~reporting.plain-text.ansi-font-style~1]
+    // [utest->dsn~reporting.plain-text.ansi-color~1]
+    // [utest->dsn~reporting.plain-text.ansi-font-style~1]
     @Test
     void testSetColorScheme()
     {
         this.arguments.setColorScheme(ColorScheme.MONOCHROME);
         assertThat(this.arguments.getColorScheme(), is(ColorScheme.MONOCHROME));
     }
 
-    // [dsn~reporting.plain-text.ansi-color~1]
-    // [dsn~reporting.plain-text.ansi-font-style~1]
+    // [utest->dsn~reporting.plain-text.ansi-color~1]
+    // [utest->dsn~reporting.plain-text.ansi-font-style~1]
     @Test
     void testSetC()
     {
@@ -266,4 +267,27 @@ void testSetOutputFileOverridesColorSchemeSetting()
         this.arguments.setOutputFile("something");
         assertThat(this.arguments.getColorScheme(), is(ColorScheme.BLACK_AND_WHITE));
     }
+
+    // [utest->dsn~reporting.html.details-folding~1]
+    @Test
+    void testDetailsSectionFoldingDefaultsToHidden()
+    {
+        assertThat(this.arguments.getDetailsSectionFolding(), is(DetailsSectionFolding.HIDE_DETAILS));
+    }
+
+    // [utest->dsn~reporting.html.details-folding~1]
+    @Test
+    void testDetailsSectionFoldingNullDefaultsToHidden()
+    {
+        this.arguments.setDetailsSectionFolding(null);
+        assertThat(this.arguments.getDetailsSectionFolding(), is(DetailsSectionFolding.HIDE_DETAILS));
+    }
+
+    // [utest->dsn~reporting.html.details-folding~1]
+    @Test
+    void testDetailsSectionFoldingCustomValue()
+    {
+        this.arguments.setDetailsSectionFolding(DetailsSectionFolding.SHOW_DETAILS);
+        assertThat(this.arguments.getDetailsSectionFolding(), is(DetailsSectionFolding.SHOW_DETAILS));
+    }
 }

doc/spec/design.md

@@ -397,6 +397,17 @@ Covers:
 
 Needs: impl, itest
 
+#### HTML Reports Allows Configuring Details Folding Status
+`dsn~reporting.html.details-folding~1`
+
+OFT allows configuring the specification item detail section folding status (open or closed). Default is closed.
+
+Covers:
+
+* `req~reporting.html.details-folding~1`
+
+Needs: impl, utest, itest
+
 ## Requirement Format Conversion
 
 ### ReqM2 Export

doc/spec/system_requirements.md

@@ -569,7 +569,22 @@ OFT creates the HTML Report as a single file.
 
 Rationale:
 
-It makes exchanging reports with other people easier if everything is contained in a single file.  
+It makes exchanging reports with other people easier if everything is contained in a single file.
+
+Covers:
+
+* [feat~html-report~1](#html-report)
+
+Needs: dsn
+
+##### HTML Report Renders Details Opened or Closed by Default
+`req~reporting.html.details-folding~1`
+
+OFT allows configuring the folding status of specification item details to open or closed by default.
+
+Rationale:
+
+Allowing the details section to be opened and visible allows rendering the HTML report to a PDF document that contains all details.
 
 Covers: