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

Kiarokh · 2025-08-20T15:04:32Z

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

related to https://github.com/Lundalogik/crm-client/issues/216

Summary by CodeRabbit

New Features
- Examples now display the last triggered action/event.
- Added toggles to show/hide item icons and to enable badge-style icons in lists.
- Selectable list example includes a disabled item and live event display.
- Primary component example updated with size and ordering controls.
Documentation
- Expanded guidance on selectable lists and custom primary components.
- Reorganized example listings in the component docs.
Chores
- Removed outdated checkbox and radio-button list examples.

Review:

Commits are atomic
Commits have the correct type for the changes made
Commits with breaking changes are marked as such

Browsers tested:

(Check any that applies, it's ok to leave boxes unchecked if testing something didn't seem relevant.)

Windows:

Chrome
Edge
Firefox

Linux:

Chrome
Firefox

macOS:

Chrome
Firefox
Safari

Mobile:

Chrome on Android
iOS

coderabbitai · 2025-08-20T15:04:39Z

Important

Review skipped

Auto incremental reviews are disabled on this repository.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

📝 Walkthrough

Walkthrough

Updates multiple list example components: add reactive state and UI controls (icon toggles, badge icon toggle), display last event/action, adjust example data and docs, and wrap some renders in Host. Two example components (checkbox and radio-button) are removed, and list.tsx JSDoc example references are reordered.

Changes

Cohort / File(s)	Summary of changes
Action example state + display `src/components/list/examples/list-action.tsx`	Adds @State lastEvent, changes onSelectAction to arrow fn updating lastEvent, reduces items, and renders limel-list plus limel-example-value.
Icon toggle controls (checkbox/radio) `src/components/list/examples/list-checkbox-icons.tsx`, `src/components/list/examples/list-radio-button-icons.tsx`	Introduces showIcons state, caches original icons, adds limel-example-controls with checkbox to toggle icons, updates item icons accordingly.
Badge icons toggle `src/components/list/examples/list-badge-icons.tsx`	Adds @State badgeIcons, Host-wrapped render, checkbox control to toggle badgeIcons; updates some item colors/backgrounds; adds explanatory doc comment.
Selectable example: event display + disabled item `src/components/list/examples/list-selectable.tsx`	Imports Host; adds @State lastEvent; marks "Catan" disabled; renders list plus lastEvent value; handleChange now records event detail text/selected before updating items.
Primary component example doc/data tweak `src/components/list/examples/list-primary-component.tsx`	Expands docs; passes size: 'small' to primary components; first item adds style order: 3.
Remove deprecated examples `src/components/list/examples/list-checkbox.tsx`, `src/components/list/examples/list-radio-button.tsx`	Deletes both example components.
Example references reorder `src/components/list/list.tsx`	Updates JSDoc @exampleComponent list: reorders entries, removes radio-button example, swaps in selectable where checkbox was.

Sequence Diagram(s)

sequenceDiagram
  participant U as User
  participant L as limel-list
  participant EX as Example Component
  participant V as limel-example-value

  U->>L: select action (onSelect)
  L-->>EX: LimelListCustomEvent<ListItem>
  rect rgba(214,234,248,0.3)
    note right of EX: Update reactive state
    EX->>EX: onSelectAction formats "Executing action: ..."
    EX->>EX: this.lastEvent = message
  end
  EX-->>V: value=lastEvent (re-render)

sequenceDiagram
  participant U as User
  participant C as limel-checkbox
  participant EX as Example Component
  participant L as limel-list

  U->>C: toggle "icon"/"badgeIcons"
  C-->>EX: CustomEvent<boolean>
  rect rgba(232,248,245,0.4)
    note right of EX: Sync state and items
    EX->>EX: stopPropagation()
    EX->>EX: update state (showIcons/badgeIcons)
    EX->>EX: map items to set/restore icons (if applicable)
  end
  EX-->>L: props updated (items, badgeIcons)

sequenceDiagram
  participant U as User
  participant L as limel-list (selectable)
  participant EX as Example Component
  participant V as limel-example-value

  U->>L: change selection
  L-->>EX: LimelListCustomEvent<ListItem>
  EX->>EX: lastEvent = "Selected: {text}, selected: {selected}"
  EX->>EX: update items with event.detail
  EX-->>V: value=lastEvent

Estimated code review effort

🎯 3 (Moderate) | ⏱️ ~25 minutes

Possibly related PRs

Add limel-radio-button-group component with examples and documentation updates #3638 — Also modifies list/radio-related examples and example listings, overlapping with the removal/reordering of radio-button and selectable examples here.

Suggested labels

docs, maintenance

Suggested reviewers

adrianschmidt
Befkadu1
jgroth

✨ Finishing Touches

🧪 Generate unit tests

Create PR with unit tests
Post copyable unit tests in a comment
Commit unit tests in branch improve-list-docs

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

🪧 Tips

Chat

There are 3 ways to chat with CodeRabbit:

‼️ IMPORTANT
Auto-reply has been disabled for this repository in the CodeRabbit settings. The CodeRabbit bot will not respond to your replies unless it is explicitly tagged.

Files and specific lines of code (under the "Files changed" tab): Tag @coderabbitai in a new review comment at the desired location with your query.
PR comments: Tag @coderabbitai in a new PR comment to ask questions about the PR branch. For the best results, please provide a very specific query, as very limited context is provided in this mode. Examples:
- @coderabbitai gather interesting stats about this repository and render them as a table. Additionally, render a pie chart showing the language distribution in the codebase.
- @coderabbitai read the files in the src/scheduler package and generate a class diagram using mermaid and a README in the markdown format.

