@weavix/tracker-components 0.1.0 → 0.1.2

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

@@ -1,40 +1,164 @@
 # 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.
+     */
+    issueType:
+        | 'task'
+        | 'bug'
+        | 'design'
+        | 'epic'
+        | 'improvement'
+        | 'incident'
+        | 'info'
+        | 'milestone'
+        | 'newFeature'
+        | 'query'
+        | 'refactoring'
+        | 'release'
+        | 'research'
+        | 'serviceRequest'
+        | 'story'
+        | 'subBug'
+        | 'subTask'
+        | 'technicalDebt'
+        | string;
+
+    /**
+     * Size of the icon in pixels.
+     * @default 16
+     */
+    size?: number;
+
+    /**
+     * Additional CSS class applied to the root element.
      */
     className?: string;
+
     /**
-     * Issue type key
+     * Additional CSS class applied to the outer container element.
      */
-    issueType:
-        'task' |
-        'bug' |
-        'design' |
-        'epic' |
-        'improvement' |
-        'incident' |
-        'info' |
-        'newFeature' |
-        'query' |
-        'refactoring' |
-        'release' |
-        'serviceRequest' |
-        'story' |
-        'subBug' |
-        'subTask' |
-        'technicalDebt' |
-        'milestone' |
-        string;
+    containerClassName?: string;
+
+    /**
+     * Human-readable display name for the issue type (e.g. `"Bug"`, `"Story"`).
+     * When provided, an accessible label `"Type: <issueType>"` is rendered for
+     * screen readers and `title` is forwarded to the icon container.
+     * When omitted, the icon is treated as decorative (`aria-hidden`).
+     */
+    title?: 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>
+);
+```
+
+### From Tracker API
+
+Requires the `"tracker:issuetypes:read"` permission in your plugin's `manifest.json`:
+
+```json
+{
+    "permissions": {
+        "data": ["tracker:issuetypes:read"]
+    }
+}
+```
+
+```tsx
+import {IssueTypeIcon} from '@weavix/tracker-components';
+
+const issueType = await trackerApi.v3.get['/issues/{id}/{field}']({
+    pathParams: {
+        id: 'ISSUEKEY-1',
+        field: 'type',
+    },
+});
+
+<IssueTypeIcon
+    issueType={issueType.data.key}
+    title={issueType.data.display}
+/>
+```
+
+---
+
+## 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.
+- When `title` is omitted the icon is treated as decorative and gets `aria-hidden="true"`. Pass `title` (e.g. `type.display` from the API) to make the icon accessible.

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,136 @@
+# 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
+
+Requires the `"tracker:entities:write"` permission in your plugin's `manifest.json`:
+
+```json
+{
+    "permissions": {
+        "data": ["tracker:entities:write"]
+    }
+}
+```
+
+`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/cjs/components/Icon/PortfolioIcon/PortfolioIcon.d.ts

@@ -3,4 +3,7 @@ import type { EntityIconProps } from '../EntityIcon';
 export type PortfolioIconProps = {
     portfolioId: string;
 } & Omit<EntityIconProps, 'data' | 'id' | 'alpha'>;
-export declare const PortfolioIcon: ({ portfolioId, ...props }: PortfolioIconProps) => React.JSX.Element;
+export declare const PortfolioIcon: {
+    ({ portfolioId, ...props }: PortfolioIconProps): React.JSX.Element;
+    displayName: string;
+};

package/build/cjs/components/Icon/PortfolioIcon/PortfolioIcon.js

@@ -23,4 +23,5 @@ var PortfolioIcon = exports.PortfolioIcon = function PortfolioIcon(_ref) {
     withBackground: false
   }, props));
 };
+PortfolioIcon.displayName = 'PortfolioIcon';
 // #sourceMappingURL=PortfolioIcon.js.map

package/build/cjs/components/Icon/PortfolioIcon/PortfolioIcon.js.map

