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,56 @@
|
|
|
1
|
+
# Img
|
|
2
|
+
|
|
3
|
+
An image component with automatic fallback. If the primary `src` fails to load (onerror), it switches to the `fallback` URL. The fallback only triggers once (won't loop if fallback also fails). Supports hover styling for interactive image use cases.
|
|
4
|
+
|
|
5
|
+
## Usage
|
|
6
|
+
|
|
7
|
+
```svelte
|
|
8
|
+
<script>
|
|
9
|
+
import { Img } from 'polymorph-ui-components';
|
|
10
|
+
</script>
|
|
11
|
+
|
|
12
|
+
<Img src={'...'} alt={'...'} />
|
|
13
|
+
```
|
|
14
|
+
|
|
15
|
+
## Props
|
|
16
|
+
|
|
17
|
+
| Prop | Type | Required | Default | Description |
|
|
18
|
+
| -------- | ---------------- | -------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
19
|
+
| src | `string` | Yes | `-` | The primary image URL to display. |
|
|
20
|
+
| alt | `string` | Yes | `-` | Alt text for the image. |
|
|
21
|
+
| fallback | `string \| null` | No | `-` | Fallback image URL. If the primary src fails to load (onerror), the component switches to this URL. |
|
|
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
|
+
| testId | `string` | No | `-` | Test selector value applied as `data-pw` on the outermost element. |
|
|
24
|
+
|
|
25
|
+
## CSS Variables
|
|
26
|
+
|
|
27
|
+
Override these custom properties to theme the component.
|
|
28
|
+
|
|
29
|
+
| Variable | Default | CSS Property | Description |
|
|
30
|
+
| -------------------------- | ------------------------- | ------------- | -------------------------------------------------------------- |
|
|
31
|
+
| `--image-object-fit` | `-` | object-fit | Object-fit of the image (contain, cover, etc.). |
|
|
32
|
+
| `--image-height` | `24px` | height | Height of the image. |
|
|
33
|
+
| `--image-width` | `24px` | width | Width of the image. |
|
|
34
|
+
| `--image-padding` | `0px` | padding | Padding around the image. |
|
|
35
|
+
| `--image-border-radius` | `0px` | border-radius | Corner rounding of the image. |
|
|
36
|
+
| `--image-margin` | `0px` | margin | Margin around the image. |
|
|
37
|
+
| `--image-filter` | `none` | filter | CSS filter applied to the image (e.g., grayscale, brightness). |
|
|
38
|
+
| `--image-background` | `-` | background | Background behind the image. |
|
|
39
|
+
| `--image-border` | `-` | border | Border of the image. |
|
|
40
|
+
| `--image-transition` | `-` | transition | Transition animation for hover effects. |
|
|
41
|
+
| `--image-hover-background` | `var(--image-background)` | background | Background on hover. |
|
|
42
|
+
| `--image-hover-border` | `var(--image-border)` | border | Border on hover. |
|
|
43
|
+
|
|
44
|
+
## Events
|
|
45
|
+
|
|
46
|
+
| Event | Type | Description |
|
|
47
|
+
| ------- | ------------ | ----------------------------------- |
|
|
48
|
+
| onerror | `() => void` | Fires when the image fails to load and no fallback is available, or when the fallback image itself also fails to load. Does not fire when the primary image fails but a valid fallback URL exists — the component silently switches to the fallback instead. |
|
|
49
|
+
|
|
50
|
+
## Web Component
|
|
51
|
+
|
|
52
|
+
Tag: `<pui-img>`
|
|
53
|
+
|
|
54
|
+
```html
|
|
55
|
+
<pui-img src="/photo.jpg" alt="Description" fallback="/fallback.jpg"></pui-img>
|
|
56
|
+
```
|
|
@@ -0,0 +1,151 @@
|
|
|
1
|
+
# Input
|
|
2
|
+
|
|
3
|
+
A text input field with built-in validation for email, phone (tel), password, and text patterns. Validates automatically using `validationPattern` and `inProgressPattern` RegExp props, plus optional custom validator functions. Shows error messages when validation fails and info messages below the input. For `tel` dataType, automatically strips non-digit characters and enforces `maxLength`. Supports text transformers that modify the raw input value and view presentation transformers that format the displayed value (e.g., adding spaces to a card number). The validation state (`Valid` / `InProgress` / `Invalid`) is computed reactively and reported via `onstatechange`. Can render as a `<textarea>` when `useTextArea` is true.
|
|
4
|
+
|
|
5
|
+
## Usage
|
|
6
|
+
|
|
7
|
+
```svelte
|
|
8
|
+
<script>
|
|
9
|
+
import { Input } from 'polymorph-ui-components';
|
|
10
|
+
</script>
|
|
11
|
+
|
|
12
|
+
<Input value={'...'} />
|
|
13
|
+
```
|
|
14
|
+
|
|
15
|
+
## Props
|
|
16
|
+
|
|
17
|
+
| Prop | Type | Required | Default | Description |
|
|
18
|
+
| -------------------- | ---------------------------------------------------------------------- | -------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
19
|
+
| value | `string` | Yes | `''` | Bindable. The current input value. Two-way bound to the underlying `<input>` or `<textarea>` element. |
|
|
20
|
+
| placeholder | `string \| null` | No | `''` | Placeholder text shown when the input is empty. |
|
|
21
|
+
| dataType | `InputDataType = 'text' \| 'tel' \| 'password' \| 'email' \| 'number'` | No | `'text'` | The type of input data. Controls the HTML input type and validation behavior. 'tel' strips non-digits and applies textTransformers; 'email' uses RFC 5322 validation; 'password' and 'text' use pattern-based validation. |
|
|
22
|
+
| label | `string \| null` | No | `''` | Label text shown above the input field. Hidden when actionInput is true. |
|
|
23
|
+
| onErrorMessage | `string \| null` | No | `''` | Error message text displayed below the input when validation state is 'Invalid'. Hidden when actionInput is true. |
|
|
24
|
+
| infoMessage | `string \| null` | No | `''` | Informational text displayed below the input regardless of validation state. Hidden when actionInput is true. |
|
|
25
|
+
| validators | `CustomValidator[]` | No | `[]` | Array of custom validator functions. Each receives the input value and current validation state, and returns a new ValidationState. Validators run after the built-in validation. |
|
|
26
|
+
| disable | `boolean` | No | `false` | Whether the input is disabled (greyed out and non-interactive). |
|
|
27
|
+
| validationPattern | `RegExp \| null` | No | `null` | RegExp that the input value must match to be considered 'Valid'. If null, no pattern validation is applied. |
|
|
28
|
+
| inProgressPattern | `RegExp \| null` | No | `null` | RegExp that matches partial/incomplete input. If the value matches this pattern (but not validationPattern), the state is 'InProgress' instead of 'Invalid'. |
|
|
29
|
+
| addFocusColor | `boolean` | No | `false` | When true, adds a 1px focus border to the input. Used with actionInput mode. |
|
|
30
|
+
| maxLength | `number` | No | `1000` | Maximum number of characters allowed. For dataType='tel', this limits the digit count (excess digits are trimmed from the start). |
|
|
31
|
+
| minLength | `number` | No | `0` | Minimum number of characters required (HTML minlength attribute). |
|
|
32
|
+
| min | `number` | No | `-` | Minimum value for numeric inputs (HTML min attribute). Only applies to `<input>`, not `<textarea>`. |
|
|
33
|
+
| max | `number` | No | `-` | Maximum value for numeric inputs (HTML max attribute). Only applies to `<input>`, not `<textarea>`. |
|
|
34
|
+
| actionInput | `boolean` | No | `false` | When true, hides the label, error message, and info message, and adjusts border-radius/shadow for seamless integration inside InputButton. |
|
|
35
|
+
| useTextArea | `boolean` | No | `false` | When true, renders a `<textarea>` instead of an `<input>`. Useful for multi-line text entry. |
|
|
36
|
+
| autoComplete | `HTMLInputAttributes['autocomplete']` | No | `'on'` | The HTML autocomplete attribute value. Controls browser autofill behavior. Accepts any string for non-standard values (e.g., `'off'`, `'new-password'`). |
|
|
37
|
+
| name | `string` | No | `''` | The HTML name attribute for the input. Used for form submission and label association. |
|
|
38
|
+
| textTransformers | `TextTransformer[]` | No | `[]` | Array of functions applied to the raw input value before digit extraction (tel mode only). Use for stripping country codes or formatting. |
|
|
39
|
+
| textViewPresentation | `TextTransformer[]` | No | `[]` | Array of functions applied to the value for display purposes. The underlying value stays clean but the displayed text is transformed (e.g., adding spaces every 4 digits for card numbers). |
|
|
40
|
+
| testId | `string` | No | `''` | Value for the data-pw attribute, used for end-to-end testing selectors. |
|
|
41
|
+
| 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. |
|
|
42
|
+
| role | `string` | No | `-` | Sets the ARIA `role` attribute on the underlying `<input>`/`<textarea>`. Use `'combobox'` when building autocomplete patterns. |
|
|
43
|
+
| ariaExpanded | `boolean` | No | `-` | Sets `aria-expanded` on the input element. Use when the input controls a dropdown or listbox that can be open or closed. |
|
|
44
|
+
| ariaAutocomplete | `'none' \| 'inline' \| 'list' \| 'both'` | No | `-` | Sets `aria-autocomplete` on the input element. Indicates whether the input provides autocomplete suggestions inline, as a list, both, or neither. |
|
|
45
|
+
| ariaControls | `string \| null` | No | `-` | Sets `aria-controls` on the input element. Should reference the `id` of the listbox/dropdown element that this input controls. |
|
|
46
|
+
| ariaActivedescendant | `string \| null` | No | `-` | Sets `aria-activedescendant` on the input element. Should reference the `id` of the currently focused option in the controlled listbox, enabling screen readers to announce the active option without moving DOM focus. |
|
|
47
|
+
|
|
48
|
+
## Methods
|
|
49
|
+
|
|
50
|
+
Exported methods that can be called via `bind:this` on the component instance.
|
|
51
|
+
|
|
52
|
+
| Method | Signature | Description |
|
|
53
|
+
| --------------- | ------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- |
|
|
54
|
+
| `focus()` | `() => void` | Programmatically focuses the underlying `<input>` or `<textarea>` element. |
|
|
55
|
+
| `blur()` | `() => void` | Programmatically removes focus from the underlying `<input>` or `<textarea>` element. |
|
|
56
|
+
| `getInputRef()` | `() => HTMLInputElement \| HTMLTextAreaElement \| null` | Returns a reference to the underlying DOM element. Use for custom focus management or third-party library integration. |
|
|
57
|
+
|
|
58
|
+
## Events
|
|
59
|
+
|
|
60
|
+
| Event | Type | Description |
|
|
61
|
+
| ------------- | --------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
62
|
+
| oninput | `(value: string, event: Event) => void` | Fires on every input change. Receives the current input value (after any text transformer processing for tel type) and the original DOM Event. |
|
|
63
|
+
| onfocus | `(event: FocusEvent) => void` | Fires when the input element gains focus. |
|
|
64
|
+
| onfocusout | `(event: FocusEvent) => void` | Fires when the input element loses focus. Internally, if the validation state is 'InProgress' and the value is non-empty, the state transitions to 'Invalid' on blur. |
|
|
65
|
+
| onblur | `(event: FocusEvent) => void` | Fires when the input element loses focus, alongside `onfocusout`. Provided as a convenience alias for consumers who prefer the `blur` event naming convention. |
|
|
66
|
+
| onpaste | `(event: ClipboardEvent) => void` | Fires when content is pasted into the input. For dataType='tel', the pasted text is filtered to digits only and trimmed to maxLength. |
|
|
67
|
+
| onclick | `(event: MouseEvent) => void` | Fires when the input element is clicked. |
|
|
68
|
+
| onstatechange | `(state: ValidationState) => void` | Fires whenever the validation state changes. Receives the new ValidationState ('Valid', 'InProgress', or 'Invalid'). Runs as a reactive $effect so it fires on initial render and every state change. |
|
|
69
|
+
| onkeydown | `(event: KeyboardEvent) => void` | Fires when a key is pressed while the input has focus. |
|
|
70
|
+
|
|
71
|
+
## CSS Variables
|
|
72
|
+
|
|
73
|
+
Override these custom properties to theme the component.
|
|
74
|
+
|
|
75
|
+
| Variable | Default | CSS Property | Description |
|
|
76
|
+
| ------------------------------- | ------------------------------------------------------ | ---------------- | ------------------------------------------------------- |
|
|
77
|
+
| `--input-box-sizing` | `border-box` | box-sizing | Box sizing model for the input element. |
|
|
78
|
+
| `--input-height` | `fit-content` | height | Height of the input element. |
|
|
79
|
+
| `--input-background` | `transparent` | background-color | Background color of the input. |
|
|
80
|
+
| `--input-font-size` | `16px` | font-size | Font size of the input text. |
|
|
81
|
+
| `--input-font-family` | `inherit` | font-family | Font family of the input text. |
|
|
82
|
+
| `--input-radius` | `6px` | border-radius | Corner rounding of the input. |
|
|
83
|
+
| `--input-padding` | `10px 12px` | padding | Inner padding of the input. |
|
|
84
|
+
| `--input-font-weight` | `500` | font-weight | Font weight of the input text. |
|
|
85
|
+
| `--input-width` | `fit-content` | width | Width of the input element. |
|
|
86
|
+
| `--input-margin` | `0px 0px 12px 0px` | margin | Outer margin of the input element. |
|
|
87
|
+
| `--input-box-shadow` | `none` | box-shadow | Box shadow around the input. |
|
|
88
|
+
| `--input-border` | `1px solid currentColor` | border | Border of the input in its normal state. |
|
|
89
|
+
| `--input-visibility` | `visible` | visibility | Controls input visibility (visible/hidden). |
|
|
90
|
+
| `--input-text-align` | `left` | text-align | Text alignment inside the input. |
|
|
91
|
+
| `--input-text-color` | `-` | color | Color of the input text. |
|
|
92
|
+
| `--input-focus-border` | `1px solid currentColor` | border | Border of the input when focused. |
|
|
93
|
+
| `--input-container-margin` | `-` | margin | Outer margin of the input container. |
|
|
94
|
+
| `--input-container-padding` | `-` | padding | Inner padding of the input container. |
|
|
95
|
+
| `--input-container-width` | `-` | width | Width of the input container. |
|
|
96
|
+
| `--input-label-msg-text-weight` | `400` | font-weight | Font weight of the label text. |
|
|
97
|
+
| `--input-label-msg-text-size` | `12px` | font-size | Font size of the label text. |
|
|
98
|
+
| `--input-label-msg-text-color` | `currentColor` | color | Color of the label text. |
|
|
99
|
+
| `--input-label-msg-margin` | `0px 0px 6px 0px` | margin | Margin around the label. |
|
|
100
|
+
| `--input-label-msg-padding` | `-` | padding | Padding inside the label. |
|
|
101
|
+
| `--input-error-msg-text-weight` | `400` | font-weight | Font weight of the error message. |
|
|
102
|
+
| `--input-error-msg-text-size` | `12px` | font-size | Font size of the error message. |
|
|
103
|
+
| `--input-error-msg-text-color` | `currentColor` | color | Color used for the error border and error message text. |
|
|
104
|
+
| `--input-error-msg-margin` | `-` | margin | Margin around the error message. |
|
|
105
|
+
| `--input-error-msg-padding` | `-` | padding | Padding inside the error message. |
|
|
106
|
+
| `--input-info-msg-text-weight` | `400` | font-weight | Font weight of the info message. |
|
|
107
|
+
| `--input-info-msg-text-size` | `12px` | font-size | Font size of the info message. |
|
|
108
|
+
| `--input-info-msg-text-color` | `currentColor` | color | Color of the info message text. |
|
|
109
|
+
| `--input-info-msg-margin` | `-` | margin | Margin around the info message. |
|
|
110
|
+
| `--input-info-msg-padding` | `-` | padding | Padding inside the info message. |
|
|
111
|
+
| `--input-placeholder-color` | `#a1a1aa` | color | Color of placeholder text. |
|
|
112
|
+
| `--input-error-border` | `1px solid var(--input-error-msg-text-color, currentColor)` | border | Border of the input when in error state. |
|
|
113
|
+
|
|
114
|
+
## Type Reference
|
|
115
|
+
|
|
116
|
+
Custom types used by this component's props and events:
|
|
117
|
+
|
|
118
|
+
### InputDataType
|
|
119
|
+
|
|
120
|
+
```typescript
|
|
121
|
+
type InputDataType = 'text' | 'tel' | 'password' | 'email' | 'number';
|
|
122
|
+
```
|
|
123
|
+
|
|
124
|
+
### CustomValidator
|
|
125
|
+
|
|
126
|
+
```typescript
|
|
127
|
+
type CustomValidator = (
|
|
128
|
+
inputValue: string,
|
|
129
|
+
currentValidationState: ValidationState
|
|
130
|
+
) => ValidationState;
|
|
131
|
+
```
|
|
132
|
+
|
|
133
|
+
### TextTransformer
|
|
134
|
+
|
|
135
|
+
```typescript
|
|
136
|
+
type TextTransformer = (text: string) => string;
|
|
137
|
+
```
|
|
138
|
+
|
|
139
|
+
### ValidationState
|
|
140
|
+
|
|
141
|
+
```typescript
|
|
142
|
+
type ValidationState = 'Valid' | 'InProgress' | 'Invalid';
|
|
143
|
+
```
|
|
144
|
+
|
|
145
|
+
## Web Component
|
|
146
|
+
|
|
147
|
+
Tag: `<pui-input>`
|
|
148
|
+
|
|
149
|
+
```html
|
|
150
|
+
<pui-input placeholder="Enter email" data-type="email" label="Email"></pui-input>
|
|
151
|
+
```
|
|
@@ -0,0 +1,246 @@
|
|
|
1
|
+
# InputButton
|
|
2
|
+
|
|
3
|
+
A composite component that combines an Input field with optional left, right, and bottom Button components. The right button is automatically disabled until the input validation state becomes `Valid`, and the bottom button's click handler only fires once validation is `Valid`. Pressing Enter in the input triggers the right button's `onkeyup` handler when validation passes. The input label and error/info messages are rendered outside the input-button group. Internally uses the Input component with `actionInput=true` for seamless visual integration.
|
|
4
|
+
|
|
5
|
+
## Usage
|
|
6
|
+
|
|
7
|
+
```svelte
|
|
8
|
+
<script>
|
|
9
|
+
import { InputButton } from 'polymorph-ui-components';
|
|
10
|
+
</script>
|
|
11
|
+
|
|
12
|
+
<InputButton />
|
|
13
|
+
```
|
|
14
|
+
|
|
15
|
+
## Props
|
|
16
|
+
|
|
17
|
+
| Prop | Type | Required | Default | Description |
|
|
18
|
+
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------- | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
19
|
+
| value | `string` | Yes | `''` | Bindable. The current input value. Passed through to the internal Input component. |
|
|
20
|
+
| inputProperties | `OptionalInputProperties = { placeholder?: string \| null; dataType?: InputDataType; label?: string \| null; onErrorMessage?: string \| null; infoMessage?: string \| null; validators?: CustomValidator[]; disable?: boolean; validationPattern?: RegExp \| null; inProgressPattern?: RegExp \| null; addFocusColor?: boolean; maxLength?: number; minLength?: number; min?: number; max?: number; actionInput?: boolean; useTextArea?: boolean; autoComplete?: HTMLInputAttributes['autocomplete']; name?: string; textTransformers?: TextTransformer[]; textViewPresentation?: TextTransformer[]; testId?: string; classes?: string; role?: string; ariaExpanded?: boolean; ariaAutocomplete?: 'none' \| 'inline' \| 'list' \| 'both'; ariaControls?: string \| null; ariaActivedescendant?: string \| null }` | Yes | `-` | Configuration for the internal Input component. Accepts all optional Input props (placeholder, dataType, label, validators, etc.). |
|
|
21
|
+
| rightButtonProperties | `OptionalButtonProperties \| null` | No | `-` | Configuration for the right-side Button. Pass text, icon, loaderType, etc. The button is auto-disabled when input validation is not 'Valid'. Set to null to hide. |
|
|
22
|
+
| leftButtonProperties | `OptionalButtonProperties \| null` | No | `-` | Configuration for the left-side Button. Pass text, icon, etc. Set to null to hide. |
|
|
23
|
+
| bottomButtonProperties | `OptionalButtonProperties \| null` | No | `-` | Configuration for the bottom Button (rendered below the input row). Its onclick handler only fires when input validation is 'Valid'. Set to null to hide. |
|
|
24
|
+
| 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. |
|
|
25
|
+
| testId | `string` | No | `-` | Test selector value applied as `data-pw` on the outermost element. |
|
|
26
|
+
|
|
27
|
+
## Methods
|
|
28
|
+
|
|
29
|
+
Exported methods that can be called via `bind:this` on the component instance.
|
|
30
|
+
|
|
31
|
+
| Method | Signature | Description |
|
|
32
|
+
| --------- | ------------ | ----------------------------------------------------------------- |
|
|
33
|
+
| `focus()` | `() => void` | Programmatically focuses the underlying input element. |
|
|
34
|
+
| `blur()` | `() => void` | Programmatically removes focus from the underlying input element. |
|
|
35
|
+
|
|
36
|
+
## Snippets
|
|
37
|
+
|
|
38
|
+
Svelte 5 Snippet props — pass content blocks to the component.
|
|
39
|
+
|
|
40
|
+
| Snippet | Type | Description |
|
|
41
|
+
| --------- | --------- | --------------------------------------------------------------- |
|
|
42
|
+
| leftIcon | `Snippet` | A Svelte 5 Snippet passed as the icon prop to the left Button. |
|
|
43
|
+
| rightIcon | `Snippet` | A Svelte 5 Snippet passed as the icon prop to the right Button. |
|
|
44
|
+
|
|
45
|
+
## Events
|
|
46
|
+
|
|
47
|
+
| Event | Type | Description |
|
|
48
|
+
| --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
49
|
+
| inputEventProperties | `InputEventProperties = { oninput?: (value: string, event: Event) => void; onfocus?: (event: FocusEvent) => void; onfocusout?: (event: FocusEvent) => void; onblur?: (event: FocusEvent) => void; onpaste?: (event: ClipboardEvent) => void; onclick?: (event: MouseEvent) => void; onstatechange?: (state: ValidationState) => void; onkeydown?: (event: KeyboardEvent) => void }` | Event handlers passed to the internal Input. The onstatechange callback will receive validation state changes. Note: internally the component intercepts onstatechange to update button enable states before forwarding to your handler. |
|
|
50
|
+
| rightButtonEventProperties | `ButtonEventProperties \| null` | Event handlers for the right Button. The onclick handler is only called when the input validation state is 'Valid'. The onkeyup is triggered when Enter is pressed in the input with valid state. |
|
|
51
|
+
| leftButtonEventProperties | `ButtonEventProperties \| null` | Event handlers for the left Button. These are passed directly to the Button component. |
|
|
52
|
+
| bottomButtonEventProperties | `ButtonEventProperties \| null` | Event handlers for the bottom Button. The onclick handler is only called when the input validation state is 'Valid'. |
|
|
53
|
+
|
|
54
|
+
## CSS Variables
|
|
55
|
+
|
|
56
|
+
Override these custom properties to theme the component.
|
|
57
|
+
|
|
58
|
+
| Variable | Default | CSS Property | Description |
|
|
59
|
+
| --------------------------------------- | ---------------------------------------------------- | ------------------------------- | --------------------------------------------------------------------------- |
|
|
60
|
+
| `--input-button-container-margin` | `-` | margin | Outer margin of the entire InputButton container. |
|
|
61
|
+
| `--input-height` | `fit-content` | height | |
|
|
62
|
+
| `--input-font-size` | `16px` | font-size | |
|
|
63
|
+
| `--input-button-margin` | `-` | margin | Margin of the inner input-button row. |
|
|
64
|
+
| `--input-button-radius` | `6px` | border-radius | Corner rounding of the input-button row. |
|
|
65
|
+
| `--input-button-container-border` | `-` | border | Border of the outer container. |
|
|
66
|
+
| `--input-button-container-background` | `-` | background | Background of the outer container. |
|
|
67
|
+
| `--input-button-container-padding` | `-` | padding | Padding inside the outer container. |
|
|
68
|
+
| `--input-button-border` | `1px solid currentColor` | border | Border of the inner input-button row (matches the Input border theme). |
|
|
69
|
+
| `--input-button-box-shadow` | `none` | box-shadow | Box shadow of the input-button row. |
|
|
70
|
+
| `--input-button-background` | `-` | background | Background of the input-button row. |
|
|
71
|
+
| `--input-button-focus-border` | `-` | border | Border applied to the container when any child has focus. |
|
|
72
|
+
| `--input-bottom-btn-padding` | `10px 0px` | padding | Padding around the bottom button. |
|
|
73
|
+
| `--input-button-bottom-cursor` | `-` | --button-cursor | Cursor of the bottom button. |
|
|
74
|
+
| `--input-button-bottom-color` | `-` | --button-color | Background color of the bottom button. |
|
|
75
|
+
| `--input-button-bottom-text-color` | `-` | --button-text-color | Text color of the bottom button. |
|
|
76
|
+
| `--input-button-bottom-font-family` | `-` | --button-font-family | Font family of the bottom button. |
|
|
77
|
+
| `--input-button-bottom-font-weight` | `-` | --button-font-weight | Font weight of the bottom button. |
|
|
78
|
+
| `--input-button-bottom-font-size` | `-` | --button-font-size | Font size of the bottom button. |
|
|
79
|
+
| `--input-button-bottom-height` | `54px` | --button-height | Height of the bottom button. |
|
|
80
|
+
| `--input-button-bottom-padding` | `-` | --button-padding | Padding inside the bottom button. |
|
|
81
|
+
| `--input-button-bottom-border-radius` | `-` | --button-border-radius | Corner rounding of the bottom button. |
|
|
82
|
+
| `--input-button-bottom-width` | `-` | --button-width | Width of the bottom button. |
|
|
83
|
+
| `--input-label-msg-text-weight` | `400` | font-weight | |
|
|
84
|
+
| `--input-label-msg-text-size` | `12px` | font-size | |
|
|
85
|
+
| `--input-label-msg-text-color` | `currentColor` | color | |
|
|
86
|
+
| `--input-label-msg-text-line-height` | `-` | line-height | |
|
|
87
|
+
| `--input-label-msg-text-margin` | `0px 0px 6px 0px` | margin | |
|
|
88
|
+
| `--invalid-outline` | `1px solid var(--input-field-error-stroke, currentColor)` | outline | Outline applied to the input-button row when validation state is 'Invalid'. |
|
|
89
|
+
| `--input-error-msg-text-weight` | `400` | font-weight | |
|
|
90
|
+
| `--input-error-msg-text-size` | `12px` | font-size | |
|
|
91
|
+
| `--input-error-msg-text-color` | `currentColor` | color | |
|
|
92
|
+
| `--input-btn-error-msg-margin` | `12px 0px 0px 0px` | margin | Margin around the error message. |
|
|
93
|
+
| `--input-info-msg-text-weight` | `400` | font-weight | |
|
|
94
|
+
| `--input-info-msg-text-size` | `12px` | font-size | |
|
|
95
|
+
| `--input-info-msg-text-color` | `currentColor` | color | |
|
|
96
|
+
| `--input-btn-info-msg-margin` | `12px 0px 0px 0px` | margin | Margin around the info message. |
|
|
97
|
+
| `--input-button-left-color` | `-` | --button-color | Background color of the left button. |
|
|
98
|
+
| `--input-button-left-text-color` | `-` | --button-text-color | Text color of the left button. |
|
|
99
|
+
| `--input-button-left-font-family` | `-` | --button-font-family | Font family of the left button. |
|
|
100
|
+
| `--input-button-left-font-weight` | `-` | --button-font-weight | Font weight of the left button. |
|
|
101
|
+
| `--input-button-left-font-size` | `-` | --button-font-size | Font size of the left button. |
|
|
102
|
+
| `--input-button-left-height` | `100%` | --button-height | Height of the left button (fills the row to match the input). |
|
|
103
|
+
| `--input-button-left-padding` | `0px 16px` | --button-padding | Padding inside the left button. |
|
|
104
|
+
| `--input-button-left-border-radius` | `-` | --button-border-radius | Corner rounding of the left button. |
|
|
105
|
+
| `--input-button-left-width` | `-` | --button-width | Width of the left button. |
|
|
106
|
+
| `--input-button-left-cursor` | `-` | --button-cursor | Cursor of the left button. |
|
|
107
|
+
| `--input-button-left-opacity` | `-` | --button-opacity | Opacity of the left button. |
|
|
108
|
+
| `--input-button-left-border` | `-` | --button-border | Border of the left button. |
|
|
109
|
+
| `--input-button-left-content-gap` | `-` | --button-content-gap | Gap between icon/text in the left button. |
|
|
110
|
+
| `--input-button-left-content-flex-direction` | `row` | --button-content-flex-direction | Layout direction of the left button content. |
|
|
111
|
+
| `--input-button-left-icon-order` | `-` | --button-icon-order | Flex order of the icon in the left button. |
|
|
112
|
+
| `--input-button-left-icon-display` | `-` | --button-icon-display | Display of the icon in the left button. |
|
|
113
|
+
| `--input-button-left-text-order` | `-` | --button-text-order | Flex order of the text in the left button. |
|
|
114
|
+
| `--input-button-left-disabled-cursor` | `-` | --button-disabled-cursor | Cursor of the left button when disabled. |
|
|
115
|
+
| `--input-button-left-disabled-opacity` | `-` | --button-disabled-opacity | Opacity of the left button when disabled. |
|
|
116
|
+
| `--input-button-right-flex` | `1` | flex | Flex value of the right button container. |
|
|
117
|
+
| `--input-button-right-min-width` | `0px` | min-width | Minimum width of the right button. |
|
|
118
|
+
| `--input-button-right-color` | `-` | --button-color | Background color of the right button. |
|
|
119
|
+
| `--input-button-right-text-color` | `-` | --button-text-color | Text color of the right button. |
|
|
120
|
+
| `--input-button-right-font-family` | `-` | --button-font-family | Font family of the right button. |
|
|
121
|
+
| `--input-button-right-font-weight` | `-` | --button-font-weight | Font weight of the right button. |
|
|
122
|
+
| `--input-button-right-font-size` | `-` | --button-font-size | Font size of the right button. |
|
|
123
|
+
| `--input-button-right-height` | `100%` | --button-height | Height of the right button (fills the row to match the input). |
|
|
124
|
+
| `--input-button-right-padding` | `0px 16px` | --button-padding | Padding inside the right button. |
|
|
125
|
+
| `--input-button-right-border-radius` | `0px 6px 6px 0px` | --button-border-radius | Corner rounding of the right button. |
|
|
126
|
+
| `--input-button-right-width` | `100%` | --button-width | Width of the right button. |
|
|
127
|
+
| `--input-button-right-cursor` | `-` | --button-cursor | Cursor of the right button. |
|
|
128
|
+
| `--input-button-right-opacity` | `-` | --button-opacity | Opacity of the right button. |
|
|
129
|
+
| `--input-button-right-border` | `-` | --button-border | Border of the right button. |
|
|
130
|
+
| `--input-button-right-content-gap` | `-` | --button-content-gap | Gap between icon/text in the right button. |
|
|
131
|
+
| `--input-button-right-visibility` | `visible` | --button-visibility | Visibility of the right button. |
|
|
132
|
+
| `--input-button-right-content-flex-direction` | `row` | --button-content-flex-direction | Layout direction of the right button content. |
|
|
133
|
+
| `--input-button-right-icon-order` | `-` | --button-icon-order | Flex order of the icon in the right button. |
|
|
134
|
+
| `--input-button-right-icon-display` | `-` | --button-icon-display | Display of the icon in the right button. |
|
|
135
|
+
| `--input-button-right-text-order` | `-` | --button-text-order | Flex order of the text in the right button. |
|
|
136
|
+
| `--input-button-right-disabled-cursor` | `-` | --button-disabled-cursor | Cursor of the right button when disabled. |
|
|
137
|
+
| `--input-button-right-disabled-opacity` | `-` | --button-disabled-opacity | Opacity of the right button when disabled. |
|
|
138
|
+
|
|
139
|
+
## Type Reference
|
|
140
|
+
|
|
141
|
+
Custom types used by this component's props and events:
|
|
142
|
+
|
|
143
|
+
### OptionalInputProperties
|
|
144
|
+
|
|
145
|
+
```typescript
|
|
146
|
+
type OptionalInputProperties = {
|
|
147
|
+
placeholder?: string | null;
|
|
148
|
+
dataType?: InputDataType;
|
|
149
|
+
label?: string | null;
|
|
150
|
+
onErrorMessage?: string | null;
|
|
151
|
+
infoMessage?: string | null;
|
|
152
|
+
validators?: CustomValidator[];
|
|
153
|
+
disable?: boolean;
|
|
154
|
+
validationPattern?: RegExp | null;
|
|
155
|
+
inProgressPattern?: RegExp | null;
|
|
156
|
+
addFocusColor?: boolean;
|
|
157
|
+
maxLength?: number;
|
|
158
|
+
minLength?: number;
|
|
159
|
+
min?: number;
|
|
160
|
+
max?: number;
|
|
161
|
+
actionInput?: boolean;
|
|
162
|
+
useTextArea?: boolean;
|
|
163
|
+
autoComplete?: HTMLInputAttributes['autocomplete'];
|
|
164
|
+
name?: string;
|
|
165
|
+
textTransformers?: TextTransformer[];
|
|
166
|
+
textViewPresentation?: TextTransformer[];
|
|
167
|
+
testId?: string;
|
|
168
|
+
classes?: string;
|
|
169
|
+
role?: string;
|
|
170
|
+
ariaExpanded?: boolean;
|
|
171
|
+
ariaAutocomplete?: 'none' | 'inline' | 'list' | 'both';
|
|
172
|
+
ariaControls?: string | null;
|
|
173
|
+
ariaActivedescendant?: string | null;
|
|
174
|
+
};
|
|
175
|
+
```
|
|
176
|
+
|
|
177
|
+
### OptionalButtonProperties
|
|
178
|
+
|
|
179
|
+
```typescript
|
|
180
|
+
type OptionalButtonProperties = {
|
|
181
|
+
text?: string;
|
|
182
|
+
enable?: boolean;
|
|
183
|
+
showProgressBar?: boolean;
|
|
184
|
+
showLoader?: boolean;
|
|
185
|
+
loaderType?: LoaderType;
|
|
186
|
+
type?: 'submit' | 'reset' | 'button';
|
|
187
|
+
testId?: string;
|
|
188
|
+
icon?: Snippet;
|
|
189
|
+
children?: Snippet;
|
|
190
|
+
ariaLabel?: string;
|
|
191
|
+
ariaExpanded?: boolean;
|
|
192
|
+
ariaSelected?: boolean;
|
|
193
|
+
role?: string;
|
|
194
|
+
disabled?: boolean;
|
|
195
|
+
classes?: string;
|
|
196
|
+
};
|
|
197
|
+
```
|
|
198
|
+
|
|
199
|
+
### InputEventProperties
|
|
200
|
+
|
|
201
|
+
```typescript
|
|
202
|
+
type InputEventProperties = {
|
|
203
|
+
oninput?: (value: string, event: Event) => void;
|
|
204
|
+
onfocus?: (event: FocusEvent) => void;
|
|
205
|
+
onfocusout?: (event: FocusEvent) => void;
|
|
206
|
+
onblur?: (event: FocusEvent) => void;
|
|
207
|
+
onpaste?: (event: ClipboardEvent) => void;
|
|
208
|
+
onclick?: (event: MouseEvent) => void;
|
|
209
|
+
onstatechange?: (state: ValidationState) => void;
|
|
210
|
+
onkeydown?: (event: KeyboardEvent) => void;
|
|
211
|
+
};
|
|
212
|
+
```
|
|
213
|
+
|
|
214
|
+
### ButtonEventProperties
|
|
215
|
+
|
|
216
|
+
```typescript
|
|
217
|
+
type ButtonEventProperties = {
|
|
218
|
+
onclick?: (event: MouseEvent) => void;
|
|
219
|
+
onkeyup?: (event: KeyboardEvent) => void;
|
|
220
|
+
};
|
|
221
|
+
```
|
|
222
|
+
|
|
223
|
+
## Internal Dependencies
|
|
224
|
+
|
|
225
|
+
This component uses the following library components internally:
|
|
226
|
+
|
|
227
|
+
- Button
|
|
228
|
+
- Input
|
|
229
|
+
|
|
230
|
+
## Web Component
|
|
231
|
+
|
|
232
|
+
Tag: `<pui-input-button>`
|
|
233
|
+
|
|
234
|
+
```html
|
|
235
|
+
<pui-input-button value="Search...">
|
|
236
|
+
<svg slot="left-icon">...</svg>
|
|
237
|
+
<svg slot="right-icon">...</svg>
|
|
238
|
+
</pui-input-button>
|
|
239
|
+
```
|
|
240
|
+
|
|
241
|
+
### Slots
|
|
242
|
+
|
|
243
|
+
| Slot Name | Maps to Snippet | Description |
|
|
244
|
+
| ------------ | --------------- | --------------------------------------------- |
|
|
245
|
+
| `left-icon` | `leftIcon` | Icon rendered on the left side of the input. |
|
|
246
|
+
| `right-icon` | `rightIcon` | Icon rendered on the right side of the input. |
|
|
@@ -0,0 +1,104 @@
|
|
|
1
|
+
# KeyboardInput
|
|
2
|
+
|
|
3
|
+
Renders keyboard shortcut badges inline. Each key is displayed in a styled `<kbd>` element with separators between them. Accepts keys as a string array or a single string that is split by the separator. Common modifier keys are automatically rendered as platform-aware symbols.
|
|
4
|
+
|
|
5
|
+
## Usage
|
|
6
|
+
|
|
7
|
+
```svelte
|
|
8
|
+
<script>
|
|
9
|
+
import { KeyboardInput } from 'polymorph-ui-components';
|
|
10
|
+
</script>
|
|
11
|
+
|
|
12
|
+
<KeyboardInput keys={['Ctrl', 'K']} />
|
|
13
|
+
|
|
14
|
+
<KeyboardInput keys="Cmd+Shift+P" />
|
|
15
|
+
```
|
|
16
|
+
|
|
17
|
+
## Props
|
|
18
|
+
|
|
19
|
+
| Prop | Type | Required | Default | Description |
|
|
20
|
+
| --------- | -------------------- | -------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
21
|
+
| keys | `string[] \| string` | Yes | `-` | The keys to display. Pass an array of individual key labels (e.g. `['Ctrl', 'K']`) or a single string with keys separated by the separator character (e.g. `"Ctrl+K"`). When a string is given it is split by the separator prop. |
|
|
22
|
+
| separator | `string` | No | `"+"` | The character displayed between key badges and used to split a string `keys` value into individual keys. |
|
|
23
|
+
| testId | `string` | No | `-` | Value for the `data-pw` attribute on the root element, used for end-to-end testing selectors. |
|
|
24
|
+
| 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. |
|
|
25
|
+
|
|
26
|
+
## Events
|
|
27
|
+
|
|
28
|
+
| Event | Type | Description |
|
|
29
|
+
| ------- | ----------------------------- | ------------------------------------------------- |
|
|
30
|
+
| onclick | `(event: MouseEvent) => void` | Fires when the keyboard input element is clicked. |
|
|
31
|
+
|
|
32
|
+
## Key Symbols
|
|
33
|
+
|
|
34
|
+
The component automatically converts common modifier key names (case-insensitive) into their typographic symbols:
|
|
35
|
+
|
|
36
|
+
| Input | Symbol | Description |
|
|
37
|
+
| -------------------------------- | ------- | ------------------ |
|
|
38
|
+
| `Cmd` / `Command` | ⌘ | macOS Command key |
|
|
39
|
+
| `Ctrl` / `Control` | ⌃ | Control key |
|
|
40
|
+
| `Alt` / `Option` | ⌥ | Alt / Option key |
|
|
41
|
+
| `Shift` | ⇧ | Shift key |
|
|
42
|
+
| `Enter` | ↵ | Enter / Return key |
|
|
43
|
+
| `Backspace` | ⌫ | Backspace key |
|
|
44
|
+
| `Delete` | ⌦ | Forward delete key |
|
|
45
|
+
| `Tab` | ⇥ | Tab key |
|
|
46
|
+
| `Escape` / `Esc` | Esc | Escape key |
|
|
47
|
+
| `Up` / `Down` / `Left` / `Right` | Arrow | Arrow keys |
|
|
48
|
+
| `Space` | ␣ | Space bar |
|
|
49
|
+
|
|
50
|
+
Any key name not in this list is rendered as-is (e.g. `"K"` stays `"K"`).
|
|
51
|
+
|
|
52
|
+
## CSS Variables
|
|
53
|
+
|
|
54
|
+
Override these custom properties to theme the component.
|
|
55
|
+
|
|
56
|
+
| Variable | Default | CSS Property | Description |
|
|
57
|
+
| -------------------------------------- | ------------------- | ---------------- | --------------------------------------------------------------------------------- |
|
|
58
|
+
| `--keyboard-input-gap` | `4px` | gap | Spacing between key badges and separators. |
|
|
59
|
+
| `--keyboard-input-font-family` | `inherit` | font-family | Font family for the entire component. |
|
|
60
|
+
| `--keyboard-input-font-size` | `14px` | font-size | Font size of the entire component. |
|
|
61
|
+
| `--keyboard-input-cursor` | `default` | cursor | Cursor style when hovering over the component. |
|
|
62
|
+
| `--keyboard-input-separator-color` | `currentColor` | color | Text color of the separator character between keys. |
|
|
63
|
+
| `--keyboard-input-separator-font-size` | `0.85em` | font-size | Font size of the separator character. |
|
|
64
|
+
| `--keyboard-input-key-font-family` | `inherit` | font-family | Font family for individual key badges. |
|
|
65
|
+
| `--keyboard-input-key-font-weight` | `500` | font-weight | Font weight of the key text. |
|
|
66
|
+
| `--keyboard-input-key-color` | `currentColor` | color | Text color inside key badges. |
|
|
67
|
+
| `--keyboard-input-key-background` | `transparent` | background-color | Background color of key badges. |
|
|
68
|
+
| `--keyboard-input-key-border` | `1px solid currentColor` | border | Border of key badges. |
|
|
69
|
+
| `--keyboard-input-key-border-radius` | `6px` | border-radius | Corner rounding of key badges. |
|
|
70
|
+
| `--keyboard-input-key-box-shadow` | `0 1px 0 currentColor` | box-shadow | Shadow below key badges giving a raised keyboard key effect. |
|
|
71
|
+
| `--keyboard-input-key-min-width` | `1.6em` | min-width | Minimum width of each key badge (ensures narrow keys like "K" are not too small). |
|
|
72
|
+
| `--keyboard-input-key-padding` | `2px 6px` | padding | Inner padding of key badges. |
|
|
73
|
+
|
|
74
|
+
## Type Reference
|
|
75
|
+
|
|
76
|
+
```typescript
|
|
77
|
+
type KeyboardInputProperties = MandatoryKeyboardInputProperties &
|
|
78
|
+
OptionalKeyboardInputProperties &
|
|
79
|
+
KeyboardInputEventProperties;
|
|
80
|
+
|
|
81
|
+
type MandatoryKeyboardInputProperties = {
|
|
82
|
+
keys: string[] | string;
|
|
83
|
+
};
|
|
84
|
+
|
|
85
|
+
type OptionalKeyboardInputProperties = {
|
|
86
|
+
separator?: string;
|
|
87
|
+
testId?: string;
|
|
88
|
+
classes?: string;
|
|
89
|
+
};
|
|
90
|
+
|
|
91
|
+
type KeyboardInputEventProperties = {
|
|
92
|
+
onclick?: (event: MouseEvent) => void;
|
|
93
|
+
};
|
|
94
|
+
```
|
|
95
|
+
|
|
96
|
+
## Web Component
|
|
97
|
+
|
|
98
|
+
Tag: `<pui-keyboard-input>`
|
|
99
|
+
|
|
100
|
+
```html
|
|
101
|
+
<pui-keyboard-input separator="+"></pui-keyboard-input>
|
|
102
|
+
```
|
|
103
|
+
|
|
104
|
+
> **Note:** The `keys` prop is an array — set it via JavaScript property.
|