Skip to content

Commit

Permalink
Moving styles back to components. Updated docs for v5
Browse files Browse the repository at this point in the history
  • Loading branch information
@rob-balfre
rob-balfre committed Dec 19, 2021
1 parent 08b5425 commit 0ca29f2
Show file tree
Hide file tree
Showing 23 changed files with 814 additions and 2,289 deletions.
11 changes: 6 additions & 5 deletions CHANGELOG.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -2,9 +2,11 @@

## unreleased


* select-container -> svelte-select
* removed imports prop, not worth it for the annoyance
* removed clear all from multi select
* added justValue
* Placeholder default change from 'Select...' to 'Please select'
* breaking: `value` just binds to selected option value
* updated readme
* LoadingIcon
* added blur and focus events
Expand All @@ -31,7 +33,7 @@
* virtualList -> virtual-list
* listContainer -> list
* bye bye yarn
* selectContainer and other CSS class names updated, selectContainer -> select-container for example
* selectContainer and other CSS class names updated, selectContainer -> svelte-select for example
* LoadingIcon prop added, must be imported to have a spinner/loader
* CSS props updates. Added .icons and removed some css vars
* ClearIcon and ChevronIcon no longer included by default
Expand All @@ -41,12 +43,11 @@
* indicatorSvg removed, use ChevronIcon going forward
* removed playwright and puppeteer, tests now just run in the browser with sirv
* debounce method is now exported as a prop
* Multi component no longer included by default, must be imported going forward
* VirtualList null by default
* Removed isVirtualList, will use VirtualList going forward
* Convert repo to use SvelteKit
* Change licence from LIL to ISC
* Cleaned up package.json


## 4.4.1

Expand Down
230 changes: 104 additions & 126 deletions README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -24,101 +24,102 @@

```bash
npm install svelte-select
npm install svelte-select
```

## Usage
## Migrating for v4 to v5