Support

Need help? Create a ticket on our support page for assistance with any issues or questions.

CodeRabbit Commands (Invoked using PR/Issue comments)

Type @coderabbitai help to get the list of available commands.

Other keywords and placeholders

Add @coderabbitai ignore anywhere in the PR description to prevent this PR from being reviewed.
Add @coderabbitai summary to generate the high-level summary at a specific location in the PR description.
Add @coderabbitai anywhere in the PR title to generate the title automatically.

Status, Documentation and Community

Visit our Status Page to check the current availability of CodeRabbit.
Visit our Documentation for detailed information on how to use CodeRabbit.
Join our Discord Community to get help, request features, and share feedback.
Follow us on X/Twitter for updates and announcements.

github-actions · 2025-08-20T15:07:10Z

Documentation has been published to https://lundalogik.github.io/lime-elements/versions/PR-3651/

coderabbitai

Actionable comments posted: 10

Caution

Some comments are outside the diff and can’t be posted inline due to platform limitations.

⚠️ Outside diff range comments (3)

src/components/list/examples/list-radio-button-icons.tsx (1)

96-111: Don’t return an array of JSX elements; wrap in Host.

Per our Stencil guidelines, avoid array literals at the top level. This also sidesteps “missing key” lints.

Apply this diff:

-    public render() {
-        return [
-            <limel-list
-                onChange={this.handleChange}
-                items={this.items}
-                type="radio"
-            />,
-            <limel-example-value value={this.selectedItem} />,
-            <limel-example-controls>
-                <limel-checkbox
-                    checked={this.showIcons}
-                    label="icon"
-                    onChange={this.setIcon}
-                />
-            </limel-example-controls>,
-        ];
-    }
+    public render() {
+        return (
+            <Host>
+                <limel-list
+                    onChange={this.handleChange}
+                    items={this.items}
+                    type="radio"
+                />
+                <limel-example-value value={this.selectedItem} />
+                <limel-example-controls>
+                    <limel-checkbox
+                        checked={this.showIcons}
+                        label="icon"
+                        onChange={this.setIcon}
+                    />
+                </limel-example-controls>
+            </Host>
+        );
+    }

Additionally, ensure Host is imported:

// at top of file
import { Component, h, State, Host } from '@stencil/core';

src/components/list/examples/list-checkbox-icons.tsx (2)

96-112: Wrap multiple top-level elements in Host instead of an array

Stencil examples must not return an array. Wrap siblings in to satisfy our guidelines and fix the Biome “Missing key property in iterable” error.

Apply this diff:

-    public render() {
-        return [
-            <limel-list
-                onChange={this.handleChange}
-                items={this.items}
-                type="checkbox"
-            />,
-            <limel-example-value value={this.selectedItems} />,
-            <limel-example-controls>
-                <limel-checkbox
-                    checked={this.showIcons}
-                    label="icon"
-                    onChange={this.setIcon}
-                />
-            </limel-example-controls>,
-        ];
-    }
+    public render() {
+        return (
+            <Host>
+                <limel-list
+                    onChange={this.handleChange}
+                    items={this.items}
+                    type="checkbox"
+                />
+                <limel-example-value value={this.selectedItems} />
+                <limel-example-controls>
+                    <limel-checkbox
+                        checked={this.showIcons}
+                        label="icon"
+                        onChange={this.setIcon}
+                    />
+                </limel-example-controls>
+            </Host>
+        );
+    }

Remember to import Host (see separate comment).

2-2: Import Host from @stencil/core

Required to use the Host wrapper in render.

-import { Component, h, State } from '@stencil/core';
+import { Component, h, Host, State } from '@stencil/core';

📜 Review details

Configuration used: .coderabbit.yaml
Review profile: ASSERTIVE
Plan: Pro

💡 Knowledge Base configuration:

MCP integration is disabled by default for public repositories
Jira integration is disabled
Linear integration is disabled

You can enable these sources in your CodeRabbit configuration.

📥 Commits

Reviewing files that changed from the base of the PR and between cc0eca8 and 843e442.

📒 Files selected for processing (9)

src/components/list/examples/list-action.tsx (3 hunks)
src/components/list/examples/list-badge-icons.tsx (3 hunks)
src/components/list/examples/list-checkbox-icons.tsx (4 hunks)
src/components/list/examples/list-checkbox.tsx (0 hunks)
src/components/list/examples/list-primary-component.tsx (5 hunks)
src/components/list/examples/list-radio-button-icons.tsx (4 hunks)
src/components/list/examples/list-radio-button.tsx (0 hunks)
src/components/list/examples/list-selectable.tsx (2 hunks)
src/components/list/list.tsx (1 hunks)

💤 Files with no reviewable changes (2)

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

🧰 Additional context used

📓 Path-based instructions (5)

**/*.tsx

📄 CodeRabbit Inference Engine (.cursor/rules/wrap-multiple-jsx-elements-in-host-not-in-array.mdc)

When returning multiple JSX elements from the render method, never wrap them in an array literal. Instead, always wrap them in the special <Host> element. When there is already a single top-level element, it does not have to be wrapped in <Host>.

Files:

src/components/list/list.tsx
src/components/list/examples/list-primary-component.tsx
src/components/list/examples/list-badge-icons.tsx
src/components/list/examples/list-selectable.tsx
src/components/list/examples/list-radio-button-icons.tsx
src/components/list/examples/list-checkbox-icons.tsx
src/components/list/examples/list-action.tsx