@ptlm-azulejo/combobox 0.0.1-alpha.121
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/CHANGELOG.md +4 -0
- package/README.md +146 -0
- package/dist/index.js +3753 -0
- package/dist/index.umd.cjs +1 -0
- package/dist/packages/Combobox/index.d.ts +3 -0
- package/dist/packages/Combobox/index.d.ts.map +1 -0
- package/dist/packages/Combobox/src/index.vue.d.ts +373 -0
- package/dist/packages/Combobox/src/index.vue.d.ts.map +1 -0
- package/dist/style.css +1 -0
- package/package.json +46 -0
package/CHANGELOG.md
ADDED
package/README.md
ADDED
|
@@ -0,0 +1,146 @@
|
|
|
1
|
+
# Combobox
|
|
2
|
+
|
|
3
|
+
A combobox is an input that lets users pick an option from a dropdown list — or
|
|
4
|
+
several, in multiple mode. Also known as select, dropdown, or listbox input.
|
|
5
|
+
|
|
6
|
+
## Installation
|
|
7
|
+
|
|
8
|
+
Install the component, the theme package, and **the font package matching your
|
|
9
|
+
project's brand**:
|
|
10
|
+
|
|
11
|
+
**Leroy Merlin projects**
|
|
12
|
+
|
|
13
|
+
```bash
|
|
14
|
+
npm install @ptlm-azulejo/combobox @ptlm-azulejo/themes @ptlm-azulejo/fonts-leroy-merlin
|
|
15
|
+
# or
|
|
16
|
+
yarn add @ptlm-azulejo/combobox @ptlm-azulejo/themes @ptlm-azulejo/fonts-leroy-merlin
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
**Adeo projects**
|
|
20
|
+
|
|
21
|
+
```bash
|
|
22
|
+
npm install @ptlm-azulejo/combobox @ptlm-azulejo/themes @ptlm-azulejo/fonts-adeo
|
|
23
|
+
# or
|
|
24
|
+
yarn add @ptlm-azulejo/combobox @ptlm-azulejo/themes @ptlm-azulejo/fonts-adeo
|
|
25
|
+
```
|
|
26
|
+
|
|
27
|
+
## Styles & theming
|
|
28
|
+
|
|
29
|
+
The component ships no colors or typeface of its own — it reads design tokens from
|
|
30
|
+
CSS variables at runtime. Those tokens come from `@ptlm-azulejo/themes`, and **the
|
|
31
|
+
brand is selected by a class on your app's `<html>` element**, so switching brand
|
|
32
|
+
never touches component code.
|
|
33
|
+
|
|
34
|
+
| Project | Preset stylesheet | Root class | Typeface | Font package |
|
|
35
|
+
| ------------ | ----------------------------------------------- | ------------- | --------------- | ---------------------------------- |
|
|
36
|
+
| Leroy Merlin | `@ptlm-azulejo/themes/presets/leroy-merlin.css` | `preset-lm` | LeroyMerlinSans | `@ptlm-azulejo/fonts-leroy-merlin` |
|
|
37
|
+
| Adeo | `@ptlm-azulejo/themes/presets/adeo.css` | `preset-adeo` | Roboto | `@ptlm-azulejo/fonts-adeo` |
|
|
38
|
+
|
|
39
|
+
**Leroy Merlin projects**
|
|
40
|
+
|
|
41
|
+
```js
|
|
42
|
+
import '@ptlm-azulejo/themes/presets/leroy-merlin.css'
|
|
43
|
+
import '@ptlm-azulejo/fonts-leroy-merlin'
|
|
44
|
+
import '@ptlm-azulejo/combobox/style.css'
|
|
45
|
+
```
|
|
46
|
+
|
|
47
|
+
```html
|
|
48
|
+
<html lang="pt" class="preset-lm"></html>
|
|
49
|
+
```
|
|
50
|
+
|
|
51
|
+
**Adeo projects**
|
|
52
|
+
|
|
53
|
+
```js
|
|
54
|
+
import '@ptlm-azulejo/themes/presets/adeo.css'
|
|
55
|
+
import '@ptlm-azulejo/fonts-adeo'
|
|
56
|
+
import '@ptlm-azulejo/combobox/style.css'
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
```html
|
|
60
|
+
<html lang="pt" class="preset-adeo"></html>
|
|
61
|
+
```
|
|
62
|
+
|
|
63
|
+
> The preset class is what resolves the brand at runtime. Without it — even with
|
|
64
|
+
> the stylesheets imported — the component renders uncolored and in a fallback
|
|
65
|
+
> typeface. See the [themes package](../themes/README.md) for brand switching,
|
|
66
|
+
> dark mode, and custom brands.
|
|
67
|
+
|
|
68
|
+
### Light and dark mode
|
|
69
|
+
|
|
70
|
+
Add `data-theme` alongside the brand class to pin the color scheme. Leave it off
|
|
71
|
+
and the preset follows the OS `prefers-color-scheme`:
|
|
72
|
+
|
|
73
|
+
```html
|
|
74
|
+
<html lang="pt" class="preset-lm" data-theme="dark"></html>
|
|
75
|
+
```
|
|
76
|
+
|
|
77
|
+
### Why the font package is separate
|
|
78
|
+
|
|
79
|
+
The preset only _names_ its typeface in `--font-family` and ships no font files.
|
|
80
|
+
[Loading them is your app's job](../themes/README.md#fonts), as with upstream
|
|
81
|
+
Mozaic, so you keep control of hosting, subsetting and preload. Without the
|
|
82
|
+
matching font package, `font-sans` falls back to a generic sans-serif. A
|
|
83
|
+
multi-brand app can install both and switch by swapping the `.preset-*` class:
|
|
84
|
+
only the active brand's file is ever downloaded.
|
|
85
|
+
|
|
86
|
+
## Props
|
|
87
|
+
|
|
88
|
+
| Name | Type | Default | Description |
|
|
89
|
+
| ------------------- | ------------------------------------------ | --------------------- | ------------------------------------------------------ |
|
|
90
|
+
| `options` | `ComboboxOption[]` | — | Options and optional `{ type: 'section' }` headers |
|
|
91
|
+
| `modelValue` | `string \| number \| (string \| number)[]` | — | Selected value(s) (`v-model`) |
|
|
92
|
+
| `open` | `boolean` | — | Listbox open state (`v-model:open`); omit for internal |
|
|
93
|
+
| `multiple` | `boolean` | `false` | Allow more than one selected value |
|
|
94
|
+
| `size` | `'s' \| 'm'` | `'m'` | `m` = 3rem (`min-h-12`), `s` = 2rem (`min-h-8`) |
|
|
95
|
+
| `disabled` | `boolean` | `false` | Disables the control |
|
|
96
|
+
| `readonly` | `boolean` | `false` | Prevents opening and changing the value |
|
|
97
|
+
| `isInvalid` | `boolean` | `false` | Invalid state |
|
|
98
|
+
| `isClearable` | `boolean` | `false` | Show a clear button when a value is selected |
|
|
99
|
+
| `search` | `boolean` | `false` | Search field inside the listbox |
|
|
100
|
+
| `actions` | `boolean` | `false` | Select-all / clear row when `multiple` |
|
|
101
|
+
| `checkableSections` | `boolean` | `false` | Section headers toggle their options (`multiple`) |
|
|
102
|
+
| `placeholder` | `string` | `'Select an option'` | Trigger text when empty |
|
|
103
|
+
| `counterLabel` | `string` | — | Compact summary + count badge (`multiple`, trigger) |
|
|
104
|
+
| `tagPlacement` | `'trigger' \| 'below'` | `'trigger'` | Selected tags inside the field, or as chips below it |
|
|
105
|
+
| `maxTags` | `number` | `2` | Visible tags before `+N more` / Show all |
|
|
106
|
+
| `showAllLabel` | `string` | `'Show all'` | Overflow control when `tagPlacement="below"` |
|
|
107
|
+
| `showLessLabel` | `string` | `'Show less'` | Label after below tags have been expanded |
|
|
108
|
+
| `searchPlaceholder` | `string` | `'Find an option...'` | Search field placeholder |
|
|
109
|
+
| `selectLabel` | `string` | `'Select all'` | Select-all action label |
|
|
110
|
+
| `clearLabel` | `string` | `'Clear'` | Listbox clear-action label |
|
|
111
|
+
| `controlAriaLabel` | `string` | `'Combobox input'` | Accessible name for the trigger |
|
|
112
|
+
| `clearAriaLabel` | `string` | `'Clear selection'` | Accessible name for the trigger clear button |
|
|
113
|
+
| `ui` | `ComboboxUi` | `{}` | Per-part Tailwind class overrides |
|
|
114
|
+
|
|
115
|
+
## Slots
|
|
116
|
+
|
|
117
|
+
| Name | Props | Description |
|
|
118
|
+
| ------ | -------------------------- | ------------------------------------ |
|
|
119
|
+
| `item` | `{ item: ComboboxOption }` | Customize the content of each option |
|
|
120
|
+
|
|
121
|
+
## Events
|
|
122
|
+
|
|
123
|
+
| Name | Payload | Description |
|
|
124
|
+
| ------------------- | ------------------------------------------ | ------------------------- |
|
|
125
|
+
| `update:modelValue` | `string \| number \| (string \| number)[]` | Selected value(s) changed |
|
|
126
|
+
| `update:open` | `boolean` | Listbox opened or closed |
|
|
127
|
+
|
|
128
|
+
## Basic usage
|
|
129
|
+
|
|
130
|
+
```vue
|
|
131
|
+
<script setup>
|
|
132
|
+
import { ref } from 'vue'
|
|
133
|
+
import { AzCombobox } from '@ptlm-azulejo/combobox'
|
|
134
|
+
|
|
135
|
+
const country = ref()
|
|
136
|
+
const options = [
|
|
137
|
+
{ label: 'Portugal', value: 'pt' },
|
|
138
|
+
{ label: 'France', value: 'fr' },
|
|
139
|
+
{ label: 'Spain', value: 'es' },
|
|
140
|
+
]
|
|
141
|
+
</script>
|
|
142
|
+
|
|
143
|
+
<template>
|
|
144
|
+
<AzCombobox v-model="country" :options="options" control-aria-label="Select a country" />
|
|
145
|
+
</template>
|
|
146
|
+
```
|