```html
<script>
import Select from 'svelte-select';
let items = [
{value: 'chocolate', label: 'Chocolate'},
{value: 'pizza', label: 'Pizza'},
{value: 'cake', label: 'Cake'},
{value: 'chips', label: 'Chips'},
{value: 'ice-cream', label: 'Ice Cream'},
];
v5 is a major release that that includes some ⚠️ BREAKING CHANGES ⚠️

let value = {value: 'cake', label: 'Cake'};
Removed `isVirtualList` instead `npm i svelte-tiny-virtual-list -D` and

function handleSelect(event) {
console.log('selected item', event.detail);
// .. do something here 🙂
}
```svelte
<script>
import VirtualList from 'svelte-tiny-virtual-list';
</script>
<Select {items} {value} on:select={handleSelect}></Select>
<Select VirtualList />
```

## API


| Prop | Type | Default | Description |
| ---------------- | --------- | --------------- | ------------------------------------------------------- |
| items | `array` | `[]` | Array items available to display / filter |
| value | `any` | `null` | Selected value(s) |
| justValue | `any` | `null` | Selected value(s) excluding container object |
| optionIdentifier | `string` | `value` | Override default identifier |
| labelIdentifier | `string` | `label` | Override default identifier |
| id | `string` | `null` | Add an id to the filter input field |
| filterText | `string` | `''` | Text to filter `items` by |
| placeholder | `string` | `Please select` | Placeholder text |
| noOptionsMessage | `string` | `No options` | Message displayed when no items |
| hideEmptyState | `boolean` | `false` | When no items hide list and `noOptionsMessage` |
| listOpen | `boolean` | `false` | Open/close list |
| class | `string` | `''` | container classes |
| containerStyles | `string` | `''` | Add inline styles to container |
| isClearable | `boolean` | `true` | Enable clearing of value(s) |
| isCreatable | `boolean` | `false` | Can create new item(s) to be added to `value` |
| isDisabled | `boolean` | `false` | Disable select |
| isMulti | `boolean` | `false` | Enable multi-select (must include `Multi` in `imports`) |
| imports | `object` | `{}` | Optional imports |



### Optional imports
CSS classes and custom properties converted from camel to kebab case. For example `selectedItem` → `selected-item` and `--borderRadius` → `--border-radius`

### Other CSS class name changes:
`selectContainer` → `svelte-select`
`listContainer` → `list`
`indicator` → `chevron`
`virtual-list` removed

### Prop changes:
`containerClasses` → `class`
`MultiSelection` → `Multi`
`indicatorSvg` → `ChevronIcon`
`selectedValue` removed (was already deprecated in v4 in favour of `value`)
`loadOptionsInterval` → `debounceWait`


## Props


| Prop | Type | Default | Description |
| ----------------------- | --------- | --------------- | -------------------------------------------------- |
| items | `array` | `[]` | Array items available to display / filter |
| value | `any` | `null` | Selected value(s) |
| justValue | `any` | `null` | Selected value(s) excluding container object |
| optionIdentifier | `string` | `value` | Override default identifier |
| labelIdentifier | `string` | `label` | Override default identifier |
| id | `string` | `null` | Add an id to the filter input field |
| filterText | `string` | `''` | Text to filter `items` by |
| placeholder | `string` | `Please select` | Placeholder text |
| noOptionsMessage | `string` | `No options` | Message displayed when no items |
| hideEmptyState | `boolean` | `false` | When no items hide list and `noOptionsMessage` |
| listOpen | `boolean` | `false` | Open/close list |
| class | `string` | `''` | container classes |
| containerStyles | `string` | `''` | Add inline styles to container |
| isClearable | `boolean` | `true` | Enable clearing of value(s) |
| isCreatable | `boolean` | `false` | Can create new item(s) to be added to `value` |
| isDisabled | `boolean` | `false` | Disable select |
| isMulti | `boolean` | `false` | Enable multi-select |
| isSearchable | `boolean` | `true` | If `false` search/filtering is disabled |
| isGroupHeaderSelectable | `boolean` | `false` | Enable selectable group headers |
| listPlacement | `string` | `auto` | Display list `'auto'`, `'top'` or `'bottom'` |
| hasError | `boolean` | `false` | Show error styles around select input |
| listAutoWidth | `boolean` | `true` | If `false` will ignore width of select |
| showChevron | `boolean` | `false` | Show chevron at all times |
| inputAttributes | `object` | `{}` | Pass in HTML attributes to Select's input |
| iconProps | `object` | `{}` | Icon props |
| filteredItems | `array` | `[]` | List of items after filtering (read only) |
| placeholderAlwaysShow | `boolean` | `false` | When `isMulti` placeholder text will always show |
| isWaiting | `boolean` | `false` | Show LoadingIcon. `loadOptions` will override this |
| listOffset | `number` | `5` | `px` space between select and list |
| debounceWait | `number` | `300` | `milliseconds` debounce wait |
| suggestions | `boolean` | `false` | Show search suggestions before user input |


### Replaceable components

| Import | Type | Description |
| ----------- | ----------- | --------------------- |
| Item | `component` | Item component |
| Selection | `component` | Selection component |
| Multi | `component` | Multi select support |
| ChevronIcon | `component` | Chevron Icon |
| ClearIcon | `component` | Clear Icon |
| LoadingIcon | `component` | Spinning Loading Icon |


### Optional component imports

| Import | Type | Description |
| ----------- | ----------- | ------------------------------------------------------ |
| VirtualList | `component` | Virtual list support (uses `svelte-tiny-virtual-list`) |
| Multi | `component` | Multi select support |
| ChevronIcon | `component` | Chevron Icon |
| ClearIcon | `component` | Clear Icon |
| LoadingIcon | `component` | Spinning Loading Icon |
| debounce | `function` | Debounce function |
| filter | `function` | Filter options function |
| getItems | `function` | Async get items function |



- `isMulti: Boolean` Default: `false`. Enable multi-select, `value` becomes an array of selected items.
- `isSearchable: Boolean` Default: `true`. Enable search/filtering of `items` via `filterText`.
- `isGroupHeaderSelectable: Boolean` Default: `false`. Enable selectable group headers in `items` (see adv demo).
- `listPlacement: String` Default: `'auto'`. When `'auto'` displays either `'top'` or `'bottom'` depending on viewport.
- `hasError: Boolean` Default: `false`. Show/hide error styles around select input (red border by default).
- `listAutoWidth: Boolean` Default: `true`. List width will grow wider than the Select container (depending on list item content length).
- `showChevron: Boolean` Default: `false`. If true, the chevron indicator is always shown.
- `inputAttributes: Object` Default: `{}`. Pass in HTML attributes to the Select input.
- `Item: Component` Default: `Item`. Item component.
- `Selection: Component` Default: `Selection`. Selection component.
- `Multi: Component` Default: `Multi`. Multi selection component.
- `Icon: Component` Default: `Icon`. Icon component.
- `iconProps: Object` Default: `{}`. Icon props.
- `ClearIcon` Default: `ClearIcon`. ClearIcon component.
- `filteredItems: Array` Default: `[]`. List of items that are filtered by `filterText`
- `placeholderAlwaysShow: Boolean` Default: `false`. When `isMulti` then placeholder text will always still show.
- `isWaiting: Boolean` Default: `false`. If true then loader shows. `loadOptions` will automatically set this as true until promise resolves.
- `listOffset: Number` Default: `5`. Controls the spacing offset between the list and the input.
- `debounceWait`
- `suggestions`
| Icon | `component` | Icon component |


### Items

`items` can be simple arrays or collections.

```html
```svelte
<script>
import Select from 'svelte-select';
Expand All @@ -138,7 +139,7 @@ npm install svelte-select

They can also be grouped and include non-selectable items.

```html
```svelte
<script>
import Select from 'svelte-select';
Expand All @@ -154,12 +155,11 @@ They can also be grouped and include non-selectable items.
</script>
<Select {items} {groupBy} />

```

