@rescui/chip-list 0.14.0 → 0.14.1-RUI-296-Build-docs-md-files-for-each-docs-section-b138dd5bf.19

package/llm/components/chip-list.md

@@ -0,0 +1,615 @@
+# ChipList
+
+Created with adaptivity in mind, ChipList is the component for radiogroup-like controls and navigational panels. It wraps items onto a new line if the screen is too narrow to fit all of the content.
+
+## Usage
+
+### Features showcase
+
+`ChipList` component can only be a controlled component. It requires `value` and `onChange` props to function properly.
+
+By default, `ChipList` uses `pattern="auto"`. It renders native `input[type="radio"]` elements with `role="radiogroup"` when chips do not have `href`, switches to `role="navigation"` when at least one chip has `href`, and switches to `role="tablist"` when chips use `aria-controls`.
+
+`ChipList` interactive overview:
+
+#### Content Switcher made of ChipList with default values
+
+`ChipList` enumerates `Chip` children components, so by default it has different keys for `onChange` prop function. When chips switch panels, add `aria-controls` to every chip so `pattern="auto"` resolves to `role="tablist"`.
+
+```tsx
+import { useState } from 'react';
+import { ChipList, Chip } from '@rescui/chip-list';
+import { Switcher } from '@rescui/switcher';
+
+const ContentSwitcher = ({ index, children }) => {
+  return children[index];
+};
+const Demo = () => {
+  const [activeIndex, setActiveIndex] = useState(1);
+  return (
+    <div>
+      <Switcher
+        size="xs"
+        value={activeIndex}
+        options={[
+          { label: 'First', value: 0 },
+          { label: 'Second', value: 1 },
+          { label: 'Third', value: 2 }
+        ]}
+        onChange={v => setActiveIndex(v)}
+        className="rs-docs-offset-top-12"
+      />
+      <ChipList
+        value={activeIndex}
+        onChange={v => setActiveIndex(v)}
+        className="rs-docs-offset-top-12"
+      >
+        <Chip id="first-default-tab" aria-controls="first-default-panel">
+          First
+        </Chip>
+        <Chip id="second-default-tab" aria-controls="second-default-panel">
+          Second
+        </Chip>
+        <Chip id="third-default-tab" aria-controls="third-default-panel">
+          Third
+        </Chip>
+      </ChipList>
+      <div className="rs-docs-offset-top-12">
+        <ContentSwitcher index={activeIndex}>
+          <div
+            id="first-default-panel"
+            role="tabpanel"
+            aria-labelledby="first-default-tab"
+          >
+            First
+          </div>
+          <div
+            id="second-default-panel"
+            role="tabpanel"
+            aria-labelledby="second-default-tab"
+          >
+            Second
+          </div>
+          <div
+            id="third-default-panel"
+            role="tabpanel"
+            aria-labelledby="third-default-tab"
+          >
+            Third
+          </div>
+        </ContentSwitcher>
+      </div>
+    </div>
+  );
+};
+
+render(<Demo />);
+```
+
+#### Switcher with custom values on Chips and component for tab content
+
+`ChipList` component works as radiogroup-like control with custom `value` on `Chip` components.
+
+```tsx
+import { useState } from 'react';
+import { ChipList, Chip } from '@rescui/chip-list';
+import { Switcher } from '@rescui/switcher';
+
+const Content = ({ activeChip }) => {
+  switch (activeChip) {
+    case 'first':
+      return <div>First</div>;
+    case 'second':
+      return <div>Second</div>;
+    case 'third':
+      return <div>Third</div>;
+  }
+};
+const Demo = () => {
+  const [activeChip, setActiveChip] = useState('second');
+  return (
+    <div>
+      <div>
+        <Switcher
+          size="xs"
+          value={activeChip}
+          options={[
+            { label: 'First', value: 'first' },
+            { label: 'Second', value: 'second' },
+            { label: 'Third', value: 'third' }
+          ]}
+          onChange={tab => setActiveChip(tab)}
+          className="rs-docs-offset-top-12"
+        />
+      </div>
+      <ChipList
+        value={activeChip}
+        onChange={v => setActiveChip(v)}
+        className="rs-docs-offset-top-12"
+      >
+        <Chip value="first">First</Chip>
+        <Chip value="second">Second</Chip>
+        <Chip value="third">Third</Chip>
+      </ChipList>
+      <div className="rs-docs-offset-top-12">
+        <Content activeChip={activeChip} />
+      </div>
+    </div>
+  );
+};
+
+render(<Demo />);
+```
+
+#### SEO tip: render the content from every tab and hide it with display: none
+
+Content could be rendered to DOM and hidden with CSS. This is a usefull trick for SEO optimization. This is also the most complete tablist pattern because every controlled panel stays in the DOM.
+
+```tsx
+import { useState, cloneElement } from 'react';
+import { ChipList, Chip } from '@rescui/chip-list';
+
+const CSSContentSwitcher = ({ index, children }) => {
+  return children.map((ch, i) => {
+    const chStyles = ch.props.style || {};
+    const addStyles = i === index ? {} : { display: 'none' };
+    return cloneElement(ch, { key: i, style: { ...chStyles, ...addStyles } });
+  });
+};
+
+const Demo = () => {
+  const [activeIndex, setActiveIndex] = useState(0);
+  return (
+    <div className="rs-docs-offset-top-24">
+      <ChipList value={activeIndex} onChange={v => setActiveIndex(v)}>
+        <Chip id="first-seo-tab" aria-controls="first-seo-panel">
+          First
+        </Chip>
+        <Chip id="second-seo-tab" aria-controls="second-seo-panel">
+          Second
+        </Chip>
+        <Chip id="third-seo-tab" aria-controls="third-seo-panel">
+          Third
+        </Chip>
+      </ChipList>
+      <CSSContentSwitcher index={activeIndex}>
+        <div
+          id="first-seo-panel"
+          role="tabpanel"
+          aria-labelledby="first-seo-tab"
+        >
+          First
+        </div>
+        <div
+          id="second-seo-panel"
+          role="tabpanel"
+          aria-labelledby="second-seo-tab"
+        >
+          Second
+        </div>
+        <div
+          id="third-seo-panel"
+          role="tabpanel"
+          aria-labelledby="third-seo-tab"
+        >
+          Third
+        </div>
+      </CSSContentSwitcher>
+    </div>
+  );
+};
+
+render(<Demo />);
+```
+
+#### Controls for the e2e tests
+
+When testing the page, you can get access to the arrows with `data-e2e` attributes. You should set the scope with the `data-e2e` attribute from the outside.
+
+```tsx
+import { useState, cloneElement } from 'react';
+import { ChipList, Chip } from '@rescui/chip-list';
+
+const CSSContentSwitcher = ({ index, children }) => {
+  return children.map((ch, i) => {
+    const chStyles = ch.props.style || {};
+    const addStyles = i === index ? {} : { display: 'none' };
+    return cloneElement(ch, { key: i, style: { ...chStyles, ...addStyles } });
+  });
+};
+
+const Demo = () => {
+  const [activeIndex, setActiveIndex] = useState(0);
+  return (
+    <div className="rs-docs-offset-top-24">
+      <ChipList
+        value={activeIndex}
+        onChange={v => setActiveIndex(v)}
+        data-e2e={'example-chips'}
+      >
+        <Chip id="first-e2e-tab" aria-controls="first-e2e-panel">
+          First
+        </Chip>
+        <Chip id="second-e2e-tab" aria-controls="second-e2e-panel">
+          Second
+        </Chip>
+        <Chip id="third-e2e-tab" aria-controls="third-e2e-panel">
+          Third
+        </Chip>
+      </ChipList>
+      <CSSContentSwitcher index={activeIndex}>
+        <div
+          id="first-e2e-panel"
+          role="tabpanel"
+          aria-labelledby="first-e2e-tab"
+        >
+          First
+        </div>
+        <div
+          id="second-e2e-panel"
+          role="tabpanel"
+          aria-labelledby="second-e2e-tab"
+        >
+          Second
+        </div>
+        <div
+          id="third-e2e-panel"
+          role="tabpanel"
+          aria-labelledby="third-e2e-tab"
+        >
+          Third
+        </div>
+      </CSSContentSwitcher>
+    </div>
+  );
+};
+
+render(<Demo />);
+```
+
+#### Usage with Icons
+
+```tsx
+import { useState } from 'react';
+import { ChipList, Chip } from '@rescui/chip-list';
+import {
+  TeamOutlineIcon,
+  WinOutlineIcon,
+  ThumbsUpOutlineIcon
+} from '@rescui/icons';
+
+const Demo = () => {
+  const [activeChip, setActiveChip] = useState('second');
+  return (
+    <div>
+      <ChipList
+        value={activeChip}
+        onChange={v => setActiveChip(v)}
+        className="rs-docs-offset-top-12"
+      >
+        <Chip icon={<TeamOutlineIcon />} value="first">
+          First
+        </Chip>
+        <Chip icon={<WinOutlineIcon />} value="second">
+          Second
+        </Chip>
+        <Chip icon={<ThumbsUpOutlineIcon />} value="third">
+          Third
+        </Chip>
+      </ChipList>
+    </div>
+  );
+};
+
+render(<Demo />);
+```
+
+#### Chips as links
+
+With the default `pattern="auto"`, chips with `href` switch the whole list to navigation behavior. You can also set `pattern="navigation"` explicitly. In `pattern="radiogroup"`, `href` is ignored and a development warning is printed.
+
+```tsx
+import { useState } from 'react';
+import { ChipList, Chip } from '@rescui/chip-list';
+
+const Demo = () => {
+  const [activeChip, setActiveChip] = useState('second');
+  return (
+    <div>
+      <div>
+        <h4 id="first">First</h4>
+        <h4 id="second">Second</h4>
+        <h4 id="third">Third</h4>
+      </div>
+      <ChipList
+        value={activeChip}
+        onChange={v => setActiveChip(v)}
+        className="rs-docs-offset-top-24"
+      >
+        <Chip href="#first" value="first">
+          First
+        </Chip>
+        <Chip href="#second" value="second">
+          Second
+        </Chip>
+        <Chip href="#third" value="third">
+          Third
+        </Chip>
+      </ChipList>
+    </div>
+  );
+};
+
+render(<Demo />);
+```
+
+#### Chips as navigation buttons
+
+Use `pattern="navigation"` when chips without `href` should control page navigation through JavaScript.
+
+```tsx
+import { useState } from 'react';
+import { ChipList, Chip } from '@rescui/chip-list';
+
+const Demo = () => {
+  const [activeChip, setActiveChip] = useState('second');
+  const navigateToSection = value => {
+    setActiveChip(value);
+    window.location.hash = `${value}-buttons`;
+  };
+
+  return (
+    <div>
+      <div>
+        <h4 id="first-buttons">First</h4>
+        <h4 id="second-buttons">Second</h4>
+        <h4 id="third-buttons">Third</h4>
+      </div>
+      <ChipList
+        value={activeChip}
+        onChange={navigateToSection}
+        pattern="navigation"
+        className="rs-docs-offset-top-24"
+      >
+        <Chip value="first">First</Chip>
+        <Chip value="second">Second</Chip>
+        <Chip value="third">Third</Chip>
+      </ChipList>
+    </div>
+  );
+};
+
+render(<Demo />);
+```
+
+#### Compact mode
+
+```tsx
+import { useState } from 'react';
+import { ChipList, Chip } from '@rescui/chip-list';
+
+const Demo = () => {
+  const [activeChip, setActiveChip] = useState('second');
+  return (
+    <div>
+      <ChipList
+        value={activeChip}
+        onChange={v => setActiveChip(v)}
+        compact
+        className="rs-docs-offset-top-12"
+      >
+        <Chip value="first">First</Chip>
+        <Chip value="second">Second</Chip>
+        <Chip value="third">Third</Chip>
+      </ChipList>
+    </div>
+  );
+};
+
+render(<Demo />);
+```
+
+## ChipListMulti
+
+### Features showcase
+
+`ChipListMulti` component can only be a controlled component. It requires `value` and `onChange` props to function properly.
+
+`ChipListMulti` interactive overview:
+
+#### Usage with Icons
+
+```tsx
+import { useState } from 'react';
+import { ChipListMulti, Chip } from '@rescui/chip-list';
+import {
+  TeamOutlineIcon,
+  WinOutlineIcon,
+  ThumbsUpOutlineIcon
+} from '@rescui/icons';
+
+const Demo = () => {
+  const [activeChips, setActiveChips] = useState(['second', 'third']);
+  return (
+    <div>
+      <ChipListMulti
+        value={activeChips}
+        onChange={setActiveChips}
+        className="rs-docs-offset-top-12"
+      >
+        <Chip icon={<TeamOutlineIcon />} value="first">
+          First
+        </Chip>
+        <Chip icon={<WinOutlineIcon />} value="second">
+          Second
+        </Chip>
+        <Chip icon={<ThumbsUpOutlineIcon />} value="third">
+          Third
+        </Chip>
+      </ChipListMulti>
+    </div>
+  );
+};
+
+render(<Demo />);
+```
+
+## CSS Mixins API
+
+#### `Chip` mixins
+
+| Mixin name | Details |
+| --- | --- |
+| `rs-chip-icon-left` | prop: `iconPosition`<br><br>value: `"left"` |
+| `rs-chip-icon-right` | prop: `iconPosition`<br><br>value: `"right"` |
+
+#### `ChipList` mixins
+
+| Mixin name | Details |
+| --- | --- |
+| `rs-chip-list-align-left` | prop: `alignItems`<br><br>value: `"left"` |
+| `rs-chip-list-align-center` | prop: `alignItems`<br><br>value: `"center"` |
+| `rs-chip-list-align-right` | prop: `alignItems`<br><br>value: `"right"` |
+| `rs-chip-list-sparse-true` | prop: `sparse`<br><br>value: `true` |
+| `rs-chip-list-sparse-false` | prop: `sparse`<br><br>value: `false` |
+| `rs-chip-list-size-xs` | prop: `size`<br><br>value: `"xs"` |
+| `rs-chip-list-size-s` | prop: `size`<br><br>value: `"s"` |
+| `rs-chip-list-size-m` | prop: `size`<br><br>value: `"m"` |
+| `rs-chip-list-size-l` | prop: `size`<br><br>value: `"l"` |
+| `rs-chip-list-mode-classic` | prop: `mode`<br><br>value: `"classic"` |
+| `rs-chip-list-mode-rock` | prop: `mode`<br><br>value: `"rock"` |
+
+#### `ChipListMulti` mixins
+
+| Mixin name | Details |
+| --- | --- |
+| `rs-chip-list-multi-align-left` | prop: `alignItems`<br><br>value: `"left"` |
+| `rs-chip-list-multi-align-center` | prop: `alignItems`<br><br>value: `"center"` |
+| `rs-chip-list-multi-align-right` | prop: `alignItems`<br><br>value: `"right"` |
+| `rs-chip-list-multi-sparse-true` | prop: `sparse`<br><br>value: `true` |
+| `rs-chip-list-multi-sparse-false` | prop: `sparse`<br><br>value: `false` |
+| `rs-chip-list-multi-size-xs` | prop: `size`<br><br>value: `"xs"` |
+| `rs-chip-list-multi-size-s` | prop: `size`<br><br>value: `"s"` |
+| `rs-chip-list-multi-size-m` | prop: `size`<br><br>value: `"m"` |
+| `rs-chip-list-multi-size-l` | prop: `size`<br><br>value: `"l"` |
+| `rs-chip-list-multi-mode-classic` | prop: `mode`<br><br>value: `"classic"` |
+| `rs-chip-list-multi-mode-rock` | prop: `mode`<br><br>value: `"rock"` |
+
+#### Demo
+
+Instead of separate classes, it may be a single class with `@media` queries inside:
+
+```tsx
+import { ChipList, ChipListMulti, Chip } from '@rescui/chip-list';
+import { useState } from 'react';
+import cn from 'classnames';
+import { TeamOutlineIcon, WinOutlineIcon, ThumbsUpOutlineIcon } from '@rescui/icons';
+
+const MyChipLists = ({ singleClassName, multiClassName }) => {
+  const [activeIndex, setActiveIndex] = useState(1);
+  const [activeChips, setActiveChips] = useState(['second', 'third']);
+  return (
+    <div style={{ padding: 12, backgroundColor: 'var(--rs-color-black-t5)' }}>
+      <ChipList
+        value={activeIndex}
+        onChange={v => setActiveIndex(v)}
+        className={singleClassName}
+      >
+        <Chip className="my-chip" icon={<TeamOutlineIcon />}>
+          First
+        </Chip>
+        <Chip className="my-chip" icon={<WinOutlineIcon />}>
+          Second
+        </Chip>
+        <Chip className="my-chip" icon={<ThumbsUpOutlineIcon />}>
+          Third
+        </Chip>
+      </ChipList>
+      <ChipListMulti
+        value={activeChips}
+        onChange={v => setActiveChips(v)}
+        className={cn(multiClassName, 'rs-docs-offset-top-12')}
+      >
+        <Chip className="my-chip" icon={<TeamOutlineIcon />} value="first">
+          First multi
+        </Chip>
+        <Chip className="my-chip" icon={<WinOutlineIcon />} value="second">
+          Second multi
+        </Chip>
+        <Chip className="my-chip" icon={<ThumbsUpOutlineIcon />} value="third">
+          Third multi
+        </Chip>
+      </ChipListMulti>
+    </div>
+  );
+};
+
+render(
+  <div style={{ display: 'flex', flexDirection: 'column', gap: 24 }}>
+    <div>
+      <p>Default:</p>
+      <MyChipLists />
+    </div>
+    <div>
+      <p>Var1:</p>
+      <MyChipLists
+        singleClassName={`my-chip-list-var-1`}
+        multiClassName={`my-chip-list-multi-var-1`}
+      />
+    </div>
+    <div>
+      <p>Var1 & Var2 combined:</p>
+      <MyChipLists
+        singleClassName={`my-chip-list-var-1 my-chip-list-var-2`}
+        multiClassName={`my-chip-list-multi-var-1 my-chip-list-multi-var-2`}
+      />
+    </div>
+  </div>
+);
+```
+
+```postcss
+@import '@rescui/chip-list/lib/public-api.p.css';
+
+.my-chip-list-var-1 {
+  @mixin rs-chip-list-size-l;
+  @mixin rs-chip-list-mode-rock;
+  @mixin rs-chip-list-align-center;
+  @mixin rs-chip-list-sparse-true;
+
+  .my-chip {
+    @mixin rs-chip-icon-right;
+  }
+}
+.my-chip-list-var-2 {
+  @mixin rs-chip-list-size-s;
+  @mixin rs-chip-list-mode-classic;
+  @mixin rs-chip-list-align-right;
+  @mixin rs-chip-list-sparse-false;
+
+  .my-chip {
+    @mixin rs-chip-icon-left;
+  }
+}
+
+.my-chip-list-multi-var-1 {
+  @mixin rs-chip-list-multi-size-l;
+  @mixin rs-chip-list-multi-mode-rock;
+  @mixin rs-chip-list-multi-align-center;
+  @mixin rs-chip-list-multi-sparse-true;
+
+  .my-chip {
+    @mixin rs-chip-icon-right;
+  }
+}
+.my-chip-list-multi-var-2 {
+  @mixin rs-chip-list-multi-size-s;
+  @mixin rs-chip-list-multi-mode-classic;
+  @mixin rs-chip-list-multi-align-right;
+  @mixin rs-chip-list-multi-sparse-false;
+
+  .my-chip {
+    @mixin rs-chip-icon-left;
+  }
+}
+```

package/llm/index.md

@@ -0,0 +1,2 @@
+- Components and Hooks
+  - [ChipList](./components/chip-list.md)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rescui/chip-list",
-  "version": "0.14.0",
+  "version": "0.14.1-RUI-296-Build-docs-md-files-for-each-docs-section-b138dd5bf.19+b138dd5bf",
   "description": "",
   "license": "Apache-2.0",
   "author": "JetBrains",
@@ -9,6 +9,7 @@
   "src:main": "src/index.ts",
   "files": [
     "lib",
+    "llm",
     "LICENSE.txt"
   ],
   "publishConfig": {
@@ -24,15 +25,15 @@
     "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"
   },
   "scripts": {
     "build": "rescui-scripts build && yarn run build-pcss-api",
     "build-pcss-api": "rescui-scripts build-pcss-api --file public-api.p.css"
   },
   "nx": {},
-  "gitHead": "e9aedd97a4cc372540ec8d75dda4f122baacca10"
+  "gitHead": "b138dd5bf3dbdca6c21fa339dd567517d5c5d1d9"
 }