@brijbyte/agentic-ui 0.0.3 → 0.0.4

package/src/dialog/dialog.tsx

@@ -3,12 +3,17 @@ import { Dialog as BaseDialog } from "@base-ui/react/dialog";
 import styles from "./dialog.module.css";
 
 export interface DialogProps {
+  /** Controlled open state. */
   open?: boolean;
+  /** Whether the dialog is initially open (uncontrolled). */
   defaultOpen?: boolean;
-  /** `eventDetails` is the base-ui event details object. */
+  /** Called when the dialog opens or closes. `eventDetails` is the base-ui event details object. */
   onOpenChange?: (open: boolean, eventDetails: unknown) => void;
+  /** Element that opens the dialog when clicked. */
   trigger?: ReactElement;
+  /** Heading rendered at the top of the dialog. */
   title?: ReactNode;
+  /** Supplementary text below the title. */
   description?: ReactNode;
   children?: ReactNode;
   /** Buttons aligned to the right (cancel, confirm). */
@@ -20,6 +25,7 @@ export interface DialogProps {
    */
   footerStart?: ReactNode;
   className?: string;
+  /** Whether the dialog can be closed by clicking the backdrop or pressing Escape. @default true */
   dismissible?: boolean;
 }
 
@@ -31,6 +37,12 @@ function XIcon() {
   );
 }
 
