@rescui/ui-contexts 0.6.1 → 0.6.3-RUI-297-Add-react-compiler-to-the-packages-build-dbbefd7b8.14

package/README.md

@@ -1,3 +1,5 @@
-UI contexts
+# UI contexts
 
-* [Usage examples of UI contexts](./docs/demo.md)
+## LLM
+
+To get the docs for the LLM, check out [this index](./llm/index.md).

package/llm/index.md

@@ -0,0 +1,4 @@
+- Utils
+  - [Theming](./utils/theming.md)
+  - [UI Contexts](./utils/ui-contexts.md)
+  - [Animations](./utils/animations.md)

package/llm/utils/animations.md

@@ -0,0 +1,114 @@
+# Animations
+
+## Animations
+
+### RescUI animations easing control
+
+RescUI components use the `--rs-transition-function` CSS variable to control the easing function of their CSS transitions and animations. The variable is inherited, so it can be set for the whole app, for a section, or directly on a single component.
+
+Each component keeps its own fallback value. For example, `Collapse` uses `ease` by default, while some special animations may keep their own timing function.
+
+### Component-level override
+
+Set the variable on a component when only this component should use a custom easing function.
+
+```tsx
+import { Collapse } from '@rescui/collapse';
+
+const DemoCollapse = ({ className, title }) => (
+  <Collapse title={title} className={className}>
+    <div style={{ padding: '8px 0 16px' }}>
+      The same Collapse component uses a different easing function when
+      `--rs-transition-function` is set on it.
+    </div>
+  </Collapse>
+);
+
+render(
+  <div style={{ display: 'flex', flexDirection: 'column', gap: 16 }}>
+    <DemoCollapse title="Default easing" />
+    <DemoCollapse
+      title={'Custom "bounce" easing: cubic-bezier(0.34, 2, 0.64, 1)'}
+      className="custom-bounce-animation-collapse"
+    />
+    <DemoCollapse
+      title={'Custom "stepped" easing: steps(4, end)'}
+      className="custom-stepped-animation-collapse"
+    />
+  </div>
+);
+```
+
+```postcss
+.custom-bounce-animation-collapse {
+  --rs-transition-function: cubic-bezier(0.34, 2, 0.64, 1);
+}
+.custom-stepped-animation-collapse {
+  --rs-transition-function: steps(4, end);
+}
+```
+
+### Inline override
+
+Use inline styles when the easing function is calculated in JavaScript or is part of local component state.
+
+```tsx
+import { Collapse } from '@rescui/collapse';
+
+const MyCollapse = () => (
+  <Collapse
+    title="Custom easing"
+    style={{ '--rs-transition-function': 'cubic-bezier(0.2, 0, 0, 1)' }}
+  >
+    Content
+  </Collapse>
+);
+
+render(<MyCollapse />);
+```
+
+### Section-level override
+
+Because CSS variables are inherited, setting `--rs-transition-function` on a wrapper changes the easing function for all RescUI components inside it.
+
+```tsx
+import { Collapse } from '@rescui/collapse';
+import { Toggle } from '@rescui/toggle';
+import { useState } from 'react';
+
+const AnimatedSection = ({ className }) => {
+  const [checked, setChecked] = useState(false);
+
+  return (
+    <div className={className}>
+      <Collapse title="Collapse inside a section">Section content</Collapse>
+      <div style={{ marginTop: 16 }}>
+        <Toggle
+          checked={checked}
+          onChange={event => setChecked(event.target.checked)}
+        >
+          Toggle inside the same section
+        </Toggle>
+      </div>
+    </div>
+  );
+};
+
+render(<AnimatedSection className="custom-animation-section" />);
+```
+
+```postcss
+.custom-animation-section {
+  --rs-transition-function: cubic-bezier(0.34, 2, 0.64, 1);
+}
+```
+
+### App-level default
+
+Set the variable on `:root` to change the default easing function for the whole application.
+
+```postcss
+:root {
+  --rs-transition-function: cubic-bezier(0.4, 0, 0.2, 1);
+}
+```

package/llm/utils/theming.md

