svelte-ant-design 0.4.1 → 0.5.0

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/README.md CHANGED
@@ -18,7 +18,7 @@ Ant Design.
18
18
 
19
19
  ## Status
20
20
 
21
- Version `0.4.1`. Available components: `Button`, `Checkbox` (with `CheckboxGroup`), `Input` (with `InputTextArea`, `InputPassword`, `InputSearch` and `InputOTP`), `Switch`. More components are planned.
21
+ Version `0.5.0`. Available components: `Button`, `Checkbox` (with `CheckboxGroup`), `Input` (with `InputTextArea`, `InputPassword`, `InputSearch` and `InputOTP`), `Select` (with `SelectOption` and `SelectOptGroup`), `Switch`. More components are planned.
22
22
 
23
23
  ## Installation
24
24
 
@@ -51,11 +51,13 @@ Vite in `tests/packaging`; other bundlers are not covered.
51
51
 
52
52
  See the [Button](https://prostreyd.github.io/ant-design-svelte/components/button/),
53
53
  [Checkbox](https://prostreyd.github.io/ant-design-svelte/components/checkbox/),
54
- [Input](https://prostreyd.github.io/ant-design-svelte/components/input/) and
54
+ [Input](https://prostreyd.github.io/ant-design-svelte/components/input/),
55
+ [Select](https://prostreyd.github.io/ant-design-svelte/components/select/) and
55
56
  [Switch](https://prostreyd.github.io/ant-design-svelte/components/switch/) pages of the documentation site for
56
57
  examples and the API tables, or [`src/lib/Button/README.md`](./src/lib/Button/README.md),
57
58
  [`src/lib/Checkbox/README.md`](./src/lib/Checkbox/README.md),
58
- [`src/lib/Input/README.md`](./src/lib/Input/README.md) and
59
+ [`src/lib/Input/README.md`](./src/lib/Input/README.md),
60
+ [`src/lib/Select/README.md`](./src/lib/Select/README.md) and
59
61
  [`src/lib/Switch/README.md`](./src/lib/Switch/README.md) in the repository.
60
62
 
61
63
  ### Colors and contrast
@@ -0,0 +1,104 @@
1
+ # Select
2
+
3
+ A drop-down list with Ant Design-inspired styles and a Svelte 5 API. Three components:
4
+
5
+ | Component | What it is |
6
+ |---|---|
7
+ | `Select` | the field and its list, in the modes single (default), `multiple` and `tags` |
8
+ | `SelectOption` | one option, written inside `Select` or `SelectOptGroup` (the markup form of an `options` entry) |
9
+ | `SelectOptGroup` | a labelled group of `SelectOption`s |
10
+
11
+ ## Usage
12
+
13
+ Import the design tokens once in the application entry point:
14
+
15
+ ```ts
16
+ import 'svelte-ant-design/tokens.css';
17
+ ```
18
+
19
+ ```svelte
20
+ <script lang="ts">
21
+ import { Select } from 'svelte-ant-design';
22
+
23
+ let city = $state<string | number | undefined>();
24
+ </script>
25
+
26
+ <Select
27
+ bind:value={city}
28
+ aria-label="City"
29
+ placeholder="Pick a city"
30
+ options={['Bishkek', 'Almaty', { value: 'tashkent', label: 'Tashkent' }]}
31
+ style="width: 240px"
32
+ />
33
+ ```
34
+
35
+ A Select has no label of its own: name it with an external `<label for>` (and the `id` of the field), `aria-label`
36
+ or `aria-labelledby`. The placeholder is not a name. The field fills its container like `Input`; set the width with
37
+ `class` or `style`.
38
+
39
+ `options` take strings and numbers (both the value and the label), objects (`{ value, label, disabled, title, class }`,
40
+ other keys pass through to the callbacks) and groups (an object with an `options` array). `fieldNames` maps the keys of
41
+ your own data. `onchange` receives the value and the option object; for `multiple` and `tags` the value is an array and
42
+ the option is an array of objects.
43
+
44
+ ```svelte
45
+ <Select mode="multiple" bind:value={languages} options={['Svelte', 'Rust', 'Go']} aria-label="Languages" maxTagCount={2} />
46
+ <Select mode="tags" bind:value={tags} tokenSeparators={[',']} aria-label="Tags" />
47
+ <Select showSearch options={people} optionFilterProp={['label', 'team']} aria-label="Person" />
48
+ ```
49
+
50
+ ## Options as markup
51
+
52
+ `SelectOption` and `SelectOptGroup` written inside `Select` give the same options as `options`, in the order of the
53
+ markup, also after `{#each}` and `{#if}` insert or move one. A non-empty `options` wins and the children are ignored.
54
+
55
+ ```svelte
56
+ <Select bind:value aria-label="Mood">
57
+ <SelectOption value="happy" label="Happy" />
58
+ <SelectOptGroup label="Other">
59
+ <SelectOption value="sad" label="Sad" />
60
+ </SelectOptGroup>
61
+ </Select>
62
+ ```
63
+
64
+ The text that search, type-ahead and the accessible name use is the `label` when it is a string, then the `title`, then
65
+ the value. The content of an option (its `children`) is only drawn, so write a `label` for an option that has to be found
66
+ by search.
67
+
68
+ ## Behavior to know
69
+
70
+ - DOM focus never leaves the field: the highlighted option is shown by `aria-activedescendant`, and a press inside the
71
+ list does not blur the field.
72
+ - The list is put at the end of the page (`container` changes that), so it is never cut off by the container of the field.
73
+ It flips at the edge of the screen and follows the field while the page scrolls.
74
+ - The search text is cleared when the list closes, and `onsearch` is told. `filterOption={false}` leaves the list to you
75
+ (server-side search).
76
+ - Tab only closes the list and keeps the value.
77
+ - A long list renders all its options in this version (there is no `virtual` yet); `listHeight` makes it scroll.
78
+ - The built-in texts (`No data`, `Clear`, `Remove ...`, and the number of matches announced while searching) are English;
79
+ `notFoundContent`, `allowClear.label` and `resultsText` replace three of them.
80
+ - The type of an option object is `SelectOptionItem`, because `SelectOption` is the component.
81
+ - The field is not a native form control: it does not submit with a `<form>`. Read `value`.
82
+
83
+ ## Accessibility
84
+
85
+ The focused element is a `<div>` or, with `showSearch`, an `<input>`, with `role="combobox"`, `aria-expanded`,
86
+ `aria-controls` and `aria-activedescendant`; the list is a `listbox` of `option`s and `group`s. Keys: Down, Up, Alt+Down,
87
+ Alt+Up, Enter, Space, Home, End, PageUp, PageDown, Escape, Tab, Backspace, and typing characters in a field that cannot
88
+ search. Forced-colors modes (Windows High Contrast) are supported. Support for `aria-activedescendant` in iOS VoiceOver has
89
+ been weak, so check a Select by hand there.
90
+
91
+ Known limitation: Orca announces a change of `aria-selected` only after the Space key. In a field that searches (the default
92
+ of `multiple` and `tags`) Space types a space and Enter toggles an option, so Orca says nothing when one is toggled; the
93
+ field reads the selected values when it gets focus. The React, Vue and Angular demos of Ant Design are silent in the same
94
+ case. An announcement of the toggled option (`selectionText`) is planned for v1.1 with the translation of the built-in texts,
95
+ after NVDA, JAWS and VoiceOver have been tried.
96
+
97
+ The default light colors are Ant Design's own and do not reach WCAG AA for every text. Import `tokens-accessible.css`
98
+ after `tokens.css` for colors that do.
99
+
100
+ ## API and examples
101
+
102
+ The API tables, the methods and the design tokens are on the
103
+ [Select page](https://prostreyd.github.io/ant-design-svelte/components/select/) of the documentation site, with a live
104
+ example for every property. The specification is [`specs/select.md`](../../../specs/select.md).