@gravity-ui/querieskit 1.0.1

package/.agents/skills/gravity-ui/scripts/icon-image-search.sh

@@ -0,0 +1,63 @@
+#!/usr/bin/env bash
+#
+# icon-image-search.sh — reverse image search for Gravity UI icons.
+#
+# Send a screenshot/photo/mock of an icon, get back the closest
+# @gravity-ui/icons names from https://gravity-ui.com.
+#
+# Usage:
+#   icon-image-search.sh <path-to-image> [--png|--jpeg]
+#
+# Examples:
+#   icon-image-search.sh ./screenshot.png
+#   icon-image-search.sh ./icon.jpg --jpeg
+#
+# Requires: curl. Exits non-zero on missing file / curl failure.
+# Prints the raw response body (the matched icon names).
+
+set -euo pipefail
+
+ENDPOINT="https://gravity-ui.com/api/icons-search"
+
+if [ "$#" -lt 1 ]; then
+  echo "Usage: $0 <path-to-image> [--png|--jpeg]" >&2
+  exit 64
+fi
+
+IMAGE="$1"
+shift || true
+
+# Content type: explicit flag wins, else infer from extension, default png.
+CTYPE="image/png"
+EXPLICIT=0
+while [ "$#" -gt 0 ]; do
+  case "$1" in
+    --png)        CTYPE="image/png";  EXPLICIT=1 ;;
+    --jpeg|--jpg) CTYPE="image/jpeg"; EXPLICIT=1 ;;
+    *) echo "Unknown option: $1" >&2; exit 64 ;;
+  esac
+  shift
+done
+# Infer from extension only when no explicit flag was passed.
+if [ "$EXPLICIT" -eq 0 ]; then
+  case "${IMAGE##*.}" in
+    jpg|JPG|jpeg|JPEG) CTYPE="image/jpeg" ;;
+    png|PNG)           CTYPE="image/png" ;;
+  esac
+fi
+
+if [ ! -f "$IMAGE" ]; then
+  echo "File not found: $IMAGE" >&2
+  exit 66
+fi
+
+# Minimal headers: content-type is required (raw image body); origin/referer
+# in case the server gates on same-origin. Analytics cookies are omitted.
+exec curl -sS --fail-with-body "$ENDPOINT" \
+  -X POST \
+  -H 'accept: */*' \
+  -H "content-type: $CTYPE" \
+  -H 'origin: https://gravity-ui.com' \
+  -H 'referer: https://gravity-ui.com/icons' \
+  -H 'user-agent: gravity skill' \
+  --data-binary "@$IMAGE"

package/.eslintignore

@@ -0,0 +1,3 @@
+node_modules
+dist
+build

package/.github/workflows/ci.yml

@@ -0,0 +1,25 @@
+name: PR Checks
+
+on:
+    pull_request:
+        branches: [ main ]
+
+jobs:
+    lint-and-type-check:
+        runs-on: ubuntu-latest
+
+        steps:
+            - name: Checkout code
+              uses: actions/checkout@v4
+
+            - name: Set up Node.js
+              uses: actions/setup-node@v4
+              with:
+                  node-version: '20'
+                  cache: 'npm'
+
+            - name: Install dependencies
+              run: npm ci
+
+            - name: Check TypeScript types
+              run: npx tsc --noEmit

package/.github/workflows/main-preview.yml

@@ -0,0 +1,31 @@
+name: Main Preview
+
+on:
+  push:
+    branches: [main]
+
+jobs:
+  main:
+    name: Build and Deploy
+    runs-on: ubuntu-latest
+    steps:
+    - name: Checkout
+      uses: actions/checkout@v3
+    - name: Setup Node
+      uses: actions/setup-node@v3
+      with:
+        node-version: 20
+        cache: npm
+    - name: Install Packages
+      run: npm ci
+      shell: bash
+    - name: Build Storybook
+      run: npm run build-storybook
+      shell: bash
+    - name: Upload to S3
+      uses: gravity-ui/preview-upload-to-s3-action@v1
+      with:
+        src-path: storybook-static
+        dest-path: /timeline/main/
+        s3-key-id: ${{ secrets.STORYBOOK_S3_KEY_ID }}
+        s3-secret-key: ${{ secrets.STORYBOOK_S3_SECRET_KEY }}