You can also use custom collections.

```html
```svelte
<script>
import Select from 'svelte-select';
Expand All @@ -179,7 +179,7 @@ You can also use custom collections.

To load items asynchronously then `loadOptions` is the simplest solution. Supply a function that returns a `Promise` that resolves with a list of items. `loadOptions` has debounce baked in and fires each time `filterText` is updated.

```html
```svelte
<script>
import Select from 'svelte-select';
Expand Down Expand Up @@ -268,6 +268,21 @@ export const getFilteredItems = () => {
};
```

```js
export function debounce(fn, wait = 1) {
let timeout;
return function (...args) {
clearTimeout(timeout);
timeout = setTimeout(() => fn.apply(this, ...args), wait);
};
}
```

| debounce | `function` | Debounce function |
| filter | `function` | Filter options function |
| loadOptions | `function` | Return a `Promise` that resolves with items |
| getItems | `function` | Take full control of async and loadOptions defaults |

## A11y (Accessibility)

Override these methods to change the `aria-context` and `aria-selection` text.
Expand All @@ -288,32 +303,19 @@ export let ariaFocused = () => {

## Styling

You can style a component by overriding [the available CSS variables](/docs/theming_variables.md).
You can style a component by overriding [the available CSS custom properties](/docs/theming_variables.md).

```html
```svelte
<script>
import Select from 'svelte-select';
const items = ['One', 'Two', 'Three'];
</script>
<style>
.themed {
--border: 3px solid blue;
--borderRadius: 10px;
--placeholderColor: blue;
}
</style>

<div class="themed">
<h2>Theming</h2>
<Select {items}></Select>
</div>
<Select --border-radius= "10px" --placeholder-color="blue" />
```

You can also use the `inputStyles` prop to write in any override styles needed for the input.

```html
```svelte
<script>
import Select from 'svelte-select';
Expand All @@ -328,38 +330,21 @@ You can also use the `inputStyles` prop to write in any override styles needed f
| Event Name | Callback | Description |
| ---------- | ----------------- | ------------------------------------------------------------------------------ |
| select | { detail } | fires when value changes |
| focus | { detail } | fires when select > input on:focus |
| blur | { detail } | fires when select > input on:blur |
| clear | { detail } | fires when clear all is invoked or item is removed (by user) from multi select |
| loaded | { options } | fires when `loadOptions` resolves |
| error | { type, details } | fires when error is caught |

```html
<script>
import Select from 'svelte-select';
let items = [...];
function handleSelect(event) {
// event.detail will contain the selected value
...
}
function handleClear(event) {
// event.detail will be null unless isMulti is true and user has removed a single item
...
}
</script>

<Select {items} on:select={handleSelect} on:clear={handleClear}></Select>
```

## Development

```bash
yarn global add serve@8
yarn
yarn dev
npm i
npm run dev-tests
yarn test:browser
```

In your favourite browser go to http://localhost:3000 and open devtools and see the console for the test output. When developing its handy to see the component on the page; comment out the `select.$destroy();` on the last test in /test/src/index.js or use the `test.only()` to target just one test.
In your browser go to http://localhost:3000 and open devtools and see the console output. When developing it's useful to see the component on the page; comment out the `select.$destroy();` on the last test in /test/src/index.js or use the `test.only()` to target just one test.

For example:

Expand All @@ -381,13 +366,6 @@ test.only('when getSelectionLabel contains HTML then render the HTML', async (t)
```


## Configuring webpack

If you're using webpack with [svelte-loader](https://github.com/sveltejs/svelte-loader), make sure that you add `"svelte"` to [`resolve.mainFields`](https://webpack.js.org/configuration/resolve/#resolve-mainfields) in your webpack config. This ensures that webpack imports the uncompiled component — this is more efficient.

If you're using Rollup with [rollup-plugin-svelte](https://github.com/rollup/rollup-plugin-svelte), this will happen automatically.


## License

[LIL](LICENSE)
Loading

0 comments on commit 0ca29f2

Please sign in to comment.