@rescui/select 0.17.2 → 0.18.0

package/llm/components/select.md

@@ -0,0 +1,572 @@
+# Select
+
+Select is a control that allows users to select one option from a longer list.
+
+## Usage
+
+### Features showcase
+
+### Usage
+
+Countries:
+
+```tsx
+import { useState } from 'react';
+import { Select } from '@rescui/select';
+import COUNTRIES from '@/parts/select/countries';
+
+const options = COUNTRIES.map(country => ({
+  label: country,
+  value: country
+}));
+
+const MySelect = () => {
+  const [selected, setSelected] = useState(options[42]);
+
+  return (
+    <div style={{ maxWidth: '380px' }}>
+      <Select
+        options={options}
+        value={selected}
+        onChange={value => setSelected(value)}
+        size="s"
+        isSearchable
+        label="Select country"
+      />
+    </div>
+  );
+};
+
+render(<MySelect />);
+```
+
+Default value:
+
+```tsx
+import { useState } from 'react';
+import { Select } from '@rescui/select';
+
+const options = [
+  { label: 'Light', value: 'light' },
+  { label: 'Regular', value: 'regular' },
+  { label: 'Medium', value: 'medium' },
+  { label: 'Bold', value: 'bold' }
+];
+const MySelect = () => {
+  const [selected, setSelected] = useState({
+    label: 'Medium',
+    value: 'medium'
+  });
+
+  return (
+    <div style={{ maxWidth: '380px' }}>
+      <Select
+        options={options}
+        value={selected}
+        onChange={value => setSelected(value)}
+        size="m"
+        placeholder="Select font weight..."
+        aria-label="Select font weight"
+      />
+    </div>
+  );
+};
+
+render(<MySelect />);
+```
+
+#### With fallback to NativeSelect on iOS and Android devices
+
+```tsx
+import { useEffect, useState } from 'react';
+import Sniffr from 'sniffr';
+import { Select, NativeSelect } from '@rescui/select';
+import COUNTRIES from '@/parts/select/countries';
+
+const options = COUNTRIES.map(country => ({ label: country, value: country }));
+
+const FallbackSelect = props => {
+  const [os, setOs] = useState(null);
+
+  useEffect(() => {
+    const sniffer = new Sniffr();
+    const os = sniffer.sniff(navigator.userAgent).os.name;
+    setOs(os);
+  }, []);
+
+  return os === 'ios' || os === 'android' ? (
+    <NativeSelect {...props} />
+  ) : (
+    <Select {...props} />
+  );
+};
+
+const MySelect = () => {
+  const [selected, setSelected] = useState(null);
+
+  return (
+    <div style={{ maxWidth: '380px' }}>
+      <FallbackSelect
+        options={options}
+        value={selected}
+        onChange={setSelected}
+        size="s"
+        placeholder="Select country..."
+        aria-label="Select country"
+      />
+    </div>
+  );
+};
+
+render(<MySelect />);
+```
+
+#### GroupOptions example with headers
+
+```tsx
+import { useEffect, useState } from 'react';
+import Sniffr from 'sniffr';
+import { Select, NativeSelect } from '@rescui/select';
+import COUNTRIES from '@/parts/select/countries';
+
+const COUNTRIES_WITH_OFFICES = [
+  'Czech Republic',
+  'Germany',
+  'Netherlands',
+  'United States'
+];
+
+const popularCountries = COUNTRIES_WITH_OFFICES.map(country => ({
+  label: country,
+  value: country
+}));
+
+const allCountries = COUNTRIES.map(country => ({
+  label: country,
+  value: country
+}));
+
+const options = [
+  { label: 'Popular countries', options: popularCountries },
+  { label: 'All countries', options: allCountries }
+];
+
+const FallbackSelect = props => {
+  const [os, setOs] = useState(null);
+
+  useEffect(() => {
+    const sniffer = new Sniffr();
+    const os = sniffer.sniff(navigator.userAgent).os.name;
+    setOs(os);
+  }, []);
+
+  return os === 'ios' || os === 'android' ? (
+    <NativeSelect {...props} />
+  ) : (
+    <Select {...props} />
+  );
+};
+
+const MySelect = () => {
+  const [selected, setSelected] = useState(null);
+
+  return (
+    <div style={{ maxWidth: '380px' }}>
+      <FallbackSelect
+        options={options}
+        value={selected}
+        onChange={value => setSelected(value)}
+        size="s"
+        placeholder="Select country..."
+        aria-label="Select country"
+      />
+    </div>
+  );
+};
+
+render(<MySelect />);
+```
+
+#### Why pass `SelectOption` as value instead of `option.value`?
+
+There are two main options of passing values:
+
+1. Passing only `value={option.value}`
+2. Passing the entire option as `value={option}`
+
+We've adopted a second option. Here are the main reasons:
+
+- _Async Options Loading:_ The first method is not suitable when options are loaded asynchronously and a default option is already known.
+
+- _Easy Wrapper Implementation:_ It’s easier to create a wrapper that turns the second option into the first option, than the other way around.
+
+##### Example Wrapper:
+
+Here's a concise example of a wrapper that modifies the API to a key-only approach, offering a cleaner interface.
+
+```tsx
+import { useState } from 'react';
+import { Select as RSelect } from '@rescui/select';
+
+const Select = ({ value, options, onChange, ...restProps }) => {
+  const selectedOption = options.find(o => o.value === value);
+
+  const handleChange = option => onChange(option.value);
+
+  return (
+    <RSelect
+      {...restProps}
+      value={selectedOption}
+      onChange={handleChange}
+      options={options}
+    />
+  );
+};
+
+// -------- End of Wrapper --------
+
+// -------- Code for Demo --------
+
+const options = [
+  { label: 'Munich', value: 'MUC' },
+  { label: 'Amsterdam', value: 'AMS' },
+  { label: 'Berlin', value: 'BER' },
+  { label: 'Paphos', value: 'PFO' },
+  { label: 'Belgrade', value: 'BEG' },
+  { label: 'Yerevan', value: 'EVN' }
+];
+
+const MySelect = () => {
+  const [selected, setSelected] = useState('AMS');
+
+  return (
+    <div style={{ maxWidth: '380px' }}>
+      <Select
+        options={options}
+        value={selected}
+        onChange={value => setSelected(value)}
+        size="s"
+        placeholder="Select city..."
+        aria-label="Select city"
+      />
+    </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 { Select } from '@rescui/select';
+
+const options = [
+  { label: 'Light', value: 'light' },
+  { label: 'Regular', value: 'regular' },
+  { label: 'Bold', value: 'bold' }
+];
+const MySelect = () => {
+  const [selected, setSelected] = useState(options[1]);
+
+  return (
+    <div style={{ maxWidth: '380px' }} className="light-green-primary">
+      <Select
+        options={options}
+        value={selected}
+        onChange={value => setSelected(value)}
+        className="select-with-contrast-primary"
+        size="m"
+        placeholder="Select font weight..."
+        aria-label="Select font weight"
+      />
+    </div>
+  );
+};
+
+render(<MySelect />);
+```
+
+```postcss attached
+.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);
+}
+```
+
+#### In the native dialog element
+
+Because the [popover API](https://developer.mozilla.org/en-US/docs/Web/API/Popover_API/Using) places the dialog element on the Top Layer, any value of `z-index` for the options list will be ignored.
+
+To work around this, we can use the `renderInTrigger` prop to render the popover in the dialog element instead of the bottom of the `body`.
+
+Also use `disableFlip` prop and `overflow: visible` css on the dialog if options will overflow it.
+
+```tsx
+import { useState } from 'react';
+import { Select } from '@rescui/select';
+
+const options = [
+  { label: 'Light', value: 'light' },
+  { label: 'Regular', value: 'regular' },
+  { label: 'Medium', value: 'medium' },
+  { label: 'Bold', value: 'bold' }
+];
+
+const MySelect = () => {
+  const [selected, setSelected] = useState(options[2]);
+
+  return (
+    <Select
+      options={options}
+      value={selected}
+      onChange={value => setSelected(value)}
+      size="m"
+      placeholder="Select font weight..."
+      aria-label="Select font weight"
+      placement="bottom"
+      renderInTrigger
+      disableFlip
+    />
+  );
+};
+
+render(
+  <>
+    <button command="show-modal" commandfor="my-dialog">
+      Open dialog
+    </button>
+
+    <dialog id="my-dialog" style={{ width: 500, overflow: 'visible' }}>
+      <div>
+        <button commandfor="my-dialog" command="close">
+          Close
+        </button>
+      </div>
+      <div style={{ marginTop: 12 }}>
+        <MySelect />
+      </div>
+    </dialog>
+  </>
+);
+```
+
+## Native
+
+### Features showcase
+
+#### Example:
+
+```tsx
+import { useState } from 'react';
+import { NativeSelect } from '@rescui/select';
+
+const options = [
+  { label: 'Light', value: 'light' },
+  { label: 'Regular', value: 'regular' },
+  { label: 'Bold', value: 'bold' }
+];
+
+const MySelect = () => {
+  const [selected, setSelected] = useState(options[1]);
+
+  return (
+    <div style={{ maxWidth: '380px' }}>
+      <NativeSelect
+        options={options}
+        value={selected}
+        onChange={value => setSelected(value)}
+        size="m"
+        placeholder="Select font weight..."
+        aria-label="Select font weight"
+      />
+    </div>
+  );
+};
+
+render(<MySelect />);
+```
+
+#### Custom trigger for NativeSelect
+
+```tsx
+import { useState } from 'react';
+import { NativeSelect } from '@rescui/select';
+
+const options = [
+  { label: 'Light', value: '300' },
+  { label: 'Regular', value: '400' },
+  { label: 'Bold', value: '600' }
+];
+const MySelect = () => {
+  const [selected, setSelected] = useState(options[0]);
+
+  return (
+    <div style={{ maxWidth: '380px' }}>
+      <NativeSelect
+        options={options}
+        value={selected}
+        onChange={value => setSelected(value)}
+        placeholder="Select font weight..."
+        aria-label="Select font weight"
+        trigger={({ selectedLabel, selectedValue, hovered, focused }) => {
+          return (
+            <div
+              style={{
+                fontWeight: selectedValue,
+                borderRadius: '30px',
+                padding: '15px',
+                border: `1px solid ${focused || hovered ? '#aaa' : '#ddd'}`
+              }}
+            >
+              Hey, I am {selectedLabel}
+            </div>
+          );
+        }}
+      />
+    </div>
+  );
+};
+
+render(<MySelect />);
+```
+
+## CSS Mixins API
+
+#### `Select` mixins
+
+| Mixin name | Details |
+| --- | --- |
+| `rs-select-size-s` | prop: `size`<br><br>value: `"s"` |
+| `rs-select-size-m` | prop: `size`<br><br>value: `"m"` |
+| `rs-select-size-l` | prop: `size`<br><br>value: `"l"` |
+
+##### Demo
+
+Use the controls to see the effect at different viewport widths.
+
+```tsx
+import { useState } from 'react';
+import { Select } 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 = ({ className }) => {
+  const [selected, setSelected] = useState(options[0]);
+
+  return (
+    <div style={{ maxWidth: 380, height: 380 }}>
+      <Select
+        options={options}
+        value={selected}
+        onChange={value => setSelected(value)}
+        size="m"
+        placeholder="Сhoose your favorite city..."
+        aria-label="Choose your favorite city"
+        className={className}
+      />
+    </div>
+  );
+};
+
+render(<MySelect className="my-select" />);
+```
+
+```postcss attached
+@import '@rescui/select/lib/public-api.p.css';
+
+.my-select {
+  @media (max-width: 640px) {
+    @mixin rs-select-size-l;
+  }
+  @media (max-width: 500px) {
+    @mixin rs-select-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/select/#contrast-primary-color) for contrast primary.
+
+#### `NativeSelect` mixins
+
+| Mixin name | Details |
+| --- | --- |
+| `rs-native-select-size-s` | prop: `size`<br><br>value: `"s"` |
+| `rs-native-select-size-m` | prop: `size`<br><br>value: `"m"` |
+| `rs-native-select-size-l` | prop: `size`<br><br>value: `"l"` |
+
+##### Demo
+
+Use the controls to see the effect at different viewport widths.
+
+```tsx
+import { useState } from 'react';
+import { NativeSelect } 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 MyNativeSelect = ({ className }) => {
+  const [selected, setSelected] = useState(options[0]);
+
+  return (
+    <div style={{ maxWidth: 380, height: 380 }}>
+      <NativeSelect
+        options={options}
+        value={selected}
+        onChange={value => setSelected(value)}
+        size="m"
+        placeholder="Сhoose your favorite city..."
+        aria-label="Choose your favorite city"
+        className={className}
+      />
+    </div>
+  );
+};
+
+render(<MyNativeSelect className="my-native-select" />);
+```
+
+```postcss
+@import '@rescui/select/lib/public-api.p.css';
+
+.my-native-select {
+  @media (max-width: 640px) {
+    @mixin rs-native-select-size-l;
+  }
+  @media (max-width: 500px) {
+    @mixin rs-native-select-size-s;
+  }
+}
+```

package/llm/index.md

@@ -0,0 +1,3 @@
+- Components and Hooks
+  - [Multiselect](./components/multiselect.md)
+  - [Select](./components/select.md)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rescui/select",
-  "version": "0.17.2",
+  "version": "0.18.0",
   "description": "",
   "license": "Apache-2.0",
   "author": "JetBrains",
@@ -9,6 +9,7 @@
   "src:main": "src/index.ts",
   "files": [
     "lib",
+    "llm",
     "LICENSE.txt"
   ],
   "publishConfig": {
@@ -16,10 +17,10 @@
   },
   "dependencies": {
     "@babel/runtime-corejs3": "^7.26.0",
-    "@rescui/dropdown": "^0.10.2",
-    "@rescui/form-field": "^0.1.4",
-    "@rescui/tag": "^0.13.10",
-    "@rescui/use-resize-observer": "^0.3.1",
+    "@rescui/dropdown": "^0.11.0",
+    "@rescui/form-field": "^0.1.5",
+    "@rescui/tag": "^0.13.11",
+    "@rescui/use-resize-observer": "^0.3.3",
     "classnames": "^2.2.6",
     "downshift": "^9.3.2",
     "scroll-into-view-if-needed": "3.1.0"
@@ -30,9 +31,9 @@
     "react": ">=16.8.0 <20"
   },
   "devDependencies": {
-    "@rescui/colors": "^0.3.1",
+    "@rescui/colors": "^0.3.2",
     "@rescui/scripts": "^0.5.2",
-    "@rescui/typography": "^0.27.1",
+    "@rescui/typography": "^0.27.2",
     "@rescui/visual-regression": "^0.1.4",
     "sniffr": "^1.2.0"
   },
@@ -41,5 +42,5 @@
     "build-pcss-api": "rescui-scripts build-pcss-api --file public-api.p.css"
   },
   "nx": {},
-  "gitHead": "a04f6790abce8e72834eedce3512ee83513c5e78"
+  "gitHead": "7aade8fced69c4a1ac61078a1daf2c1cd4f5a1c9"
 }