package/.github/workflows/pr-preview-build.yml

@@ -0,0 +1,13 @@
+name: PR Preview Build
+
+on:
+  pull_request:
+
+jobs:
+  build:
+    name: Build
+    runs-on: ubuntu-latest
+    steps:
+      - uses: gravity-ui/preview-build-action@v2
+        with:
+          node-version: 20

package/.github/workflows/pr-preview-deploy.yml

@@ -0,0 +1,22 @@
+name: PR Preview Deploy
+
+on:
+  workflow_run:
+    workflows: [PR Preview Build]
+    types:
+      - completed
+
+jobs:
+  deploy:
+    name: Deploy
+    if: >
+      github.event.workflow_run.event == 'pull_request' &&
+      github.event.workflow_run.conclusion == 'success'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: gravity-ui/preview-deploy-action@v2
+        with:
+          project: timeline
+          github-token: ${{ secrets.GRAVITY_UI_BOT_GITHUB_TOKEN }}
+          s3-key-id: ${{ secrets.STORYBOOK_S3_KEY_ID }}
+          s3-secret-key: ${{ secrets.STORYBOOK_S3_SECRET_KEY }}

package/.github/workflows/pr-title.yml

@@ -0,0 +1,27 @@
+name: PR Title
+
+on:
+  pull_request:
+    types:
+      - opened
+      - synchronize
+      - reopened
+      - edited
+
+jobs:
+  verify_title:
+    name: Verify Title
+    runs-on: ubuntu-latest
+    if: ${{github.event.action != 'edited' || github.event.changes.title}}
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+      - name: Setup Node
+        uses: actions/setup-node@v4
+        with:
+          node-version: 20
+          cache: npm
+      - name: Install Packages
+        run: npm ci
+      - name: Run Commitlint
+        run: echo "${{github.event.pull_request.title}}" | npx commitlint

package/.github/workflows/release.yml

@@ -0,0 +1,20 @@
+name: Release
+
+on:
+  push:
+    branches:
+      - main
+      - release/v*
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    steps:
+      - name: Release from ${{ github.ref_name }}
+        uses: gravity-ui/release-action@v1
+        with:
+          github-token: ${{ secrets.GRAVITY_UI_BOT_GITHUB_TOKEN }}
+          npm-token: ${{ secrets.GRAVITY_UI_BOT_NPM_TOKEN }}
+          node-version: 20
+          default-branch: ${{ github.ref_name != 'main' && github.ref_name || null }}
+          npm-dist-tag: ${{ github.ref_name != 'main' && 'untagged' || 'latest' }}

package/.nvmrc

@@ -0,0 +1 @@
+20

package/.prettierrc.js

@@ -0,0 +1 @@
+module.exports = require("@gravity-ui/prettier-config");

package/.storybook/main.ts

@@ -0,0 +1,31 @@
+import type {StorybookConfig} from '@storybook/react-vite';
+import svgr from 'vite-plugin-svgr';
+
+const config: StorybookConfig = {
+    stories: ['../src/**/*.stories.@(js|jsx|mjs|ts|tsx)'],
+    addons: ['@storybook/addon-essentials'],
+    framework: {
+        name: '@storybook/react-vite',
+        options: {},
+    },
+    async viteFinal(viteConfig) {
+        const {mergeConfig} = await import('vite');
+
+        return mergeConfig(viteConfig, {
+            optimizeDeps: {
+                include: [
+                    // Pre-bundle React JSX entries so Vite does not serve the raw CJS files.
+                    'react/jsx-runtime',
+                    'react/jsx-dev-runtime',
+                ],
+            },
+            plugins: [
+                svgr({
+                    include: /@gravity-ui\/icons\/.*\.svg(?:\?.*)?$/,
+                }),
+            ],
+        });
+    },
+};
+
+export default config;

package/.storybook/preview.tsx

