@trackunit/react-components 1.17.21 → 1.17.23

package/src/components/Tag/Tag.d.ts

@@ -46,14 +46,21 @@ export interface TagProps extends CommonProps {
     onMouseEnter?: MouseEventHandler<HTMLDivElement>;
 }
 /**
- * The Tag component is used for labeling or categorizing items in the UI.
- * It's commonly used to indicate the status of an asset, mark a feature as Beta,
- * or display selected options in multi-select inputs.
+ * Tag is used for labeling or categorizing items in the UI. Common use cases include indicating asset status,
+ * marking features as Beta, or displaying selected options in multi-select inputs.
+ * Tags support dismissal (close button), icons, and multiple color variants.
  *
- * How to choose between Tag, Badge and Highlight?
+ * ### When to use
+ * Use Tag to label statuses, categories, or user selections. It supports colors for intent (success, warning, danger) and activity states.
+ *
+ * ### When not to use
+ * Do not use Tag for numeric counts — use `Badge`.
+ * Do not use Tag for highlighting data values — use `Highlight`.
+ *
+ * How to choose between Tag, `Badge` and `Highlight`?
  * - Use a Tag for labeling statuses, categories, or selections.
- * - Use a [Badge](https://design.iris.trackunit.com/?path=/docs/react-components-badge--docs) to indicate notifications or counts of applied elements, such as filters.
- * - Use a [Highlight](https://design.iris.trackunit.com/?path=/docs/react-components-highlight--docs) to draw attention to values in plain text that require special attention or have crossed a threshold.
+ * - Use a `Badge` to indicate notifications or counts of applied elements, such as filters.
+ * - Use a `Highlight` to draw attention to values in plain text that require special attention or have crossed a threshold.
  *
  * @example Status tags with different colors
  * ```tsx

package/src/components/Text/Text.d.ts

@@ -63,12 +63,37 @@ export interface TextProps extends CommonProps {
     title?: string;
 }
 /**
- *  The Text component is used to apply Trackunit default typography styles to text.
+ * Text applies Trackunit default typography styles to body text. It renders as a `<p>`, `<span>`, or `<div>` element
+ * and supports size, weight, alignment, and style variants (subtle, inverted, uppercase, etc.).
  *
- *  ### When to use
+ * ### When to use
+ * Use Text for body content, descriptions, labels, and any non-heading text. It ensures consistent typography across the application.
  *
- *  Use Text when you want to show a text section, use Heading if you want to show a heading.
+ * ### When not to use
+ * Do not use Text for page or section headings — use `Heading` instead.
  *
+ * @example Text with different sizes and weights
+ * ```tsx
+ * import { Text } from "@trackunit/react-components";
+ *
+ * const TextExamples = () => (
+ *   <div>
+ *     <Text size="large" weight="bold">Large bold text</Text>
+ *     <Text size="medium">Default body text</Text>
+ *     <Text size="small" subtle>Small subtle caption</Text>
+ *   </div>
+ * );
+ * ```
+ * @example Inline text using span
+ * ```tsx
+ * import { Text } from "@trackunit/react-components";
+ *
+ * const InlineExample = () => (
+ *   <Text>
+ *     Asset status: <Text type="span" weight="bold">Active</Text>
+ *   </Text>
+ * );
+ * ```
  * @param {TextProps} props - The props for the Text component
  * @returns {ReactElement} Text component
  */

package/src/components/ToggleGroup/ToggleGroup.d.ts

@@ -58,8 +58,37 @@ export type ToggleGroupProps<TSelectedId extends string = string> = CommonProps
     setSelected: Dispatch<SetStateAction<TSelectedId>>;
 };
 /**
- *  Toggle Group allows users to toggle between two or more closely related options, and immediately apply that selection.
+ * ToggleGroup allows users to toggle between two or more closely related options and immediately apply the selection.
+ * It renders a segmented control with a sliding background indicator. Supports text-only, icon-only, and text+icon modes.
  *
+ * ### When to use
+ * Use ToggleGroup when the user needs to switch between 2-5 mutually exclusive options that take effect immediately (e.g., view modes, map/list toggle, time ranges).
+ *
+ * ### When not to use
+ * Do not use ToggleGroup for navigation — use `Tabs`.
+ * Do not use ToggleGroup for form selections with many options — use a Select or RadioGroup.
+ *
+ * @example ToggleGroup for view mode switching
+ * ```tsx
+ * import { ToggleGroup } from "@trackunit/react-components";
+ * import { useState } from "react";
+ *
+ * const ViewToggle = () => {
+ *   const [selected, setSelected] = useState("list");
+ *
+ *   return (
+ *     <ToggleGroup
+ *       selected={selected}
+ *       setSelected={setSelected}
+ *       onChange={(id) => console.log("Selected:", id)}
+ *       list={[
+ *         { id: "list", title: "List", iconName: "Bars3" },
+ *         { id: "map", title: "Map", iconName: "MapPin" },
+ *       ]}
+ *     />
+ *   );
+ * };
+ * ```
  * @param {ToggleGroupProps} props - The props for the ToggleGroup component
  * @returns {ReactElement} ToggleGroup component
  */

