@rescui/typography 0.27.1 → 0.27.3-RUI-297-Add-react-compiler-to-the-packages-build-dbbefd7b8.14

package/llm/typography/code.md

@@ -0,0 +1,97 @@
+# Code
+
+This style is used in RescUI to display inline code elements and blocks of code
+
+## Overview
+
+### Specification
+
+Code text style is displayed on the background color (`--rs-color-black-t10` or `--rs-color-white-t10`, depending on selected theme), with rounded edges to highlight code examples.
+
+|  | Weight | Font size | Line height | Letter spacing, % |
+| --- | --- | --- | --- | --- |
+| Code block | Regular | 16px | 24px | 0 |
+| Code inline | Regular | 90% | inherit | 0 |
+
+### Usage and Examples
+
+Code text style is used to highlight code examples in text or in special code blocks.
+
+Inline code is used to present small instances of code, like class or variable names, and you can also use it for keyboard shortcuts.
+
+Code blocks are used to represent code snippets or console commands. Even if you’re just presenting one line of code, we recommend using a code block.
+
+## API
+
+### textCn helper examples
+
+For raw `textCn` to work correctly in the dark theme, you have to specify `--rs-theme-dark: 1` CSS variable for the target element or above. If you don't use the `--rs-theme-dark` CSS variable, please refer to the [useTextStyles method](#usetextstyles-hook-examples).
+
+Use inline code as a child of one of the base texts `textCn("rs-text-<1|2|3>")`.
+
+```tsx
+import { textCn } from '@rescui/typography';
+
+render(
+  <div>
+    <p className={textCn('rs-text-2')}>
+      <code className={textCn('rs-code')}>inline CODE</code>
+    </p>
+    <pre className={textCn('rs-pre')}>
+      <code>CODE</code>
+    </pre>
+  </div>
+);
+```
+
+### useTextStyles hook examples
+
+If you use [`ThemeContext`](/utils/ui-contexts/#themecontext) to manage the theme of your application, you should use `useTextStyles` hook.
+
+Use inline code as a child of one of the base texts `textCn("rs-text-<1|2|3>")`.
+
+```tsx
+import { useTextStyles } from '@rescui/typography';
+
+const Example = () => {
+  const textCn = useTextStyles();
+
+  return (
+    <div>
+      <p className={textCn('rs-text-2')}>
+        <code className={textCn('rs-code')}>inline CODE</code>
+      </p>
+      <pre className={textCn('rs-pre')}>
+        <code>CODE</code>
+      </pre>
+    </div>
+  );
+};
+
+render(<Example />);
+```
+
+### Dark theme example
+
+Use `--rs-theme-dark` CSS variable to set dark theme for `textCn` helper.
+
+```tsx
+import { textCn } from '@rescui/typography';
+
+render(
+  <div
+    style={{
+      background: 'var(--rs-color-black)',
+      padding: 16,
+      '--rs-theme-dark': 1
+    }}
+  >
+    <p className={textCn('rs-text-2')}>
+      <code className={textCn('rs-code')}>inline CODE</code>
+    </p>
+    <pre className={textCn('rs-pre')}>
+      <code>CODE</code>
+    </pre>
+  </div>
+);
+```

package/llm/typography/color-cn.md

@@ -0,0 +1,68 @@
+# colorCn
+
+Typography JavaScript className helper `colorCn` allows to change the color of the text of the typography colors.
+
+## colorCn
+
+### Helper description
+
+`colorCn` className JS-helper accepts only one string argument: `"average" | "hard" | "pale" | "base"`
+
+Each of them, except `base`, set the corresponding typography color using the `color` CSS property. `base` sets the element color to the base typography color, that is declared higher ([see example](#base-color))
+
+### Example
+
+```tsx
+import { textCn, colorCn } from '@rescui/typography';
+
+const Demo = () => {
+  return (
+    <div style={{ maxWidth: 800 }}>
+      <p className={textCn('rs-text-2')}>
+        Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed aliquam in
+        sem at mollis. Aenean eget tincidunt arcu.{' '}
+        <span className={colorCn('hard')}>Donec luctus placerat magna.</span>{' '}
+        Morbi tristique mollis lacus eu congue.
+      </p>
+    </div>
+  );
+};
+
+render(<Demo />);
+```
+
+### Standalone example
+
+You can also use `colorCn` without typography classes at all, except the `base` value:
+
+```tsx
+import { colorCn } from '@rescui/typography';
+
+render(<span className={colorCn('pale')}>Donec luctus placerat magna.</span>);
+```
+
+### Base color
+
+You can get base typography color out of the nested structure using `base` value:
+
+```tsx
+import { textCn, colorCn } from '@rescui/typography';
+
+const Demo = () => {
+  return (
+    <div style={{ maxWidth: 800 }}>
+      <p className={textCn('rs-text-2')}>
+        Lorem ipsum dolor sit amet, consectetur adipiscing elit. Sed aliquam in
+        sem at mollis.{' '}
+        <span style={{ color: 'var(--rs-color-danger)' }}>
+          Aenean eget tincidunt arcu.{' '}
+          <span className={colorCn('base')}>Donec luctus placerat magna.</span>{' '}
+          Morbi tristique mollis lacus eu congue.
+        </span>
+      </p>
+    </div>
+  );
+};
+
+render(<Demo />);
+```

package/llm/typography/digits.md

@@ -0,0 +1,92 @@
+# Digits
+
+RescUI has 2 special Digits styles for key numeric data. The Digits styles are distinguished from the Subtitles style by their use of monospaced versions of numbers.
+
+## Overview
+
+### Specification
+
+|  | Weight | Font size, px | Line height, px | Letter spacing, % |
+| --- | --- | --- | --- | --- |
+| Digits 1 | Regular | 69 | 71 | \-0.5 |
+| Digits 2 | Light | 40 | 44 | \-0.5 |
+
+### Usage and Examples
+
+The Digits styles are used to call attention to a specific numerical data, for example for:
+
+- Dates for events
+- Numbers, such as of new or active users or company products
+- Percentages
+- Growth or decline of key indicators
+
+### Adaptivity
+
+The font-size and line-height values on the different screen breakpoints
+
+|  | Desktop | Tablet (≤ 1000px) | Mobile (≤ 640px) |
+| --- | --- | --- | --- |
+| Digits 1 | 69/71 | ← | 40/44 |
+| Digits 2 | 40/44 | ← | ← |
+
+### Recommendations
+
+Long values look bulky, but sometimes you can make them shorter by using common abbreviations, like M for millions or K for thousands. You can also use +- >< symbols to convey changes or to relate your figure to a round value that is easier to display.
+
+Do not make the description accompanying your number too long. 1 line is ideal. 2 lines is the maximum. If you are struggling to cut the description down to a size that fits, try distilling your message to only the essential information. If it is still too long, you may consider moving some of the details into a note.
+
+This style should not be applied to non-numeric elements, like words or graphics, and it should not be mixed with other data types. In general, when deciding whether to use this style, you should always ask yourself why this information should merit the readers’ special attention and interest.
+
+Wherever possible, round numbers to values that will be more familiar to readers. This will make them easier to process.
+
+## API
+
+### textCn helper examples
+
+For raw `textCn` to work correctly in the dark theme, you have to specify `--rs-theme-dark: 1` CSS variable for the target element or above. If you don't use the `--rs-theme-dark` CSS variable, please refer to the [useTextStyles method](#usetextstyles-hook-examples).
+
+```tsx
+import { textCn } from '@rescui/typography';
+
+render(<span className={textCn('rs-digits-1')}>$56873.23</span>);
+```
+
+### useTextStyles hook examples
+
+If you use [`ThemeContext`](/utils/ui-contexts/#themecontext) to manage the theme of your application, you should use `useTextStyles` hook.
+
+```tsx
+import { useTextStyles } from '@rescui/typography';
+
+const MyReactComponent = () => {
+  const textCn = useTextStyles();
+  return <span className={textCn('rs-digits-1')}>$56873.23</span>;
+};
+render(<MyReactComponent />);
+```
+
+### Dark theme example
+
+Use `--rs-theme-dark` CSS variable to set dark theme for `textCn` helper.
+
+```tsx
+import { textCn } from '@rescui/typography';
+
+render(
+  <div
+    style={{
+      background: 'var(--rs-color-black)',
+      padding: 16,
+      '--rs-theme-dark': 1
+    }}
+  >
+    <span className={textCn('rs-digits-2')}>€28721.93</span>
+  </div>
+);
+```
+
+### Parameters
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| `hardness` | "average" \| "hard" \| "pale" | `"hard"` |  |

package/llm/typography/headings.md

@@ -0,0 +1,105 @@
+# Headings
+
+Text headings give content a structure and make it easy for the reader to navigate, both for entire webpages and within individual components. They are larger than the regular text and create a clear contrast with it. There are 3 levels of Hero heading, 5 levels of general headers and 2 additional header levels, which are indicated simply by the letter H and the level number.
+
+## Overview
+
+### Specification
+
+|  | Weight | Font size, px | Line height, px | Letter spacing, % |
+| --- | --- | --- | --- | --- |
+| Superhero | Semibold | 142 | 142 | \-2 |
+| Middlehero | Semibold | 92 | 92 | \-0.8 |
+| Hero | Semibold | 72 | 72 | \-0.5 |
+| H1 | Semibold | 43 | 49 | \-0.1 |
+| H2 | Semibold | 35 | 42 | 0 |
+| H3-plus | Semibold | 28 | 34 | 0 |
+| H3 | Semibold | 20 | 28 | 0 |
+| H4 | Semibold | 16 | 24 | 0 |
+| H5 | Semibold | 13 | 20 | 0 |
+| Overline | Semibold | 13 | 18 | 10 |
+
+### Usage and Examples
+
+Hero headings (or Hero titles) are used for the main message on a page, such as the name of a product or service, or a call to action.
+
+H1–H5 headings are used to separate text content semantically, and they are also used in most components where there are at least 2 text styles.
+
+### Adaptivity
+
+The font-size and line-height values for the different screen breakpoints
+
+|  | Desktop | Tablet (≤ 1000px) | Mobile (≤ 640px) |
+| --- | --- | --- | --- |
+| Superhero | 142/142 | 92/92 | 58/62 |
+| Middlehero | 92/92 | ← | 58/62 |
+| Hero | 72/72 | ← | 42/50 |
+| H1 | 43/49 | ← | 35/39 |
+| H2 | 35/42 | ← | 28/32 |
+| H3-plus | 28/34 | ← | 20/28 |
+| H3 | 20/28 | ← | ← |
+| H4 | 16/24 | ← | ← |
+| H5 | 13/20 | ← | ← |
+| Overline | 13/18 | ← | ← |
+
+### Recommendations
+
+Keep your headlines short. Long headlines can be difficult for readers to process at a glance, making it hard for them to tell quickly whether the page’s content is right for them. Long headlines also make the page look “heavier”. Localization is also a concern, since titles may become longer in translation, so an already long title may become too unwieldy.
+
+For the most part, only the Hard style is used for headers. The exception is the disabled state for some components. Changing the preset parameters of the text styles is not recommended.
+
+The use of too many headers on a text page creates a lot of visual noise and can be an indication that the content does not have a clear structure. If your page has a lot of headers, try reorganizing it so there are no more than 4 levels of headers (including Hero headings). This may require significant revision, but it will be worth it when your content is streamlined and accessible.
+
+Avoid using formatting – such as italics, bold, or changes in font color – to highlight elements within a headline. Headlines work best when they present a unified message without distractions.
+
+Do not use right or center alignment for headlines. The center alignment of Hero titles is still present on some jetbrains.com pages, but the new version of the design system aligns headlines to the left edge.
+
+When multiple headlines follow each other, they should each be distinct enough that they don't conflict with each other in terms of emphasis. Strings of headlines can be disrupted by adding plain text, subtitles, and images.
+
+## API
+
+### textCn helper examples
+
+For raw `textCn` to work correctly in the dark theme, you have to specify `--rs-theme-dark: 1` CSS variable for the target element or above. If you don't use the `--rs-theme-dark` CSS variable, please refer to the [useTextStyles method](#usetextstyles-hook-examples).
+
+```tsx
+import { textCn } from '@rescui/typography';
+
+render(<span className={textCn('rs-hero')}>This is Hero heading</span>);
+```
+
+### useTextStyles hook examples
+
+If you use [`ThemeContext`](/utils/ui-contexts/#themecontext) to manage the theme of your application, you should use `useTextStyles` hook.
+
+```tsx
+import { useTextStyles } from '@rescui/typography';
+
+const MyReactComponent = () => {
+  const textCn = useTextStyles();
+  return <span className={textCn('rs-hero')}>This is Hero heading</span>;
+};
+render(<MyReactComponent />);
+```
+
+### Dark theme example
+
+Use `--rs-theme-dark` CSS variable to set dark theme for `textCn` helper.
+
+```tsx
+import { createTextCn } from '@rescui/typography';
+
+const textCn = createTextCn('dark');
+
+render(
+  <div
+    style={{
+      background: 'var(--rs-color-black)',
+      padding: 16,
+      '--rs-theme-dark': 1
+    }}
+  >
+    <span className={textCn('rs-hero')}>This is Hero heading</span>
+  </div>
+);
+```

package/llm/typography/links.md

@@ -0,0 +1,150 @@
+# Links
+
+RescUI supports link that allow user to navigate between content and web pages.
+
+## Overview
+
+### Usage and Examples
+
+Links are used to direct the reader to internal pages on the same site or to external sources.
+
+##### Text links
+
+There are 2 modes for links in text: Classic and Rock. You can add links to text blocks, descriptions, subtitles, titles, and tables.
+
+Classic text linkRock text link
+
+##### Standalone links
+
+You can use standalone links in cards after text blocks. They are typically used inside components, such as cards, but they can also be used in small lists (4–6 items).
+
+Standalone link
+
+##### Clear links
+
+Use clear links in navigation blocks, such as side menus, menus, and footers. You can also use them in cards for secondary actions (if it doesn't detract from UX).
+
+Clear link
+
+Links to external sources are always marked with an arrow symbol ↗ and must be opened in a new tab.
+
+### Recommendations
+
+The text in links should have the same font size as the surrounding text. Do not change the color or formatting of the text link, for example by using italics, caps, or bold.
+
+Try not to use links inside the text of the card description, as doing so increases the chances that users will accidentally click on it or miss it. At the bottom of the card, there is a special non-clickable area for the main and secondary actions.
+
+Most users are used to underlined text being a link, so don't apply this style to text as a decorative element.
+
+When your text contains multiple important links, try putting them in separate lists so they are easier to find.
+
+## API
+
+### Use cases
+
+- For content, tables, and headers, use `mode: "classic"` links.
+- For pages or sections with other `rock` components, use the `mode: "rock"` link.
+- If the link is the only text in the paragraph element, use the `mode: "standalone"` modifier. An example of that is a standalone `Learn more` link or a card footer.
+- For links in lists, for example, in navigation menus, use `mode: "clear"` or `mode: "standalone"` links.
+
+### textCn helper examples
+
+For raw `textCn` to work correctly in the dark theme, you have to specify `--rs-theme-dark: 1` CSS variable for the target element or above. If you don't use the `--rs-theme-dark` CSS variable, please refer to the [useTextStyles method](#usetextstyles-hook-examples).
+
+Typography link should be a child of one of the base texts `textCn("rs-text-<1|2|3>")`.
+
+```tsx
+import { textCn } from '@rescui/typography';
+
+render(
+  <p className={textCn('rs-text-2')}>
+    <a className={textCn('rs-link')} href="#">
+      This is link
+    </a>
+  </p>
+);
+```
+
+### useTextStyles hook examples
+
+If you use [`ThemeContext`](/utils/ui-contexts/#themecontext) to manage the theme of your application, you should use `useTextStyles` hook.
+
+Typography link should be a child of one of the base texts `textCn("rs-text-<1|2|3>")`.
+
+```tsx
+import { useTextStyles } from '@rescui/typography';
+
+const MyReactComponent = () => {
+  const textCn = useTextStyles();
+  return (
+    <p className={textCn('rs-text-2')}>
+      <a className={textCn('rs-link')} href="#">
+        This is link
+      </a>
+    </p>
+  );
+};
+
+render(<MyReactComponent />);
+```
+
+### Dark theme example
+
+```tsx
+import { textCn } from '@rescui/typography';
+
+render(
+  <div
+    style={{
+      background: 'var(--rs-color-black)',
+      padding: 16,
+      '--rs-theme-dark': 1
+    }}
+  >
+    <p className={textCn('rs-text-1')}>
+      <a className={textCn('rs-link', { hardness: 'hard' })} href="#">
+        This is always dark theme link
+      </a>
+    </p>
+  </div>
+);
+```
+
+### Standalone external link example
+
+```tsx
+import { textCn } from '@rescui/typography';
+
+render(
+  <p className={textCn('rs-text-2')}>
+    <a
+      className={textCn('rs-link', { external: true, mode: 'standalone' })}
+      href="#"
+    >
+      This is external standalone link
+    </a>
+  </p>
+);
+```
+
+### Clear link example
+
+```tsx
+import { textCn } from '@rescui/typography';
+
+render(
+  <p className={textCn('rs-text-3')}>
+    <a className={textCn('rs-link', { mode: 'clear' })} href="#">
+      Clear link
+    </a>
+  </p>
+);
+```
+
+### Parameters
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| `external` | boolean | `false` |  |
+| `hardness` | "average" \| "hard" \| "pale" | `"null"` |  |
+| `mode` | "classic" \| "rock" \| "clear" \| "standalone" | `"classic"` |  |

package/llm/typography/lists.md

@@ -0,0 +1,145 @@
+# Text Lists
+
+With RescUI, you have the ability to arrange text in numbered and bulleted lists.
+
+## Overview
+
+### Usage and Examples
+
+Lists are most commonly used to make content easy for readers to parse quickly. They can be used everywhere – both in solid text and in components, such as buy-cards.
+
+Use a bulleted list when the order of the nested items is not important to the content. Numbered lists are generally needed to describe a sequence of actions or to enumerate items.
+
+### Recommendations
+
+Avoid nesting items within lists, and take special care not to have more than more than 2 levels.
+
+The markers for list items must be consistent. Don’t use different types of markers for items at the same level in a list, or for different lists in the same context. Also, using custom markers is not recommended for this list type. It is better to use a special component for this instead.
+
+Don't put long lists inside box-components, as doing so may make them appear overly long. Limit yourself to the main benefits, the rest can be hidden in a tooltip or put separately out.
+
+Do not adjust the spacing between list items, or between one marker and the text.
+
+## API
+
+### Usage variants
+
+Typography lists should be mixed with one of base texts `textCn("rs-text-<1|2|3>")`.
+
+```jsx
+<>
+  <ul className={`${textCn('rs-ul')} ${textCn('rs-text-1')}`}>
+    <li>Item</li>
+  </ul>
+
+  <ol className={`${textCn('rs-ol')} ${textCn('rs-text-2')}`}>
+    <li>Item</li>
+  </ol>
+</>
+```
+
+or
+
+```jsx
+<div className={textCn('rs-text-2')}>
+  <ul className={textCn('rs-ul')}>
+    <li>Item</li>
+  </ul>
+</div>
+```
+
+### textCn helper examples
+
+```tsx
+import { textCn } from '@rescui/typography';
+
+render(
+  <ul className={`${textCn('rs-text-2')} ${textCn('rs-ul')}`}>
+    <li>Item 1</li>
+    <li>Item 2</li>
+  </ul>
+);
+```
+
+### Change default offset
+
+```tsx
+import { textCn } from '@rescui/typography';
+
+render(
+  <ul
+    className={`${textCn('rs-text-2')} ${textCn('rs-ul', {
+      offsetItems: 12
+    })}`}
+  >
+    <li>Item 1</li>
+    <li>Item 2</li>
+    <li>Item 3</li>
+  </ul>
+);
+```
+
+### Compact mode
+
+```tsx
+import { textCn } from '@rescui/typography';
+
+render(
+  <ul
+    className={`${textCn('rs-text-2')} ${textCn('rs-ul', { compact: true })}`}
+  >
+    <li>Item 1</li>
+    <li>Item 2</li>
+    <li>Item 3</li>
+  </ul>
+);
+```
+
+### Ordered list
+
+```tsx
+import { textCn } from '@rescui/typography';
+
+render(
+  <ol className={`${textCn('rs-text-2')} ${textCn('rs-ol')}`}>
+    <li>Item 1</li>
+    <li>Item 2</li>
+    <li>Item 3</li>
+  </ol>
+);
+```
+
+### Set upper-alpha for the counter
+
+```tsx
+import { textCn } from '@rescui/typography';
+
+render(
+  <ol
+    className={`${textCn('rs-text-2')} ${textCn('rs-ol', {
+      alpha: 'upper'
+    })}`}
+  >
+    <li>Item 1</li>
+    <li>Item 2</li>
+    <li>Item 3</li>
+  </ol>
+);
+```
+
+### Parameters
+
+#### Ordered list
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| `alpha` | "lower" \| "upper" | `null` |  |
+| `offsetItems` | 8 \| 12 \| 16 \| 24 \| 4 |  |  |
+| `compact` | boolean | `false` |  |
+
+#### Unordered list
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| `offsetItems` | 8 \| 12 \| 16 \| 24 \| 4 |  |  |
+| `compact` | boolean | `false` |  |