docs: 📝 Add cell selection syntax docs (#583)

* docs: 📝 Add cell selection syntax docs
jvalue · Jun 10, 2024 · c4a3062 · c4a3062
1 parent 8bf5053
commit c4a3062
Show file tree

Hide file tree

Showing 8 changed files with 268 additions and 10 deletions.
diff --git a/apps/docs/docs/user/cell-range.md b/apps/docs/docs/user/cell-range.md
@@ -0,0 +1,243 @@
+---
+sidebar_position: 9
+---
+
+# Cell Range
+
+Cell ranges can be used to select a subset of cells in a 2D data structure, such as a `Sheet`. The syntax for cell ranges follows conventions from spreadsheet-software. Rows are referenced by one-based indices and columns by capitalized characters, ordered alphabetically.
+
+<table>
+    <tr>
+        <td></td>
+        <td>A</td>
+        <td>B</td>
+        <td>C</td>
+    </tr>
+    <tr>
+        <td>1</td>
+        <td class="example-table__highlighted">Cell A1</td>
+        <td class="example-table__highlighted">Cell B1</td>
+        <td class="example-table__highlighted">Cell C1</td>
+    </tr>
+    <tr>
+        <td>2</td>
+        <td class="example-table__highlighted">Cell A2</td>
+        <td class="example-table__highlighted">Cell B2</td>
+        <td class="example-table__highlighted">Cell C2</td>
+    </tr>
+    <tr>
+        <td>3</td>
+        <td class="example-table__highlighted">Cell A3</td>
+        <td class="example-table__highlighted">Cell B3</td>
+        <td class="example-table__highlighted">Cell C3</td>
+    </tr>
+</table>
+
+Cell ranges can be expressed as whole rows using the **`row`** keyword, whole columns using the **`column`** keyword and custom ranges using the **`range`** keyword.
+
+## Selecting Custom Ranges
+
+Using the **`range`** keyword, custom ranges can be selected. Ranges must define a start cell and end cell with the syntax `range <start-cell>:<end-cell>`. All cells between these cells are part of the range as if a user had selected the start cell in a spreadsheet-software and dragged the mouse until the end cell. For example `range A1:B2` is a range over four cells, from cell `A1` to `B2`.
+
+Instead of a specific character or integer, the placeholder `*` denotes the last available cell in the row or column. For example: `A*` is the last cell in column `A` and `*2` is the last cell in row `2`.
+
+### Examples
+The following `CellRangeSelector` block will select the four cells in the top left corner of a `Sheet`:
+
+<div class="side-by-side__container">
+
+```jayvee
+ block ExampleDataSelector oftype CellRangeSelector {
+   select: range A1:B2;
+ }
+```
+
+<table>
+    <tr>
+        <td></td>
+        <td>A</td>
+        <td>B</td>
+        <td>C</td>
+    </tr>
+    <tr>
+        <td>1</td>
+        <td class="example-table__highlighted">Cell A1</td>
+        <td class="example-table__highlighted">Cell B1</td>
+        <td>Cell C1</td>
+    </tr>
+    <tr>
+        <td>2</td>
+        <td class="example-table__highlighted">Cell A2</td>
+        <td class="example-table__highlighted">Cell B2</td>
+        <td>Cell C2</td>
+    </tr>
+    <tr>
+        <td>3</td>
+        <td>Cell A3</td>
+        <td>Cell B3</td>
+        <td>Cell C3</td>
+    </tr>
+</table>
+</div>
+
+The following `CellRangeSelector` block will select cells from the first to the last cell in row 2 in a `Sheet`:
+
+<div class="side-by-side__container">
+
+```jayvee
+ block ExampleDataSelector oftype CellRangeSelector {
+   select: range A2:*2;
+ }
+```
+
+<table>
+    <tr>
+        <td></td>
+        <td>A</td>
+        <td>B</td>
+        <td>C</td>
+    </tr>
+    <tr>
+        <td>1</td>
+        <td>Cell A1</td>
+        <td>Cell B1</td>
+        <td>Cell C1</td>
+    </tr>
+    <tr>
+        <td>2</td>
+        <td class="example-table__highlighted">Cell A2</td>
+        <td class="example-table__highlighted">Cell B2</td>
+        <td class="example-table__highlighted">Cell C2</td>
+    </tr>
+    <tr>
+        <td>3</td>
+        <td>Cell A3</td>
+        <td>Cell B3</td>
+        <td>Cell C3</td>
+    </tr>
+</table>
+</div>
+
+The following `CellRangeSelector` block will select cells from the top-left most cell to the last cell in column B in a `Sheet`:
+
+<div class="side-by-side__container">
+
+```jayvee
+ block ExampleDataSelector oftype CellRangeSelector {
+   select: range A1:B*;
+ }
+```
+
+<table>
+    <tr>
+        <td></td>
+        <td>A</td>
+        <td>B</td>
+        <td>C</td>
+    </tr>
+    <tr>
+        <td>1</td>
+        <td class="example-table__highlighted">Cell A1</td>
+        <td class="example-table__highlighted">Cell B1</td>
+        <td>Cell C1</td>
+    </tr>
+    <tr>
+        <td>2</td>
+        <td class="example-table__highlighted">Cell A2</td>
+        <td class="example-table__highlighted">Cell B2</td>
+        <td>Cell C2</td>
+    </tr>
+    <tr>
+        <td>3</td>
+        <td class="example-table__highlighted">Cell A3</td>
+        <td class="example-table__highlighted">Cell B3</td>
+        <td>Cell C3</td>
+    </tr>
+</table>
+</div>
+
+## Selecting Rows
+
+Using the **`row`** keyword, individual rows can be selected. For example, `row 2` will select the second row in a `Sheet`. By adding multiple rows to a `Collection<CellRange>`, multiple rows can be selected.
+
+### Examples
+The following `RowDeleter` block will delete the first two rows of a `Sheet`:
+
+<div class="side-by-side__container">
+
+```jayvee
+ block ExampleRowDeleter oftype RowDeleter {
+   delete: [row 1, row 2];
+ }
+```
+
+<table>
+    <tr>
+        <td></td>
+        <td>A</td>
+        <td>B</td>
+        <td>C</td>
+    </tr>
+    <tr>
+        <td>1</td>
+        <td class="example-table__highlighted">Cell A1</td>
+        <td class="example-table__highlighted">Cell B1</td>
+        <td class="example-table__highlighted">Cell C1</td>
+    </tr>
+    <tr>
+        <td>2</td>
+        <td class="example-table__highlighted">Cell A2</td>
+        <td class="example-table__highlighted">Cell B2</td>
+        <td class="example-table__highlighted">Cell C2</td>
+    </tr>
+    <tr>
+        <td>3</td>
+        <td>Cell A3</td>
+        <td>Cell B3</td>
+        <td>Cell C3</td>
+    </tr>
+</table>
+</div>
+
+## Selecting Columns
+
+Using the **`column`** keyword, individual columns can be selected. For example, `column 2` will select the second column in a `Sheet`. By adding multiple columns to a `Collection<CellRange>`, multiple columns can be selected.
+
+### Examples
+The following `ColumnDeleter` block will delete the first two columns of a `Sheet`:
+
+<div class="side-by-side__container">
+
+```jayvee
+ block ExampleColumnDeleter oftype ColumnDeleter {
+   delete: [column A, column B];
+ }
+```
+
+<table>
+    <tr>
+        <td></td>
+        <td>A</td>
+        <td>B</td>
+        <td>C</td>
+    </tr>
+    <tr>
+        <td>1</td>
+        <td class="example-table__highlighted">Cell A1</td>
+        <td class="example-table__highlighted">Cell B1</td>
+        <td>Cell C1</td>
+    </tr>
+    <tr>
+        <td>2</td>
+        <td class="example-table__highlighted">Cell A2</td>
+        <td class="example-table__highlighted">Cell B2</td>
+        <td>Cell C2</td>
+    </tr>
+    <tr>
+        <td>3</td>
+        <td class="example-table__highlighted">Cell A3</td>
+        <td class="example-table__highlighted">Cell B3</td>
+        <td>Cell C3</td>
+    </tr>
+</table>
+</div>
diff --git a/apps/docs/docs/user/cell-range.md.license b/apps/docs/docs/user/cell-range.md.license
@@ -0,0 +1,3 @@
+SPDX-FileCopyrightText: 2024 Friedrich-Alexander-Universitat Erlangen-Nurnberg
+
+SPDX-License-Identifier: AGPL-3.0-only
diff --git a/apps/docs/docs/user/runtime-parameters.md b/apps/docs/docs/user/runtime-parameters.md
@@ -1,5 +1,5 @@
 ---
-sidebar_position: 9
+sidebar_position: 10
 ---
 
 # Runtime Parameters

diff --git a/apps/docs/src/css/custom.css b/apps/docs/src/css/custom.css
@@ -36,12 +36,13 @@
 }
 
 .header-github-link:before {
-    background: url("data:image/svg+xml;charset=utf-8,%3Csvg viewBox='0 0 24 24' xmlns='http://www.w3.org/2000/svg'%3E%3Cpath d='M12 .297c-6.63 0-12 5.373-12 12 0 5.303 3.438 9.8 8.205 11.385.6.113.82-.258.82-.577 0-.285-.01-1.04-.015-2.04-3.338.724-4.042-1.61-4.042-1.61C4.422 18.07 3.633 17.7 3.633 17.7c-1.087-.744.084-.729.084-.729 1.205.084 1.838 1.236 1.838 1.236 1.07 1.835 2.809 1.305 3.495.998.108-.776.417-1.305.76-1.605-2.665-.3-5.466-1.332-5.466-5.93 0-1.31.465-2.38 1.235-3.22-.135-.303-.54-1.523.105-3.176 0 0 1.005-.322 3.3 1.23.96-.267 1.98-.399 3-.405 1.02.006 2.04.138 3 .405 2.28-1.552 3.285-1.23 3.285-1.23.645 1.653.24 2.873.12 3.176.765.84 1.23 1.91 1.23 3.22 0 4.61-2.805 5.625-5.475 5.92.42.36.81 1.096.81 2.22 0 1.606-.015 2.896-.015 3.286 0 .315.21.69.825.57C20.565 22.092 24 17.592 24 12.297c0-6.627-5.373-12-12-12'/%3E%3C/svg%3E") no-repeat;
-    display: flex;
-    height: 24px;
-    width: 24px;
-    content: "";
+  background: url("data:image/svg+xml;charset=utf-8,%3Csvg viewBox='0 0 24 24' xmlns='http://www.w3.org/2000/svg'%3E%3Cpath d='M12 .297c-6.63 0-12 5.373-12 12 0 5.303 3.438 9.8 8.205 11.385.6.113.82-.258.82-.577 0-.285-.01-1.04-.015-2.04-3.338.724-4.042-1.61-4.042-1.61C4.422 18.07 3.633 17.7 3.633 17.7c-1.087-.744.084-.729.084-.729 1.205.084 1.838 1.236 1.838 1.236 1.07 1.835 2.809 1.305 3.495.998.108-.776.417-1.305.76-1.605-2.665-.3-5.466-1.332-5.466-5.93 0-1.31.465-2.38 1.235-3.22-.135-.303-.54-1.523.105-3.176 0 0 1.005-.322 3.3 1.23.96-.267 1.98-.399 3-.405 1.02.006 2.04.138 3 .405 2.28-1.552 3.285-1.23 3.285-1.23.645 1.653.24 2.873.12 3.176.765.84 1.23 1.91 1.23 3.22 0 4.61-2.805 5.625-5.475 5.92.42.36.81 1.096.81 2.22 0 1.606-.015 2.896-.015 3.286 0 .315.21.69.825.57C20.565 22.092 24 17.592 24 12.297c0-6.627-5.373-12-12-12'/%3E%3C/svg%3E") no-repeat;
+  display: flex;
+  height: 24px;
+  width: 24px;
+  content: "";
 }