@@ -0,0 +1,43 @@
+import type {Decorator, Preview} from '@storybook/react';
+import {ThemeProvider, configure} from '@gravity-ui/uikit';
+import React from 'react';
+
+import '@gravity-ui/uikit/styles/styles.css';
+import '@gravity-ui/unipika/dist/unipika.css';
+import '@gravity-ui/illustrations/styles/styles.scss';
+import './redefinition.css';
+
+configure({lang: 'en'});
+
+const withYtComponentsTheme: Decorator = (Story, context) => {
+    const globalsTheme = context.globals.theme;
+    const isDark = globalsTheme === 'dark';
+    const uikitTheme = isDark ? 'dark' : 'light';
+
+    return (
+        <ThemeProvider theme={uikitTheme}>
+            <Story />
+        </ThemeProvider>
+    );
+};
+
+const preview: Preview = {
+    decorators: [withYtComponentsTheme],
+    globalTypes: {
+        theme: {
+            defaultValue: 'light',
+            toolbar: {
+                title: 'Theme',
+                icon: 'mirror',
+                items: [
+                    {value: 'light', right: '☼', title: 'Light'},
+                    {value: 'dark', right: '☾', title: 'Dark'},
+                ],
+                dynamicTitle: true,
+            },
+        },
+    },
+    parameters: {},
+};
+
+export default preview;

package/.storybook/redefinition.css

@@ -0,0 +1,3 @@
+* {
+    box-sizing: border-box;
+}

package/.storybook/tsconfig.json

@@ -0,0 +1,9 @@
+{
+    "extends": "../tsconfig.json",
+    "compilerOptions": {
+        "rootDir": "..",
+        "noEmit": true,
+        "declaration": false
+    },
+    "include": ["./**/*", "../src/**/*"]
+}

package/.stylelintrc

@@ -0,0 +1,9 @@
+{
+    "extends": ["@gravity-ui/eslint-config", "@gravity-ui/eslint-config/prettier"],
+    "rules": {
+        "property-case": null,
+        "at-rule-no-unknown": null,
+        "scss/at-rule-no-unknown": true,
+        "declaration-no-important": null
+    }
+}

package/AGENTS.md

