@rescui/select 0.17.1 → 0.17.2-RUI-296-Build-docs-md-files-for-each-docs-section-b138dd5bf.15

package/llm/components/multiselect.md

@@ -0,0 +1,237 @@
+# Multiselect
+
+Multiselect is a control that allows users to select multiple options from a list.
+
+## Usage
+
+### Features showcase
+
+#### Example:
+
+You can control what has been selected through `value`/`onChange` props combination. The state represents the collection of options displayed in the select box. The empty state represents by `[]`.
+
+```tsx
+import { useState } from 'react';
+import { Multiselect } from '@rescui/select';
+
+const options = [
+  { label: 'St. Petersburg', value: 'spb' },
+  { label: 'Moscow', value: 'msk' },
+  { label: 'Novosibirsk', value: 'nsk' },
+  { label: 'Prague', value: 'prg' },
+  { label: 'Boston', value: 'bos' },
+  { label: 'Munich', value: 'muc' }
+];
+
+const MySelect = () => {
+  const [selected, setSelected] = useState([options[0], options[5]]);
+
+  return (
+    <div>
+      <span>Selected cities: </span>
+      <code>{JSON.stringify(selected)}</code>
+      <div style={{ maxWidth: '380px', marginTop: '24px' }}>
+        <Multiselect
+          options={options}
+          value={selected}
+          onChange={value => {
+            console.log('value', value);
+            setSelected(value);
+          }}
+          size="m"
+          placeholder="Сhoose your favorite cities..."
+          aria-label="Сhoose your favorite cities"
+        />
+      </div>
+    </div>
+  );
+};
+
+render(<MySelect />);
+```
+
+#### SingleLine mode:
+
+You can use the `isSingleLine` prop to limit from grow and force it to be always single line. In this case extra tags is hidden and display the count of hidden tags instead.
+
+```tsx
+import { useState } from 'react';
+import { Multiselect } from '@rescui/select';
+
+const options = [
+  { label: 'Blue', value: 'blue' },
+  { label: 'Black', value: 'black' },
+  { label: 'Red', value: 'red' },
+  { label: 'Orange', value: 'orange' },
+  { label: 'Yellow', value: 'yellow' },
+  { label: 'White', value: 'white' }
+];
+
+const MySelect = () => {
+  const [selected, setSelected] = useState([options[1], options[5]]);
+
+  return (
+    <div style={{ maxWidth: '380px' }}>
+      <Multiselect
+        className="clazz"
+        options={options}
+        value={selected}
+        onChange={value => setSelected(value)}
+        isSingleLine
+        size="m"
+        placeholder="Select colors..."
+        aria-label="Select colors"
+      />
+    </div>
+  );
+};
+
+render(<MySelect />);
+```
+
+#### Contrast primary color
+
+If your primary color background requires dark text color, use `--rs-select-contrast-primary` CSS variable.
+
+```tsx
+import { useState } from 'react';
+import { Multiselect } from '@rescui/select';
+
+const options = [
+  { label: 'St. Petersburg', value: 'spb' },
+  { label: 'Moscow', value: 'msk' },
+  { label: 'Novosibirsk', value: 'nsk' },
+  { label: 'Prague', value: 'prg' },
+  { label: 'Boston', value: 'bos' },
+  { label: 'Munich', value: 'muc' }
+];
+
+const MySelect = () => {
+  const [selected, setSelected] = useState([options[0], options[5]]);
+
+  return (
+    <div>
+      <span>Selected cities: </span>
+      <code>{JSON.stringify(selected)}</code>
+      <div
+        style={{ maxWidth: '380px', marginTop: '24px' }}
+        className="light-green-primary"
+      >
+        <Multiselect
+          options={options}
+          value={selected}
+          onChange={setSelected}
+          size="m"
+          className="select-with-contrast-primary"
+          placeholder="Сhoose your favorite cities..."
+          aria-label="Сhoose your favorite cities"
+        />
+      </div>
+    </div>
+  );
+};
+
+render(<MySelect />);
+```
+
+```postcss
+.select-with-contrast-primary {
+  --rs-select-contrast-primary: 1;
+}
+
+.light-green-primary {
+  --rs-color-primary-light-theme: rgb(71, 224, 84);
+  --rs-color-primary-t-dim-light-theme: rgba(71, 224, 84, 0.8);
+  --rs-color-primary-t-fog-light-theme: rgba(71, 224, 84, 0.2);
+
+  --rs-color-primary-dark-theme: rgb(71, 224, 84);
+  --rs-color-primary-t-dim-dark-theme: rgba(71, 224, 84, 0.8);
+  --rs-color-primary-t-fog-dark-theme: rgba(71, 224, 84, 0.2);
+}
+```
+
+## CSS Mixins API
+
+#### `Multiselect` mixins
+
+| Mixin name | Details |
+| --- | --- |
+| `rs-multiselect-size-s` | prop: `size`<br><br>value: `"s"` |
+| `rs-multiselect-size-m` | prop: `size`<br><br>value: `"m"` |
+| `rs-multiselect-size-l` | prop: `size`<br><br>value: `"l"` |
+
+#### Demo
+
+Resize the grey area below to see the effect.
+
+You can use `@media` queries instead of `@container` queries:
+
+```tsx
+import { useState } from 'react';
+import { Multiselect } from '@rescui/select';
+
+const options = [
+  { label: 'St. Petersburg', value: 'spb' },
+  { label: 'Moscow', value: 'msk' },
+  { label: 'Novosibirsk', value: 'nsk' },
+  { label: 'Prague', value: 'prg' },
+  { label: 'Boston', value: 'bos' },
+  { label: 'Munich', value: 'muc' }
+];
+
+const MyMultiselect = ({ className }) => {
+  const [selected, setSelected] = useState([options[0], options[5]]);
+
+  return (
+    <div style={{ maxWidth: '380px' }}>
+      <Multiselect
+        options={options}
+        value={selected}
+        onChange={value => setSelected(value)}
+        size="m"
+        placeholder="Сhoose your favorite cities..."
+        aria-label="Choose your favorite cities"
+        className={className}
+      />
+    </div>
+  );
+};
+
+render(
+  <div className="preview-container">
+    <p style={{ position: 'absolute', right: 12, bottom: 12 }}>Resize me</p>
+    <MyMultiselect className="my-multiselect" />
+  </div>
+);
+```
+
+```postcss
+@import '@rescui/select/lib/public-api.p.css';
+
+.preview-container {
+  position: relative;
+  container-type: inline-size;
+  resize: horizontal;
+  overflow: auto;
+  padding: 12px;
+  background-color: var(--rs-color-black-t5);
+  max-width: 800px;
+}
+
+.my-multiselect {
+  @container (max-width: 640px) {
+    @mixin rs-multiselect-size-l;
+  }
+  @container (max-width: 500px) {
+    @mixin rs-multiselect-size-s;
+  }
+}
+```
+
+#### `Select` CSS Vars
+
+| Variable | Syntax | Description |
+| --- | --- | --- |
+| `--rs-select-contrast-primary` | `0 \| 1` | The flag whenever the current primary is contrast enough and highlighted text color should be inverted |
+
+Check out [this example](/components/multiselect/#contrast-primary-color) for contrast primary.