+
 .header-github-link:hover {
   opacity: 0.6;
 }
@@ -50,4 +51,15 @@
   background: linear-gradient(45deg, var(--ifm-color-primary), var(--ifm-color-primary-lightest) 80%);
   background-clip: text;
   -webkit-text-fill-color: transparent;
+}
+
+.example-table__highlighted {
+  background-color: var(--ifm-color-primary-lightest);
+}
+
+.side-by-side__container {
+  display: flex;
+  flex-direction: row;
+  flex-wrap: wrap;
+  justify-content: space-evenly;
 }
diff --git a/libs/language-server/src/stdlib/builtin-block-types/CellRangeSelector.jv b/libs/language-server/src/stdlib/builtin-block-types/CellRangeSelector.jv
@@ -15,7 +15,7 @@ publish builtin blocktype CellRangeSelector {
 	output default oftype Sheet;
 
 	/**
-	* The cell range to select.
+	* The cell range to select. See <https://jvalue.github.io/jayvee/docs/user/cell-range>.
 	*/
 	property select oftype CellRange;
 }
diff --git a/libs/language-server/src/stdlib/builtin-block-types/CellWriter.jv b/libs/language-server/src/stdlib/builtin-block-types/CellWriter.jv
@@ -27,7 +27,7 @@ publish builtin blocktype CellWriter {
 	property write oftype Collection<text>;
 
 	/**
-	* The cells to write into.
+	* The cells to write into. See <https://jvalue.github.io/jayvee/docs/user/cell-range>.
 	*/
 	property at oftype CellRange;
 }
diff --git a/libs/language-server/src/stdlib/builtin-block-types/ColumnDeleter.jv b/libs/language-server/src/stdlib/builtin-block-types/ColumnDeleter.jv
@@ -15,7 +15,7 @@ publish builtin blocktype ColumnDeleter {
 	output default oftype Sheet;
 
 	/** 
-	* The columns to delete. Has to be a full column.
+	* The columns to delete. Has to be a full column. See <https://jvalue.github.io/jayvee/docs/user/cell-range>.
 	*/
 	property delete oftype Collection<CellRange>;
 }
diff --git a/libs/language-server/src/stdlib/builtin-block-types/RowDeleter.jv b/libs/language-server/src/stdlib/builtin-block-types/RowDeleter.jv
@@ -15,7 +15,7 @@ publish builtin blocktype RowDeleter {
 	output default oftype Sheet;
 
 	/**
-	* The rows to delete.
+	* The rows to delete. See <https://jvalue.github.io/jayvee/docs/user/cell-range>.
 	*/
 	property delete oftype Collection<CellRange>;
 }