@weavix/tracker-components 0.1.0 → 0.1.2

package/build/esm/components/Icon/PortfolioIcon/README.md

@@ -1,51 +1,136 @@
 # PortfolioIcon
 
 <!-- description:start -->
-Component displaying an icon for a portfolio entity
+Displays a colored icon for a Tracker portfolio entity. The icon color is deterministically derived from the `portfolioId`, so the same portfolio always renders the same color across sessions and environments.
 <!-- description:end -->
 
+## Usage
+
+```tsx
+import {PortfolioIcon} from '@weavix/tracker-components';
+
+<PortfolioIcon portfolioId="portfolio-abc" />
+```
+
 ## Component props
 
 <!-- props:start -->
 ```ts
 {
     /**
-     * Portfolio ID used to generate a deterministic color
+     * Portfolio ID used to generate a deterministic color.
+     * Typically the string entity ID returned by the Tracker API.
      */
     portfolioId: string;
+
     /**
-     * Additional class
+     * Additional CSS class applied to the root element.
      */
     className?: string;
+
     /**
-     * Entity type label (defaults to "portfolio")
+     * Entity type label. Defaults to "portfolio".
      */
     type?: string;
+
     /**
-     * Size of the SVG icon inside the container in pixels
+     * Size of the SVG icon inside the container in pixels.
      * @default 16
      */
     size?: number;
+
     /**
-     * Size of the icon container in pixels
+     * Size of the icon container (the colored square) in pixels.
      * @default 24
      */
     refugeSize?: number;
+
     /**
-     * Whether to render a colored background behind the icon
+     * Whether to render a colored background behind the icon.
+     * `PortfolioIcon` defaults this to `false`; `EntityIcon`'s own default is `true`.
      * @default false
      */
     withBackground?: boolean;
+
     /**
-     * Border radius variant of the icon container
+     * Alpha (opacity) of the icon foreground color, in the range 0–1.
+     * @default 1
+     */
+    colorAlpha?: number;
+
+    /**
+     * Border radius variant of the icon container.
      * @default 'm'
      */
     radius?: 'm' | 'l';
+
     /**
-     * Alpha (opacity) of the icon color
+     * Alpha (opacity) of the icon foreground color.
      * @default 1
      */
     colorAlpha?: number;
 }
 ```
 <!-- props:end -->
+
+---
+
+## Examples
+
+### Default
+
+```tsx
+import {PortfolioIcon} from '@weavix/tracker-components';
+
+<PortfolioIcon portfolioId="portfolio-abc" />
+```
+
+### With background
+
+```tsx
+<PortfolioIcon portfolioId="portfolio-abc" withBackground />
+```
+
+### Custom size
+
+```tsx
+<PortfolioIcon portfolioId="portfolio-abc" size={20} refugeSize={32} />
+```
+
+### Alongside portfolio name
+
+```tsx
+import {PortfolioIcon} from '@weavix/tracker-components';
+
+export const PortfolioLabel = ({portfolio}: {portfolio: {id: string; name: string}}) => (
+    <div style={{display: 'flex', alignItems: 'center', gap: 8}}>
+        <PortfolioIcon portfolioId={portfolio.id} />
+        <span>{portfolio.name}</span>
+    </div>
+);
+```
+
+### Multiple portfolios (each gets a unique color)
+
+```tsx
+const portfolios = [
+    {id: 'port-1', name: 'Platform'},
+    {id: 'port-2', name: 'Growth'},
+    {id: 'port-3', name: 'Infrastructure'},
+];
+
+portfolios.map((p) => (
+    <div key={p.id} style={{display: 'flex', alignItems: 'center', gap: 8}}>
+        <PortfolioIcon portfolioId={p.id} />
+        <span>{p.name}</span>
+    </div>
+));
+```
+
+---
+
+## Notes
+
+- Unlike [`ProjectIcon`](../ProjectIcon/README.md) and [`GoalIcon`](../GoalIcon/README.md), `PortfolioIcon` uses the **string `id`** (not `shortId`) for color generation.
+- `withBackground` defaults to `false` for portfolios (vs `true` for projects). Pass `withBackground` explicitly if you want the colored square background.
+- To render the correct icon for an arbitrary meta entity type, use [`MetaEntityIcon`](../MetaEntityIcon/README.md) instead.

package/build/esm/components/Icon/ProjectIcon/README.md

@@ -1,51 +1,175 @@
 # ProjectIcon
 
 <!-- description:start -->
-Component displaying an icon for a project entity
+Displays a colored icon for a Tracker project entity. The icon color is deterministically derived from the `projectId`, so the same project always renders the same color across sessions and environments.
 <!-- description:end -->
 
