docs: updated items/collections

kalisio · Oct 6, 2024 · 4aefb3b · 4aefb3b
1 parent 85c44c8
commit 4aefb3b
Show file tree

Hide file tree

Showing 17 changed files with 389 additions and 2 deletions.
diff --git a/.gitignore b/.gitignore
@@ -33,8 +33,9 @@ lib/
 # dotenv environment variables file
 .env
 
-# gitbook build
-_book/
+# draw.io backup
+*.bkp
+*.dtmp
 
 # vitepress
 docs/.vitepress/cache

diff --git a/docs/.vitepress/public/items.drawio b/docs/.vitepress/public/items.drawio
@@ -0,0 +1,84 @@
+<mxfile host="Electron" modified="2024-10-06T20:11:56.618Z" agent="Mozilla/5.0 (X11; Linux x86_64) AppleWebKit/537.36 (KHTML, like Gecko) draw.io/24.5.1 Chrome/124.0.6367.207 Electron/30.0.6 Safari/537.36" etag="3zzpfvAGJPawzNM8dYS5" version="24.5.1" type="device" pages="2">
+  <diagram id="IqU7WHgcD0uiOO1NTE0H" name="KCard">
+    <mxGraphModel dx="1487" dy="969" grid="1" gridSize="10" guides="1" tooltips="1" connect="1" arrows="1" fold="1" page="1" pageScale="1" pageWidth="827" pageHeight="1169" math="0" shadow="0">
+      <root>
+        <mxCell id="0" />
+        <mxCell id="1" parent="0" />
+        <mxCell id="HvI_MeQyovm3IAeio-AX-49" value="" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#dae8fc;strokeColor=#6c8ebf;sketch=1;curveFitting=1;jiggle=2;" vertex="1" parent="1">
+          <mxGeometry x="490" y="770" width="350" height="150" as="geometry" />
+        </mxCell>
+        <mxCell id="qZt2UY9Dv8WojuRAOEdF-6" value="" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#dae8fc;strokeColor=#6c8ebf;sketch=1;curveFitting=1;jiggle=2;" parent="1" vertex="1">
+          <mxGeometry x="130" y="140" width="350" height="370" as="geometry" />
+        </mxCell>
+        <mxCell id="HvI_MeQyovm3IAeio-AX-1" value="Header" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#fff2cc;strokeColor=#d6b656;sketch=1;curveFitting=1;jiggle=2;" vertex="1" parent="1">
+          <mxGeometry x="140" y="147" width="330" height="40" as="geometry" />
+        </mxCell>
+        <mxCell id="HvI_MeQyovm3IAeio-AX-2" value="Footer" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#fff2cc;strokeColor=#d6b656;sketch=1;curveFitting=1;jiggle=2;" vertex="1" parent="1">
+          <mxGeometry x="140" y="447" width="330" height="40" as="geometry" />
+        </mxCell>
+        <mxCell id="HvI_MeQyovm3IAeio-AX-5" value="Sections" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#fff2cc;strokeColor=#d6b656;sketch=1;curveFitting=1;jiggle=2;" vertex="1" parent="1">
+          <mxGeometry x="140" y="240" width="330" height="200" as="geometry" />
+        </mxCell>
+        <mxCell id="HvI_MeQyovm3IAeio-AX-7" value="" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#dae8fc;strokeColor=#6c8ebf;sketch=1;curveFitting=1;jiggle=2;" vertex="1" parent="1">
+          <mxGeometry x="520" y="140" width="350" height="540" as="geometry" />
+        </mxCell>
+        <mxCell id="HvI_MeQyovm3IAeio-AX-8" value="Header" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#fff2cc;strokeColor=#d6b656;sketch=1;curveFitting=1;jiggle=2;" vertex="1" parent="1">
+          <mxGeometry x="530" y="147" width="330" height="40" as="geometry" />
+        </mxCell>
+        <mxCell id="HvI_MeQyovm3IAeio-AX-9" value="Footer" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#fff2cc;strokeColor=#d6b656;sketch=1;curveFitting=1;jiggle=2;" vertex="1" parent="1">
+          <mxGeometry x="530" y="616" width="330" height="40" as="geometry" />
+        </mxCell>
+        <mxCell id="HvI_MeQyovm3IAeio-AX-10" value="Sections" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#fff2cc;strokeColor=#d6b656;sketch=1;curveFitting=1;jiggle=2;" vertex="1" parent="1">
+          <mxGeometry x="530" y="240" width="330" height="200" as="geometry" />
+        </mxCell>
+        <mxCell id="HvI_MeQyovm3IAeio-AX-32" value="Heading" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#fff2cc;strokeColor=#d6b656;sketch=1;curveFitting=1;jiggle=2;" vertex="1" parent="1">
+          <mxGeometry x="140" y="194" width="330" height="40" as="geometry" />
+        </mxCell>
+        <mxCell id="HvI_MeQyovm3IAeio-AX-33" value="Heading" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#fff2cc;strokeColor=#d6b656;sketch=1;curveFitting=1;jiggle=2;" vertex="1" parent="1">
+          <mxGeometry x="530" y="194" width="330" height="40" as="geometry" />
+        </mxCell>
+        <mxCell id="HvI_MeQyovm3IAeio-AX-34" value="" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#fff2cc;strokeColor=#d6b656;sketch=1;curveFitting=1;jiggle=2;" vertex="1" parent="1">
+          <mxGeometry x="140" y="630" width="330" height="40" as="geometry" />
+        </mxCell>
+        <mxCell id="HvI_MeQyovm3IAeio-AX-35" value="Content" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#dae8fc;strokeColor=#6c8ebf;sketch=1;curveFitting=1;jiggle=2;" vertex="1" parent="1">
+          <mxGeometry x="150" y="637" width="310" height="25" as="geometry" />
+        </mxCell>
+        <mxCell id="HvI_MeQyovm3IAeio-AX-36" value="" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#fff2cc;strokeColor=#d6b656;sketch=1;curveFitting=1;jiggle=2;" vertex="1" parent="1">
+          <mxGeometry x="140" y="690" width="330" height="40" as="geometry" />
+        </mxCell>
+        <mxCell id="HvI_MeQyovm3IAeio-AX-37" value="A" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#ffe6cc;strokeColor=#d79b00;sketch=1;curveFitting=1;jiggle=2;" vertex="1" parent="1">
+          <mxGeometry x="150" y="697" width="30" height="25" as="geometry" />
+        </mxCell>
+        <mxCell id="HvI_MeQyovm3IAeio-AX-38" value="Title" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#ffe6cc;strokeColor=#d79b00;sketch=1;curveFitting=1;jiggle=2;" vertex="1" parent="1">
+          <mxGeometry x="190" y="697.5" width="270" height="25" as="geometry" />
+        </mxCell>
+        <mxCell id="HvI_MeQyovm3IAeio-AX-12" value="" style="html=1;verticalLabelPosition=bottom;labelBackgroundColor=#ffffff;verticalAlign=top;shadow=0;dashed=0;strokeWidth=2;shape=mxgraph.ios7.misc.down;strokeColor=#808080;rotation=-180;sketch=1;curveFitting=1;jiggle=2;" vertex="1" parent="1">
+          <mxGeometry x="688.61" y="668" width="13.391304347826086" height="7" as="geometry" />
+        </mxCell>
+        <mxCell id="HvI_MeQyovm3IAeio-AX-14" value="" style="html=1;verticalLabelPosition=bottom;labelBackgroundColor=#ffffff;verticalAlign=top;shadow=0;dashed=0;strokeWidth=2;shape=mxgraph.ios7.misc.down;strokeColor=#808080;" vertex="1" parent="1">
+          <mxGeometry x="295.99869565217386" y="497.5" width="13.391304347826086" height="7" as="geometry" />
+        </mxCell>
+        <mxCell id="HvI_MeQyovm3IAeio-AX-45" value="Expandable&lt;div&gt;sections&lt;/div&gt;" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#fff2cc;strokeColor=#d6b656;sketch=1;curveFitting=1;jiggle=2;" vertex="1" parent="1">
+          <mxGeometry x="530" y="447" width="330" height="163" as="geometry" />
+        </mxCell>
+        <mxCell id="HvI_MeQyovm3IAeio-AX-46" value="Title" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#fff2cc;strokeColor=#d6b656;sketch=1;curveFitting=1;jiggle=2;" vertex="1" parent="1">
+          <mxGeometry x="498" y="779" width="196" height="25" as="geometry" />
+        </mxCell>
+        <mxCell id="HvI_MeQyovm3IAeio-AX-47" value="Actions" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#dae8fc;strokeColor=#6c8ebf;sketch=1;curveFitting=1;jiggle=2;" vertex="1" parent="1">
+          <mxGeometry x="702" y="779" width="130" height="25" as="geometry" />
+        </mxCell>
+        <mxCell id="HvI_MeQyovm3IAeio-AX-51" value="Custom" style="rounded=0;whiteSpace=wrap;html=1;fillColor=#e1d5e7;strokeColor=#9673a6;sketch=1;curveFitting=1;jiggle=2;" vertex="1" parent="1">
+          <mxGeometry x="498" y="810" width="334" height="100" as="geometry" />
+        </mxCell>
+      </root>
+    </mxGraphModel>
+  </diagram>
+  <diagram id="3J6XpfmjnVEyp5UPETQi" name="KItem">
+    <mxGraphModel dx="1784" dy="1163" grid="1" gridSize="10" guides="1" tooltips="1" connect="1" arrows="1" fold="1" page="1" pageScale="1" pageWidth="827" pageHeight="1169" math="0" shadow="0">
+      <root>
+        <mxCell id="0" />
+        <mxCell id="1" parent="0" />
+      </root>
+    </mxGraphModel>
+  </diagram>
+</mxfile>
diff --git a/docs/api/core/components.md b/docs/api/core/components.md
@@ -121,6 +121,9 @@ The **k-table** component is powered by [Quasar lists](https://quasar.dev/vue-co
 
 The same properties as with the **k-grid** component can be used to customize it. There is no specific component to be used to render items as it relies on the rows of the table. As a consequence, the `item-actions` property has to be directly set on the **k-table** component.
 
+
+## [Items](./components/items.md)
+
 ## Forms 
 
 The **k-form** is a generic form component capable of building HTML forms from of a [JSON schema](https://json-schema.org/). Moreover **k-form** validates that the data is conformed to the schema using [AJV validator](https://github.com/epoberezkin/ajv). 

diff --git a/docs/api/core/components/collections.md b/docs/api/core/components/collections.md
@@ -0,0 +1,50 @@
+# Collections
+
+**Collections** are specialized components used to render collection of objects. 
+
+The **KDK** provides a set of pre-built **Collections** components. These components are based on the [useCollection](../composables.md#usecollection) composable which can also be used to develop your own **Collection** components.
+
+## Pre-built Collections
+
+### KGrid
+
+The **KGrid** component provides two different ways to render a collection: using _pagination_ or _infinite scroll_.
+
+* `pagination` mode
+
+  ![KGrid](./diagrams/kgrid-pagination.png)
+
+  The items are rendered page per page and the **Pagination** part enables the user to navigate though the pages. It is implemented using the **Quasar** [Pagination](https://quasar.dev/vue-components/pagination) component.
+
+* `infinite scroll` mode
+
+  ![KGrid](./diagrams/kgrid-infinite-scroll.png)
+
+  The items are rendered as long as the user scroll down. In that mode, two buttons are displayed :
+    * a **Scroll down** which is displayed as long as there are items to be loaded.
+    * a **Scroll to top** which allows the user to return to the top of the page.
+
+  ::: tip
+  These buttons can be hidden if needed.
+  :::
+
+In both modes, the **KGrid** component let you provide a **Header** or **Footer** which are implemented using a **KPanel**:
+
+![KGrid Header/Footer](./diagrams/kgrid-header-footer.png)
+
+Regarding the items, the **KGrid** component, rely on a **Renderer** to render an item. A **Renderer** is an abstract objet that define:
+* the component used to render each item, called [Items](./items.md) component
+* the _props_ to be applied to the **Item** component
+* the _layout_ to be used to render the items. By default, the items are rendered using a **Grid** layout. But you can easily define the layout you desire using **Quasar** [responsive classes](https://quasar.dev/layout/grid/row#responsive-classes). For example, assigning the `class="col-12"` to the renderer allows you to display the items as a **List**.
+
+  ![KGrid layouts](./diagrams/kgrid-layout.png)
+
+### KTable
+
+_TODO_
+
+### KTimeLine
+
+_TODO_
+
+## Custom Collections