package/src/components/ValueBar/SegmentedValueBar.d.ts

@@ -0,0 +1,40 @@
+import { ReactElement } from "react";
+import { CommonProps } from "../../common/CommonProps";
+import type { SegmentedValueBarSize, ValueBarSegment } from "./SegmentedValueBarTypes";
+export interface SegmentedValueBarProps extends CommonProps {
+    /**
+     * Array of segments to display. Each segment has a numeric value and a color and optionally a label.
+     * Segments render in the order they are provided; the component does not sort or reorder them.
+     */
+    readonly segments: Array<ValueBarSegment>;
+    /**
+     * The total value that segments are measured against.
+     */
+    readonly total: number;
+    /**
+     * Size of the bar. Determines height and whether value text can be displayed.
+     */
+    readonly size?: SegmentedValueBarSize;
+    /**
+     * Show the sum of segment values with unit (if provided) on the bar in large version or after the bar in the small version.
+     * Ignored when size is "extraSmall".
+     */
+    readonly showValue?: boolean;
+    /**
+     * Unit appended to the displayed value, e.g. "%", "h", "°C".
+     */
+    readonly unit?: string;
+    /**
+     * Custom color for the displayed value text.
+     */
+    readonly valueColor?: string;
+    /**
+     * Show a tooltip on hover with the individual segment value (and unit if provided). If a segment has a label, it is shown alongside the value.
+     */
+    readonly showTooltip?: boolean;
+}
+/**
+ * SegmentedValueBar displays multiple colored segments on a bar to visualize values relative to a total.
+ * Supports optional tooltips per segment, showing value and optionally a label.
+ */
+export declare const SegmentedValueBar: ({ segments, total, size, showValue, unit, valueColor, showTooltip, className, "data-testid": dataTestId, }: SegmentedValueBarProps) => ReactElement;

package/src/components/ValueBar/SegmentedValueBar.variants.d.ts

@@ -0,0 +1,3 @@
+export declare const cvaSegmentedValueBar: (props?: ({
+    size?: "extraSmall" | "small" | "large" | null | undefined;
+} & import("class-variance-authority/dist/types").ClassProp) | undefined) => string;

package/src/components/ValueBar/SegmentedValueBarHelper.d.ts

@@ -0,0 +1,16 @@
+import type { SegmentedValueBarSize, ValueBarSegment } from "./SegmentedValueBarTypes";
+type ComputedSegment = {
+    readonly width: number;
+    readonly value: number;
+    readonly color: string;
+    readonly label?: string;
+};
+/** Formats a numeric value to one decimal place with an optional unit suffix. */
+export declare const formatValue: (value: number, unit?: string) => string;
+/** Returns the sum of all positive segment values. */
+export declare const computeSum: (segments: Array<ValueBarSegment>) => number;
+/** Computes percentage widths for each positive segment, scaling proportionally when the sum exceeds total. */
+export declare const computeSegments: (segments: Array<ValueBarSegment>, total: number) => Array<ComputedSegment>;
+/** Determines the text variant size for value overlay placement on the bar. */
+export declare const getValueTextVariant: (size: SegmentedValueBarSize, sum: number, segments: Array<ValueBarSegment>, total: number) => "small" | "large";
+export {};

package/src/components/ValueBar/SegmentedValueBarTypes.d.ts

@@ -0,0 +1,6 @@
+export type ValueBarSegment = {
+    readonly value: number;
+    readonly color: string;
+    readonly label?: string;
+};
+export type SegmentedValueBarSize = "small" | "large" | "extraSmall";

package/src/components/ValueBar/ValueBar.d.ts

@@ -45,8 +45,44 @@ export interface ValueBarProps extends CommonProps, Refable<HTMLSpanElement> {
     zeroScoreAllowed?: boolean;
 }
 /**
- * ValueBar component is used to display value on a colorful bar within provided range.
- 
+ * ValueBar displays a numeric value as a colored progress bar within a defined range.
+ * The bar color changes based on the score (value relative to min/max) using either default or custom level colors.
+ * It can optionally display the numeric value and unit alongside the bar.
+ *
+ * ### When to use
+ * Use ValueBar to visualize a metric relative to a range (e.g., battery level, fuel percentage, utilization rate, temperature).
+ *
+ * ### When not to use
+ * Do not use ValueBar for progress through a multi-step process. Use a stepper or progress indicator instead.
+ *
+ * @example Basic value bar with percentage
+ * ```tsx
+ * import { ValueBar } from "@trackunit/react-components";
+ *
+ * const BatteryLevel = () => (
+ *   <ValueBar value={72} min={0} max={100} unit="%" showValue />
+ * );
+ * ```
+ * @example Value bar with custom level colors
+ * ```tsx
+ * import { ValueBar } from "@trackunit/react-components";
+ *
+ * const TemperatureBar = () => (
+ *   <ValueBar
+ *     value={85}
+ *     min={0}
+ *     max={120}
+ *     unit="°C"
+ *     showValue
+ *     size="large"
+ *     levelColors={[
+ *       { min: 0, max: 0.5, color: "#22c55e" },
+ *       { min: 0.5, max: 0.75, color: "#f59e0b" },
+ *       { min: 0.75, max: 1, color: "#ef4444" },
+ *     ]}
+ *   />
+ * );
+ * ```
  * @param {ValueBarProps} props - The props for the ValueBar component
  * @returns {ReactElement} ValueBar component
  */

