From 60b9f16d8f3d4cb644f992ee436a5e2f809196cf Mon Sep 17 00:00:00 2001 From: inga Date: Tue, 14 May 2024 11:25:06 +0200 Subject: [PATCH] chore: add more documentation --- .../lib/components/list/list-documentation.md | 131 ++++++++++++++++-- 1 file changed, 122 insertions(+), 9 deletions(-) diff --git a/libs/sketch/src/lib/components/list/list-documentation.md b/libs/sketch/src/lib/components/list/list-documentation.md index f79898c..88d1972 100644 --- a/libs/sketch/src/lib/components/list/list-documentation.md +++ b/libs/sketch/src/lib/components/list/list-documentation.md @@ -2,9 +2,11 @@ The List Component gives you the opportunity to list items and even nest them. You can also connect it to routing to have deep links to nested items. +It can be used for normal lists (with the option for routing) or a Folder like structure with. + ## Basic Usage -Lets have a look at the basic usage of the List without children: +### Without Children (no Routing) ```html @@ -18,9 +20,35 @@ Lets have a look at the basic usage of the List without children: ``` -As you see, you only need the `sk-list` and `sk-list-item` with `[skListItemId]` to get started. +As you see, you only need the `sk-list` with `skListProvider` and `sk-list-item` with a unique [`[skListItemId]`](#inputsoutputs) and an `skLabel` to get started. + +> The `[skListItemId]` is an identifier for the individual items and must be unique for each item. If it's not there, no item will be displayed. + +The `skLabel` declares the visible part of the item. When you don't set it, it is not visible but still there. It can contain any content you like.
+As element that holds the `skLabel` you can use what you want, for example `
`, ``, `

`, etc. + +### Without Children (with Routing) + +```html + + @for (item of items(); track item.id) { + +

+ {{ item.label }} +
+ + } + +``` + +In addition to the code above you just set the [`skEnableRouting`](#inputsoutputs) (which is the input set to true) and [`(activeIdChanged)`](#inputsoutputs). +(`itemActiveId` is a signal where the event from the output is set. You can use it to add styling depending on the route, conditional displaying of content etc.) -With child items it looks like this: +### With Children (no routing) ```html @@ -43,13 +71,92 @@ With child items it looks like this: ``` -You just nest another `sk-list` within the `sk-list-item`. Of course it works only if you have child items. -Let's have a closer look. +You just nest another `sk-list` within the `sk-list-item` and add `skChilds` to the list to declare it as children. +Not setting `skChilds` will result in not seeing them. + +> Once you opened a item to see the children, you can't close it to only see the parent elements. If you wish to do so, use the Collapse Component. + +> You can nest the children as deep as you want. It is recommended to nest it only two times. + +### With Children (with Routing) + +```html + + @for (item of items(); track item.id) { + +
+ {{ item.label }} +
+ @if (item.children?.length && itemActiveId() === item.id) { + + @for (childItem of item.children; track childItem.id) { + +
+ {{ childItem.label }} +
+ + } + + } + + } + +``` -## Child Elements +In addition to the code with routing above you just add the child with a `childActiveId`. It is also recommended to wrap it in a condition to check, if the child items are actually there. ## Styling +The `sk-list-item` has a basic default styling (You can find them in the [Properties Overview](#styling-with-custom-properties)). +You have the option to style it as you want with custom properties. + +Here is an example: + +```css +sk-list-item { + --sk-list-item-label-background: thistle; + --sk-list-item-label-color: purple; + --sk-list-item-label-padding: 0.5rem 2rem; + --sk-list-item-label-border: 3px solid indigo; + --sk-list-item-label-active-color: navy; +} +``` + +This only targets the list-item itself. Applying other styles does not change it. +To add styles like a `border-radius`, `box-shadow` etc., target the element with `skLabel` in it and add your styles. +The `--sk-list-item-label-background` should be set to transparent. The `--sk-list-item-label-border` should be set to `none` or `transparent` to avoid the lines in the gaps. +The label will have a width fitting it's content. Add your desired width to the label to change it. + +```css +sk-list-item { + --sk-list-item-label-background: transparent; + --sk-list-item-label-border: none; +} + +.sk-label { + width: 100%; + border-radius: 1rem; + background-color: thistle; + box-shadow: rgb(0 0 0 / 20%) 0 10px 20px; +} +``` + +> You can also adjust the displaying of the items. Use `display: flex/grid` to adjust it to your needs. + +### Animations + +You can add animations to your list. Just add the name of the animation to the `sk-list` and you are ready to go. + +### Active Items + +Whe you only want to style the label, use the custom property `--sk-list-item-label-active-color` and add a color. This wills style the text color. + +To style the active items (with routing) you could add a class `[class.active-item]` and add a condition `itemActiveId() === item.route`. This is great for transitions, scaling etc. + ## Properties Overview ### Inputs/Outputs @@ -70,7 +177,7 @@ Let's have a closer look. yes - Determines the unique id of the item. + Determines the unique identifier of the items. - @@ -106,13 +213,19 @@ Let's have a closer look. `(activeIdChanged)` - yes - Handles the change of the active id. + + +only when `skEnableRouting` is `true` + + + Handles the change of the active id for routing. ### Styling with custom properties +Apply the styles to the `sk-list-item`. +
Name Description Default Value