@gravity-ui/querieskit 1.3.0 → 1.3.1

package/.agents/skills/gravity-ui/SKILL.md

@@ -1,175 +0,0 @@
----
-name: gravity-ui
-description: Builds, fixes, styles, and composes UI with the Gravity UI design system — the React ecosystem of @gravity-ui/* packages (uikit, charts, table, navigation, date-components, icons, and more). Routes to the correct package when look-alikes exist, applies theming and required setup, and prevents invented component APIs. Applies when working with @gravity-ui imports, uikit, ThemeProvider, --g- CSS tokens, or any prompt (EN or RU) mentioning gravity-ui, гравити, дизайн-система, компоненты, дашборд, таблица, график, or форма.
----
-
-# Building UI with Gravity UI
-
-Build UI on **real** Gravity UI components, not from memory. Gravity UI is a
-multi-package React design system (`@gravity-ui/*`), so the two things that go
-wrong are picking the wrong package and using an API from the wrong version.
-This skill routes you to the right package, grounds you in the installed
-version, and stops you from inventing APIs — match the installed versions and
-follow the ecosystem catalog instead of guessing.
-
-## Step 0 — pick the right package first (ecosystem routing)
-
-Before doing anything else, work out which `@gravity-ui/*` library the task
-needs. Do not guess from training data — the ecosystem has look-alike packages
-(`charts` vs `chartkit`, uikit `Table` vs `@gravity-ui/table`, `date-components`
-vs `date-utils`, …) and picking the wrong one is the #1 failure.
-
-Open [`references/package-routing.md`](references/package-routing.md) and read
-its top: it is the ecosystem catalog, with the live-vs-offline source order,
-the "painful pairs" disambiguation, and a one-line "what it's for / what to use
-instead" per package. Use it to choose the package, then come back here for
-Step 1.
-
-Only after the package is chosen, run Step 1 to ground in that package's
-installed version and API.
-
-## Step 1 — ground in the installed version of the chosen package
-
-1. **Read `package.json`.** Note each installed `@gravity-ui/*` package and its
-   version. The installed version is the source of truth, not your memory.
-   Resolve ranges from `node_modules` (`<pkg>/package.json` `version` field), not
-   the range string in the root `package.json`.
-
-2. **Fetch the docs for the package you are about to use, in this order,
-   stopping at the first source that answers your question:**
-
-   (a) **LOCAL** — start with `node_modules/@gravity-ui/<pkg>/dist/docs/INDEX.md` or `node_modules/@gravity-ui/<pkg>/build/docs/INDEX.md`.
-      If `INDEX.md` is absent for this package, fall back to the package's root `node_modules/@gravity-ui/<pkg>/README.md`.
-      This is the *exact* installed version — always preferred for version-sensitive questions.
-   (b) **ONLINE** — per-package llms.txt at the **major line**:
-      `https://gravity-ui.com/llms/<pkg>/<major>/llms.txt`
-      (e.g. `/llms/uikit/7/llms.txt` for `^7.2.1`). The major-line URL serves the
-      latest minor of that major — it tracks the major but not the exact patch.
-      Use it when LOCAL has no docs for the package.
-
-3. **Fallback rule — never silently proceed on a failed or empty source:**
-
-   - If LOCAL has no README / `dist/docs` / `build/docs` for the package, or they are empty
-     → fetch the ONLINE major-line llms.txt (b).
-   - If the ONLINE request fails — network timeout, DNS, connection refused
-     (air-gapped / corporate proxy), HTTP 404 (major not hosted), or an empty /
-     non-markdown body → fall back to LOCAL README + dist/docs or build/docs (a).
-   - **Do NOT use the `/llms/<pkg>/llms.txt` "latest" alias** as a fallback — it
-     serves the newest major, which may differ from the installed one and have a
-     different API. The major-line URL is the versioned fallback; below it, go
-     LOCAL, not "latest".
-   - If BOTH are unreachable for a package → STOP and tell the user the
-     package's docs are unreachable. Do not guess its API from training data.
-
-## Step 2 — implement on the chosen packages, then typecheck
-
-1. **Implement using only the `@gravity-ui/*` packages chosen in Step 0 and
-   confirmed installed in Step 1.** Import from those packages exactly — do
-   not substitute look-alike libraries (MUI, Ant, plain `<input>`) and do not
-   reach for a `@gravity-ui/*` package that Step 1 did not confirm installed.
-   Follow the prop APIs from the docs you just read, not memory; if a prop
-   you want is not documented, it does not exist — use the documented one, or
-   ask the user.
-
-2. **Apply the cross-cutting rules** in `rules/hallucination-traps.md` while
-   writing: typography variants, the flex contract, theming/ladders,
-   `Button view`, `Icon data`. Per-component traps live in the package's own
-   `dist/docs`.
-
-3. **Typecheck before declaring done.** Run the project's typecheck command
-   (typically `tsc --noEmit`; for monorepos, the workspace's typecheck script).
-   Fix every error before reporting completion — a type error almost always
-   means a wrong/invented prop, a wrong import path, or a version mismatch,
-   which is precisely what Steps 0–1 were meant to prevent.
-
-   - If the typecheck surfaces a prop/path that contradicts the docs you read
-     in Step 1, trust the **installed version** (the typechecker), not the
-     docs snapshot — the docs may be from a different minor. Re-ground: read
-     the package's `dist/docs/INDEX.md` in `node_modules` for the exact
-     installed types.
-   - If the typecheck is unavailable (no TS in the project), say so
-     explicitly and ask the user how they want to verify; do not silently
-     skip verification.
-   - **Escape hatch.** If the user explicitly waived verification ("just
-     sketch it", "quick prototype", "no need to check"), you may skip the
-     typecheck — but state this plainly in your reply: *"typecheck skipped by
-     user request — code is not verified"*. Do not skip silently.
-
-## Hard rules
-
-- **`@gravity-ui/uikit` MUST be installed in every Gravity UI project.** It is
-  the base component + design-token library every other `@gravity-ui/*` package
-  builds on; without it components render unstyled. If `package.json` lacks it,
-  stop and have the user install and configure it first (setup:
-  `https://gravity-ui.com/llms/uikit/llms.txt`).
-- **Read `package.json` before importing any `@gravity-ui/*` package.** Never
-  assume a package is installed; never assume its major version.
-- **Do not invent props or components.** Before using a component API you are
-  not 100% sure of, check `rules/hallucination-traps.md` (ecosystem patterns)
-  and the component's README in `dist/docs`. If still unsure, ask the user
-  rather than guessing.
-- **Never guess icon names** — they are hallucinated more often than not. To
-  match an icon from a screenshot/photo/mock, run `scripts/icon-image-search.sh`
-  (reverse image search). With only a description, look the name up on
-  `gravity-ui.com/icons` or ask the user — do not invent one. Then pass it as an
-  object (`<Icon data={CheckIcon} />`), never a string key. See
-  `references/icons.md`.
-- **Theming uses semantic `--g-*` tokens.** Never hardcode colors (`#fff`,
-  `blue-500`); never hand-write `dark:` overrides. Full token tables live in
-  `references/theming.md`; the cross-cutting traps (partial brand overrides,
-  scoped vs nested `ThemeProvider`, controls on a brand background) live in
-  `rules/hallucination-traps.md`.
-- **Required setup is package-specific** (style imports, `ThemeProvider`,
-  peer-deps). It lives in each package's root README under "Required setup" —
-  read it once per package, do not rely on memory.
-
-## What NOT to do
-
-These are the five most common ways agents break Gravity UI code. They are
-already implied by the rules above; this section exists as an explicit
-stop-sign. If you are about to do any of these, stop and re-ground.
-
-- **Do not substitute non-Gravity libraries.** No MUI, Ant Design, plain
-  `<input>`/`<button>`, or look-alike component libs. Use the `@gravity-ui/*`
-  package the task needs.
-- **Do not invent component APIs or props.** If a prop is not in the docs you
-  read in Step 1, it does not exist — do not write `variant=`, `color=`,
-  `name=` (on `Icon`), or a `header-3` variant. Use the documented prop or
-  ask the user. See `rules/hallucination-traps.md`.
-- **Do not use the `/llms/<pkg>/llms.txt` "latest" alias as a fallback.** It
-  serves the newest major, which may differ from the installed one and have a
-  different API. The versioned online fallback is the major-line URL
-  (`/llms/<pkg>/<major>/llms.txt`); below that, go LOCAL.
-- **Do not partial-brand.** Setting only `--g-color-base-brand` leaves
-  selection, focus, links and contrast on the default accent — a mismatched
-  UI. Override the full brand token set, on each theme you support.
-- **Do not override internal markup with `[class*='…']` / ID selectors.**
-  That's written against one DOM structure and breaks silently when the
-  component changes. Climb the customization ladder
-  (global token → component CSS API → narrow flagged hack) before ever
-  touching structure.
-
-## Deeper material — read on demand
-
-These files live alongside this SKILL.md and load only when relevant:
-
-- `references/package-routing.md` — offline snapshot of the ecosystem catalog
-  (`gravity-ui.com/llms.txt`), refreshed each skill release. Used as the
-  offline fallback in Step 0.
-- `references/theming.md` — verbatim copy of uikit's `docs/theming.md`:
-  `--g-*` token layers, `ThemeProvider`, branding, custom themes, scoped
-  themes, `uikit-themer`. The bundled copy may lag — read
-  `node_modules/@gravity-ui/uikit/build/docs/guides/theming.md` for the
-  version-matched file.
-- `references/layout.md` — verbatim copy of uikit's `docs/layout.md`:
-  spacing scale (`--g-spacing-*`), `Flex`/`Box`, `Row`/`Col`/`Container`
-  grid, breakpoints, `useLayoutContext`.
-- `references/icons.md` — finding an icon by image
-  (`scripts/icon-image-search.sh`) or on gravity-ui.com/icons; the
-  object-vs-string rendering rule.
-- `rules/hallucination-traps.md` — Incorrect/Correct pairs for the most
-  commonly invented APIs: typography variants (`header-3..6` don't exist, no
-  `Heading`), the flex contract (`min-width:0`, who shrinks), theming traps
-  (partial brand overrides, scoped vs nested `ThemeProvider`, customization
-  ladder), `Button view` not `variant`, `Icon data` not `name`. Per-component
-  traps live in each package's `dist/docs`, not here.

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

@@ -1,60 +0,0 @@
-# Icons — finding the right `@gravity-ui/icons` name
-
-Icon names are hallucinated more often than not. **Never guess.** Find the real
-name, then render it correctly.
-
-## By image (screenshot / photo / mock) — preferred
-
-When the user has a picture of the icon — a screenshot, a design mock, a photo —
-use **reverse image search**:
-
-```
-scripts/icon-image-search.sh <path-to-image>
-```
-
-It POSTs the image to `https://gravity-ui.com/api/icons-search` and prints the
-closest `@gravity-ui/icons` names. The script infers the content type from the
-extension; force it if ambiguous: `--png` / `--jpeg`.
-
-**Image requirements:** send a small image of the icon *alone* — ideally
-**square** and tightly cropped to the glyph (no surrounding UI, large
-whitespace, or several icons in one shot). A full-page screenshot gives worse
-matches, so crop to the icon first if needed.
-
-Workflow:
-1. Have the user drop the image into the project, or point you at its path — a
-   small, square crop of just the icon.
-2. Run the script (it needs `curl`).
-3. The response is JSON: `{"results":[{"name","componentName","style","score"}, …]}`
-   sorted by descending `score` (0–1). Use **`componentName`** (PascalCase) for
-   the import: `import { Sphere } from '@gravity-ui/icons'`.
-4. If the top scores are close (within ~0.02) or the image is low-res, show the
-   user the top few candidates and ask which one — don't pick the first blindly.
-5. Render the chosen component (below).
-
-## When you only have a description (no image)
-
-This skill ships **no text-search endpoint**. To avoid inventing a name:
-
-- Look the icon up on the catalog at `https://gravity-ui.com/icons`.
-- If still unclear, ask the user for a screenshot and run image search.
-
-Do not guess a name from memory.
-
-## Rendering the chosen icon
-
-- The glyph set is `@gravity-ui/icons`; the renderer is uikit's `Icon`. Two
-  packages, two roles — don't confuse them.
-- Import the icon component and pass it via uikit's `Icon` `data` prop:
-
-  ```tsx
-  import { Icon } from '@gravity-ui/uikit';
-  import { ShieldCheck } from '@gravity-ui/icons';
-  import '@gravity-ui/uikit/styles/styles.css';
-
-  <Icon data={ShieldCheck} size={16} />
-  ```
-
-- Pass the icon as an **object** (`data={ShieldCheck}`), never as a string key.
-- For a custom or brand icon not in the set, import your own SVG and pass it to
-  `Icon` — do not expect it to live in `@gravity-ui/icons`.

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>;
-};
-```