@weavix/tracker-components 0.1.0 → 0.1.1

package/build/cjs/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/cjs/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/cjs/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/build/esm/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>
+));
+```