@danxbot/ui 2.7.1 → 2.8.0

package/dist/types/components/Progress.d.ts

@@ -1,4 +1,4 @@
-import type { ReactNode, Ref } from "react";
+import { type ReactNode, type Ref } from "react";
 import { type VariantProps } from "tailwind-variants";
 declare const bar: import("tailwind-variants").TVReturnType<{
     size: {
@@ -151,8 +151,28 @@ declare const ring: import("tailwind-variants").TVReturnType<{
         lg: "size-24";
     };
 }, undefined>>;
-export interface ProgressRingProps extends VariantProps<typeof ring> {
-    value: number | null;
+/** The tones a bar, meter or ring arc can be drawn in. */
+export type ProgressTone = NonNullable<VariantProps<typeof bar>["tone"]>;
+/** One arc of a segmented ring: how much, in what tone, called what. */
+export interface ProgressRingSegment {
+    /**
+     * How much of `total` this arc covers, in the caller's own units — tokens,
+     * megabytes, jobs. Never a percentage of its own accord; the denominator is
+     * `total` and nothing else.
+     */
+    value: number;
+    tone: ProgressTone;
+    /**
+     * What this arc IS, in words.
+     *
+     * Not decorative and not optional: it is read out as part of the ring's
+     * description, and it is the only thing a legend beside the ring has to name
+     * a colour by. A segmented ring whose arcs had no names would encode its
+     * entire breakdown in hue alone.
+     */
+    label: string;
+}
+interface ProgressRingBase extends VariantProps<typeof ring> {
     /**
      * REQUIRED, and a plain string.
      *
@@ -163,16 +183,108 @@ export interface ProgressRingProps extends VariantProps<typeof ring> {
      * of this component existing.
      */
     label: string;
-    tone?: VariantProps<typeof bar>["tone"];
+    /**
+     * Draw the number in the middle. On by default, which is the behaviour this
+     * component has always had.
+     *
+     * Worth turning off on a `sm` ring used as an affordance rather than a
+     * readout — two digits inside a 40px circle is a number nobody reads and a
+     * ring nobody can see past.
+     */
+    showValue?: boolean;
     className?: string;
 }
+/** A ring showing ONE number. `null` is "working, length unknown". */
+export interface ProgressRingValueProps extends ProgressRingBase {
+    value: number | null;
+    tone?: ProgressTone;
+    segments?: never;
+    total?: never;
+    remainderLabel?: never;
+}
+/**
+ * A ring showing a BREAKDOWN: contiguous arcs around one circle.
+ *
+ * The two shapes are a union rather than two optional props, so passing both
+ * `value` and `segments` does not type-check. There is no precedence rule to
+ * learn and no silent winner.
+ */
+export interface ProgressRingSegmentsProps extends ProgressRingBase {
+    /** Drawn in order, starting at twelve o'clock and running clockwise. */
+    segments: ProgressRingSegment[];
+    /**
+     * The whole the segments are parts OF, in the same units as their values.
+     *
+     * REQUIRED, with no default. A default of 100 would read as "the values are
+     * percentages" and quietly turn a ring of token counts into a ring that
+     * overflows on its first render — and the denominator is the one fact that
+     * makes a remainder arc mean anything.
+     *
+     * SEGMENTS SUMMING TO MORE THAN THIS ARE **CLAMPED, NOT NORMALISED** — see
+     * the note above `layoutRingSegments`.
+     */
+    total: number;
+    /**
+     * What the unfilled part of the ring IS, for the description: "Remaining",
+     * "Free", "Unallocated".
+     *
+     * The arc itself needs no drawing — it is the track showing through — but it
+     * still needs a name, because "72% used" and "28% free" are the same fact
+     * and readers act on different halves of it.
+     */
+    remainderLabel?: string;
+    value?: never;
+    tone?: never;
+}
+export type ProgressRingProps = ProgressRingValueProps | ProgressRingSegmentsProps;
+/** One arc, resolved to the two fractions an SVG dash actually needs. */
+export interface ProgressRingArc {
+    label: string;
+    tone: ProgressTone;
+    /** The segment's own magnitude, in caller units, before any clamping. */
+    value: number;
+    /** Where the arc begins, as a fraction of the circumference. */
+    start: number;
+    /** How far it is drawn for, as a fraction, with its gap already taken off. */
+    length: number;
+}
+export interface ProgressRingLayout {
+    arcs: ProgressRingArc[];
+    /** Every segment added up, in caller units. NOT clamped — this is the fact. */
+    used: number;
+    /** How far `used` overshoots `total`. Zero when the segments fit. */
+    overflow: number;
+}
+export declare function layoutRingSegments(segments: ProgressRingSegment[], total: number): ProgressRingLayout;
 /**
  * Circular progress, for when the number belongs INSIDE the indicator —
  * a tile, a card corner, a stat.
  *
+ * Two shapes, chosen by which prop is passed:
+ *
+ * ```tsx
+ * <ProgressRing value={62} label="Context used" />
+ * <ProgressRing
+ *   label="Context used"
+ *   total={200_000}
+ *   segments={[
+ *     { label: "System prompt", value: 12_000, tone: "brand" },
+ *     { label: "Conversation", value: 84_000, tone: "accent" },
+ *   ]}
+ *   remainderLabel="Free"
+ * />
+ * ```
+ *
  * Uses `pathLength="1"` so the dash numbers are fractions rather than
  * circumference maths: the same two values work at any radius, and it dodges
  * the Safari bug where a zoomed SVG rescales absolute dash lengths.
+ *
+ * THE ROLE IS `progressbar` IN BOTH SHAPES, and stays that way even though a
+ * breakdown of a budget is arguably a gauge. The role is a property of the
+ * component a caller reached for, not of the data they handed it — a component
+ * that announced itself as a different thing depending on the shape of its
+ * props would be two components sharing one name. A caller whose fact is a
+ * gauge has `Meter`.
  */
-export declare function ProgressRing({ value, label, size, tone, className, }: ProgressRingProps): import("react").JSX.Element;
+export declare function ProgressRing(props: ProgressRingProps): import("react").JSX.Element;
 export {};

package/dist/types/index.d.ts

@@ -48,7 +48,7 @@ export { Toggle, ToggleGroup, Toolbar, ToolbarSeparator, type ToggleProps, type
 export { Separator, ScrollArea, Collapsible, EmptyState, Timeline, type SeparatorProps, type ScrollAreaProps, type CollapsibleProps, type EmptyStateProps, type TimelineProps, type TimelineItem, } from "./components/Surface";
 export { PanelGroup, Panel, PanelResizer, type PanelGroupProps, type PanelProps, type PanelResizerProps, type PanelDirection, type PanelNarrowMode, } from "./components/Panel";
 export { Avatar, AvatarGroup, type AvatarProps, type AvatarGroupProps, type AvatarStatus, } from "./components/Avatar";
-export { Progress, Meter, ProgressRing, type ProgressProps, type MeterProps, type ProgressRingProps, } from "./components/Progress";
+export { Progress, Meter, ProgressRing, type ProgressProps, type MeterProps, type ProgressRingProps, type ProgressRingValueProps, type ProgressRingSegmentsProps, type ProgressRingSegment, type ProgressTone, } from "./components/Progress";
 export { Stat, Sparkline, type StatProps, type SparklineProps, type StatTrend, type StatSentiment, } from "./components/Stat";
 export { DataTable, TableEmptyState, CellStack, type DataTableProps, type TableDensity, } from "./components/Table";
 export { CodeEditor, CodeEditorToolbar, CodeEditorCaption, CodeEditorCopyButton, CodeEditorWrapToggle, CodeEditorViewSwitch, type CodeEditorProps, type CodeEditorToolbarProps, type CodeEditorView, } from "./components/CodeEditor";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@danxbot/ui",
-  "version": "2.7.1",
+  "version": "2.8.0",
   "type": "module",
   "description": "Danxbot — a domain-agnostic React design system with motion as a first-class primitive.",
   "license": "MIT",