@@ -0,0 +1,201 @@
+# Theming
+
+## Theming
+
+### RescUI Theming with CSS Variables
+
+RescUI components support theming using CSS variables. The primary CSS variable for controlling the theme is `--rs-theme-dark`.
+
+#### The `--rs-theme-dark` CSS Variable
+
+The `--rs-theme-dark` CSS variable is used to toggle between light and dark themes in RescUI components. It accepts two values:
+
+- `0`: Light theme (default)
+- `1`: Dark theme
+
+This variable affects the appearance of all RescUI components, including colors, backgrounds, borders, and other visual elements.
+
+#### How It Works
+
+When you set `--rs-theme-dark` to `1`, components will use their dark theme styles. When set to `0` or not set at all, components will use their light theme styles.
+
+Each component in the RescUI library checks for this variable and applies the appropriate styles based on its value. This allows for consistent theming across all components.
+
+#### Usage Examples
+
+##### Setting Theme at the Root Level
+
+To set the theme for your entire application, add the CSS variable to your root element:
+
+```postcss
+:root {
+  --rs-theme-dark: 0; /* Light theme */
+}
+```
+
+For dark theme:
+
+```postcss
+:root {
+  --rs-theme-dark: 1; /* Dark theme */
+}
+```
+
+##### Setting Theme for Specific Sections
+
+You can also set the theme for specific sections of your application:
+
+```jsx
+<div style={{ '--rs-theme-dark': 1 }}>
+  {/* All RescUI components in this div will use dark theme */}
+  <Button>Dark Theme Button</Button>
+  <Input placeholder="Dark Theme Input" />
+</div>
+```
+
+##### Toggling Themes Dynamically
+
+You can toggle between themes dynamically using JavaScript:
+
+```tsx
+import { useState } from 'react';
+import { Button } from '@rescui/button';
+import { textCn } from '@rescui/typography';
+
+const ThemeToggleExample = () => {
+  const [isDarkTheme, setIsDarkTheme] = useState(true);
+
+  return (
+    <div
+      style={{
+        '--rs-theme-dark': isDarkTheme ? 1 : 0,
+        background: isDarkTheme ? '#000' : '#f4f4f4',
+        padding: 24
+      }}
+    >
+      <Button mode="rock" onClick={() => setIsDarkTheme(!isDarkTheme)}>
+        Toggle Theme
+      </Button>
+      <p className={textCn('rs-text-2')} style={{ marginTop: 12 }}>
+        Current theme: {isDarkTheme ? 'Dark' : 'Light'}
+      </p>
+    </div>
+  );
+};
+
+render(<ThemeToggleExample />);
+```
+
+#### The `--rs-theme-flip` CSS Variable
+
+In addition to the `--rs-theme-dark` CSS Variable, RescUI components support the `--rs-theme-flip` CSS Variable. It also accepts two values:
+
+- `0`: Normal theme (default)
+- `1`: Inverted theme
+
+It becomes useful when toggling the theme based on different CSS states of a component — for example, [rock cards](/cards/clickable/#rock-mode).
+
+```postcss attached
+.flip-theme-on-hover {
+  --rs-theme-dark: 0; /* light theme by default */
+  background: #fff;
+  border: 1px solid black;
+
+  &:hover {
+    --rs-theme-flip: 1; /* components inside will be with inverted theme on hover */
+    background: #000;
+    border-color: white;
+  }
+}
+```
+
+### ThemeProvider
+
+While the CSS variable approach is recommended, RescUI also provides a React context-based theming solution through the `ThemeProvider` component:
+
+`ThemeProvider` has issues with [server components](https://react.dev/reference/rsc/server-components) and server-side rendering when trying to [apply theme based on user preferences](https://developer.mozilla.org/en-US/docs/Web/CSS/@media/prefers-color-scheme). We recommend using CSS variables approach for theming instead.
+
+```tsx
+import { ThemeProvider, useThemeWithUndefined } from '@rescui/ui-contexts';
+import { Button } from '@rescui/button';
+import { useTextStyles } from '@rescui/typography';
+
+const ThemedSection = () => {
+  const theme = useThemeWithUndefined();
+  const textCn = useTextStyles();
+  const isDarkTheme = theme === 'dark';
+  return (
+    <div
+      style={{
+        background: isDarkTheme ? '#000' : '#f4f4f4',
+        padding: 24
+      }}
+    >
+      <Button>Dark Theme Button</Button>
+      <p className={textCn('rs-text-2')} style={{ marginTop: 12 }}>
+        Current theme: {isDarkTheme ? 'Dark' : 'Light'}
+      </p>
+    </div>
+  );
+};
+
+const App = () => (
+  <ThemeProvider theme="dark">
+    <ThemedSection />
+  </ThemeProvider>
+);
+
+render(<App />);
+```
+
+See more in the [UI-contexts](/utils/ui-contexts/) section.
+
+### Best Practices
+
+- **Prefer CSS Variables**: Use the `--rs-theme-dark` CSS variable directly when possible, as it provides better performance and flexibility.
+
+- **Consistent Theming**: Apply the theme at the highest appropriate level in your component hierarchy to ensure consistent styling.
+
+- **Component-Specific Overrides**: You can override the theme for specific components by setting the `--rs-theme-dark` variable on their container elements.
+
+- **Media Queries**: You can use media queries to automatically switch between light and dark themes based on user preferences:
+
+```postcss
+:root {
+  --rs-theme-dark: 0;
+}
+
+@media (prefers-color-scheme: dark) {
+  :root {
+    --rs-theme-dark: 1;
+  }
+}
+```
+
+- **Group Theme-Related Styles**: The `--rs-theme-dark` variable controls the theme only for RescUI components. To apply both RescUI and local styles from a single source, group theme-related styles together. For example, using [Postcss Mixins](https://github.com/postcss/postcss-mixins):
+
+```postcss
+@define-mixin site-theme-light {
+  --rs-theme-dark: 0;
+  --main-background-color: #fff;
+  --secondary-border-color: #d1d1d2;
+}
+
+@define-mixin site-theme-dark {
+  --rs-theme-dark: 1;
+  --main-background-color: #000;
+  --secondary-border-color: #474749;
+}
+
+.light-section {
+  @mixin site-theme-light;
+}
+.dark-section {
+  @mixin site-theme-dark;
+}
+
+.inner-element {
+  background: var(--main-background-color);
+  border: 1px solid var(--secondary-border-color);
+}
+```

package/llm/utils/ui-contexts.md

@@ -0,0 +1,171 @@
+# UI Contexts
+
+UI Contexts allow you to set parameters for entire component trees and subtrees, making it easy to add stylistic variety to your pages without having to manually adjust all the components.
+
+## UI Contexts
+
+### ThemeContext
+
+`ThemeProvider` has issues with [server components](https://react.dev/reference/rsc/server-components) and server-side rendering when trying to [apply theme based on user preferences](https://developer.mozilla.org/en-US/docs/Web/CSS/@media/prefers-color-scheme). We recommend using [CSS variables](/utils/theming/) approach for theming instead.
+
+Provides the default theme to descendant components. Can be overridden by component's props.
+
+Also used for some hooks like `useGlowHover`, `useTextStyles` and so on.
+
+#### Usage
+
+```tsx
+import { useState } from 'react';
+import { ThemeProvider, useThemeWithUndefined } from '@rescui/ui-contexts';
+import { useTextStyles } from '@rescui/typography';
+import { Switcher } from '@rescui/switcher';
+
+const MyCustomSectionComponent = ({ children }) => {
+  const theme = useThemeWithUndefined();
+
+  return (
+    <div
+      style={{
+        background: theme === 'dark' ? '#000' : '#F4F4F4',
+        padding: '20px'
+      }}
+    >
+      {children}
+    </div>
+  );
+};
+
+const MyCustomComponentThatUsingTheme = () => {
+  const textCn = useTextStyles();
+
+  return (
+    <div className={textCn('rs-text-2', { hardness: 'hard' })}>
+      I'm text with class from textCn
+    </div>
+  );
+};
+
+const Demo = () => {
+  const [theme, setTheme] = useState('light');
+
+  return (
+    <ThemeProvider theme={theme}>
+      <MyCustomSectionComponent>
+        <Switcher
+          size="xs"
+          options={[
+            { label: 'Light', value: 'light' },
+            { label: 'Dark', value: 'dark' }
+          ]}
+          value={theme}
+          onChange={setTheme}
+        />
+        <div style={{ marginTop: '24px' }}>
+          <MyCustomComponentThatUsingTheme />
+        </div>
+      </MyCustomSectionComponent>
+    </ThemeProvider>
+  );
+};
+
+render(<Demo />);
+```
+
+#### Props
+
+| Name | Type | Default | Description |
+| --- | --- | --- | --- |
+| `theme` | "light" \| "dark" |  |  |
+| `ignoreThemeValueForCSSApi` | boolean | `false` |  |
+
+#### Always dark or light themed components
+
+##### The problem
+
+Sometimes you need to have specific component (custom card, section, block...) to always be in a specific theme - for example, always dark section.
+
+And if using `ThemeProvider` would help children components, it won't work for top-level hooks:
+
+```tsx
+import { ThemeProvider } from '@rescui/ui-contexts';
+import { Button } from '@rescui/button';
+import { useTextStyles } from '@rescui/typography';
+
+/* export */ const DarkSection = () => {
+  // by default light typography
+  const textCn = useTextStyles();
+
+  return (
+    <ThemeProvider theme="dark">
+      <div style={{ background: '#000', padding: '20px' }}>
+        <p className={textCn('rs-text-2', { hardness: 'hard' })}>
+          You won't see it, because it's a light typography text
+        </p>
+        <Button>I'm in the dark theme</Button>
+      </div>
+    </ThemeProvider>
+  );
+};
+
+render(<DarkSection />);
+```
+
+##### Manual solution
+
+One of the solutions for that problem is to use the `createTextCn` helper with manually specified theme instead of the hook:
+
+```tsx
+import { ThemeProvider } from '@rescui/ui-contexts';
+import { Button } from '@rescui/button';
+import { createTextCn } from '@rescui/typography';
+
+/* export */ const DarkSection = () => {
+  // now its dark typography
+  const textCn = createTextCn('dark');
+
+  return (
+    <ThemeProvider theme="dark">
+      <div style={{ background: '#000', padding: '20px' }}>
+        <p className={textCn('rs-text-2', { hardness: 'hard' })}>
+          I'm the dark typography text
+        </p>
+        <Button>I'm in the dark theme</Button>
+      </div>
+    </ThemeProvider>
+  );
+};
+
+render(<DarkSection />);
+```
+
+##### Automatic solution
+
+Another, more preferable solution, is to wrap your base component inside the `ThemeProvider` so all the hooks inside will use it:
+
+```tsx
+import { ThemeProvider } from '@rescui/ui-contexts';
+import { useTextStyles } from '@rescui/typography';
+
+const DarkSectionInner = () => {
+  // dark typography
+  const textCn = useTextStyles();
+
+  return (
+    <div
+      className={textCn('rs-text-2', { hardness: 'hard' })}
+      style={{ background: '#000', padding: '20px' }}
+    >
+      The whole component and its children are in the dark theme
+    </div>
+  );
+};
+
+// use this component for export instead of the "Inner" one
+/* export */ const DarkSection = () => (
+  <ThemeProvider theme="dark">
+    <DarkSectionInner />
+  </ThemeProvider>
+);
+
+render(<DarkSection />);
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rescui/ui-contexts",
-  "version": "0.6.1",
+  "version": "0.6.3-RUI-297-Add-react-compiler-to-the-packages-build-dbbefd7b8.14+dbbefd7b8",
   "description": "",
   "license": "Apache-2.0",
   "author": "JetBrains",
@@ -9,6 +9,7 @@
   "src:main": "src/index.ts",
   "files": [
     "lib",
+    "llm",
     "typings",
     "LICENSE.txt"
   ],
@@ -20,14 +21,14 @@
   },
   "peerDependencies": {
     "prop-types": "^15",
-    "react": ">=16.8.0 <20"
+    "react": ">=17.0.0 <20"
   },
   "devDependencies": {
-    "@rescui/scripts": "^0.5.2"
+    "@rescui/scripts": "0.5.2"
   },
   "scripts": {
     "build": "rescui-scripts build"
   },
   "nx": {},
-  "gitHead": "a04f6790abce8e72834eedce3512ee83513c5e78"
+  "gitHead": "dbbefd7b8e24da18262edf3baffa35039ae01af3"
 }