@hilum/ui 3.5.1 → 3.5.2

package/llms.txt

@@ -5,10 +5,10 @@
 ## Key Facts
 
 - Package name: `@hilum/ui`
-- Package version: 3.4.0
-- Component modules: 99
+- Package version: 3.5.2
+- Component modules: 100
 - Atom components: 70
-- Molecule components: 29
+- Molecule components: 30
 - Docs site: https://ui.hilum.dev
 - GitHub repository: https://github.com/hilum-labs/hilum-ui
 - Machine-readable docs index: https://ui.hilum.dev/catalog.json
@@ -153,6 +153,7 @@ Primary exports:
 - Spinner (/atoms/spinner/) — Animated loading indicator for async operations.
 - Stacked List (/molecules/stacked-list/) — Vertically stacked rows with consistent padding and optional hover behavior. Composes: Badge · Avatar.
 - Stat Card (/molecules/stat-card/) — Metric display card with label, value, optional trend, and optional icon. Composes: Card · Badge · Icon.
+- Usage Bar (/molecules/usage-bar/) — Compact quota, readiness, and capacity meter with inline and stacked layouts. Composes: Progress.
 - Status Badge (/atoms/status-badge/) — Semantic badge that maps status values to labels, variants, icons, and dots.
 - Steps (/atoms/steps/) — Multi-step progress indicator with circles, bullets, and progress variants.
 - Switch (/atoms/switch/) — Toggle between two states, on and off.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hilum/ui",
-  "version": "3.5.1",
+  "version": "3.5.2",
   "private": false,
   "description": "Hilum UI — design system primitives (Button, Input, Dialog, Combobox, …) + tokens + fonts + icons",
   "license": "MIT",

package/src/components/usage-bar.tsx

@@ -0,0 +1,105 @@
+import * as React from "react";
+import { cn } from "../lib/utils";
+
+type UsageBarTone = "primary" | "warning" | "destructive" | "success" | "muted";
+type UsageBarLayout = "stacked" | "inline";
+
+interface UsageBarProps extends React.HTMLAttributes<HTMLDivElement> {
+  label?: React.ReactNode;
+  value?: number;
+  max?: number;
+  percent?: number;
+  valueLabel?: React.ReactNode;
+  showPercent?: boolean;
+  layout?: UsageBarLayout;
+  tone?: UsageBarTone;
+  barClassName?: string;
+  indicatorClassName?: string;
+}
+
+const toneClassName: Record<UsageBarTone, string> = {
+  primary: "bg-primary",
+  warning: "bg-warning",
+  destructive: "bg-destructive",
+  success: "bg-success",
+  muted: "bg-muted-foreground",
+};
+
+function clampPercent(value: number) {
+  if (!Number.isFinite(value)) return 0;
+  return Math.min(Math.max(value, 0), 100);
+}
+
+function inferTone(percent: number): UsageBarTone {
+  if (percent >= 90) return "destructive";
+  if (percent >= 75) return "warning";
+  return "primary";
+}
+
+function formatUsageValue(value: number | undefined, max: number | undefined) {
+  if (typeof value !== "number" || typeof max !== "number") return undefined;
+  return `${value.toLocaleString()} / ${max.toLocaleString()}`;
+}
+
+function UsageBar({
+  label,
+  value,
+  max,
+  percent,
+  valueLabel,
+  showPercent,
+  layout = "stacked",
+  tone,
+  className,
+  barClassName,
+  indicatorClassName,
+  ...props
+}: UsageBarProps) {
+  const resolvedPercent = clampPercent(
+    typeof percent === "number" ? percent : max && max > 0 && typeof value === "number" ? (value / max) * 100 : 0,
+  );
+  const resolvedTone = tone ?? inferTone(resolvedPercent);
+  const resolvedValueLabel = valueLabel ?? formatUsageValue(value, max);
+  const percentLabel = `${Math.round(resolvedPercent)}%`;
+
+  const bar = (
+    <div
+      className={cn("h-2 w-full overflow-hidden rounded-full bg-muted", layout === "inline" && "w-28", barClassName)}
+      aria-hidden="true"
+    >
+      <div
+        className={cn("h-full rounded-full transition-all", toneClassName[resolvedTone], indicatorClassName)}
+        style={{ width: `${resolvedPercent}%` }}
+      />
+    </div>
+  );
+
+  if (layout === "inline") {
+    return (
+      <div className={cn("flex min-w-0 items-center gap-2", className)} {...props}>
+        {label ? <span className="caption shrink-0 text-muted-foreground">{label}</span> : null}
+        {bar}
+        {showPercent !== false ? (
+          <span className="w-10 shrink-0 text-xs tabular-nums text-muted-foreground">{percentLabel}</span>
+        ) : null}
+      </div>
+    );
+  }
+
+  return (
+    <div className={cn("space-y-1.5", className)} {...props}>
+      {(label || resolvedValueLabel || showPercent) && (
+        <div className="flex min-w-0 items-center justify-between gap-3 text-sm">
+          {label ? <span className="min-w-0 truncate text-muted-foreground">{label}</span> : <span />}
+          <span className="shrink-0 font-medium tabular-nums text-foreground">
+            {resolvedValueLabel ?? (showPercent ? percentLabel : null)}
+          </span>
+        </div>
+      )}
+      {bar}
+    </div>
+  );
+}
+
+export { UsageBar };
+export type { UsageBarProps, UsageBarLayout, UsageBarTone };

package/src/index.ts

@@ -108,3 +108,4 @@ export * from "./components/toggle-group";
 export * from "./components/toggle";
 export * from "./components/tooltip";
 export * from "./components/url-redirect-prompt";
+export * from "./components/usage-bar";