@weavix/tracker-components 0.1.0 → 0.1.1

package/README.md

@@ -1,45 +1,217 @@
 # @weavix/tracker-components
 
+Shared UI component library for **Yandex Tracker plugins**. Provides ready-made React components for selecting queues, fields, and meta entities (projects, portfolios, goals), displaying issue-type and entity icons, and building collapsible sections — all styled to match the Tracker design system.
+
+---
+
 ## Installation
 
 ```bash
 pnpm add @weavix/tracker-components
 ```
 
-Peer-зависимости:
+### Peer dependencies
+
+| Package | Version |
+|---|---|
+| `react`, `react-dom` | `^18` |
+| `@gravity-ui/uikit` | `^7` |
+| `@gravity-ui/icons` | `^2` |
+
+---
+
+## Component catalogue
+
+### Select components
+
+| Component | Description | README |
+|---|---|---|
+| [`QueueSelect`](#queueselect) | Dropdown for choosing a Tracker queue. Supports static lists, async suggest, icons, loading states, and confirmation dialogs. | [→ README](src/components/QueueSelect/README.md) |
+| [`MetaEntitiesSelect`](#metaentitiesselect) | Suggest-based select for projects, portfolios, goals, or reports. Async item fetching, loading states, error display, clear button. | [→ README](src/components/MetaEntitiesSelect/README.md) |
+| [`PluginFieldsSelect`](#pluginfieldsselect) | Dropdown for choosing Tracker fields inside a plugin. Auto-groups fields by category, supports search, multi-select, submit/reset, loading states. | [→ README](src/components/PluginFieldsSelect/README.md) |
+
+### Icon components
+
+| Component | Description | README |
+|---|---|---|
+| [`IssueTypeIcon`](#issuetypeicon) | Icon for a Tracker issue type (task, bug, epic, …). | [→ README](src/components/Icon/IssueTypeIcon/README.md) |
+| [`MetaEntityIcon`](#metaentityicon) | Dispatcher icon that renders the correct icon for any meta entity type (project, portfolio, goal, key result). | [→ README](src/components/Icon/MetaEntityIcon/README.md) |
+| [`ProjectIcon`](#projecticon) | Colored icon for a project entity. Color is deterministically derived from the project ID. | [→ README](src/components/Icon/ProjectIcon/README.md) |
+| [`PortfolioIcon`](#portfolioicon) | Colored icon for a portfolio entity. Color is deterministically derived from the portfolio ID. | [→ README](src/components/Icon/PortfolioIcon/README.md) |
+| [`GoalIcon`](#goalicon) | Colored icon for a goal entity. Color is deterministically derived from the goal ID. | [→ README](src/components/Icon/GoalIcon/README.md) |
+| [`KeyResultIcon`](#keyresulticon) | Icon for a key result entity, with a built-in tooltip. | [→ README](src/components/Icon/KeyResultIcon/README.md) |
+
+### Layout components
+
+| Component | Description | README |
+|---|---|---|
+| [`TrackerDisclosure`](#trackerdisclosure) | Collapsible section with Tracker-specific styling. Extends Gravity UI `Disclosure` with configurable arrow position, size, and an optional toolbar slot. | [→ README](src/components/TrackerDisclosure/README.md) |
+
+---
+
+## Quick start
+
+### QueueSelect
+
+```tsx
+import {QueueSelect} from '@weavix/tracker-components';
+import type {QueueInfo} from '@weavix/tracker-components';
+
+const queues: QueueInfo[] = [
+    {key: 'DEV', display: 'Development'},
+    {key: 'DESIGN', display: 'Design'},
+];
+
+<QueueSelect
+    queues={queues}
+    defaultQueue={queues[0]}
+    onChange={(queue) => console.log(queue)}
+/>;
+```
+
+→ Full documentation including async suggest and Tracker API integration: [src/components/QueueSelect/README.md](src/components/QueueSelect/README.md)
+
+---
+
+### MetaEntitiesSelect
+
+```tsx
+import {MetaEntitiesSelect} from '@weavix/tracker-components';
+
+<MetaEntitiesSelect
+    getItems={(text) => fetchProjects(text)}
+    onChange={(entity) => console.log('selected', entity)}
+/>;
+```
+
+→ Full documentation including Tracker API integration: [src/components/MetaEntitiesSelect/README.md](src/components/MetaEntitiesSelect/README.md)
+
+---
+
+### PluginFieldsSelect
+
+```tsx
+import {PluginFieldsSelect} from '@weavix/tracker-components';
+import type {PluginFieldsSelectField} from '@weavix/tracker-components';
+
+const fields: PluginFieldsSelectField[] = [
+    {id: 'summary', name: 'Summary', category: {id: '1', display: 'System Fields'}},
+    {id: 'sprint', name: 'Sprint', category: {id: '2', display: 'Custom Fields'}},
+];
+
+<PluginFieldsSelect
+    open={true}
+    fields={fields}
+    onOpenChange={setOpen}
+    onItemSelect={(item) => console.log('selected', item)}
+    onItemDeselect={(item) => console.log('deselected', item)}
+/>;
+```
+
+→ Full documentation including 3 Tracker API fetch flows: [src/components/PluginFieldsSelect/README.md](src/components/PluginFieldsSelect/README.md)
+
+---
+
+### IssueTypeIcon
+
+```tsx
+import {IssueTypeIcon} from '@weavix/tracker-components';
+
+<IssueTypeIcon issueType="bug" />
+<IssueTypeIcon issueType="epic" size={24} />
+```
+
+→ Full documentation: [src/components/Icon/IssueTypeIcon/README.md](src/components/Icon/IssueTypeIcon/README.md)
+
+---
+
+### MetaEntityIcon
+
+```tsx
+import {MetaEntityIcon} from '@weavix/tracker-components';
+
+// Automatically renders the correct icon based on entityType
+<MetaEntityIcon entity={{entityType: 'project', id: 'proj-1', shortId: 42}} />
+<MetaEntityIcon entity={{entityType: 'portfolio', id: 'port-1', shortId: 7}} size={24} />
+```
+
+→ Full documentation: [src/components/Icon/MetaEntityIcon/README.md](src/components/Icon/MetaEntityIcon/README.md)
+
+---
+
+### ProjectIcon / PortfolioIcon / GoalIcon
+
+```tsx
+import {ProjectIcon, PortfolioIcon, GoalIcon} from '@weavix/tracker-components';
+
+<ProjectIcon projectId={123} />
+<PortfolioIcon portfolioId="portfolio-abc" />
+<GoalIcon goalId={456} />
+```
+
+→ [ProjectIcon README](src/components/Icon/ProjectIcon/README.md) · [PortfolioIcon README](src/components/Icon/PortfolioIcon/README.md) · [GoalIcon README](src/components/Icon/GoalIcon/README.md)
+
+---
+
+### KeyResultIcon
+
+```tsx
+import {KeyResultIcon} from '@weavix/tracker-components';
+
+<KeyResultIcon size={16} />
+```
+
+→ Full documentation: [src/components/Icon/KeyResultIcon/README.md](src/components/Icon/KeyResultIcon/README.md)
 
-- `react`, `react-dom` ^18
-- `@gravity-ui/uikit` ^7
-- `@gravity-ui/icons` ^2
+---
 
-## Usage
+### TrackerDisclosure
 
 ```tsx
-import {Hello} from '@weavix/tracker-components';
+import {TrackerDisclosure} from '@weavix/tracker-components';
 
-<Hello name="Tracker" />;
+<TrackerDisclosure summary="Section title" defaultExpanded>
+    Content goes here
+</TrackerDisclosure>
 ```
 
+→ Full documentation: [src/components/TrackerDisclosure/README.md](src/components/TrackerDisclosure/README.md)
+
+---
+
+## Architecture notes
+
+### Data-agnostic pattern
+
+All select components (`QueueSelect`, `MetaEntitiesSelect`, `PluginFieldsSelect`) are **data-agnostic**: they accept data via props and callbacks. You are responsible for fetching data from the Tracker API and passing it to the component. This keeps the components reusable and testable without a live API.
+
+### Tracker API integration
+
+Each select component's README contains a dedicated **Tracker API** section with:
+- The exact API endpoints to call
+- Ready-to-copy fetch functions
+- Complete working examples
+
+### Styling
+
+Components use [Gravity UI](https://gravity-ui.com/) design tokens and BEM class names. Import the component CSS by ensuring your bundler processes `.scss` files from this package (the package declares `sideEffects: ["*.scss"]`).
+
+---
+
 ## Development
 
 ```bash
 pnpm install
-pnpm run build
-pnpm run typecheck
-pnpm run lint
-pnpm run test
+pnpm run build       # compile to build/
+pnpm run typecheck   # TypeScript type check
+pnpm run lint        # ESLint + Stylelint + Prettier
+pnpm run test        # Jest unit tests
 ```
 
 ### Storybook
 
-Для запуска Storybook-сервера:
-
 ```bash
-pnpm run storybook
+pnpm run storybook   # starts at http://localhost:7008
 ```
 
-Storybook запустится по адресу `http://localhost:7008` для просмотра и взаимодействия с историями компонентов.
-
-To build a static version of Storybook:
-
-Истории компонентов находятся в директориях `__stories__` в папках компонентов.
+Component stories live in `__stories__/` directories inside each component folder.

package/build/cjs/components/Icon/GoalIcon/README.md

@@ -0,0 +1,123 @@
+# GoalIcon
+
+<!-- description:start -->
+Displays a colored icon for a Tracker goal entity. The icon color is deterministically derived from the `goalId`, so the same goal always renders the same color across sessions and environments.
+<!-- description:end -->
+
+## Usage
+
+```tsx
+import {GoalIcon} from '@weavix/tracker-components';
+
+<GoalIcon goalId={456} />
+```
+
+## Component props
+
+<!-- props:start -->
+```ts
+{
+    /**
+     * Goal ID used to generate a deterministic color.
+     * Accepts either a numeric shortId or a string entity ID.
+     */
+    goalId: number | string;
+
+    /**
+     * Additional CSS class applied to the root element.
+     */
+    className?: string;
+
+    /**
+     * Entity type label. Defaults to "goal".
+     */
+    type?: string;
+
+    /**
+     * Size of the SVG icon inside the container in pixels.
+     * @default 16
+     */
+    size?: number;
+
+    /**
+     * Size of the icon container (the colored square) in pixels.
+     * @default 24
+     */
+    refugeSize?: number;
+
+    /**
+     * Whether to render a colored background behind the icon.
+     * @default true
+     */
+    withBackground?: boolean;
+
+    /**
+     * Border radius variant of the icon container.
+     * @default 'm'
+     */
+    radius?: 'm' | 'l';
+
+    /**
+     * Alpha (opacity) of the icon foreground color.
+     * @default 1
+     */
+    colorAlpha?: number;
+}
+```
+<!-- props:end -->
+
+---
+
+## Examples
+
+### Default
+
+```tsx
+import {GoalIcon} from '@weavix/tracker-components';
+
+<GoalIcon goalId={456} />
+```
+
+### Custom size
+
+```tsx
+// Larger icon container with a larger SVG inside
+<GoalIcon goalId={456} size={20} refugeSize={32} />
+```
+
+### Without background
+
+```tsx
+// Renders only the colored SVG, no background square
+<GoalIcon goalId={456} withBackground={false} />
+```
+
+### Alongside goal name
+
+```tsx
+import {GoalIcon} from '@weavix/tracker-components';
+
+export const GoalLabel = ({goal}: {goal: {shortId: number; summary: string}}) => (
+    <div style={{display: 'flex', alignItems: 'center', gap: 8}}>
+        <GoalIcon goalId={goal.shortId} />
+        <span>{goal.summary}</span>
+    </div>
+);
+```
+
+### Multiple goals (each gets a unique color)
+
+```tsx
+const goals = [
+    {shortId: 1, summary: 'Increase retention'},
+    {shortId: 2, summary: 'Launch mobile app'},
+    {shortId: 3, summary: 'Reduce churn'},
+];
+
+goals.map((g) => (
+    <div key={g.shortId} style={{display: 'flex', alignItems: 'center', gap: 8}}>
+        <GoalIcon goalId={g.shortId} />
+        <span>{g.summary}</span>
+    </div>
+));
+```

package/build/cjs/components/Icon/IssueTypeIcon/README.md

@@ -1,40 +1,122 @@
 # IssueTypeIcon
 
 <!-- description:start -->
-Component displaying icons for the various issue types
+Displays the icon for a Tracker issue type (task, bug, epic, improvement, etc.). Each issue type maps to a distinct SVG asset. Unknown type keys fall back to a generic icon.
 <!-- description:end -->
 
+## Usage
+
+```tsx
+import {IssueTypeIcon} from '@weavix/tracker-components';
+
+<IssueTypeIcon issueType="bug" />
+```
+
 ## Component props
 
 <!-- props:start -->
 ```ts
 {
     /**
-     * Additional class
+     * Issue type key. Known values are listed below; any other string is
+     * accepted and falls back to a generic icon.
      */
-    className?: string;
+    issueType:
+        | 'task'
+        | 'bug'
+        | 'design'
+        | 'epic'
+        | 'improvement'
+        | 'incident'
+        | 'info'
+        | 'milestone'
+        | 'newFeature'
+        | 'query'
+        | 'refactoring'
+        | 'release'
+        | 'research'
+        | 'serviceRequest'
+        | 'story'
+        | 'subBug'
+        | 'subTask'
+        | 'technicalDebt'
+        | string;
+
     /**
-     * Issue type key
+     * Size of the icon in pixels.
+     * @default 16
      */
-    issueType:
-        'task' |
-        'bug' |
-        'design' |
-        'epic' |
-        'improvement' |
-        'incident' |
-        'info' |
-        'newFeature' |
-        'query' |
-        'refactoring' |
-        'release' |
-        'serviceRequest' |
-        'story' |
-        'subBug' |
-        'subTask' |
-        'technicalDebt' |
-        'milestone' |
-        string;
+    size?: number;
+
+    /**
+     * Additional CSS class applied to the root element.
+     */
+    className?: string;
 }
 ```
 <!-- props:end -->
+
+---
+
+## Examples
+
+### Single icon
+
+```tsx
+import {IssueTypeIcon} from '@weavix/tracker-components';
+
+<IssueTypeIcon issueType="task" />
+<IssueTypeIcon issueType="bug" />
+<IssueTypeIcon issueType="epic" />
+```
+
+### Custom size
+
+```tsx
+<IssueTypeIcon issueType="story" size={24} />
+<IssueTypeIcon issueType="story" size={32} />
+```
+
+### Alongside issue summary
+
+```tsx
+import {IssueTypeIcon} from '@weavix/tracker-components';
+
+export const IssueRow = ({issue}: {issue: {type: string; summary: string}}) => (
+    <div style={{display: 'flex', alignItems: 'center', gap: 8}}>
+        <IssueTypeIcon issueType={issue.type} size={16} />
+        <span>{issue.summary}</span>
+    </div>
+);
+```
+
+### All known issue types
+
+```tsx
+import {IssueTypeIcon} from '@weavix/tracker-components';
+
+const ISSUE_TYPES = [
+    'task', 'bug', 'design', 'epic', 'improvement',
+    'incident', 'info', 'milestone', 'newFeature', 'query',
+    'refactoring', 'release', 'research', 'serviceRequest',
+    'story', 'subBug', 'subTask', 'technicalDebt',
+] as const;
+
+export const IssueTypeGallery = () => (
+    <div style={{display: 'flex', flexWrap: 'wrap', gap: 16}}>
+        {ISSUE_TYPES.map((type) => (
+            <div key={type} style={{display: 'flex', flexDirection: 'column', alignItems: 'center', gap: 4}}>
+                <IssueTypeIcon issueType={type} size={24} />
+                <span style={{fontSize: 11}}>{type}</span>
+            </div>
+        ))}
+    </div>
+);
+```
+
+---
+
+## Notes
+
+- The `issueType` value is matched case-sensitively against the known keys. Values returned by the Tracker API (e.g. `"newFeature"`, `"subTask"`) match directly without transformation.
+- Passing an unknown string does not throw — the component renders a generic fallback icon.

package/build/cjs/components/Icon/KeyResultIcon/README.md

@@ -0,0 +1,73 @@
+# KeyResultIcon
+
+<!-- description:start -->
+Displays the icon for a Tracker key result entity. Renders a fixed SVG asset wrapped in a sized container, with a built-in tooltip that shows the localized "Key result" label on hover.
+<!-- description:end -->
+
+## Usage
+
+```tsx
+import {KeyResultIcon} from '@weavix/tracker-components';
+
+<KeyResultIcon />
+```
+
+## Component props
+
+<!-- props:start -->
+```ts
+{
+    /**
+     * Size of the SVG icon inside the container in pixels.
+     * @default 16
+     */
+    size?: number;
+
+    /**
+     * Size of the icon container in pixels.
+     * @default 24
+     */
+    refugeSize?: number;
+}
+```
+<!-- props:end -->
+
+---
+
+## Examples
+
+### Default
+
+```tsx
+import {KeyResultIcon} from '@weavix/tracker-components';
+
+<KeyResultIcon />
+```
+
+### Custom size
+
+```tsx
+// Larger icon for a header row
+<KeyResultIcon size={20} refugeSize={32} />
+```
+
+### Alongside key result name
+
+```tsx
+import {KeyResultIcon} from '@weavix/tracker-components';
+
+export const KeyResultLabel = ({name}: {name: string}) => (
+    <div style={{display: 'flex', alignItems: 'center', gap: 8}}>
+        <KeyResultIcon />
+        <span>{name}</span>
+    </div>
+);
+```
+
+---
+
+## Notes
+
+- The tooltip text is **automatically localized** using the Gravity UI `getConfig().lang` setting. No additional i18n setup is required.
+- Unlike [`GoalIcon`](../GoalIcon/README.md), [`ProjectIcon`](../ProjectIcon/README.md), and [`PortfolioIcon`](../PortfolioIcon/README.md), `KeyResultIcon` does **not** accept an entity ID — it always renders the same fixed asset.
+- To render the correct icon for an arbitrary meta entity type, use [`MetaEntityIcon`](../MetaEntityIcon/README.md) instead.

package/build/cjs/components/Icon/MetaEntityIcon/README.md

@@ -0,0 +1,126 @@
+# MetaEntityIcon
+
+<!-- description:start -->
+A dispatcher component that renders the correct icon for any Tracker meta entity type — project, portfolio, goal, or key result. Pass the entity object and the component automatically selects and renders the appropriate icon with a deterministic color derived from the entity ID.
+<!-- description:end -->
+
+## Usage
+
+```tsx
+import {MetaEntityIcon} from '@weavix/tracker-components';
+
+<MetaEntityIcon entity={{entityType: 'project', id: 'proj-1', shortId: 42}} />
+```
+
+## Component props
+
+<!-- props:start -->
+```ts
+{
+    /**
+     * The meta entity to display an icon for.
+     * Only `entityType`, `id`, and `shortId` are required.
+     */
+    entity: {
+        entityType: 'project' | 'portfolio' | 'goal' | 'keyResult';
+        /** String entity ID (used for portfolio color generation). */
+        id: string;
+        /** Numeric short ID (used for project and goal color generation). */
+        shortId: number;
+    };
+
+    /**
+     * Size of the SVG icon inside the container in pixels.
+     * @default 20
+     */
+    size?: number;
+}
+```
+<!-- props:end -->
+
+---
+
+## Supported entity types
+
+| `entityType` | Rendered component | Color source |
+|---|---|---|
+| `'project'` | [`ProjectIcon`](../ProjectIcon/README.md) | `shortId` |
+| `'portfolio'` | [`PortfolioIcon`](../PortfolioIcon/README.md) | `id` |
+| `'goal'` | [`GoalIcon`](../GoalIcon/README.md) | `shortId` |
+| `'keyResult'` | [`KeyResultIcon`](../KeyResultIcon/README.md) | fixed asset, no color |
+| anything else | `null` (renders nothing) | — |
+
+---
+
+## Examples
+
+### All entity types
+
+```tsx
+import {MetaEntityIcon} from '@weavix/tracker-components';
+
+<MetaEntityIcon entity={{entityType: 'project',   id: 'proj-1',  shortId: 42}} />
+<MetaEntityIcon entity={{entityType: 'portfolio', id: 'port-1',  shortId: 7}}  />
+<MetaEntityIcon entity={{entityType: 'goal',      id: 'goal-1',  shortId: 99}} />
+```
+
+### Custom size
+
+```tsx
+// 32 px icon for a page header
+<MetaEntityIcon
+    entity={{entityType: 'project', id: 'proj-1', shortId: 42}}
+    size={32}
+/>
+```
+
+### Rendering from a Tracker API response
+
+`MetaEntityIcon` accepts the shape returned directly by the Tracker entities search endpoint, so you can pass `result.data[i]` without any mapping:
+
+```tsx
+import React, {useEffect, useState} from 'react';
+import {MetaEntityIcon} from '@weavix/tracker-components';
+import type {MetaEntityV2} from '@weavix/tracker-api-types';
+
+interface Props {
+    trackerApi: TrackerApi;
+}
+
+export const EntityList: React.FC<Props> = ({trackerApi}) => {
+    const [entities, setEntities] = useState<MetaEntityV2[]>([]);
+
+    useEffect(() => {
+        trackerApi.v3
+            .post['/entities/{entityType}/_search']({
+                pathParams: {entityType: 'project'},
+                queryParams: {fields: ['summary'], page: 1, perPage: 20},
+                bodyParams: {filter: {}, filterTypes: ['ALL'], input: ''},
+            })
+            .then((result) => setEntities(result.data));
+    }, [trackerApi]);
+
+    return (
+        <ul>
+            {entities.map((entity) => (
+                <li key={entity.id} style={{display: 'flex', alignItems: 'center', gap: 8}}>
+                    <MetaEntityIcon entity={entity} size={20} />
+                    <span>{entity.fields?.summary?.value ?? entity.id}</span>
+                </li>
+            ))}
+        </ul>
+    );
+};
+```
+
+### Used inside MetaEntitiesSelect
+
+`MetaEntityIcon` is used internally by [`MetaEntitiesSelect`](../../MetaEntitiesSelect/README.md) to render each item in the suggest list. You do not need to use it directly when using that component.
+
+---
+
+## Notes
+
+- The `entity` prop only requires `entityType`, `id`, and `shortId` — it is compatible with the full `MetaEntityV2` type from `@weavix/tracker-api-types`.
+- For unknown `entityType` values the component renders `null` silently.
+- To render individual entity icons directly, use [`ProjectIcon`](../ProjectIcon/README.md), [`PortfolioIcon`](../PortfolioIcon/README.md), [`GoalIcon`](../GoalIcon/README.md), or [`KeyResultIcon`](../KeyResultIcon/README.md).