polymorph-ui-components-mcp 0.0.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/build/docs/Accordion.md +45 -0
- package/build/docs/Avatar.md +80 -0
- package/build/docs/Badge.md +58 -0
- package/build/docs/Banner.md +134 -0
- package/build/docs/Book.md +111 -0
- package/build/docs/Browser.md +92 -0
- package/build/docs/Button.md +154 -0
- package/build/docs/CHANGELOG.md +0 -0
- package/build/docs/Calendar.md +129 -0
- package/build/docs/Carousel.md +73 -0
- package/build/docs/CheckListItem.md +76 -0
- package/build/docs/Checkbox.md +84 -0
- package/build/docs/Choicebox.md +71 -0
- package/build/docs/ColorPicker.md +83 -0
- package/build/docs/Combobox.md +336 -0
- package/build/docs/CommandMenu.md +208 -0
- package/build/docs/ContextMenu.md +132 -0
- package/build/docs/GUIDELINES.md +380 -0
- package/build/docs/Gauge.md +46 -0
- package/build/docs/GridItem.md +78 -0
- package/build/docs/Icon.md +66 -0
- package/build/docs/IconStack.md +68 -0
- package/build/docs/Img.md +56 -0
- package/build/docs/Input.md +151 -0
- package/build/docs/InputButton.md +246 -0
- package/build/docs/KeyboardInput.md +104 -0
- package/build/docs/ListItem.md +156 -0
- package/build/docs/Loader.md +55 -0
- package/build/docs/LoadingDots.md +45 -0
- package/build/docs/Menu.md +139 -0
- package/build/docs/Modal.md +221 -0
- package/build/docs/ModalAnimation.md +29 -0
- package/build/docs/OverlayAnimation.md +21 -0
- package/build/docs/Pagination.md +102 -0
- package/build/docs/Phone.md +82 -0
- package/build/docs/Pill.md +122 -0
- package/build/docs/Progress.md +53 -0
- package/build/docs/Radio.md +75 -0
- package/build/docs/RelativeTime.md +76 -0
- package/build/docs/Scroller.md +194 -0
- package/build/docs/Select.md +177 -0
- package/build/docs/Sheet.md +133 -0
- package/build/docs/Shimmer.md +76 -0
- package/build/docs/Slider.md +68 -0
- package/build/docs/Snippet.md +99 -0
- package/build/docs/SplitButton.md +157 -0
- package/build/docs/SplitInput.md +157 -0
- package/build/docs/Step.md +52 -0
- package/build/docs/Stepper.md +85 -0
- package/build/docs/Table.md +252 -0
- package/build/docs/Tabs.md +117 -0
- package/build/docs/ThemeSwitcher.md +125 -0
- package/build/docs/Toast.md +140 -0
- package/build/docs/Toggle.md +70 -0
- package/build/docs/Toolbar.md +100 -0
- package/build/docs/Tooltip.md +86 -0
- package/build/docs/_index.json +218 -0
- package/build/docs/templates/changelog.hbs +36 -0
- package/build/index.d.ts +2 -0
- package/build/index.js +163 -0
- package/build/index.js.map +1 -0
- package/build/services/registry.d.ts +11 -0
- package/build/types.d.ts +4 -0
- package/package.json +34 -0
|
@@ -0,0 +1,156 @@
|
|
|
1
|
+
# ListItem
|
|
2
|
+
|
|
3
|
+
A multi-section list row with left image (with fallback), center label (supports HTML), right image, and optional text on the right. Supports an accordion-expandable bottom section. Each section (left image, right image, center text, top section, whole item) has its own click handler. Shows a loading overlay and optional right-side circular loader spinner. The `preventFocus` prop removes focus outlines for non-keyboard navigation contexts.
|
|
4
|
+
|
|
5
|
+
## Usage
|
|
6
|
+
|
|
7
|
+
```svelte
|
|
8
|
+
<script>
|
|
9
|
+
import { ListItem } from 'polymorph-ui-components';
|
|
10
|
+
</script>
|
|
11
|
+
|
|
12
|
+
<ListItem />
|
|
13
|
+
```
|
|
14
|
+
|
|
15
|
+
## Props
|
|
16
|
+
|
|
17
|
+
| Prop | Type | Required | Default | Description |
|
|
18
|
+
| ---------------------- | ---------------- | -------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
19
|
+
| leftImageUrl | `string \| null` | No | `-` | URL for the left-side image. Rendered using the Img component with fallback support. |
|
|
20
|
+
| leftImageFallbackUrl | `string \| null` | No | `-` | Fallback image URL if leftImageUrl fails to load. |
|
|
21
|
+
| rightImageUrl | `string \| null` | No | `-` | URL for the right-side image (e.g., an arrow or action icon). |
|
|
22
|
+
| label | `string \| null` | No | `-` | Center text content. Supports HTML (rendered via {@html}). Used for the main list item label. |
|
|
23
|
+
| useAccordion | `boolean` | No | `false` | When true, wraps the bottomContent in an Accordion component for expand/collapse animation. |
|
|
24
|
+
| rightContentText | `string \| null` | No | `-` | Text displayed on the right side of the list item (e.g., a price or status). |
|
|
25
|
+
| testId | `string` | No | `-` | Value for data-pw on the outer item container. |
|
|
26
|
+
| topSectionTestId | `string` | No | `-` | Value for data-pw on the top section (left + center + right). |
|
|
27
|
+
| rightImageTestId | `string` | No | `-` | Value for data-pw on the right image wrapper. |
|
|
28
|
+
| leftImageTestId | `string` | No | `-` | Value for data-pw on the left image wrapper. |
|
|
29
|
+
| centerTextTestId | `string` | No | `-` | Value for data-pw on the center text element. |
|
|
30
|
+
| showLoader | `boolean` | No | `false` | When true, shows a semi-transparent animated overlay that fills across the item (progress bar animation). |
|
|
31
|
+
| showRightContentLoader | `boolean` | No | `false` | When true, shows a circular Loader spinner in the right content area. |
|
|
32
|
+
| expand | `boolean` | No | `false` | Bindable. Controls whether the accordion bottom section is expanded or collapsed. |
|
|
33
|
+
| preventFocus | `boolean` | No | `false` | When true, removes the focus outline from interactive elements. Useful when the list item is used in a non-keyboard context. |
|
|
34
|
+
| classes | `string` | No | `-` | CSS class string applied to the component's top-level element. Useful for theming — define classes with CSS variable overrides and pass them to create variant styles. |
|
|
35
|
+
| role | `string` | No | `'button'` | ARIA role for the outer item container. Set to `'option'` when using ListItem inside a `role="listbox"` container (e.g., autocomplete dropdowns). When `'option'`, tabindex is automatically set to -1 for proper listbox focus management. |
|
|
36
|
+
| ariaSelected | `boolean` | No | `-` | Sets `aria-selected` on the item container. Use when the ListItem represents a selectable option (e.g., the currently highlighted item in a listbox). |
|
|
37
|
+
| id | `string` | No | `-` | Sets the `id` attribute on the item container. Needed for `aria-activedescendant` references from a parent combobox input. |
|
|
38
|
+
|
|
39
|
+
## Snippets
|
|
40
|
+
|
|
41
|
+
Svelte 5 Snippet props — pass content blocks to the component.
|
|
42
|
+
|
|
43
|
+
| Snippet | Type | Description |
|
|
44
|
+
| ------------- | --------- | ---------------------------------------------------------------------------------------------------- |
|
|
45
|
+
| leftContent | `Snippet` | A Svelte 5 Snippet for custom content in the left area (beside or replacing the left image). |
|
|
46
|
+
| centerContent | `Snippet` | A Svelte 5 Snippet for custom content in the center area (beside or replacing the label). |
|
|
47
|
+
| rightContent | `Snippet` | A Svelte 5 Snippet for custom content in the right area (beside the right image). |
|
|
48
|
+
| bottomContent | `Snippet` | A Svelte 5 Snippet for content below the main row. Only renders when `useAccordion` is `true`; displayed inside an Accordion that expands/collapses based on the `expand` prop. |
|
|
49
|
+
|
|
50
|
+
## Events
|
|
51
|
+
|
|
52
|
+
| Event | Type | Description |
|
|
53
|
+
| ----------------- | -------------------------------- | -------------------------------------------------------------------------------------------------- |
|
|
54
|
+
| onleftimageclick | `(event: MouseEvent) => void` | Fires when the left image is clicked. |
|
|
55
|
+
| onrightimageclick | `(event: MouseEvent) => void` | Fires when the right image is clicked. |
|
|
56
|
+
| oncentertextclick | `(event: MouseEvent) => void` | Fires when the center text/label area is clicked. |
|
|
57
|
+
| onitemclick | `(event: MouseEvent) => void` | Fires when the entire list item container is clicked (including all sub-areas). |
|
|
58
|
+
| ontopsectionclick | `(event: MouseEvent) => void` | Fires when the top section (left + center + right row, excluding the accordion bottom) is clicked. |
|
|
59
|
+
| onkeydown | `(event: KeyboardEvent) => void` | Fires when a key is pressed while any focusable section of the list item has focus. |
|
|
60
|
+
|
|
61
|
+
## CSS Variables
|
|
62
|
+
|
|
63
|
+
Override these custom properties to theme the component.
|
|
64
|
+
|
|
65
|
+
| Variable | Default | CSS Property | Description |
|
|
66
|
+
| ------------------------------------------------ | ----------------------------------------- | ----------------------- | -------------------------------------------------------- |
|
|
67
|
+
| `--list-item-loader-foreground` | `currentColor` | --loader-foreground | Color of the Loader spinner foreground. |
|
|
68
|
+
| `--list-item-loader-background` | `#ffffff` | --loader-background | Color of the Loader spinner background/center. |
|
|
69
|
+
| `--list-item-loader-foreground-end` | `#ffffff` | --loader-foreground-end | End color of the Loader spinner gradient. |
|
|
70
|
+
| `--list-item-loader-background-color` | `#00000030` | background | Background overlay color when showLoader is true. |
|
|
71
|
+
| `--list-item-background-color` | `transparent` | background-color | Background color of the list item. |
|
|
72
|
+
| `--list-item-cursor` | `pointer` | cursor | Cursor style when hovering the list item. |
|
|
73
|
+
| `--list-item-box-shadow` | `none` | box-shadow | Box shadow of the list item. |
|
|
74
|
+
| `--list-item-box-width` | `-` | width | Width of the list item. |
|
|
75
|
+
| `--list-item-border-radius` | `0px` | border-radius | Corner rounding of the list item. |
|
|
76
|
+
| `--list-item-margin` | `-` | margin | Outer margin of the list item. |
|
|
77
|
+
| `--list-item-padding` | `-` | padding | Inner padding of the list item. |
|
|
78
|
+
| `--list-item-border` | `-` | border | Border of the list item. |
|
|
79
|
+
| `--list-item-transition` | `-` | transition | Transition animation for the list item (e.g., on hover). |
|
|
80
|
+
| `--list-item-hover-background-color` | `var(--list-item-background-color)` | background-color | Background color on hover. |
|
|
81
|
+
| `--list-item-hover-border` | `var(--list-item-border)` | border | Border on hover. |
|
|
82
|
+
| `--list-item-left-content-display` | `flex` | display | |
|
|
83
|
+
| `--list-item-left-image-height` | `24px` | --image-height | Height of the left image. |
|
|
84
|
+
| `--list-item-left-image-width` | `24px` | --image-width | Width of the left image. |
|
|
85
|
+
| `--list-item-left-image-padding` | `0px` | --image-padding | Padding around the left image. |
|
|
86
|
+
| `--list-item-left-image-border-radius` | `0px` | --image-border-radius | Corner rounding of the left image. |
|
|
87
|
+
| `--list-item-left-image-margin` | `0px` | --image-margin | Margin around the left image. |
|
|
88
|
+
| `--list-item-left-image-filter` | `none` | --image-filter | CSS filter applied to the left image. |
|
|
89
|
+
| `--list-item-left-image-background` | `-` | --image-background | Background behind the left image. |
|
|
90
|
+
| `--list-item-left-image-border` | `-` | --image-border | Border of the left image. |
|
|
91
|
+
| `--list-item-left-image-hover-background` | `var(--list-item-left-image-background)` | background | Background color of left image on hover. |
|
|
92
|
+
| `--list-item-left-image-hover-border` | `var(--list-item-left-image-border)` | border | Border of left image on hover. |
|
|
93
|
+
| `--list-item-left-image-object-fit` | `-` | --image-object-fit | Object-fit of the left image. |
|
|
94
|
+
| `--list-item-center-text-justify-content` | `flex-start` | justify-content | Vertical alignment of center text. |
|
|
95
|
+
| `--list-item-center-text-padding` | `0px 20px` | padding | Padding around the center text. |
|
|
96
|
+
| `--list-item-center-text-color` | `inherit` | color | Color of the center text. |
|
|
97
|
+
| `--list-item-center-text-font-size` | `inherit` | font-size | Font size of the center text. |
|
|
98
|
+
| `--list-item-center-text-font-weight` | `inherit` | font-weight | Font weight of the center text. |
|
|
99
|
+
| `--list-item-center-text-vertical-align` | `-` | align-items | Vertical alignment inside the center text. |
|
|
100
|
+
| `--list-item-center-text-margin` | `-` | margin | Margin around the center text. |
|
|
101
|
+
| `--list-item-center-text-border` | `-` | border | Border around the center text. |
|
|
102
|
+
| `--list-item-center-text-cursor` | `pointer` | cursor | Cursor for the center text. |
|
|
103
|
+
| `--list-item-center-text-font-family` | `-` | font-family | Font family of the center text. |
|
|
104
|
+
| `--list-item-right-content-display` | `flex` | display | Display mode of the right content area. |
|
|
105
|
+
| `--list-item-right-content-loader-margin` | `-` | margin | |
|
|
106
|
+
| `--list-item-right-image-height` | `18px` | --image-height | Height of the right image. |
|
|
107
|
+
| `--list-item-right-image-width` | `18px` | --image-width | Width of the right image. |
|
|
108
|
+
| `--list-item-right-image-padding` | `0px` | --image-padding | Padding around the right image. |
|
|
109
|
+
| `--list-item-right-image-border-radius` | `0px` | --image-border-radius | Corner rounding of the right image. |
|
|
110
|
+
| `--list-item-right-image-margin` | `0px` | --image-margin | Margin around the right image. |
|
|
111
|
+
| `--list-item-right-image-filter` | `-` | --image-filter | CSS filter applied to the right image. |
|
|
112
|
+
| `--list-item-right-image-background` | `-` | --image-background | Background behind the right image. |
|
|
113
|
+
| `--list-item-right-image-border` | `-` | --image-border | Border of the right image. |
|
|
114
|
+
| `--list-item-right-image-hover-background` | `var(--list-item-right-image-background)` | --image-hover-background | Background color of right image on hover. |
|
|
115
|
+
| `--list-item-right-image-hover-border` | `var(--list-item-right-image-border)` | --image-hover-border | Border of right image on hover. |
|
|
116
|
+
| `--list-item-right-content-text-color` | `inherit` | color | Color of the right side text. |
|
|
117
|
+
| `--list-item-right-content-text-font-size` | `inherit` | font-size | Font size of the right side text. |
|
|
118
|
+
| `--list-item-right-content-text-font-weight` | `inherit` | font-weight | Font weight of the right side text. |
|
|
119
|
+
| `--list-item-right-content-text-vertical-align` | `-` | align-items | |
|
|
120
|
+
| `--list-item-right-content-text-padding` | `0px` | padding | |
|
|
121
|
+
| `--list-item-right-content-text-margin` | `0px` | margin | |
|
|
122
|
+
| `--list-item-right-content-text-border` | `-` | border | |
|
|
123
|
+
| `--list-item-right-content-text-cursor` | `pointer` | cursor | |
|
|
124
|
+
| `--list-item-right-content-text-font-family` | `-` | font-family | |
|
|
125
|
+
| `--list-item-right-content-text-justify-content` | `-` | justify-content | |
|
|
126
|
+
| `--list-item-loader-duration` | `8s` | animation | Duration of the loading progress bar animation. |
|
|
127
|
+
|
|
128
|
+
## Internal Dependencies
|
|
129
|
+
|
|
130
|
+
This component uses the following library components internally:
|
|
131
|
+
|
|
132
|
+
- Accordion
|
|
133
|
+
- Loader
|
|
134
|
+
- Img
|
|
135
|
+
|
|
136
|
+
## Web Component
|
|
137
|
+
|
|
138
|
+
Tag: `<pui-list-item>`
|
|
139
|
+
|
|
140
|
+
```html
|
|
141
|
+
<pui-list-item label="Item Title">
|
|
142
|
+
<img slot="left-content" src="/avatar.jpg" />
|
|
143
|
+
<span slot="center-content">Description</span>
|
|
144
|
+
<span slot="right-content">$10.00</span>
|
|
145
|
+
<div slot="bottom-content">Extra info</div>
|
|
146
|
+
</pui-list-item>
|
|
147
|
+
```
|
|
148
|
+
|
|
149
|
+
### Slots
|
|
150
|
+
|
|
151
|
+
| Slot Name | Maps to Snippet | Description |
|
|
152
|
+
| ---------------- | --------------- | ------------------------------------------------ |
|
|
153
|
+
| `left-content` | `leftContent` | Content on the left side (e.g., avatar, icon). |
|
|
154
|
+
| `center-content` | `centerContent` | Center area content (e.g., description). |
|
|
155
|
+
| `right-content` | `rightContent` | Content on the right side (e.g., price, action). |
|
|
156
|
+
| `bottom-content` | `bottomContent` | Content below the main row. |
|
|
@@ -0,0 +1,55 @@
|
|
|
1
|
+
# Loader
|
|
2
|
+
|
|
3
|
+
A rotating circular spinner with a gradient foreground that transitions from `--loader-foreground` to `--loader-foreground-end`. The center is cut out using an `::after` pseudo-element with `--loader-background` color, creating a ring/donut shape. Spins continuously with a 1.4s linear animation.
|
|
4
|
+
|
|
5
|
+
## Usage
|
|
6
|
+
|
|
7
|
+
```svelte
|
|
8
|
+
<script>
|
|
9
|
+
import { Loader } from 'polymorph-ui-components';
|
|
10
|
+
</script>
|
|
11
|
+
|
|
12
|
+
<Loader />
|
|
13
|
+
```
|
|
14
|
+
|
|
15
|
+
## Props
|
|
16
|
+
|
|
17
|
+
| Prop | Type | Required | Default | Description |
|
|
18
|
+
| ------- | -------- | -------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
19
|
+
| testId | `string` | No | `-` | Test selector value applied as `data-pw` on the outermost element. |
|
|
20
|
+
| classes | `string` | No | `-` | CSS class string applied to the component's top-level element. Useful for theming — define classes with CSS variable overrides and pass them to create variant styles. |
|
|
21
|
+
|
|
22
|
+
## CSS Variables
|
|
23
|
+
|
|
24
|
+
Override these custom properties to theme the component.
|
|
25
|
+
|
|
26
|
+
| Variable | Default | CSS Property | Description |
|
|
27
|
+
| ------------------------------- | ------------ | ------------- | ---------------------------------------------------- |
|
|
28
|
+
| `--loader-font-size` | `10px` | font-size | Font size (used internally for text-indent trick). |
|
|
29
|
+
| `--loader-text-indent` | `-9999em` | text-indent | Text indent to hide text content. |
|
|
30
|
+
| `--loader-width` | `20px` | width | Width of the spinner. |
|
|
31
|
+
| `--loader-height` | `20px` | height | Height of the spinner. |
|
|
32
|
+
| `--loader-border-radius` | `50%` | border-radius | Corner rounding of the spinner (50% for circle). |
|
|
33
|
+
| `--loader-foreground` | `currentColor` | background | Gradient start color of the spinner ring. |
|
|
34
|
+
| `--loader-foreground-end` | `transparent` | background | Gradient end color of the spinner ring. |
|
|
35
|
+
| `--loader-before-width` | `10px` | width | Width of the ::before pseudo-element (top gradient). |
|
|
36
|
+
| `--loader-before-height` | `10px` | height | Height of the ::before pseudo-element. |
|
|
37
|
+
| `--loader-before-border-radius` | `100% 0 0 0` | border-radius | Corner rounding of the ::before element. |
|
|
38
|
+
| `--loader-before-position` | `absolute` | position | CSS position of the ::before element. |
|
|
39
|
+
| `--loader-before-top` | `0` | top | Top position of the ::before element. |
|
|
40
|
+
| `--loader-before-left` | `0` | left | Left position of the ::before element. |
|
|
41
|
+
| `--loader-background` | `#ffffff` | background | Color of the center cutout (creates the ring hole). |
|
|
42
|
+
| `--loader-after-width` | `15px` | width | Width of the center cutout circle. |
|
|
43
|
+
| `--loader-after-height` | `15px` | height | Height of the center cutout circle. |
|
|
44
|
+
| `--loader-after-border-radius` | `50%` | border-radius | Corner rounding of the cutout (50% for circle). |
|
|
45
|
+
| `--loader-after-position` | `absolute` | position | CSS position of the cutout. |
|
|
46
|
+
| `--loader-after-top` | `50%` | top | Top position of the cutout. |
|
|
47
|
+
| `--loader-after-left` | `50%` | left | Left position of the cutout. |
|
|
48
|
+
|
|
49
|
+
## Web Component
|
|
50
|
+
|
|
51
|
+
Tag: `<pui-loader>`
|
|
52
|
+
|
|
53
|
+
```html
|
|
54
|
+
<pui-loader></pui-loader>
|
|
55
|
+
```
|
|
@@ -0,0 +1,45 @@
|
|
|
1
|
+
# LoadingDots
|
|
2
|
+
|
|
3
|
+
Animated dot sequence for inline loading indication. Three dots animate in sequence to indicate background activity. Displays inline so it works naturally within text, buttons, or any other container.
|
|
4
|
+
|
|
5
|
+
## Usage
|
|
6
|
+
|
|
7
|
+
```svelte
|
|
8
|
+
<script>
|
|
9
|
+
import { LoadingDots } from 'polymorph-ui-components';
|
|
10
|
+
</script>
|
|
11
|
+
|
|
12
|
+
<LoadingDots />
|
|
13
|
+
```
|
|
14
|
+
|
|
15
|
+
## Props
|
|
16
|
+
|
|
17
|
+
| Prop | Type | Required | Default | Description |
|
|
18
|
+
| --------- | --------------------- | -------- | ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
19
|
+
| dots | `number` | No | `3` | Number of dots to display. Values are rounded to the nearest integer and clamped to a minimum of 1. |
|
|
20
|
+
| animation | `'bounce' \| 'pulse'` | No | `'bounce'` | The animation style applied to the dots. Bounce moves dots vertically using translateY. Pulse fades dots in and out using opacity. |
|
|
21
|
+
| testId | `string` | No | `-` | Value for the data-pw attribute on the root element, used for end-to-end testing selectors. |
|
|
22
|
+
| classes | `string` | No | `-` | CSS class string applied to the component's top-level element. Useful for theming — define classes with CSS variable overrides and pass them to create variant styles. |
|
|
23
|
+
|
|
24
|
+
## CSS Variables
|
|
25
|
+
|
|
26
|
+
Override these custom properties to theme the component.
|
|
27
|
+
|
|
28
|
+
| Variable | Default | CSS Property | Description |
|
|
29
|
+
| ---------------------------------- | -------------- | ------------------ | --------------------------------------------------------------------------------------------------------------------------- |
|
|
30
|
+
| `--loading-dots-color` | `currentColor` | background-color | Color of the dots. Inherits from the parent text color by default, so it automatically matches surrounding content. |
|
|
31
|
+
| `--loading-dots-size` | `6px` | width, height | Diameter of each dot. |
|
|
32
|
+
| `--loading-dots-gap` | `3px` | gap | Horizontal spacing between dots. |
|
|
33
|
+
| `--loading-dots-border-radius` | `50%` | border-radius | Corner rounding of each dot. Default of 50% creates circles; set to 0 for squares. |
|
|
34
|
+
| `--loading-dots-duration` | `1.4s` | animation-duration | Total duration of one animation cycle. |
|
|
35
|
+
| `--loading-dots-stagger` | `0.16s` | animation-delay | Delay between each successive dot's animation start, creating the sequential wave effect. |
|
|
36
|
+
| `--loading-dots-bounce-height` | `-6px` | translateY | How far the dots travel upward during the bounce animation. Negative values move up. Only applies when animation is bounce. |
|
|
37
|
+
| `--loading-dots-pulse-min-opacity` | `0.2` | opacity | The minimum opacity a dot fades to during the pulse animation. Only applies when animation is pulse. |
|
|
38
|
+
|
|
39
|
+
## Web Component
|
|
40
|
+
|
|
41
|
+
Tag: `<pui-loading-dots>`
|
|
42
|
+
|
|
43
|
+
```html
|
|
44
|
+
<pui-loading-dots dots="3" animation="bounce"></pui-loading-dots>
|
|
45
|
+
```
|
|
@@ -0,0 +1,139 @@
|
|
|
1
|
+
# Menu
|
|
2
|
+
|
|
3
|
+
A dropdown action menu that opens from a trigger element and displays a list of selectable actions. Supports full keyboard navigation (ArrowUp/Down to move focus, Enter/Space to select, Escape to close, Home/End to jump), typeahead search (type characters to focus matching items), click-outside to close, separator lines between groups, danger-styled items for destructive actions, disabled items, optional per-item icons, and configurable dropdown position. Focus is managed automatically: the first item receives focus on open, and focus returns to the trigger on close.
|
|
4
|
+
|
|
5
|
+
## Usage
|
|
6
|
+
|
|
7
|
+
```svelte
|
|
8
|
+
<script>
|
|
9
|
+
import { Menu } from 'polymorph-ui-components';
|
|
10
|
+
</script>
|
|
11
|
+
|
|
12
|
+
<Menu
|
|
13
|
+
items={[
|
|
14
|
+
{ label: 'Edit', value: 'edit' },
|
|
15
|
+
{ label: 'Duplicate', value: 'duplicate' },
|
|
16
|
+
{ label: 'Delete', value: 'delete', danger: true }
|
|
17
|
+
]}
|
|
18
|
+
onselect={(item) => console.log(item.value)}
|
|
19
|
+
>
|
|
20
|
+
{#snippet trigger()}
|
|
21
|
+
<button>Actions</button>
|
|
22
|
+
{/snippet}
|
|
23
|
+
</Menu>
|
|
24
|
+
```
|
|
25
|
+
|
|
26
|
+
## Props
|
|
27
|
+
|
|
28
|
+
| Prop | Type | Required | Default | Description |
|
|
29
|
+
| ------- | ------------ | -------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
30
|
+
| items | `MenuItem[]` | Yes | `-` | Array of menu items to display. Each item defines a label, value, and optional icon, disabled, danger, or separator flags. See MenuItem type below. |
|
|
31
|
+
| open | `boolean` | No | `false` | Bindable. Controls whether the dropdown is visible. Set to true to open programmatically; bind to react to open/close state changes. |
|
|
32
|
+
| testId | `string` | No | `-` | Value for the data-pw attribute on the container, used for end-to-end testing selectors. Individual items get `{testId}-item-{value}`. |
|
|
33
|
+
| classes | `string` | No | `-` | CSS class string applied to the component's top-level element. Useful for theming — define classes with CSS variable overrides and pass them to create variant styles. |
|
|
34
|
+
| role | `'menu' \| 'listbox'` | No | `'menu'` | ARIA role for the dropdown container. Set to `'listbox'` to use the menu as an autocomplete suggestions list. Items automatically get `role="option"` instead of `role="menuitem"`, and `aria-selected` is managed on the focused item. |
|
|
35
|
+
| ariaLabel | `string` | No | `-` | Sets `aria-label` on the dropdown container for screen reader identification. |
|
|
36
|
+
| id | `string` | No | `-` | Sets the `id` attribute on the dropdown container. Needed for `aria-controls` references from a parent combobox input. |
|
|
37
|
+
|
|
38
|
+
## Snippets
|
|
39
|
+
|
|
40
|
+
Svelte 5 Snippet props -- pass content blocks to the component.
|
|
41
|
+
|
|
42
|
+
| Snippet | Type | Description |
|
|
43
|
+
| ------- | --------- | ------------------------------------------------------------------------------------------------------------------------ |
|
|
44
|
+
| trigger | `Snippet` | The trigger element that the menu attaches to. Clicking or pressing Enter/Space/ArrowDown on the trigger opens the menu. |
|
|
45
|
+
|
|
46
|
+
## Events
|
|
47
|
+
|
|
48
|
+
| Event | Type | Description |
|
|
49
|
+
| -------- | -------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
|
|
50
|
+
| onselect | `(item: MenuItem) => void` | Fires when a non-disabled menu item is selected (via click, Enter, or Space). Receives the full MenuItem object. |
|
|
51
|
+
| onopen | `() => void` | Fires when the menu dropdown opens, whether by click, Enter, Space, or ArrowDown/ArrowUp on the trigger. |
|
|
52
|
+
| onclose | `() => void` | Fires when the menu dropdown closes, whether by selecting an item, pressing Escape, clicking outside, or pressing Tab. |
|
|
53
|
+
|
|
54
|
+
## CSS Variables
|
|
55
|
+
|
|
56
|
+
Override these custom properties to theme the component.
|
|
57
|
+
|
|
58
|
+
| Variable | Default | CSS Property | Description |
|
|
59
|
+
| ------------------------------------------- | ---------------------------------------- | ---------------- | ---------------------------------------------------------------------- |
|
|
60
|
+
| `--menu-container-position` | `relative` | position | Position of the outer container that anchors the dropdown. |
|
|
61
|
+
| `--menu-container-display` | `inline-block` | display | Display mode of the outer container. |
|
|
62
|
+
| `--menu-font-family` | `inherit` | font-family | Font family for all menu text. |
|
|
63
|
+
| `--menu-font-size` | `14px` | font-size | Base font size for menu items. |
|
|
64
|
+
| `--menu-trigger-focus-outline` | `none` | outline | Focus outline style for the trigger element. |
|
|
65
|
+
| `--menu-z-index` | `10` | z-index | Stack order of the dropdown panel. |
|
|
66
|
+
| `--menu-background-color` | `#ffffff` | background-color | Background color of the dropdown panel. |
|
|
67
|
+
| `--menu-border` | `1px solid #e4e4e7` | border | Border around the dropdown panel. |
|
|
68
|
+
| `--menu-border-radius` | `8px` | border-radius | Corner rounding of the dropdown panel. |
|
|
69
|
+
| `--menu-box-shadow` | `0px 4px 16px rgba(0, 0, 0, 0.12)` | box-shadow | Shadow of the dropdown panel. |
|
|
70
|
+
| `--menu-min-width` | `160px` | min-width | Minimum width of the dropdown panel. |
|
|
71
|
+
| `--menu-max-height` | `240px` | max-height | Maximum height of the dropdown before it scrolls. |
|
|
72
|
+
| `--menu-dropdown-top` | `100%` | top | Top position of the dropdown panel relative to its container. |
|
|
73
|
+
| `--menu-dropdown-left` | `0` | left | Left position of the dropdown panel relative to its container. |
|
|
74
|
+
| `--menu-padding` | `4px 0` | padding | Inner padding of the dropdown panel. |
|
|
75
|
+
| `--menu-margin` | `4px 0` | margin | Outer margin of the dropdown panel (gap between trigger and dropdown). |
|
|
76
|
+
| `--menu-item-padding` | `8px 12px` | padding | Inner padding of each menu item. |
|
|
77
|
+
| `--menu-item-color` | `currentColor` | color | Text color of menu items. |
|
|
78
|
+
| `--menu-item-background-color` | `transparent` | background-color | Background color of menu items in their default state. |
|
|
79
|
+
| `--menu-item-gap` | `8px` | gap | Gap between icon and label within a menu item. |
|
|
80
|
+
| `--menu-item-white-space` | `nowrap` | white-space | White-space behavior for menu item text. |
|
|
81
|
+
| `--menu-item-hover-background-color` | `transparent` | background-color | Background color of a menu item on hover. |
|
|
82
|
+
| `--menu-item-hover-color` | `var(--menu-item-color, currentColor)` | color | Text color of a menu item on hover. |
|
|
83
|
+
| `--menu-item-focus-background-color` | `transparent` | background-color | Background color of a menu item when focused via keyboard. |
|
|
84
|
+
| `--menu-item-focus-outline` | `none` | outline | Focus outline of a menu item when focused via keyboard. |
|
|
85
|
+
| `--menu-item-danger-color` | `currentColor` | color | Text color for danger-flagged items (destructive actions). |
|
|
86
|
+
| `--menu-item-danger-hover-background-color` | `transparent` | background-color | Background color for danger items on hover. |
|
|
87
|
+
| `--menu-item-danger-hover-color` | `var(--menu-item-danger-color, currentColor)` | color | Text color for danger items on hover. |
|
|
88
|
+
| `--menu-item-danger-focus-background-color` | `transparent` | background-color | Background color for danger items when focused via keyboard. |
|
|
89
|
+
| `--menu-item-disabled-opacity` | `0.4` | opacity | Opacity of disabled menu items. |
|
|
90
|
+
| `--menu-item-disabled-cursor` | `not-allowed` | cursor | Cursor shown when hovering disabled items. |
|
|
91
|
+
| `--menu-separator-height` | `1px` | height | Height of the separator line between item groups. |
|
|
92
|
+
| `--menu-separator-color` | `#e4e4e7` | background-color | Color of the separator line. |
|
|
93
|
+
| `--menu-separator-margin` | `4px 0` | margin | Vertical spacing around the separator line. |
|
|
94
|
+
| `--menu-item-icon-height` | `16px` | height | Height of per-item icons. |
|
|
95
|
+
| `--menu-item-icon-width` | `16px` | width | Width of per-item icons. |
|
|
96
|
+
| `--menu-item-font-weight` | `400` | font-weight | Font weight of menu item labels. |
|
|
97
|
+
| `--menu-item-line-height` | `1.4` | line-height | Line height of menu item labels. |
|
|
98
|
+
|
|
99
|
+
## Type Reference
|
|
100
|
+
|
|
101
|
+
Custom types used by this component's props and events:
|
|
102
|
+
|
|
103
|
+
### MenuItem
|
|
104
|
+
|
|
105
|
+
```typescript
|
|
106
|
+
type MenuItem = {
|
|
107
|
+
label: string; // Display text for the menu item
|
|
108
|
+
value: string; // Unique identifier used in onselect callback and test IDs
|
|
109
|
+
icon?: string; // URL/src for an icon image displayed before the label
|
|
110
|
+
disabled?: boolean; // When true, item is dimmed and non-interactive
|
|
111
|
+
danger?: boolean; // When true, item text is styled in a destructive/red color
|
|
112
|
+
separator?: boolean; // When true, renders a horizontal line instead of a clickable item
|
|
113
|
+
id?: string; // DOM id for the item element, needed for aria-activedescendant references
|
|
114
|
+
};
|
|
115
|
+
```
|
|
116
|
+
|
|
117
|
+
## Internal Dependencies
|
|
118
|
+
|
|
119
|
+
This component uses the following library components internally:
|
|
120
|
+
|
|
121
|
+
- Img (for menu item icon rendering)
|
|
122
|
+
|
|
123
|
+
## Web Component
|
|
124
|
+
|
|
125
|
+
Tag: `<pui-menu>`
|
|
126
|
+
|
|
127
|
+
```html
|
|
128
|
+
<pui-menu>
|
|
129
|
+
<button slot="trigger">Open Menu</button>
|
|
130
|
+
</pui-menu>
|
|
131
|
+
```
|
|
132
|
+
|
|
133
|
+
### Slots
|
|
134
|
+
|
|
135
|
+
| Slot Name | Maps to Snippet | Description |
|
|
136
|
+
| --------- | --------------- | ----------------------------------------- |
|
|
137
|
+
| `trigger` | `trigger` | The element that opens the menu on click. |
|
|
138
|
+
|
|
139
|
+
> **Note:** The `items` prop is an array — set it via JavaScript property.
|