@@ -0,0 +1,117 @@
+# AGENTS.md
+
+Instructions for agents on the code structure of `@gravity-ui/querieskit`.
+
+## Three levels of the public API
+
+The library is organized into three levels of abstraction. Every new and existing widget must follow this structure:
+
+```text
+src/
+  components/   — basic atomic components
+  modules/      — assemblies of several components into a reusable scenario block
+  widgets/      — ready-made product widgets
+  types/        — public types
+  helpers/      — shared helpers not tied to a specific widget
+  index.ts
+```
+
+### `src/components` — basic components
+
+Small components that do not manage a large scenario and do not contain complex state/orchestration.
+
+Inclusion rule: a component belongs in `src/components` only if a consumer of the library can use it separately and the component has a stable props contract. Do not move a component here just for the sake of consistency.
+
+Examples: [`QueryStatusIcon`](src/components/QueryStatusIcon/QueryStatusIcon.tsx:27), [`QueryDuration`](src/components/QueryDuration/QueryDuration.tsx).
+
+Component structure:
+
+```text
+components/
+  ComponentName/
+    ComponentName.tsx
+    ComponentName.scss
+    index.ts
+```
+
+### `src/modules` — modules
+
+Blocks that assemble several `components` and define an interaction scenario within a single widget (search, list, a row with its own selection/editing logic, etc.).
+
+A module is usually not intended to be used separately from its widget — it is an internal building block, but is factored out into a separate public level for import readability and potential reuse across widgets.
+
+Parts of a module that have no standalone usage scenario (e.g. an internal row header, an internal menu) are not moved to `components`, and stay inside the module — either next to the main file or in an `internal/` subfolder.
+
+Module structure:
+
+```text
+modules/
+  ModuleName/
+    ModuleName.tsx
+    internal/
+      InternalPart.tsx
+    helpers/
+      helperFn.ts
+    index.ts
+```
+
+### `src/widgets` — widgets
+
+Complete feature blocks that can be dropped into an application as a whole widget. A widget assembles `modules` and `components`, and contains its own i18n and widget-level settings.
+
+Widget structure:
+
+```text
+widgets/
+  WidgetName/
+    WidgetName.tsx
+    i18n/
+    index.ts
+```
+
+## Import rules between levels
+
+- `widgets` import `modules` and `components`.
+- `modules` import `components`.
+- `components` do not import `modules` or `widgets`.
+
+Violating this order (e.g. importing a widget inside a module) is not allowed — it breaks the readability of the abstraction levels.
+
+## Naming
+
+- `components` / `modules` / `widgets` are fixed level names. Do not use `blocks` (conflicts with the project's BEM terminology, see `bem-cn-lite`), and do not use `compositions` or `features` (less conventional / do not match the meaning of the entities).
+- Every unit at any level is a `PascalCase` folder with an implementation file of the same name and a mandatory `index.ts` that re-exports the folder's public API.
+
+## Barrel exports
+
+- Each level (`components`, `modules`, `widgets`) must have its own `index.ts` that explicitly re-exports the public units of that level. Do not use self-referencing or circular constructs like `export * from '.'`.
+- [`src/index.ts`](src/index.ts:1) is the entry point, re-exporting the public parts of all three levels and the public types from `src/types`.
+
+## Types
+
+Public types that are part of the props contract of components/modules/widgets must live in `src/types` and be re-exported via `src/index.ts` if the library consumer needs them to type their own data (e.g. `QueryHistoryRow`, `QueryHistoryItem`).
+
+## i18n
+
+Every widget/module/component with its own reusable scenario keeps its localization in an `i18n/` subfolder (`en.json`, `ru.json`, `dicts.ts`, `index.ts`), registers its keyset via [`addI18Keysets`](src/i18n/index.ts:11) with a name like `` `qp:widget-name` ``, and uses the typed `t`/`i18n(...)` function — see the example in [`QueriesHistory`](src/widgets/QueriesHistory/i18n/index.ts:1).
+
+Brief naming notes:
+
+- Keysets: do not spread one keyset across multiple keys, keep names as short as possible (`queries.filters`, not `queries.history.filters`), and do not start a reusable component's name with the word `component.`.
+- Keys: format `<context>_<text-content>` (kebab-case), e.g. `alert_query-execution-error`, `action_query-rerun`, `title_history`. Do not use the `label_` context. Recommended contexts: `context`, `alert`, `action`, `field`, `title`, `confirm`, `value`.
+- Technical prefixes: `raw_` — disables the typograf; `md_` — markup via YFM (bold/italic/link), HTML in texts is forbidden.
+- All strings must pass validation for allowed characters (Cyrillic, Latin, digits, standard punctuation, and currency symbols).
+
+For the full keyset and key naming rules with an example table, see [`plans/i18n-rules.md`](plans/i18n-rules.md).
+
+## Checklist when adding a new widget
+
+When adding a new widget to the library:
+
+1. Determine which parts are standalone `components`, which are `modules`, and what belongs only to the `widget` itself.
+2. Do not move internal details into `components` without a real standalone usage scenario.
+3. Create/update `index.ts` at every affected level.
+4. Make sure imports flow in a single direction only: `widgets → modules → components`.
+5. Verify the build and Storybook after the changes.
+
+For a detailed example of applying these rules to the existing `QueriesHistory` widget, see [`plans/queries-history-structure.md`](plans/queries-history-structure.md).

package/CHANGELOG.md

@@ -0,0 +1,31 @@
+# Changelog
+
+## [1.0.1](https://github.com/gravity-ui/querieskit/compare/v1.0.0...v1.0.1) (2026-08-12)
+
+
+### Bug Fixes
+
+* **CI:** lost typecheck [YTFRONT-5935] ([aca9f5c](https://github.com/gravity-ui/querieskit/commit/aca9f5cee9868d8d75d628d34b831cfa04e0d2a7))
+
+## 1.0.0 (2026-08-12)
+
+
+### Features
+
+* **History:** add queries history component [YTFRONT-5935] ([81f7bb8](https://github.com/gravity-ui/querieskit/commit/81f7bb82927220c4e899419a0ef88570bc40afd5))
+* **History:** filter [YTFRONT-5935] ([d708dbd](https://github.com/gravity-ui/querieskit/commit/d708dbd53df974b5fbd839c741e237ad15abb958))
+* **History:** search [YTFRONT-5935] ([8b88de5](https://github.com/gravity-ui/querieskit/commit/8b88de55528a2bcdc96431f083816883e9151509))
+* **History:** tutorials [YTFRONT-5935] ([fce38d1](https://github.com/gravity-ui/querieskit/commit/fce38d1ea28caeabcdaba119d7f797266cf7f293))
+* **UI:** history search [YTFRONT-5935] ([1796a74](https://github.com/gravity-ui/querieskit/commit/1796a74cecbbb576f51b7a39b35d811efc6bf781))
+* **UI:** license and readme [YTFRONT-5935] ([88c0335](https://github.com/gravity-ui/querieskit/commit/88c0335f5241819e8823338e66cceaeb2c6ac2f7))
+* **UI:** simple form [YTFRONT-5935] ([8278eb4](https://github.com/gravity-ui/querieskit/commit/8278eb41e4f6d2dbccab88e6fd8077527d0c579e))
+
+
+### Bug Fixes
+
+* **Eslint:** correct import resolve ([f02bc09](https://github.com/gravity-ui/querieskit/commit/f02bc09f19ab1b4e17a6f5b0ada4e456f9c875bd))
+* **History:** wrong hover color [YTFRONT-5935] ([98f3d4c](https://github.com/gravity-ui/querieskit/commit/98f3d4c1b987e4aa127627aaec55cb27cfa1e2fa))
+* **UI:** add monaco languages [YTFRONT-5935] ([6f662ca](https://github.com/gravity-ui/querieskit/commit/6f662caff793d27f089424dda3251823f70fc842))
+* **UI:** change agents language [YTFRONT-5935] ([f249e7d](https://github.com/gravity-ui/querieskit/commit/f249e7d4590b99f042cc7a58f4ec5752078ff45c))
+* **UI:** comparison mode [YTFRONT-5935] ([7854478](https://github.com/gravity-ui/querieskit/commit/7854478d2b99f2d5c7f9c2f7f5f2caa55db0155c))
+* **UI:** history empty list [YTFRONT-5935] ([7bddc2d](https://github.com/gravity-ui/querieskit/commit/7bddc2d14915bcf16128a9cb9fc0aa902723d1d7))

package/CODEOWNERS

@@ -0,0 +1 @@
+* @simbiozizv

package/CONTRIBUTING.md

@@ -0,0 +1,31 @@
+## Notice to external contributors
+### General info
+Hello! In order for us (YANDEX LLC) to accept patches and other contributions from you, you will have to adopt our Contributor License Agreement (the “CLA”). The current version of the CLA you may find here:
+
+* https://yandex.ru/legal/cla/en/ (in English) and
+* https://yandex.ru/legal/cla/ru/ (in Russian).
+
+By adopting the CLA, you state the following:
+
+* You obviously wish and are willingly licensing your contributions to us for our open source projects under the terms of the CLA,
+* You have read the terms and conditions of the CLA and agree with them in full,
+* You are legally able to provide and license your contributions as stated,
+* We may use your contributions for our open source projects and for any other our project too,
+* We rely on your assurances concerning the rights of third parties in relation to your contributions.
+
+If you agree with these principles, please read and adopt our CLA. By providing us your contributions, you hereby declare that you have read and adopted our CLA, and we may freely merge your contributions with our corresponding open source project and use it in further in accordance with terms and conditions of the CLA.
+
+### Provide contributions
+
+If you have adopted terms and conditions of the CLA, you are able to provide your contributions. When you submit your pull request, please add the following information into it:
+
+I hereby agree to the terms of the CLA available at: [link].
+
+Replace the bracketed text as follows:
+
+* [link] is the link at the current version of the CLA (you may add here a link https://yandex.ru/legal/cla/?lang=en (in English) or a link https://yandex.ru/legal/cla/?lang=ru (in Russian).
+
+It is enough to provide us with such notification once.
+
+### Other questions
+If you have any questions, please write us at opensource-support@yandex-team.ru.

package/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2026 YANDEX LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

package/NOTICES.md

@@ -0,0 +1,8 @@
+-------------------------------------------------------------------------------
+Export control notice
+-------------------------------------------------------------------------------
+
+It is necessary to comply with the applicable export control laws and
+regulations. We declare that we comply with the applicable export control laws
+and regulations for the published software, and we expect the users of the
+software and the contributors to it to be compliant with them as well.