@gravity-ui/querieskit 1.3.0 → 1.3.2

package/.agents/skills/gravity-ui/references/layout.md

@@ -1,366 +0,0 @@
-# Layout — spacing scale, `Flex`/`Box`, grid (`Row`/`Col`/`Container`)
-
-> **Source of truth:** this is a verbatim copy of
-> [`@gravity-ui/uikit`'s `docs/layout.md`](https://github.com/gravity-ui/uikit/blob/main/docs/layout.md).
-> The current version in the installed `node_modules` may differ — for the exact
-> file matching your version, read
-> `node_modules/@gravity-ui/uikit/build/docs/guides/layout.md` (or fetch the
-> version-pinned copy at `gravity-ui.com/llms/uikit/<major>/llms.txt`).
->
-> This copy is bundled offline. If a token or prop you need is missing or looks
-> different here, prefer the version-matched source over this snapshot.
-
-This reference covers the **spacing scale, layout components, and responsive
-breakpoints**. For the **flex-contract traps** — who shrinks vs who holds, why
-`min-width:0` matters, scroll-vs-page — see
-[`../rules/hallucination-traps.md`](../rules/hallucination-traps.md).
-
----
-
-# Layout components and spacings
-
-This guide covers UIKit's layout foundations: a shared **spacing** scale (`--g-spacing-*`, used
-everywhere via tokens and props) and a responsive **grid** (`Container`/`Row`/`Col`), plus the
-flexbox-based `Flex`/`Box` primitives built on top of them. Compose pages from these instead of
-raw `div`s and inline styles.
-
-## Spacing
-
-Spacing in UIKit is a **scale**, not free-form pixels. You reference a step (`1`, `2`, … `10`)
-and the design system turns it into a concrete size. Sticking to the scale is what keeps rhythm
-consistent across the whole app, and lets you rescale everything from a single variable.
-
-### The scale
-
-Every step is a multiple of a base unit (`--g-spacing-base`, `4px` by default), so `step × 4px`:
-
-| Step  | CSS variable       | Size |
-| ----- | ------------------ | ---- |
-| `0`   | `--g-spacing-0`    | 0    |
-| `0.5` | `--g-spacing-half` | 2px  |
-| `1`   | `--g-spacing-1`    | 4px  |
-| `2`   | `--g-spacing-2`    | 8px  |
-| `3`   | `--g-spacing-3`    | 12px |
-| `4`   | `--g-spacing-4`    | 16px |
-| `5`   | `--g-spacing-5`    | 20px |
-| `6`   | `--g-spacing-6`    | 24px |
-| `7`   | `--g-spacing-7`    | 28px |
-| `8`   | `--g-spacing-8`    | 32px |
-| `9`   | `--g-spacing-9`    | 36px |
-| `10`  | `--g-spacing-10`   | 40px |
-
-Because every step is derived from `--g-spacing-base`, changing that one value rescales the
-entire spacing system proportionally (see [Customization](#customization)).
-
-### Ways to apply spacing
-
-There are three ways to consume the scale — pick by context:
-
-**1. Component props** — spacing **between** children of `Flex`/`Box`, via the `gap` prop:
-
-```tsx
-import {Flex} from '@gravity-ui/uikit';
-
-<Flex gap={5}>
-  <Button />
-  <Button />
-</Flex>; // 20px between children
-```
-
-**2. CSS custom properties** — the same steps as `--g-spacing-{step}` variables, for use in your
-own styles (e.g. `--g-spacing-half` for the `0.5` step):
-
-```css
-.example-class {
-  margin-right: var(--g-spacing-5); /* 20px */
-  padding: var(--g-spacing-2) var(--g-spacing-4);
-}
-```
-
-**3. The `spacing()` utility** — for one-off margins/paddings on any element without hand-writing
-class names. It returns a generated class name string:
-
-```tsx
-import {spacing} from '@gravity-ui/uikit';
-
-<>
-  <Button className={spacing({mr: 5})}>button 1</Button>
-  <Button className={spacing({mt: 2, px: 4})}>button 2</Button>
-</>;
-```
-
-`sp` is a shorter alias: `import {sp} from '@gravity-ui/uikit'` → `sp({mr: 5})`.
-
-Supported keys (each takes a scale step):
-
-| Key                 | Property                          |
-| ------------------- | --------------------------------- |
-| `m`                 | `margin`                          |
-| `mt` `mr` `mb` `ml` | `margin-top/right/bottom/left`    |
-| `mx`                | horizontal margin (left + right)  |
-| `my`                | vertical margin (top + bottom)    |
-| `p`                 | `padding`                         |
-| `pt` `pr` `pb` `pl` | `padding-top/right/bottom/left`   |
-| `px`                | horizontal padding (left + right) |
-| `py`                | vertical padding (top + bottom)   |
-
-You can pass a second argument to merge extra class names: `spacing({mr: 5}, myClassName)`.
-
-> **Rule of thumb:** `gap` for spacing between siblings in a `Flex`/`Box`; the `spacing()`/`sp()`
-> utility for one-off offsets on an element; raw `--g-spacing-*` variables inside your own CSS.
-> Always use scale steps, never hard-coded pixels.
-
-### Customization
-
-Override the base unit to rescale the whole system. Do it via CSS at the project level:
-
-```css
-:root {
-  --g-spacing-base: 5px; /* now step 5 = 25px, etc. */
-}
-```
-
-Or through the layout theme, which keeps the JS `Space` values and CSS variables in sync:
-
-```tsx
-import {ThemeProvider, LayoutTheme} from '@gravity-ui/uikit';
-
-const config: LayoutTheme = {
-    spaceBaseSize: 5,
-};
-
-export const App = () => {
-    return (
-        <ThemeProvider layout={{config, fixBreakpoints: true}}>
-            {...}
-        </ThemeProvider>
-    );
-};
-```
-
-## Screen sizes:
-
-We use **mobile-first** approach. It means that you should adapt your app for desktop after completing development of mobile version.
-The default breakpoints are:
-
-- `xs` - < 576px
-- `s` - ≥ 576px;
-- `m` - ≥ 768px;
-- `l` - ≥ 1080px;
-- `xl` - ≥ 1200px;
-- `xxl` - ≥ 1400px;
-- `xxxl` - ≥ 1920px;
-
-To override a breakpoint use the `breakpoints` property in the layout config:
-
-```tsx
-const APP_LAYOUT_THEME: LayoutTheme = {
-    spaceBaseSize: 4,
-    components: {
-        container: {
-            gutters: 3,
-            media: {
-                l: {
-                    gutters: 5,
-                },
-            },
-        },
-    },
-    breakpoints: {
-        s: 320,
-        l: 980,
-    },
-};
-
-<ThemeProvider layout={{config: APP_LAYOUT_THEME}}>
-    {...}
-</ThemeProvider>;
-```
-
-## Box
-
-The `Box` component is a developer friend and basic block to build other components. Aware about spacing, its own sizes and most commonly used CSS properties.
-
-Use it to declaratively describe elements with a fixed height/width. It also has built-in support for the most commonly used properties, such as `overflow`.
-It is mainly used as a base unit for other components such as `Flex` and `Card`.
-
-It is also well suited for use as a base for data loading containers, for example:
-
-```tsx
-import React, {Suspense} from 'react';
-import {Flex, Loader} from '@gravity-ui/uikit';
-
-// `Flex` extended from `Box` component and enriched flexbox model properties
-<Flex centerContent width="100%" height="100%">
-  <Suspense fallback={<Loader size="m" />}>
-    <LazyLoadedComponent />
-  </Suspense>
-</Flex>;
-```
-
-## Layout Grid
-
-Main components to describe 12-th column grid layout for your app.
-Supports nested grids. This should be used when you have mobile and desktop app versions.
-
-```tsx
-import {Row, Col} from '@gravity-ui/uikit';
-
-<Row space="5">
-  <Col size="4">...</Col>
-  <Col size="4">...</Col>
-  <Col size="4">...</Col>
-</Row>;
-```
-
-### Row
-
-**Props**
-
-- `space` - specify horizontal spacing between child `Col` components;
-- `spaceRow` - specify vertical spacing between child `Col` components. By default, it takes values from the `space` prop.
-
-### Col
-
-How many columns of your 12-th column layout will take content.
-Must be used as a child of `Row` component.
-
-**Props**
-
-- `size` - column width in column number (if omitted the column will occupy all free space in the row)
-
-```tsx
-import {Row, Col} from '@gravity-ui/uikit';
-
-<Row
-  /**
-   * In this example we override default theme behavior.
-   *
-   * space={{s: '1', xl:'5'}}
-   */
-  space="5"
->
-  <Col
-    // Will be:
-    // 12 for "xs" and "s"
-    // 6 for "m" and "l"
-    // 4 for "xl" and "xxl"
-    size={[12, {m: 6, xl: 4}]}
-  />
-</Row>;
-```
-
-> Grid system use negative margins under the hood. So you can specify background-color css property directly in `Col` components. Use wrapper components in such cases.
-
-## Container
-
-Center you content. Almost always it should be one per page. Manage max width corresponding to current screen size
-
-**Props**
-
-- `gutters` - left and right content padding. Needed when you content width equals screen width;
-- `maxWidth` - limits screen width for specific screen size;
-- `spaceRow` - ability to specify spacing between children `Row` components
-
-## Flex
-
-CSS `Flexbox` model representation in `jsx` world. Has built-in `spacing` to manage space between children. All flex properties are available in props.
-For most used properties it supports object syntax config to override behavior in different screen sizes.
-
-#### Examples
-
-_Space between children components in row direction_
-
-```jsx
-import {Flex, TextInput, Button} from '@gravity-ui/uikit';
-
-<Flex space="5">
-  <TextInput />
-  <Button />
-</Flex>;
-```
-
-_Nested `Flex` example_
-
-```jsx
-import {Flex, TextInput, Button, Table} from '@gravity-ui/uikit';
-
-<Flex direction="column" space="5">
-  <Flex space="5">
-    <TextInput />
-    <Button />
-  </Flex>
-  <Table />
-</Flex>;
-```
-
-_Responsible example_
-
-```jsx
-import {Flex, TextInput, Button} from '@gravity-ui/uikit';
-
-<Flex
-  // direction: column will be applied to l, xl, xxl, xxxl screen sizes here
-  direction={{l: 'column'}}
-  space={{s: '5', m: '3'}}
->
-  <TextInput />
-  <Button />
-</Flex>;
-```
-
-## Hooks
-
-### useLayoutContext
-
-Hook `useLayoutContext` provide ability to use `LayoutTheme` and helper functions to work with media queries.
-
-It returns the following methods and objects:
-
-- `theme` - `LayoutTheme` object;
-- `activeMediaQuery` - returns current [Screen sizes](#screen-sizes) keys.
-
-```tsx
-import {useLayoutContext} from '@gravity-ui/uikit';
-
-const Component = () => {
-  const {activeMediaQuery} = useLayoutContext();
-
-  return (
-    <>{activeMediaQuery === 'l' ? <Text>I render only on screen resolution "l"</Text> : null}</>
-  );
-};
-```
-
-- `isMediaActive` - returns `true` if passed value is equal to or greater than the current active media. It is necessary to implement logic of adaptive elements for **mobile-first** approach.
-
-```tsx
-import {useLayoutContext} from '@gravity-ui/uikit';
-
-// this example will be shown on xl, xxl and xxxl screen sizes
-const Component = () => {
-  const {isMediaActive} = useLayoutContext();
-
-  return (
-    <>{isMediaActive('xl') ? <Text>I render on "xl", "xxl" and "xxxl" screen sizes</Text> : null}</>
-  );
-};
-```
-
-- `getClosestMediaProps` - it works in a similar way as `isMediaActive`, but takes a map with screen media as an argument. Returns the nearest available value in the map taking into account the **mobile-first** approach.
-
-```tsx
-import {useLayoutContext} from '@gravity-ui/uikit';
-
-const mapOfPropsByScreen = {
-  s: "i'm will be shown on 's' and 'n' screen size",
-  l: "i'm will be shown on 'l' and 'xl' screen size",
-  xxl: "i'm will be shown on 'xxl' and 'xxxl' screen size",
-};
-
-const Component = () => {
-  const {getClosestMediaProps} = useLayoutContext();
-
-  return <Text>{getClosestMediaProps(mapOfPropsByScreen)}</Text>;
-};
-```