+## Usage
+
+```tsx
+import {ProjectIcon} from '@weavix/tracker-components';
+
+<ProjectIcon projectId={123} />
+```
+
 ## Component props
 
 <!-- props:start -->
 ```ts
 {
     /**
-     * Project ID used to generate a deterministic color
+     * Project ID used to generate a deterministic color.
+     * Accepts either the numeric shortId or a string entity ID.
      */
     projectId?: number | string;
+
     /**
-     * Additional class
+     * Additional CSS class applied to the root element.
      */
     className?: string;
+
     /**
-     * Entity type label (defaults to "project")
+     * Entity type label. Defaults to "project".
      */
     type?: string;
+
     /**
-     * Size of the SVG icon inside the container in pixels
+     * Size of the SVG icon inside the container in pixels.
      * @default 16
      */
     size?: number;
+
     /**
-     * Size of the icon container in pixels
+     * Size of the icon container (the colored square) in pixels.
      * @default 24
      */
     refugeSize?: number;
+
     /**
-     * Whether to render a colored background behind the icon
+     * Whether to render a colored background behind the icon.
      * @default true
      */
     withBackground?: boolean;
+
     /**
-     * Border radius variant of the icon container
+     * Border radius variant of the icon container.
      * @default 'm'
      */
     radius?: 'm' | 'l';
+
     /**
-     * Alpha (opacity) of the icon color
+     * Alpha (opacity) of the icon foreground color.
      * @default 1
      */
     colorAlpha?: number;
 }
 ```
 <!-- props:end -->
+
+---
+
+## Examples
+
+### Default
+
+```tsx
+import {ProjectIcon} from '@weavix/tracker-components';
+
+<ProjectIcon projectId={123} />
+```
+
+### Without background
+
+```tsx
+// Renders only the colored SVG, no background square
+<ProjectIcon projectId={123} withBackground={false} />
+```
+
+### Custom size
+
+```tsx
+<ProjectIcon projectId={123} size={20} refugeSize={32} />
+```
+
+### Large radius
+
+```tsx
+<ProjectIcon projectId={123} radius="l" />
+```
+
+### Alongside project name
+
+```tsx
+import {ProjectIcon} from '@weavix/tracker-components';
+
+export const ProjectLabel = ({project}: {project: {shortId: number; name: string}}) => (
+    <div style={{display: 'flex', alignItems: 'center', gap: 8}}>
+        <ProjectIcon projectId={project.shortId} />
+        <span>{project.name}</span>
+    </div>
+);
+```
+
+### Multiple projects (each gets a unique color)
+
+```tsx
+const projects = [
+    {shortId: 1, name: 'Backend API'},
+    {shortId: 2, name: 'Mobile App'},
+    {shortId: 3, name: 'Design System'},
+];
+
+projects.map((p) => (
+    <div key={p.shortId} style={{display: 'flex', alignItems: 'center', gap: 8}}>
+        <ProjectIcon projectId={p.shortId} />
+        <span>{p.name}</span>
+    </div>
+));
+```
+
+### Rendering from a Tracker API response
+
+The Tracker entities search endpoint returns `shortId` as a number — pass it directly:
+
+```tsx
+import React, {useEffect, useState} from 'react';
+import {ProjectIcon} from '@weavix/tracker-components';
+import type {MetaEntityV2} from '@weavix/tracker-api-types';
+
+interface Props {
+    trackerApi: TrackerApi;
+}
+
+export const ProjectList: React.FC<Props> = ({trackerApi}) => {
+    const [projects, setProjects] = 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) => setProjects(result.data));
+    }, [trackerApi]);
+
+    return (
+        <ul>
+            {projects.map((project) => (
+                <li key={project.id} style={{display: 'flex', alignItems: 'center', gap: 8}}>
+                    <ProjectIcon projectId={project.shortId} />
+                    <span>{project.fields?.summary?.value ?? project.id}</span>
+                </li>
+            ))}
+        </ul>
+    );
+};
+```
+
+---
+
+## Notes
+
+- `withBackground` defaults to `true` for projects (vs `false` for [`PortfolioIcon`](../PortfolioIcon/README.md)).
+- Pass `projectId` as the **numeric `shortId`** from the Tracker API for consistent color generation. String IDs are also accepted.
+- To render the correct icon for an arbitrary meta entity type, use [`MetaEntityIcon`](../MetaEntityIcon/README.md) instead.

package/build/esm/components/MetaEntitiesSelect/README.md

