docs(list): improve examples & clarify things a bit more

This will also make it easier to test the implementation of
the new `limel-list-item` component later.

Author: Kiarokh

src/components/list/examples/list-action.tsx

@@ -1,5 +1,5 @@
 import { LimelListCustomEvent, ListItem } from '@limetech/lime-elements';
-import { Component, h } from '@stencil/core';
+import { Component, h, Host, State } from '@stencil/core';
 
 /**
  * List with action menu
@@ -9,6 +9,9 @@ import { Component, h } from '@stencil/core';
     shadow: true,
 })
 export class ListActionExample {
+    @State()
+    private lastEvent: string = 'No actions yet';
+
     private actionItems: Array<ListItem<number>> = [
         { text: 'Go to my fab object', value: 10 },
         { text: 'Delete object', value: 11 },
@@ -22,16 +25,24 @@ export class ListActionExample {
             actions: this.actionItems,
         },
         { text: 'Smash Up!', value: 2, icon: 'alien' },
-        { text: 'Pandemic', value: 3, icon: 'virus' },
-        { text: 'Catan', value: 4, icon: 'wheat' },
-        { text: 'Ticket to Ride', value: 5, icon: 'steam_engine' },
     ];
 
     public render() {
-        return <limel-list items={this.items} onSelect={this.onSelectAction} />;
+        return (
+            <Host>
+                <limel-list items={this.items} onSelect={this.onSelectAction} />
+                <limel-example-value
+                    label="Last action"
+                    value={this.lastEvent}
+                />
+            </Host>
+        );
     }
 
-    private onSelectAction(event: LimelListCustomEvent<ListItem>) {
-        console.log('Executing action:', event.detail);
-    }
+    private onSelectAction = (event: LimelListCustomEvent<ListItem>) => {
+        const detail = event.detail as any;
+        const valuePart =
+            detail && 'value' in detail ? `, value: ${detail.value}` : '';
+        this.lastEvent = `Executing action: ${detail?.text ?? 'unknown'}${valuePart}`;
+    };
 }

src/components/list/examples/list-badge-icons.tsx

@@ -1,15 +1,22 @@
 import { ListItem } from '@limetech/lime-elements';
-import { Component, h } from '@stencil/core';
+import { Component, h, Host, State } from '@stencil/core';
 
 /**
  * List with badge icons
+ * When `badgeIcons` is set to `true`, the icon's visual motif will be
+ * rendered slightly smaller, to provide more space for a colorful background.
+ * So when using a `backgroundColor` on the icon, it could be a good idea to
+ * also set the `badgeIcons` property to `true`.
  */
 @Component({
     tag: 'limel-example-list-badge-icons',
     shadow: true,
     styleUrl: 'list-badge-icons.scss',
 })
 export class BadgeIconsListExample {
+    @State()
+    private badgeIcons = true;
+
     private items: Array<ListItem<number>> = [
         {
             text: 'King of Tokyo',
@@ -42,6 +49,7 @@ export class BadgeIconsListExample {
             icon: {
                 name: 'wheat',
                 color: 'rgb(var(--color-amber-default))',
+                backgroundColor: 'rgb(var(--color-cyan-default))',
             },
         },
         {
@@ -50,12 +58,28 @@ export class BadgeIconsListExample {
             value: 5,
             icon: {
                 name: 'steam_engine',
-                color: 'rgb(var(--color-glaucous-default))',
+                color: 'rgb(var(--color-pink-lighter))',
             },
         },
     ];
 
     public render() {
-        return <limel-list items={this.items} badgeIcons={true} />;
+        return (
+            <Host>
+                <limel-list items={this.items} badgeIcons={this.badgeIcons} />
+                <limel-example-controls>
+                    <limel-checkbox
+                        checked={this.badgeIcons}
+                        label="badgeIcons"
+                        onChange={this.setBadgeIcons}
+                    />
+                </limel-example-controls>
+            </Host>
+        );
     }
+
+    private setBadgeIcons = (event: CustomEvent<boolean>) => {
+        event.stopPropagation();
+        this.badgeIcons = event.detail;
+    };
 }

src/components/list/examples/list-checkbox-icons.tsx

@@ -3,6 +3,11 @@ import { Component, h, State } from '@stencil/core';
 
 /**
  * List with checkboxes and icons
+ *
+ * By setting `type="checkbox"`, each list item will
+ * render a checkbox next to it, indicating the user can select
+ * more than one of the items, empowering you to create
+ * UIs that clearly indicate multiple selections.
  */
 @Component({
     tag: 'limel-example-list-checkbox-icons',
@@ -72,10 +77,19 @@ export class ListCheckboxIconsExample {
     @State()
     private selectedItems: ListItem[] = [];
 
+    @State()
+    private showIcons: boolean = true;
+
+    private originalIcons: Record<string, ListItem['icon']> = {};
+
     constructor() {
         this.selectedItems = this.items.filter((item) => {
             return !!item.selected;
         });
+
+        for (const item of this.items) {
+            this.originalIcons[String(item.value)] = item.icon;
+        }
     }
 
     public render() {
@@ -86,6 +100,13 @@ export class ListCheckboxIconsExample {
                 type="checkbox"
             />,
             <limel-example-value value={this.selectedItems} />,
+            <limel-example-controls>
+                <limel-checkbox
+                    checked={this.showIcons}
+                    label="icon"
+                    onChange={this.setIcon}
+                />
+            </limel-example-controls>,
         ];
     }
 
@@ -99,4 +120,14 @@ export class ListCheckboxIconsExample {
             return { ...item, selected: selected };
         });
     };
+
+    private setIcon = (event: CustomEvent<boolean>) => {
+        this.showIcons = event.detail;
+        this.items = this.items.map((item) => ({
+            ...item,
+            icon: this.showIcons
+                ? this.originalIcons[String(item.value)]
+                : undefined,
+        }));
+    };
 }

src/components/list/examples/list-checkbox.tsx

@@ -3,6 +3,21 @@ import { Component, h } from '@stencil/core';
 
 /**
  * List with a primary component
+ *
+ * List items can render a custom primary component using the
+ * `primaryComponent` prop.
+ *
+ * :::tip
+ * By default, the primary component is rendered after the icon
+ * and before the item's text.
+ *
+ * Since the list item is a flexbox, you can easily change the
+ * order of the primary component by applying a different `order`
+ * via `style`.
+ *
+ * You can set `order` either via the primary component's own styles,
+ * or via its `props`.
+ * :::
  */
 @Component({
     tag: 'limel-example-list-primary-component',
@@ -21,6 +36,10 @@ export class ListCircularProgressExample {
                     maxValue: 10,
                     suffix: '%',
                     displayPercentageColors: true,
+                    size: 'small',
+                    style: {
+                        order: 3,
+                    },
                 },
             },
         },
@@ -35,6 +54,7 @@ export class ListCircularProgressExample {
                     maxValue: 10,
                     suffix: '%',
                     displayPercentageColors: true,
+                    size: 'small',
                 },
             },
         },
