@weavix/tracker-components 0.1.0 → 0.1.1

package/build/esm/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/esm/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/esm/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).

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

@@ -1,51 +1,129 @@
 # 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.
      * @default false
      */
     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 {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.