@@ -100,6 +100,16 @@ type MetaEntityV2 = {
 
 `MetaEntitiesSelect` is data-agnostic — it accepts items via the `getItems` prop. You are responsible for fetching data from the Tracker API and passing it to the component.
 
+Requires the `"tracker:entities:write"` permission in your plugin's `manifest.json`:
+
+```json
+{
+    "permissions": {
+        "data": ["tracker:entities:write"]
+    }
+}
+```
+
 ### Getting projects
 
 Use the entities search endpoint to fetch projects (or other entity types):

package/build/esm/components/PluginFieldsSelect/README.md

@@ -235,6 +235,24 @@ type TrackerSelectItem = {
 
 `PluginFieldsSelect` is data-agnostic — it accepts fields via the `fields` prop. You are responsible for fetching data from the Tracker API and passing it to the component.
 
+Add the required permissions to your plugin's `manifest.json`:
+
+```json
+{
+    "permissions": {
+        "data": [
+            "tracker:fields:read",
+            "tracker:fields:write",
+            "tracker:queues:read"
+        ]
+    }
+}
+```
+
+- `tracker:fields:read` — required for `GET /fields` and `POST /fields/_suggest`
+- `tracker:fields:write` — required if your plugin writes field values back to Tracker
+- `tracker:queues:read` — required when using `localFields: true` with queue keys (Flow 3)
+
 There are three fetch flows depending on whether the user has typed anything and whether local (queue-specific) fields are needed.
 
 ### Flow 1 — Initial load (no user input)

package/build/esm/components/QueueSelect/README.md

@@ -178,6 +178,16 @@ type QueueSuggestItem = {
 
 `QueueSelect` is data-agnostic — it accepts queues via the `queues` prop and search results via the `onSearch` callback. You are responsible for fetching data from the Tracker API and passing it to the component.
 
+Requires the `"tracker:queues:read"` permission in your plugin's `manifest.json`:
+
+```json
+{
+    "permissions": {
+        "data": ["tracker:queues:read"]
+    }
+}
+```
+
 There are two fetch flows depending on whether the user has typed anything in the search filter.
 
 ### Flow 1 — Initial load (no user input)

package/build/esm/components/TrackerDisclosure/README.md

@@ -0,0 +1,205 @@
+# TrackerDisclosure
+
+<!-- description:start -->
+A collapsible section component with Tracker-specific styling. Extends Gravity UI [`Disclosure`](https://gravity-ui.com/components/disclosure) with a configurable chevron arrow (position and size), an optional toolbar slot rendered alongside the summary, and BEM class name hooks for fine-grained styling.
+<!-- description:end -->
+
+## Usage
+
+```tsx
+import {TrackerDisclosure} from '@weavix/tracker-components';
+
+<TrackerDisclosure summary="Section title" defaultExpanded>
+    Content goes here
+</TrackerDisclosure>
+```
+
+## Component props
+
+<!-- props:start -->
+```ts
+{
+    /**
+     * Content shown in the clickable summary / header row.
+     * Accepts a string or any ReactNode.
+     */
+    summary?: ReactNode;
+
+    /**
+     * Content rendered inside the collapsible body.
+     */
+    children?: ReactNode;
+
+    /**
+     * Whether the section is expanded on first render (uncontrolled).
+     * @default false
+     */
+    defaultExpanded?: boolean;
+
+    /**
+     * Controlled expanded state. When provided, you must also handle onUpdate.
+     */
+    expanded?: boolean;
+
+    /**
+     * Callback fired when the expanded state changes.
+     */
+    onUpdate?: (expanded: boolean) => void;
+
+    /**
+     * Whether the disclosure is disabled (non-interactive).
+     * @default false
+     */
+    disabled?: boolean;
+
+    /**
+     * Position of the chevron arrow relative to the summary text.
+     * @default 'end'
+     */
+    arrowPosition?: 'start' | 'end';
+
+    /**
+     * Size of the chevron arrow icon in pixels.
+     * @default 20
+     */
+    arrowSize?: number;
+
+    /**
+     * Optional ReactNode rendered to the right of the toggle button inside the
+     * summary row. Useful for action buttons (edit, delete, add, …).
+     */
+    toolbar?: ReactNode;
+
+    /**
+     * Additional CSS class applied to the root element.
+     */
+    className?: string;
+
+    /**
+     * Additional CSS class applied to the summary row wrapper.
+     */
+    summaryClassName?: string;
+
+    /**
+     * Additional CSS class applied to the toggle `<button>` element.
+     */
+    toggleClassName?: string;
+
+    /**
+     * Additional CSS class applied to the chevron arrow icon.
+     */
+    arrowClassName?: string;
+}
+```
+<!-- props:end -->
+
+> **Note:** `TrackerDisclosure` accepts all props from Gravity UI [`DisclosureProps`](https://gravity-ui.com/components/disclosure) in addition to the Tracker-specific ones listed above.
+
+---
+
+## Examples
+
+### Basic (uncontrolled)
+
+```tsx
+import {TrackerDisclosure} from '@weavix/tracker-components';
+
+<TrackerDisclosure summary="Sprint details" defaultExpanded>
+    <p>Sprint 42 — 14 issues, 3 in progress.</p>
+</TrackerDisclosure>
+```
+
+---
+
+### Controlled
+
+```tsx
+import React, {useState} from 'react';
+import {TrackerDisclosure} from '@weavix/tracker-components';
+
+export const ControlledExample = () => {
+    const [expanded, setExpanded] = useState(false);
+
+    return (
+        <TrackerDisclosure
+            summary="Filters"
+            expanded={expanded}
+            onUpdate={setExpanded}
+        >
+            <p>Filter content here.</p>
+        </TrackerDisclosure>
+    );
+};
+```
+
+---
+
+### Arrow at start
+
+```tsx
+<TrackerDisclosure summary="Description" arrowPosition="start">
+    <p>Content with the chevron on the left.</p>
+</TrackerDisclosure>
+```
+
+---
+
+### With toolbar
+
+The `toolbar` prop renders additional content (e.g. action buttons) to the right of the toggle button, inside the summary row but outside the toggle click area.
+
+```tsx
+import {Button} from '@gravity-ui/uikit';
+import {TrackerDisclosure} from '@weavix/tracker-components';
+
+<TrackerDisclosure
+    summary="Attachments"
+    toolbar={
+        <Button size="s" view="flat" onClick={() => openUploadDialog()}>
+            Add file
+        </Button>
+    }
+>
+    <AttachmentList />
+</TrackerDisclosure>
+```
+
+---
+
+### Disabled
+
+```tsx
+<TrackerDisclosure summary="Locked section" disabled defaultExpanded>
+    <p>This section cannot be collapsed by the user.</p>
+</TrackerDisclosure>
+```
+
+---
+
+### Multiple sections (accordion-like)
+
+```tsx
+import React, {useState} from 'react';
+import {TrackerDisclosure} from '@weavix/tracker-components';
+
+const SECTIONS = ['Details', 'Attachments', 'Comments'];
+
+export const AccordionExample = () => {
+    const [openIndex, setOpenIndex] = useState<number | null>(0);
+
+    return (
+        <>
+            {SECTIONS.map((title, i) => (
+                <TrackerDisclosure
+                    key={title}
+                    summary={title}
+                    expanded={openIndex === i}
+                    onUpdate={(open) => setOpenIndex(open ? i : null)}
+                >
+                    <p>Content for {title}</p>
+                </TrackerDisclosure>
+            ))}
+        </>
+    );
+};
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@weavix/tracker-components",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "description": "Shared UI components for Yandex Tracker plugins",
   "main": "build/cjs/index.js",
   "module": "build/esm/index.js",

package/build/cjs/components/Icon/Icon.css

@@ -1,33 +0,0 @@
-.tpc-Icon_priority_blocker {
-  color: var(--g-color-text-danger);
-}
-.tpc-Icon_priority_critical {
-  color: var(--g-color-text-warning-heavy);
-}
-.tpc-Icon_priority_trivial {
-  color: var(--g-color-text-hint);
-}
-.tpc-Icon_priority_normal, .tpc-Icon_priority_minor {
-  color: var(--g-color-text-secondary);
-}
-.tpc-Icon-background {
-  display: flex;
-  align-items: center;
-  justify-content: center;
-  width: 100%;
-  height: 100%;
-  border-radius: 50%;
-}
-.tpc-Icon-background_priority_blocker {
-  background: var(--g-color-base-danger-light);
-}
-.tpc-Icon-background_priority_critical {
-  background: var(--g-color-base-warning-light);
-}
-.tpc-Icon-background_priority_trivial {
-  background: var(--g-color-base-neutral-light);
-}
-.tpc-Icon-background_priority_normal, .tpc-Icon-background_priority_minor {
-  background: var(--g-color-base-neutral-light);
-}
-/*# sourceMappingURL=Icon.css.map */

package/build/cjs/components/Icon/Icon.css.map

@@ -1 +0,0 @@
-{"version":3,"sources":["Icon.scss"],"names":[],"mappings":"AACI;EACI,iCAAA;AAAR;AAGI;EACI,wCAAA;AADR;AAII;EACI,+BAAA;AAFR;AAKI;EAEI,oCAAA;AAJR;AAOI;EACI,aAAA;EACA,mBAAA;EACA,uBAAA;EAEA,WAAA;EACA,YAAA;EAEA,kBAAA;AAPR;AAUI;EACI,4CAAA;AARR;AAWI;EACI,6CAAA;AATR;AAYI;EACI,6CAAA;AAVR;AAaI;EAEI,6CAAA;AAZR","file":"Icon.css","sourcesContent":[".tpc-Icon {\n    &_priority_blocker {\n        color: var(--g-color-text-danger);\n    }\n\n    &_priority_critical {\n        color: var(--g-color-text-warning-heavy);\n    }\n\n    &_priority_trivial {\n        color: var(--g-color-text-hint);\n    }\n\n    &_priority_normal,\n    &_priority_minor {\n        color: var(--g-color-text-secondary);\n    }\n\n    &-background {\n        display: flex;\n        align-items: center;\n        justify-content: center;\n\n        width: 100%;\n        height: 100%;\n\n        border-radius: 50%;\n    }\n\n    &-background_priority_blocker {\n        background: var(--g-color-base-danger-light);\n    }\n\n    &-background_priority_critical {\n        background: var(--g-color-base-warning-light);\n    }\n\n    &-background_priority_trivial {\n        background: var(--g-color-base-neutral-light);\n    }\n\n    &-background_priority_normal,\n    &-background_priority_minor {\n        background: var(--g-color-base-neutral-light);\n    }\n}\n"],"sourceRoot":""}

package/build/esm/components/Icon/Icon.css

@@ -1,33 +0,0 @@
-.tpc-Icon_priority_blocker {
-  color: var(--g-color-text-danger);
-}
-.tpc-Icon_priority_critical {
-  color: var(--g-color-text-warning-heavy);
-}
-.tpc-Icon_priority_trivial {
-  color: var(--g-color-text-hint);
-}
-.tpc-Icon_priority_normal, .tpc-Icon_priority_minor {
-  color: var(--g-color-text-secondary);
-}
-.tpc-Icon-background {
-  display: flex;
-  align-items: center;
-  justify-content: center;
-  width: 100%;
-  height: 100%;
-  border-radius: 50%;
-}
-.tpc-Icon-background_priority_blocker {
-  background: var(--g-color-base-danger-light);
-}
-.tpc-Icon-background_priority_critical {
-  background: var(--g-color-base-warning-light);
-}
-.tpc-Icon-background_priority_trivial {
-  background: var(--g-color-base-neutral-light);
-}
-.tpc-Icon-background_priority_normal, .tpc-Icon-background_priority_minor {
-  background: var(--g-color-base-neutral-light);
-}
-/*# sourceMappingURL=Icon.css.map */

package/build/esm/components/Icon/Icon.css.map

@@ -1 +0,0 @@
-{"version":3,"sources":["Icon.scss"],"names":[],"mappings":"AACI;EACI,iCAAA;AAAR;AAGI;EACI,wCAAA;AADR;AAII;EACI,+BAAA;AAFR;AAKI;EAEI,oCAAA;AAJR;AAOI;EACI,aAAA;EACA,mBAAA;EACA,uBAAA;EAEA,WAAA;EACA,YAAA;EAEA,kBAAA;AAPR;AAUI;EACI,4CAAA;AARR;AAWI;EACI,6CAAA;AATR;AAYI;EACI,6CAAA;AAVR;AAaI;EAEI,6CAAA;AAZR","file":"Icon.css","sourcesContent":[".tpc-Icon {\n    &_priority_blocker {\n        color: var(--g-color-text-danger);\n    }\n\n    &_priority_critical {\n        color: var(--g-color-text-warning-heavy);\n    }\n\n    &_priority_trivial {\n        color: var(--g-color-text-hint);\n    }\n\n    &_priority_normal,\n    &_priority_minor {\n        color: var(--g-color-text-secondary);\n    }\n\n    &-background {\n        display: flex;\n        align-items: center;\n        justify-content: center;\n\n        width: 100%;\n        height: 100%;\n\n        border-radius: 50%;\n    }\n\n    &-background_priority_blocker {\n        background: var(--g-color-base-danger-light);\n    }\n\n    &-background_priority_critical {\n        background: var(--g-color-base-warning-light);\n    }\n\n    &-background_priority_trivial {\n        background: var(--g-color-base-neutral-light);\n    }\n\n    &-background_priority_normal,\n    &-background_priority_minor {\n        background: var(--g-color-base-neutral-light);\n    }\n}\n"],"sourceRoot":""}