@@ -49,6 +69,7 @@ export class ListCircularProgressExample {
                     maxValue: 10,
                     suffix: '%',
                     displayPercentageColors: true,
+                    size: 'small',
                 },
             },
         },
@@ -63,6 +84,7 @@ export class ListCircularProgressExample {
                     maxValue: 10,
                     suffix: '%',
                     displayPercentageColors: true,
+                    size: 'small',
                 },
             },
         },

src/components/list/examples/list-primary-component.tsx

@@ -3,6 +3,11 @@ import { Component, h, State } from '@stencil/core';
 
 /**
  * List with radio buttons and icons
+ *
+ * By setting `type="radio"`, each list item will
+ * render a radio button next to it, indicating the user can select
+ * only one of the items at a time, empowering you to create
+ * UIs that clearly indicate single selections.
  */
 @Component({
     tag: 'limel-example-list-radio-button-icons',
@@ -72,10 +77,19 @@ export class ListRadioButtonIconsExample {
     @State()
     private selectedItem: ListItem;
 
+    @State()
+    private showIcons: boolean = true;
+
+    private originalIcons: Record<string, ListItem['icon']> = {};
+
     constructor() {
         this.selectedItem = this.items.find((item) => {
             return !!item.selected;
         });
+
+        for (const item of this.items) {
+            this.originalIcons[String(item.value)] = item.icon;
+        }
     }
 
     public render() {
@@ -86,6 +100,13 @@ export class ListRadioButtonIconsExample {
                 type="radio"
             />,
             <limel-example-value value={this.selectedItem} />,
+            <limel-example-controls>
+                <limel-checkbox
+                    checked={this.showIcons}
+                    label="icon"
+                    onChange={this.setIcon}
+                />
+            </limel-example-controls>,
         ];
     }
 
@@ -99,4 +120,14 @@ export class ListRadioButtonIconsExample {
             return item;
         });
     };
+
+    private setIcon = (event: CustomEvent<boolean>) => {
+        this.showIcons = event.detail;
+        this.items = this.items.map((item) => ({
+            ...item,
+            icon: this.showIcons
+                ? this.originalIcons[String(item.value)]
+                : undefined,
+        }));
+    };
 }