+/**
+ * Modal overlay dialog with title, description, body, and footer slots.
+ * Wraps `@base-ui/react` Dialog with a pre-styled backdrop, popup, and
+ * close button. Use `footerStart` for a macOS-style left-aligned
+ * destructive action.
+ */
 export function Dialog({
   trigger,
   title,

package/src/drawer/drawer.tsx

@@ -9,17 +9,23 @@ export interface DrawerProps {
   trigger?: ReactElement;
   /** Which edge the drawer slides in from. @default "right" */
   side?: DrawerSide;
+  /** Heading rendered at the top of the drawer. */
   title?: ReactNode;
+  /** Supplementary text below the title. */
   description?: ReactNode;
   children?: ReactNode;
+  /** Content rendered at the bottom of the drawer. */
   footer?: ReactNode;
   /** Show a drag handle bar (useful for bottom/top drawers). @default true for bottom/top */
   handleBar?: boolean;
   /** Show a close button in the top-right corner. @default true */
   dismissible?: boolean;
 
+  /** Controlled open state. */
   open?: boolean;
+  /** Whether the drawer is initially open (uncontrolled). */
   defaultOpen?: boolean;
+  /** Called when the drawer opens or closes. */
   onOpenChange?: (open: boolean) => void;
 }
 
@@ -47,6 +53,11 @@ const POPUP_CLASS: Record<DrawerSide, string> = {
   top: styles["popup-top"] as string,
 };
 
+/**
+ * A panel that slides in from any edge of the screen with swipe-to-dismiss
+ * gestures. Supports left, right, top, and bottom orientations with an
+ * optional drag handle bar.
+ */
 export function Drawer({
   trigger,
   side = "right",

package/src/index.ts

@@ -14,8 +14,12 @@ export * from "./dialog";
 export * from "./drawer";
 export * from "./input";
 export * from "./menu";
+export * from "./meter";
 export * from "./number-field";
+export * from "./popover";
 export * from "./progress";
+export * from "./radio";
+export * from "./radio-group";
 export * from "./select";
 export * from "./separator";
 export * from "./slider";

package/src/input/input.tsx

@@ -9,11 +9,19 @@ export type InputSize = "sm" | "md" | "lg";
 export interface InputProps extends Omit<ComponentPropsWithoutRef<"input">, "size"> {
   /** Visual size. Maps to height + font-size design tokens. Default: `"md"`. */
   size?: InputSize;
+  /** Icon or element rendered before the input text. */
   leftAdornment?: ReactNode;
+  /** Icon or element rendered after the input text. */
   rightAdornment?: ReactNode;
+  /** Applies error styling and sets `aria-invalid`. */
   invalid?: boolean;
 }
 
+/**
+ * Text input with optional left and right adornment slots. Extends the
+ * native `<input>` API — replaces the numeric `size` attribute with a
+ * token-based size prop.
+ */
 export const Input = forwardRef<HTMLInputElement, InputProps>(function Input(
   { size = "md", leftAdornment, rightAdornment, invalid, className, ...props },
   ref,

package/src/menu/menu.module.css

@@ -14,8 +14,8 @@
     font-family: var(--font-mono);
     font-size: var(--font-size-sm);
     min-width: 200px;
-    transform-origin: var(--transform-origin);
     outline: none;
+    transition: opacity 150ms var(--easing-ease-out);
   }
   @supports (backdrop-filter: blur(12px)) {
     .popup {
@@ -25,17 +25,10 @@
   }
   .popup[data-starting-style] {
     opacity: 0;
-    transform: scale(0.95);
-    transition:
-      opacity 150ms var(--easing-ease-out),
-      transform 150ms var(--easing-ease-out);
   }
   .popup[data-ending-style] {
     opacity: 0;
-    transform: scale(0.98);
-    transition:
-      opacity 75ms var(--easing-ease-in),
-      transform 75ms var(--easing-ease-in);
+    transition: opacity 75ms var(--easing-ease-in);
   }
   /* ─── Item ───────────────────────────────────────────────────────── */
   .item {
@@ -136,7 +129,7 @@
   .arrow-fill {
     fill: var(--color-overlay);
   }
-  .arrow-stroke {
+  .arrow-seam {
     fill: var(--color-line);
   }
 }

package/src/menu/menu.tsx

@@ -1,6 +1,7 @@
 import type { ReactNode, ReactElement } from "react";
 import { Menu as BaseMenu } from "@base-ui/react/menu";
 import styles from "./menu.module.css";
+import { PopupArrow } from "../shared/PopupArrow";
 
 // ─── Types ──────────────────────────────────────────────────────────────────
 
@@ -28,40 +29,21 @@ export type MenuEntry = MenuItemDef | MenuSeparatorDef | MenuGroupDef;
 export interface MenuProps {
   /** The button/element that opens the menu. */
   trigger: ReactElement;
+  /** Array of menu entries: items, separators, and groups. */
   items: MenuEntry[];
-  /** @default "bottom" */
+  /** Which edge of the trigger the menu appears on. @default "bottom" */
   side?: "top" | "bottom" | "left" | "right";
-  /** @default "start" */
+  /** Alignment along the side axis. @default "start" */
   align?: "start" | "center" | "end";
-  /** @default 4 */
+  /** Gap between the trigger and the menu popup in pixels. @default 4 */
   sideOffset?: number;
-  /** controlled open state */
+  /** Controlled open state. */
   open?: boolean;
+  /** Called when the menu opens or closes. */
   onOpenChange?: (open: boolean) => void;
   className?: string;
 }
 
-// ─── Arrow SVG ─────────────────────────────────────────────────────────────
-
-function ArrowSvg() {
-  return (
-    <svg width="20" height="10" viewBox="0 0 20 10" fill="none" aria-hidden>
-      <path
-        d="M9.66437 2.60207L4.80758 6.97318C4.07308 7.63423 3.11989 8 2.13172 8H0V10H20V8H18.5349C17.5468 8 16.5936 7.63423 15.8591 6.97318L11.0023 2.60207C10.622 2.2598 10.0447 2.25979 9.66437 2.60207Z"
-        className={styles["arrow-fill"]}
-      />
-      <path
-        d="M8.99542 1.85876C9.75604 1.17425 10.9106 1.17422 11.6713 1.85878L16.5281 6.22989C17.0789 6.72568 17.7938 7.00001 18.5349 7.00001L15.89 7L11.0023 2.60207C10.622 2.2598 10.0447 2.2598 9.66436 2.60207L4.77734 7L2.13171 7.00001C2.87284 7.00001 3.58774 6.72568 4.13861 6.22989L8.99542 1.85876Z"
-        className={styles["arrow-stroke"]}
-      />
-      <path
-        d="M10.3333 3.34539L5.47654 7.71648C4.55842 8.54279 3.36693 9 2.13172 9H0V8H2.13172C3.11989 8 4.07308 7.63423 4.80758 6.97318L9.66437 2.60207C10.0447 2.25979 10.622 2.2598 11.0023 2.60207L15.8591 6.97318C16.5936 7.63423 17.5468 8 18.5349 8H20V9H18.5349C17.2998 9 16.1083 8.54278 15.1901 7.71648L10.3333 3.34539Z"
-        className={styles["arrow-stroke"]}
-      />
-    </svg>
-  );
-}
-
 // ─── Item renderer ──────────────────────────────────────────────────────────
 
 function renderEntry(entry: MenuEntry, index: number): ReactNode {
@@ -88,6 +70,11 @@ function renderEntry(entry: MenuEntry, index: number): ReactNode {
 
 // ─── High-level Menu ────────────────────────────────────────────────────────
 
+/**
+ * A dropdown list of actions with full keyboard navigation. Supports
+ * separators, groups, and keyboard shortcuts. Items can be disabled
+ * individually.
+ */
 export function Menu({ trigger, items, side = "bottom", align = "start", sideOffset = 4, className, onOpenChange, ...props }: MenuProps) {
   return (
     <BaseMenu.Root onOpenChange={onOpenChange as never} {...props}>
@@ -96,7 +83,7 @@ export function Menu({ trigger, items, side = "bottom", align = "start", sideOff
         <BaseMenu.Positioner className={`${styles.positioner} ${className ?? ""}`} side={side} align={align} sideOffset={sideOffset}>
           <BaseMenu.Popup className={styles.popup}>
             <BaseMenu.Arrow className={styles.arrow}>
-              <ArrowSvg />
+              <PopupArrow fillClass={styles["arrow-fill"]!} seamClass={styles["arrow-seam"]!} />
             </BaseMenu.Arrow>
             {items.map((entry, i) => renderEntry(entry, i))}
           </BaseMenu.Popup>

package/src/meter/circular-meter.tsx

@@ -0,0 +1,114 @@
+import type { ReactNode } from "react";
+import { Meter as BaseMeter } from "@base-ui/react/meter";
+import styles from "./meter.module.css";
+import { getMeterState } from "./meterState";
+
+export type CircularMeterSize = "sm" | "md" | "lg";
+
+export interface CircularMeterProps {
+  /** Current value. Must be between `min` and `max`. */
+  value: number;
+  /** @default 0 */
+  min?: number;
+  /** @default 100 */
+  max?: number;
+  /** Upper boundary of the low zone. Values ≤ this are "low". */
+  low?: number;
+  /** Lower boundary of the high zone. Values ≥ this are "high". */
+  high?: number;
+  /**
+   * Which zone is optimal — determines stroke colour:
+   * - `"high"` (default) → high=green, mid=amber, low=red   (battery, signal)
+   * - `"low"`            → low=green, mid=amber, high=red   (CPU load, disk)
+   * - `"mid"`            → mid=green, low/high=amber         (temperature)
+   */
+  optimum?: "low" | "mid" | "high";
+  /** Accessible + visible label shown below the value inside the circle. */
+  label?: ReactNode;
+  /** Show the formatted value inside the circle. @default false */
+  showValue?: boolean;
+  /** `Intl.NumberFormatOptions` for value formatting. */
+  format?: Intl.NumberFormatOptions;
+  size?: CircularMeterSize;
+  className?: string;
+}
+
+const SIZES: Record<CircularMeterSize, { diameter: number; strokeWidth: number }> = {
+  sm: { diameter: 56, strokeWidth: 5 },
+  md: { diameter: 80, strokeWidth: 7 },
+  lg: { diameter: 112, strokeWidth: 9 },
+};
+
+export function CircularMeter({
+  value,
+  min = 0,
+  max = 100,
+  low,
+  high,
+  optimum = "high",
+  label,
+  showValue = false,
+  format,
+  size = "md",
+  className = "",
+}: CircularMeterProps) {
+  const clampedValue = Math.min(Math.max(value, min), max);
+  const state = getMeterState(clampedValue, min, max, low, high, optimum);
+
+  const { diameter, strokeWidth } = SIZES[size];
+  const radius = (diameter - strokeWidth) / 2;
+  const circumference = 2 * Math.PI * radius;
+  const dashOffset = circumference * (1 - (clampedValue - min) / (max - min));
+  const center = diameter / 2;
+
+  return (
+    <BaseMeter.Root
+      value={clampedValue}
+      min={min}
+      max={max}
+      {...(format !== undefined && { format })}
+      className={`${styles["circular-root"]} ${styles[`circular-${size}`]} ${className}`}
+    >
+      <div style={{ position: "relative", width: diameter, height: diameter }}>
+        <svg
+          width={diameter}
+          height={diameter}
+          viewBox={`0 0 ${diameter} ${diameter}`}
+          className={styles["circular-svg"]}
+          aria-hidden="true"
+        >
+          {/* Background track ring */}
+          <circle cx={center} cy={center} r={radius} strokeWidth={strokeWidth} className={styles["circular-track"]} />
+          {/* Value arc — origin at 12 o'clock */}
+          <circle
+            cx={center}
+            cy={center}
+            r={radius}
+            strokeWidth={strokeWidth}
+            strokeDasharray={circumference}
+            strokeDashoffset={dashOffset}
+            className={styles["circular-indicator"]}
+            data-meter-state={state}
+            style={{ transform: "rotate(-90deg)", transformOrigin: "center" }}
+          />
+        </svg>
+
+        {(showValue || label != null) && (
+          <div
+            style={{
+              position: "absolute",
+              inset: 0,
+              display: "flex",
+              flexDirection: "column",
+              alignItems: "center",
+              justifyContent: "center",
+            }}
+          >
+            {showValue && <BaseMeter.Value className={styles["circular-value"]} />}
+            {label != null && <BaseMeter.Label className={styles["circular-label"]}>{label}</BaseMeter.Label>}
+          </div>
+        )}
+      </div>
+    </BaseMeter.Root>
+  );
+}

package/src/meter/index.ts

@@ -0,0 +1,9 @@
+export { Meter } from "./meter";
+export type { MeterProps, MeterSize } from "./meter";
+export { MeterStyles } from "./meter";
+
+export { CircularMeter } from "./circular-meter";
+export type { CircularMeterProps, CircularMeterSize } from "./circular-meter";
+
+export { MeterTrack, MeterIndicator, MeterLabel, MeterValue } from "./parts";
+export type { MeterTrackProps, MeterIndicatorProps, MeterLabelProps, MeterValueProps } from "./parts";

package/src/meter/meter.module.css

@@ -0,0 +1,162 @@
+@layer components {
+  .root {
+    display: flex;
+    flex-direction: column;
+    gap: var(--space-1-5);
+    width: 100%;
+  }
+
+  /* ── Label row ──────────────────────────────────────────────────── */
+
+  .label-row {
+    display: flex;
+    align-items: center;
+    justify-content: space-between;
+    font-family: var(--font-mono);
+    font-size: var(--font-size-xs);
+    color: var(--color-secondary);
+  }
+
+  .label {
+    font-family: var(--font-mono);
+    font-size: var(--font-size-xs);
+    color: var(--color-secondary);
+  }
+
+  .value {
+    font-family: var(--font-mono);
+    font-size: var(--font-size-xs);
+    color: var(--color-secondary);
+  }
+
+  /* ── Track (the outer bar) ──────────────────────────────────────── */
+
+  .track {
+    position: relative;
+    width: 100%;
+    background-color: var(--color-surface-3);
+    border-radius: var(--radius-full);
+    overflow: hidden;
+  }
+
+  .track-sm {
+    height: 4px;
+  }
+  .track-md {
+    height: 6px;
+  }
+  .track-lg {
+    height: 8px;
+  }
+
+  /* ── Indicator (the fill) ───────────────────────────────────────── */
+
+  .indicator {
+    height: 100%;
+    border-radius: var(--radius-full);
+    background-color: var(--color-accent);
+    transition: width var(--duration-slower) var(--easing-standard);
+  }
+
+  /* Threshold-based colours — driven by data attributes set in JS */
+  .indicator[data-meter-state="optimum"] {
+    background-color: var(--color-success-solid);
+  }
+  .indicator[data-meter-state="suboptimal"] {
+    background-color: var(--color-warning-solid);
+  }
+  .indicator[data-meter-state="critical"] {
+    background-color: var(--color-error-solid);
+  }
+
+  /* ── Tick marks for low / high thresholds ───────────────────────── */
+
+  .tick {
+    position: absolute;
+    top: 0;
+    bottom: 0;
+    width: 1px;
+    background-color: var(--color-canvas);
+    opacity: 0.6;
+    pointer-events: none;
+  }
+
+  /* ── Circular gauge ─────────────────────────────────────────────── */
+
+  .circular-root {
+    display: inline-flex;
+    flex-direction: column;
+    align-items: center;
+    gap: var(--space-1-5);
+  }
+
+  .circular-svg {
+    overflow: visible;
+  }
+
+  /* Track ring */
+  .circular-track {
+    fill: none;
+    stroke: var(--color-surface-3);
+  }
+
+  /* Value arc */
+  .circular-indicator {
+    fill: none;
+    stroke: var(--color-accent);
+    stroke-linecap: round;
+    transition: stroke-dashoffset var(--duration-slower) var(--easing-standard);
+  }
+
+  .circular-indicator[data-meter-state="optimum"] {
+    stroke: var(--color-success-solid);
+  }
+  .circular-indicator[data-meter-state="suboptimal"] {
+    stroke: var(--color-warning-solid);
+  }
+  .circular-indicator[data-meter-state="critical"] {
+    stroke: var(--color-error-solid);
+  }
+
+  /* Centre text stack */
+  .circular-center {
+    display: flex;
+    flex-direction: column;
+    align-items: center;
+    justify-content: center;
+    gap: var(--space-0-5);
+  }
+
+  .circular-value {
+    font-family: var(--font-mono);
+    font-weight: var(--font-weight-semibold);
+    color: var(--color-primary);
+    line-height: 1;
+  }
+
+  .circular-label {
+    font-family: var(--font-mono);
+    color: var(--color-secondary);
+    line-height: 1;
+  }
+
+  /* Size variants */
+  .circular-sm .circular-value {
+    font-size: var(--font-size-sm);
+  }
+  .circular-sm .circular-label {
+    font-size: var(--font-size-xs);
+  }
+  .circular-md .circular-value {
+    font-size: var(--font-size-xl);
+  }
+  .circular-md .circular-label {
+    font-size: var(--font-size-xs);
+  }
+  .circular-lg .circular-value {
+    font-size: var(--font-size-2xl);
+  }
+  .circular-lg .circular-label {
+    font-size: var(--font-size-sm);
+  }
+}

package/src/meter/meter.tsx

@@ -0,0 +1,86 @@
+import type { ReactNode } from "react";
+import { Meter as BaseMeter } from "@base-ui/react/meter";
+import styles from "./meter.module.css";
+import { getMeterState } from "./meterState";
+
+export type MeterSize = "sm" | "md" | "lg";
+
+export interface MeterProps {
+  /** Current value. Must be between `min` and `max`. */
+  value: number;
+  /** Minimum value of the range. @default 0 */
+  min?: number;
+  /** Maximum value of the range. @default 100 */
+  max?: number;
+  /** Upper boundary of the low zone. Values ≤ this are "low". */
+  low?: number;
+  /** Lower boundary of the high zone. Values ≥ this are "high". */
+  high?: number;
+  /**
+   * Which zone is optimal — determines fill colour:
+   * - `"high"` (default) → high=green, mid=amber, low=red   (battery, signal)
+   * - `"low"`            → low=green, mid=amber, high=red   (CPU load, disk)
+   * - `"mid"`            → mid=green, low/high=amber         (temperature)
+   */
+  optimum?: "low" | "mid" | "high";
+  /** Accessible + visible label. */
+  label?: ReactNode;
+  /** Show the formatted value next to the label. @default false */
+  showValue?: boolean;
+  /** `Intl.NumberFormatOptions` for value formatting. */
+  format?: Intl.NumberFormatOptions;
+  /** Show tick marks at low/high threshold positions. @default false */
+  showTicks?: boolean;
+  /** Bar thickness. @default "md" */
+  size?: MeterSize;
+  className?: string;
+}
+
+/**
+ * Displays a scalar measurement within a known range. Use `low` / `high` /
+ * `optimum` thresholds to colour the fill based on whether the value is in
+ * an optimal, suboptimal, or critical zone.
+ */
+export function Meter({
+  value,
+  min = 0,
+  max = 100,
+  low,
+  high,
+  optimum = "high",
+  label,
+  showValue = false,
+  format,
+  showTicks = false,
+  size = "md",
+  className = "",
+}: MeterProps) {
+  const clampedValue = Math.min(Math.max(value, min), max);
+  const state = getMeterState(clampedValue, min, max, low, high, optimum);
+  const lowPct = low != null ? ((low - min) / (max - min)) * 100 : null;
+  const highPct = high != null ? ((high - min) / (max - min)) * 100 : null;
+
+  return (
+    <BaseMeter.Root
+      value={clampedValue}
+      min={min}
+      max={max}
+      {...(format !== undefined && { format })}
+      className={`${styles.root} ${className}`}
+    >
+      {(label != null || showValue) && (
+        <div className={styles["label-row"]}>
+          {label != null && <BaseMeter.Label className={styles.label}>{label}</BaseMeter.Label>}
+          {showValue && <BaseMeter.Value className={styles.value} />}
+        </div>
+      )}
+      <BaseMeter.Track className={`${styles.track} ${styles[`track-${size}`]}`}>
+        <BaseMeter.Indicator className={styles.indicator} data-meter-state={state} />
+        {showTicks && lowPct != null && <div className={styles.tick} style={{ left: `${lowPct}%` }} />}
+        {showTicks && highPct != null && <div className={styles.tick} style={{ left: `${highPct}%` }} />}
+      </BaseMeter.Track>
+    </BaseMeter.Root>
+  );
+}
+
+export { styles as MeterStyles };

package/src/meter/meterState.ts

@@ -0,0 +1,29 @@
+/**
+ * Derives the semantic zone from value + thresholds,
+ * following the HTML <meter> spec colouring algorithm.
+ *
+ * Returns undefined when no thresholds are defined (plain accent colour).
+ */
+export function getMeterState(
+  value: number,
+  min: number,
+  max: number,
+  low: number | undefined,
+  high: number | undefined,
+  optimum: "low" | "mid" | "high",
+): "optimum" | "suboptimal" | "critical" | undefined {
+  if (low === undefined && high === undefined) return undefined;
+
+  const effectiveLow = low ?? min;
+  const effectiveHigh = high ?? max;
+
+  const zone: "low" | "mid" | "high" = value <= effectiveLow ? "low" : value >= effectiveHigh ? "high" : "mid";
+
+  if (zone === optimum) return "optimum";
+
+  // "mid" optimum → no critical zone, extremes are equally suboptimal
+  if (optimum === "mid") return "suboptimal";
+
+  // "low" or "high" optimum → adjacent zone = suboptimal, far end = critical
+  return zone === "mid" ? "suboptimal" : "critical";
+}