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

package/llm/components/select.md

@@ -0,0 +1,549 @@
+# 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
+.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);
+}
+```
+
+## 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
+
+Resize the grey area below to see the effect.
+
+You can use `@media` queries instead of `@container` queries:
+
+```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: '380px' }}>
+      <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(
+  <div className="select-preview-container">
+    <p style={{ position: 'absolute', right: 12, bottom: 12 }}>Resize me</p>
+    <MySelect className="my-select" />
+  </div>
+);
+```
+
+```postcss attached
+@import '@rescui/select/lib/public-api.p.css';
+
+.select-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-select {
+  @container (max-width: 640px) {
+    @mixin rs-select-size-l;
+  }
+  @container (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
+
+Resize the grey area below to see the effect.
+
+You can use `@media` queries instead of `@container` queries:
+
+```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: '380px' }}>
+      <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(
+  <div className="native-select-preview-container">
+    <p style={{ position: 'absolute', right: 12, bottom: 12 }}>Resize me</p>
+    <MyNativeSelect className="my-native-select" />
+  </div>
+);
+```
+
+```postcss
+@import '@rescui/select/lib/public-api.p.css';
+
+.native-select-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-native-select {
+  @container (max-width: 640px) {
+    @mixin rs-native-select-size-l;
+  }
+  @container (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.1",
+  "version": "0.17.2-RUI-296-Build-docs-md-files-for-each-docs-section-b138dd5bf.15+b138dd5bf",
   "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.1",
-    "@rescui/form-field": "^0.1.3",
-    "@rescui/tag": "^0.13.9",
-    "@rescui/use-resize-observer": "^0.3.0",
+    "@rescui/dropdown": "0.10.2-RUI-296-Build-docs-md-files-for-each-docs-section-b138dd5bf.15+b138dd5bf",
+    "@rescui/form-field": "0.1.4-RUI-296-Build-docs-md-files-for-each-docs-section-b138dd5bf.19+b138dd5bf",
+    "@rescui/tag": "0.13.10-RUI-296-Build-docs-md-files-for-each-docs-section-b138dd5bf.15+b138dd5bf",
+    "@rescui/use-resize-observer": "0.3.1-RUI-296-Build-docs-md-files-for-each-docs-section-b138dd5bf.166+b138dd5bf",
     "classnames": "^2.2.6",
     "downshift": "^9.3.2",
     "scroll-into-view-if-needed": "3.1.0"
@@ -30,10 +31,10 @@
     "react": ">=16.8.0 <20"
   },
   "devDependencies": {
-    "@rescui/colors": "^0.3.0",
-    "@rescui/scripts": "^0.5.1",
-    "@rescui/typography": "^0.27.0",
-    "@rescui/visual-regression": "^0.1.4",
+    "@rescui/colors": "0.3.1-RUI-296-Build-docs-md-files-for-each-docs-section-b138dd5bf.54+b138dd5bf",
+    "@rescui/scripts": "0.5.2",
+    "@rescui/typography": "0.27.1-RUI-296-Build-docs-md-files-for-each-docs-section-b138dd5bf.19+b138dd5bf",
+    "@rescui/visual-regression": "0.1.4",
     "sniffr": "^1.2.0"
   },
   "scripts": {
@@ -41,5 +42,5 @@
     "build-pcss-api": "rescui-scripts build-pcss-api --file public-api.p.css"
   },
   "nx": {},
-  "gitHead": "44a67a99c883ea9157498860898acd2d0932321c"
+  "gitHead": "b138dd5bf3dbdca6c21fa339dd567517d5c5d1d9"
 }