package/src/components/ZStack/ZStack.d.ts

@@ -5,10 +5,29 @@ export type ZStackProps = CommonProps & Refable<HTMLDivElement> & {
     children: ReactNode;
 };
 /**
- * ZStack is a component that stacks its children on the z-axis.
- * Is a good alternative to "position: absolute" that avoids some of the unfortunate side effects of absolute positioning.
+ * ZStack stacks its children on the z-axis (overlaying them on top of each other).
+ * It is a CSS grid-based alternative to `position: absolute` that avoids side effects like elements being removed from the document flow.
  *
- * @param { ZStackProps} props - The props for the  ZStack component
- * @returns {Element}  ZStack component
+ * ### When to use
+ * Use ZStack when you need to overlay elements on top of each other (e.g., an image with a badge overlay, or a scroll container with fade indicators).
+ *
+ * ### When not to use
+ * Do not use ZStack for standard stacking/layout — use flex or grid containers instead.
+ *
+ * @example Overlaying a badge on a thumbnail
+ * ```tsx
+ * import { ZStack, Badge, Icon } from "@trackunit/react-components";
+ *
+ * const ThumbnailWithBadge = () => (
+ *   <ZStack>
+ *     <Icon name="Truck" size="large" />
+ *     <div className="self-start justify-self-end">
+ *       <Badge count={3} color="danger" />
+ *     </div>
+ *   </ZStack>
+ * );
+ * ```
+ * @param {ZStackProps} props - The props for the ZStack component
+ * @returns {ReactElement} ZStack component
  */
 export declare const ZStack: ({ children, className, "data-testid": dataTestId, ref }: ZStackProps) => ReactElement;

package/src/components/buttons/Button/Button.d.ts

@@ -51,7 +51,7 @@ export interface ButtonProps extends MappedOmit<ButtonCommonProps, "size"> {
  * Use buttons to communicate actions users can take and to allow users to interact with the page. Each page should have one primary button, and any remaining calls to action should be represented as lower emphasis buttons.
  *
  * ### When not to use
- * Do not use buttons as navigational elements. Instead, use [Links](?path=/docs/components-link--docs) when the desired action is to take the user to a new page.
+ * Do not use buttons as navigational elements. Instead, use `Links` when the desired action is to take the user to a new page.
  *
  * @example Basic button with click handler
  * ```tsx

package/src/components/buttons/StarButton/StarButton.d.ts

@@ -1,12 +1,35 @@
 import { MouseEventHandler, ReactElement } from "react";
 import { Refable } from "../../../common/Refable";
 interface StarButtonProps extends Refable<HTMLDivElement> {
+    /**
+     * Whether the item is currently starred/favorited. Controls the icon color (primary when starred, neutral when not).
+     */
     starred: boolean;
+    /**
+     * Click handler triggered when the star icon is clicked.
+     */
     onClick: MouseEventHandler<HTMLDivElement>;
 }
 /**
- * The StarButton component is used for favorite actions or similar.
+ * StarButton renders a clickable star icon for toggling favorite/starred state.
+ * The star appears in the primary color when starred and neutral when unstarred.
  *
+ * ### When to use
+ * Use StarButton for favorite or bookmark actions on list items, cards, or tables.
+ *
+ * ### When not to use
+ * Do not use StarButton for primary actions — use `Button` or `IconButton`.
+ *
+ * @example Star button for favoriting an asset
+ * ```tsx
+ * import { StarButton } from "@trackunit/react-components";
+ * import { useState } from "react";
+ *
+ * const FavoriteToggle = () => {
+ *   const [starred, setStarred] = useState(false);
+ *   return <StarButton starred={starred} onClick={() => setStarred(s => !s)} />;
+ * };
+ * ```
  * @param {StarButtonProps} props - The props for the StarButton component
  * @returns {ReactElement} StarButton component
  */

package/src/index.d.ts

@@ -97,6 +97,8 @@ export * from "./components/Text/Text";
 export * from "./components/ToggleGroup/ToggleGroup";
 export * from "./components/ToggleGroup/ToggleGroup.variants";
 export * from "./components/Tooltip/Tooltip";
+export * from "./components/ValueBar/SegmentedValueBar";
+export * from "./components/ValueBar/SegmentedValueBarTypes";
 export * from "./components/ValueBar/ValueBar";
 export { getValueBarColorByValue } from "./components/ValueBar/ValueBarHelper";
 export * from "./components/ValueBar/ValueBarTypes";