@@ -1 +1 @@
-{"version":3,"names":["_react","_interopRequireDefault","require","_EntityIcon","_portfolio","_jsxRuntime","e","__esModule","default","PortfolioIcon","exports","_ref","portfolioId","props","_objectWithoutProperties","_excluded","_jsx","EntityIcon","_objectSpread","data","portfolioIcon","id","type","alpha","withBackground"],"sources":["PortfolioIcon.tsx"],"sourcesContent":["import React from 'react';\n\nimport type {EntityIconProps} from '../EntityIcon';\nimport {EntityIcon} from '../EntityIcon';\n\nimport portfolioIcon from '../../../../assets/icons/portfolio.svg';\n\nexport type PortfolioIconProps = {portfolioId: string} & Omit<\n    EntityIconProps,\n    'data' | 'id' | 'alpha'\n>;\n\nexport const PortfolioIcon = ({portfolioId, ...props}: PortfolioIconProps) => (\n    <EntityIcon\n        data={portfolioIcon}\n        id={portfolioId}\n        type=\"portfolio\"\n        alpha={0.5}\n        withBackground={false}\n        {...props}\n    />\n);\n"],"mappings":";;;;;;;;AAAA,IAAAA,MAAA,GAAAC,sBAAA,CAAAC,OAAA;AAGA,IAAAC,WAAA,GAAAD,OAAA;AAEA,IAAAE,UAAA,GAAAH,sBAAA,CAAAC,OAAA;AAAmE,IAAAG,WAAA,GAAAH,OAAA;AAAA,SAAAD,uBAAAK,CAAA,WAAAA,CAAA,IAAAA,CAAA,CAAAC,UAAA,GAAAD,CAAA,KAAAE,OAAA,EAAAF,CAAA;;AAO5D,IAAMG,aAAa,GAAAC,OAAA,CAAAD,aAAA,GAAG,SAAhBA,aAAaA,CAAAE,IAAA;EAAA,IAAKC,WAAW,GAAAD,IAAA,CAAXC,WAAW;IAAKC,KAAK,OAAAC,iCAAA,EAAAH,IAAA,EAAAI,SAAA;EAAA,oBAChD,IAAAC,eAAA,EAACC,sBAAU,MAAAC,sBAAA;IACPC,IAAI,EAAEC,kBAAc;IACpBC,EAAE,EAAET,WAAY;IAChBU,IAAI,EAAC,WAAW;IAChBC,KAAK,EAAE,GAAI;IACXC,cAAc,EAAE;EAAM,GAClBX,KAAK,CACZ,CAAC;AAAA,CACL","ignoreList":[]}
+{"version":3,"names":["_react","_interopRequireDefault","require","_EntityIcon","_portfolio","_jsxRuntime","e","__esModule","default","PortfolioIcon","exports","_ref","portfolioId","props","_objectWithoutProperties","_excluded","_jsx","EntityIcon","_objectSpread","data","portfolioIcon","id","type","alpha","withBackground","displayName"],"sources":["PortfolioIcon.tsx"],"sourcesContent":["import React from 'react';\n\nimport type {EntityIconProps} from '../EntityIcon';\nimport {EntityIcon} from '../EntityIcon';\n\nimport portfolioIcon from '../../../../assets/icons/portfolio.svg';\n\nexport type PortfolioIconProps = {portfolioId: string} & Omit<\n    EntityIconProps,\n    'data' | 'id' | 'alpha'\n>;\n\nexport const PortfolioIcon = ({portfolioId, ...props}: PortfolioIconProps) => (\n    <EntityIcon\n        data={portfolioIcon}\n        id={portfolioId}\n        type=\"portfolio\"\n        alpha={0.5}\n        withBackground={false}\n        {...props}\n    />\n);\n\nPortfolioIcon.displayName = 'PortfolioIcon';\n"],"mappings":";;;;;;;;AAAA,IAAAA,MAAA,GAAAC,sBAAA,CAAAC,OAAA;AAGA,IAAAC,WAAA,GAAAD,OAAA;AAEA,IAAAE,UAAA,GAAAH,sBAAA,CAAAC,OAAA;AAAmE,IAAAG,WAAA,GAAAH,OAAA;AAAA,SAAAD,uBAAAK,CAAA,WAAAA,CAAA,IAAAA,CAAA,CAAAC,UAAA,GAAAD,CAAA,KAAAE,OAAA,EAAAF,CAAA;;AAO5D,IAAMG,aAAa,GAAAC,OAAA,CAAAD,aAAA,GAAG,SAAhBA,aAAaA,CAAAE,IAAA;EAAA,IAAKC,WAAW,GAAAD,IAAA,CAAXC,WAAW;IAAKC,KAAK,OAAAC,iCAAA,EAAAH,IAAA,EAAAI,SAAA;EAAA,oBAChD,IAAAC,eAAA,EAACC,sBAAU,MAAAC,sBAAA;IACPC,IAAI,EAAEC,kBAAc;IACpBC,EAAE,EAAET,WAAY;IAChBU,IAAI,EAAC,WAAW;IAChBC,KAAK,EAAE,GAAI;IACXC,cAAc,EAAE;EAAM,GAClBX,KAAK,CACZ,CAAC;AAAA,CACL;AAEDJ,aAAa,CAACgB,WAAW,GAAG,eAAe","ignoreList":[]}

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