Merge pull request #382 from feelpp/380-support-figure-and-table-references

380 support figure and table references

Author: vincentchabannes

docs/antora/supplemental-ui/css/figures.css

@@ -1,31 +1,26 @@
 .figure-container {
     position: relative;
-    margin: 1.5rem auto;
-    padding: 1rem;
-    background-color: #fff;
-    border: 1px solid #ddd;
-    border-radius: 8px;
-    box-shadow: 0 2px 4px rgba(0, 0, 0, 0.08);
+    width: 100%;
+    max-width: 100%;
+    box-sizing: border-box;
+    margin: 1.2rem 0;
+    background: none;
+    box-shadow: none;
+    padding: 0.5rem;
+    border: 1px solid #ccc;
+    border-radius: 4px;
 }
 
 .subfigure-container {
     position: absolute;
-    top: 0;
-    left: 0;
-    width: 100%;
-    height: 100%;
-    background-color: #f9f9f9;
-    padding: 1rem;
-    border: 1px solid #ddd;
-    border-top: none;
-    border-radius: 0 0 8px 8px;
+    inset: 0;
+    background: none;
+    padding: 0;
+    border: none;
 }
 
 .subfigure-container.active {
     position: relative;
-    opacity: 1;
-    pointer-events: auto;
-    z-index: 1;
 }
 
 .subfigure-container.inactive {
@@ -37,42 +32,76 @@
 /* Tabs container: display buttons inline with a bottom border to indicate grouping */
 .tabs-container {
     display: flex;
-    border-bottom: 2px solid #007acc;
-    margin-bottom: 0.5rem;
+    justify-content: flex-start;
+    gap: 0;
+    margin-bottom: 0.4rem;
 }
 
-/* Figure tab button styling */
+
 .figure-tab {
-    background: transparent;
+    background: none;
     border: none;
-    outline: none;
-    padding: 0.5rem 1rem;
-    margin-right: 0.3rem;
-    font-size: 1rem;
-    color: #007acc;
+    font-size: 0.9rem;
+    color: #444;
     cursor: pointer;
-    border-radius: 4px 4px 0 0;
-    transition: background-color 0.2s ease, color 0.2s ease;
+    border: 1px solid #ccc;
+    padding: 0.2rem 0.5rem;
+}
+
+.figure-tab:hover {
+    color: #000;               /* subtle darkening on hover */
+    background: none;          /* no hover background */
 }
 
-.figure-tab:hover,
-.figure-tab.active {
-    background-color: #007acc;
-    color: #fff;
+
+.export-container {
+    display: flex;
+    justify-content: flex-end;
+    gap: 0.3rem;
+    margin-bottom: 0.3rem;
 }
 
 .export-container button {
-    background-color: #007acc;
-    color: #fff;
+    background: none;
+    color: #666;
     border: none;
-    padding: 0.4rem 0.8rem;
-    margin-right: 0.4rem;
-    border-radius: 4px;
+    padding: 0;
+    font-size: 0.75rem;
     cursor: pointer;
-    font-size: 0.9rem;
-    transition: background-color 0.2s ease;
+    text-decoration: underline;
 }
 
 .export-container button:hover {
-    background-color: #005fa3;
-}
+    color: #000;
+}
+
+.exampleblock.plot{
+    border: 1px solid #ccc;
+    border-radius: 4px;
+}
+
+/* Example block styling for plots */
+.exampleblock.plot,.exampleblock.grid,.exampleblock.image {
+    border: none;
+    padding: 0;
+    margin: 1.5rem 0;
+    display: flex;
+    flex-direction: column;
+}
+
+.exampleblock.plot>.content,.exampleblock.grid>.content ,.exampleblock.image>.content {
+    order: 1;
+    padding: 0;
+    border: none;
+}
+
+.exampleblock.plot>.title,.exampleblock.grid>.title,.exampleblock.image>.title, .plotly-figure-caption{
+    order: 2;
+    text-align: center;
+    font-style: italic;
+    margin-top: 0.5rem;
+}
+
+.exampleblock.example {
+    border-left: 4px solid var(--brand-primary);
+}

docs/modules/json_report/pages/json_schema/content/figure.adoc

@@ -10,7 +10,9 @@ The **Plot Node** defines a data visualization within the report. It specifies t
 |===
 |Field|Type|Description|Default Value
 
+|`id`|string| *Optional.* Identifies the plot node within the report. Used for internal cross referencing |`null`
 |`type`|string|Must be set to `"plot"`.|`"plot"`
+|`caption`|string|*Optional.* A descriptive caption for the figure.|`null`
 |`ref`|string|The unique `name`  of the data file (from the root `data` list) to reference for building the figure.|*Required*
 |`plot`|object|The nested configuration object (`Plot` schema) defining the figure's dimensions, type, and transformation.|*Required*
 |===

docs/modules/json_report/pages/json_schema/content/grid.adoc

@@ -1,11 +1,13 @@
 = Grid Node
 
-The **Grid Node** is a layout node that can be used to structure content into a grid.
+The **Grid Node** is a layout node that can be used to structure content into a grid. Mainly used to arrange images, plots, or tables side by side in a visually appealing manner. Sub figures or sub plots can be created using this node, but numbering and labeling must be handled manually within the captions of the child nodes.
 
 |===
 |Field|Type|Description|Default Value
 
+|`id`|string| *Optional.* Identifies the grid node within the report. Used for internal cross referencing |`null`
 |`type`|string|Must be set to `"grid"`.|`"grid"`
+|`caption`|string|*Optional.* A descriptive caption for the grid.|`null`
 |`contents`|array of objects| A list of other (non-recursive) content nodes.|[]
 |columns|int| Number of columns for the grid. Must be between 1 and 4.| 1
 |gap|int| Must be beween 1 and 3| 2.

docs/modules/json_report/pages/json_schema/content/image.adoc

@@ -12,7 +12,9 @@ The `src` file path is typically resolved relative to the passed configuration f
 |===
 |Field|Type|Description|Default Value
 
+|`id`|string| *Optional.* Identifies the image node within the report. Used for internal cross referencing |`null`
 |`type`|string|Must be set to `"image"`.|`"image"`
+|`caption`|string|*Optional.* A descriptive caption for the image.|`null`
 |`src`|string|The file path or URL of the image to embed.|*Required*
 |`caption`|string|An optional caption displayed beneath the image. If provided, the image is rendered using the `title` attribute in AsciiDoc.|`null`
 |`alt`|string|Alternative text for the image, used for accessibility and when the image cannot be displayed.|`null`

docs/modules/json_report/pages/json_schema/content/latex.adoc

@@ -5,6 +5,8 @@ The **LaTeX Node** is designed for the direct embedding of mathematical formulas
 |===
 |Field|Type|Description|Default Value
 
+|`id`|string| *Optional.* Identifies the LaTeX node within the report. Used for internal cross referencing |`null`
+|`is_equation`|boolean|*Optional.* Indicates if the LaTeX content represents a standalone equation. It adds `\begin\{equation\}` and `\end\{equation\}` around the content if true.|`false`
 |`type`|string|Must be set to `"latex"`.|`"latex"`
 |`latex`|string|The raw LaTeX content (e.g., a mathematical equation or a custom LaTeX block).|*Required*
 |`ref`|string|The `name` of the data field to reference for dynamic placeholder resolution.|`null`

docs/modules/json_report/pages/json_schema/content/list.adoc

@@ -7,6 +7,7 @@ The **List Node** is used to render ordered lists. Its primary strength is that
 |===
 |Field|Type|Description|Default Value
 
+|`id`|string| *Optional.* Identifies the list node within the report. Used for internal cross referencing |`null`
 |`type`|string|Must be set to `"itemize"`.|`"itemize"`
 |`items`|array of objects/strings|The contents of the list. Each entry can be a simple string, a full `Text Node` object, or a `Text Configuration` object.|*Required*
 |`ref`|string|The `name` of the data field to reference for dynamic placeholder resolution within all list items.|`null`

docs/modules/json_report/pages/json_schema/content/section.adoc

@@ -5,6 +5,7 @@ The **Section Node** is the fundamental building block for structuring your repo
 |===
 |Field|Type|Description|Default Value
 
+|`id`|string| *Optional.* Identifies the section node within the report. Used for internal cross referencing |`null`
 |`type`|string|Must be set to `"section"`.|`"section"`
 |`title`|string|The title of the section.|*Required*
 |`contents`|array of objects|A recursive list of other content nodes, including nested `SectionNode`s.| []

docs/modules/json_report/pages/json_schema/content/table.adoc

@@ -10,6 +10,8 @@ The structure is composed of the `TableNode` container and the nested `Table` co
 |===
 |Field|Type|Description|Default Value
 
+
+|`id`|string| *Optional.* Identifies the table node within the report. Used for internal cross referencing |`null`
 |`type`|string|Must be set to `"table"`.|`"table"`
 |`ref`|string|The unique reference of the data file (from the root `data` list) containing the table to be rendered.|*Required*
 |`caption`|string|*Optional.* Table caption.| `null`

docs/modules/json_report/pages/json_schema/content/text.adoc

@@ -5,6 +5,7 @@ The **Text Node** is used to insert narrative content into your report. It suppo
 |===
 |Field|Type|Description|Default Value
 
+|`id`|string| *Optional.* Identifies the text node within the report. Used for internal cross referencing |`null`
 |`type`|string|Must be set to `"text"`.|`"text"`
 |`text`|string or object|The text content or a nested `Text` object.|*Required*
 |`ref`|string|The `name` of the data field to reference for dynamic placeholder resolution.|`null`

docs/modules/json_report/pages/json_schema/referencing.adoc

@@ -0,0 +1,83 @@
+= Internal Cross References
+
+It is possible to assign an optional unique identifier to any content node within the JSON report schema. This identifier can then be used to create internal cross-references within the report, allowing for easy navigation between different sections or elements.
+
+== Assigning Identifiers
+
+To assign an identifier to a content node, include the `id` field in the node's JSON object. The value of this field should be a unique string that serves as the identifier for that node.
+
+[source,json]
+----
+{
+  "type": "section",
+  "id": "introduction",
+  "title": "Introduction",
+  "contents": [
+    // Other content nodes
+  ]
+}
+----
+In this example, the section node is assigned the identifier `"introduction"`.
+
+[IMPORTANT]
+Ensure that each id contains only alphanumeric characters, underscores, or hyphens, and does not start with a number. This ensures compatibility with AsciiDoc cross-referencing conventions.
+
+== Figure and Table Numbering
+
+Tables, figures and images are automatically numbered in the order they appear in the report. However, tables will be prefixed with "Table", figures, plots and images will be prefixed with "Figure". This means that automatic numbering will be independent between tables and figures/images.
+
+[IMPORTANT]
+Elements included inside a grid node are NOT automatically numbered. You must manually include numbering in the caption if desired (e.g. "Figure 1a: ..."). The counter for the automatic numbering will not be incremented for these elements.
+
+== Creating Cross-References
+
+To create a cross-reference to a content node with an assigned identifier, use the link:https://docs.asciidoctor.org/asciidoc/latest/macros/xref/#internal-cross-references[AsciiDoc cross-referencing syntax]. The format is `\<<id, Display Text>>`, where `id` is the identifier of the target node, and `Display Text` is the text that will be displayed as the link in the report.
+
+[source,asciidoc]
+----
+See <<introduction, Introduction Section>> for more details.
+----
+
+In this example, the text "Introduction Section" will be a clickable link that navigates to the section with the identifier `"introduction"`.
+
+[TIP]
+For images, figures and tables, it is possible to reference via their caption without the use of an explicit id (though it is discouraged for clarity). To do so, remove any parentheses from the reference, and replace spaces with hyphens. For example, if a table has the caption "Performance Metrics", you can reference it using `\<<Performance-Metrics>>`.
+
+[IMPORTANT]
+Ensure that the identifiers used in cross-references match exactly with those assigned to the content nodes, including case sensitivity. Mismatched identifiers will result in broken links in the final report.
+
+== Example
+
+[source,json]
+----
+{
+  "contents": [
+    {
+        "type":"text",
+        "id":"intro_text",
+        "text":"Welcome to the report."
+    },
+    {
+        "type":"section",
+        "id":"data_analysis",
+        "title":"Data Analysis",
+        "contents":[
+            {
+                "type":"table",
+                "id":"results_table",
+                "ref":"results_data",
+                "caption":"Results Overview"
+            },
+            {
+                "type":"text",
+                "text":"Refer to <<intro_text, the introduction>> for context."
+            }
+        ]
+    },
+    {
+        "type":"text",
+        "text":"See <<results_table, the results table>> for detailed metrics."
+    }
+  ]
+}
+----