@hexclave/dashboard-ui-components 1.0.2 → 1.0.5

package/src/components/analytics-chart/state.ts

@@ -0,0 +1,165 @@
+import { DEFAULT_FORMAT_KIND } from "./format";
+import type {
+  AnalyticsChartAnnotationsLayer,
+  AnalyticsChartDataLayer,
+  AnalyticsChartLayer,
+  AnalyticsChartLayers,
+  AnalyticsChartLayerType,
+  AnalyticsChartSeries,
+  AnalyticsChartState,
+  AnalyticsChartStrokeStyle,
+  AnalyticsChartTimeseriesState,
+} from "./types";
+
+export const STROKE_DASHARRAY: Record<AnalyticsChartStrokeStyle, string | undefined> = {
+  solid: undefined,
+  dashed: "5 4",
+  dotted: "1 4",
+};
+
+export const EMPTY_SERIES: readonly AnalyticsChartSeries[] = [];
+export const EMPTY_MATRIX: readonly (readonly number[])[] = [];
+
+/** Generic non-segmented defaults; demos swap in segment data. */
+export const ANALYTICS_CHART_DEFAULT_LAYERS: AnalyticsChartLayers = [
+  {
+    id: "primary",
+    kind: "primary",
+    label: "Current",
+    visible: true,
+    color: "#2563eb",
+    segmented: false,
+    type: "area",
+    strokeStyle: "solid",
+    fillOpacity: 0.22,
+    inProgressFromIndex: null,
+  },
+  {
+    id: "compare",
+    kind: "compare",
+    label: "Previous period",
+    visible: true,
+    color: "#f59e0b",
+    segmented: false,
+    type: "line",
+    strokeStyle: "dashed",
+    inProgressFromIndex: null,
+  },
+  { id: "annotations", kind: "annotations", label: "Annotations", visible: true, color: "#f59e0b" },
+];
+
+/**
+ * Default state for `AnalyticsChart`. ALWAYS spread from this when
+ * initializing state; never build the state object by hand. Ships with
+ * three pre-configured layers (primary, compare, annotations) — map over
+ * `layers` to override individual ones.
+ *
+ * ```tsx
+ * const [state, setState] = React.useState({
+ *   ...ANALYTICS_CHART_DEFAULT_STATE,
+ *   layers: ANALYTICS_CHART_DEFAULT_STATE.layers.map(l =>
+ *     l.kind === "compare" ? { ...l, visible: false } : l
+ *   ),
+ * });
+ * ```
+ *
+ * See the JSDoc on `AnalyticsChart` for the full contract, examples, and
+ * the segment data format.
+ */
+export const ANALYTICS_CHART_DEFAULT_STATE: AnalyticsChartState = {
+  view: "timeseries",
+  layers: ANALYTICS_CHART_DEFAULT_LAYERS,
+  xFormatKind: DEFAULT_FORMAT_KIND.datetime,
+  yFormatKind: DEFAULT_FORMAT_KIND.short,
+  showGrid: true,
+  showXAxis: true,
+  showYAxis: true,
+  zoomRange: null,
+  pinnedIndex: null,
+};
+
+export function findPrimaryLayer(layers: AnalyticsChartLayers): AnalyticsChartDataLayer | undefined {
+  const l = layers.find((x) => x.kind === "primary");
+  return l as AnalyticsChartDataLayer | undefined;
+}
+export function findCompareLayer(layers: AnalyticsChartLayers): AnalyticsChartDataLayer | undefined {
+  const l = layers.find((x) => x.kind === "compare");
+  return l as AnalyticsChartDataLayer | undefined;
+}
+export function findAnnotationsLayer(layers: AnalyticsChartLayers): AnalyticsChartAnnotationsLayer | undefined {
+  const l = layers.find((x) => x.kind === "annotations");
+  return l as AnalyticsChartAnnotationsLayer | undefined;
+}
+
+export function findLayerById(
+  layers: AnalyticsChartLayers,
+  id: string,
+): AnalyticsChartLayer | undefined {
+  return layers.find((l) => l.id === id);
+}
+
+export function isAnalyticsChartDataLayer(l: AnalyticsChartLayer): l is AnalyticsChartDataLayer {
+  return l.kind === "primary" || l.kind === "compare";
+}
+
+export function isTimeseriesState(
+  state: AnalyticsChartState,
+): state is AnalyticsChartTimeseriesState {
+  return state.view === "timeseries";
+}
+
+/** Replace a single layer (looked up by id) with a new layer object. */
+export function setLayerById(
+  layers: AnalyticsChartLayers,
+  id: string,
+  next: AnalyticsChartLayer,
+): AnalyticsChartLayers {
+  return layers.map((l) => (l.id === id ? next : l));
+}
+
+/** Shallow-patch fields on a layer by id. The patch type is deliberately
+ * loose — callers are trusted to supply only fields the layer's
+ * `kind`/`type` actually owns. */
+export function patchLayerById(
+  layers: AnalyticsChartLayers,
+  id: string,
+  patch: Record<string, unknown>,
+): AnalyticsChartLayers {
+  return layers.map((l) => (l.id === id ? ({ ...l, ...patch } as AnalyticsChartLayer) : l));
+}
+
+export type ResolvedDataLayerStyle = {
+  color: string,
+  type: AnalyticsChartLayerType,
+  strokeStyle: AnalyticsChartStrokeStyle,
+  fillOpacity: number,
+};
+
+export function resolveDataLayerStyle(
+  layer: AnalyticsChartDataLayer,
+): ResolvedDataLayerStyle {
+  return {
+    color: layer.color,
+    type: layer.type,
+    // Bars have no stroke pattern — default to solid for the underline.
+    strokeStyle: layer.type === "bar" ? "solid" : layer.strokeStyle,
+    // Lines have no fill — default to 0 so gradient overlays sit flat.
+    fillOpacity: layer.type === "line" ? 0 : layer.fillOpacity,
+  };
+}
+
+/** Translate a layer's absolute `inProgressFromIndex` into a local index
+ * inside the visible window. Returns `null` when the marker sits beyond
+ * the visible window, `0` when it sits before the window (whole window
+ * is dashed), or the clamped local index otherwise. */
+export function computeLocalInProgressIdx(
+  absIdx: number | null | undefined,
+  visibleStart: number,
+  visibleEnd: number,
+): number | null {
+  if (absIdx == null) return null;
+  const local = absIdx - visibleStart;
+  if (local >= visibleEnd - visibleStart + 1) return null; // beyond window
+  if (local < 0) return 0; // before window — whole window is dashed
+  return local;
+}

package/src/components/analytics-chart/strings.ts

@@ -0,0 +1,72 @@
+export type AnalyticsChartStrings = {
+  /** Reset-zoom badge in the top-right corner when `state.zoomRange` is set. */
+  resetZoom: string,
+  /** Header label above the timestamps in the live range-brush popup. */
+  rangeLabel: string,
+  /** Formatted day-count suffix used by the brush + action-bar. */
+  daysShort: (days: number) => string,
+  /** "Zoom in" button inside the committed-range action bar. */
+  zoomIn: string,
+  /** "Annotate" button inside the committed-range action bar. */
+  annotate: string,
+  /** Placeholder for the annotation label input. */
+  annotationPlaceholder: string,
+  /** `aria-label` for the annotation label input. */
+  annotationLabelAria: string,
+  /** Save button in the annotation form. */
+  save: string,
+  /** Cancel button in the annotation form. */
+  cancel: string,
+  /** `aria-label` for the X button that clears the committed range. */
+  clearSelection: string,
+  /** Pinned badge shown in the tooltip header when the tooltip is pinned. */
+  pinnedBadge: string,
+  /** "Δ vs prev" row label in the tooltip (both segmented and flat modes). */
+  deltaVsPrev: string,
+  /** Suffix appended to a layer's label in the per-layer totals section
+   * (e.g. "Sign-ups" → "Sign-ups total"). */
+  layerTotalSuffix: string,
+  /** Hint row shown in the tooltip while it is floating (not pinned). */
+  hintClickToPin: string,
+  /** Hint row shown in the tooltip while it is pinned. */
+  hintClickAnywhereUnpin: string,
+  /** Center-stat heading shown in the pie when no segment is hovered. */
+  pieTotalCenter: string,
+  /** Label on the TrendPill in the pie center. */
+  pieVsPrev: string,
+  /** `aria-label` for the PieChart SVG. */
+  pieAriaLabel: (ctx: { segmentCount: number, windowDays: number }) => string,
+  /** Percentage-of-total caption shown under an active pie slice. */
+  piePercentOfTotal: (pct: number) => string,
+};
+
+export const ANALYTICS_CHART_DEFAULT_STRINGS: AnalyticsChartStrings = {
+  resetZoom: "Reset zoom",
+  rangeLabel: "Range",
+  daysShort: (days) => `${days}d`,
+  zoomIn: "Zoom in",
+  annotate: "Annotate",
+  annotationPlaceholder: "Label this range…",
+  annotationLabelAria: "Annotation label",
+  save: "Save",
+  cancel: "Cancel",
+  clearSelection: "Clear selection",
+  pinnedBadge: "Pinned",
+  deltaVsPrev: "Δ vs prev",
+  layerTotalSuffix: " total",
+  hintClickToPin: "Click to pin this point",
+  hintClickAnywhereUnpin: "Click anywhere · Esc\u00A0to unpin",
+  pieTotalCenter: "Total",
+  pieVsPrev: "vs prev",
+  pieAriaLabel: ({ segmentCount, windowDays }) =>
+    `${segmentCount} segment share-of-total over the visible ${windowDays}-day range`,
+  piePercentOfTotal: (pct) => `${(pct * 100).toFixed(1)}% of total`,
+};
+
+/** Shallow merge — every field is a primitive or a flat function. */
+export function resolveAnalyticsChartStrings(
+  override: Partial<AnalyticsChartStrings> | undefined,
+): AnalyticsChartStrings {
+  if (!override) return ANALYTICS_CHART_DEFAULT_STRINGS;
+  return { ...ANALYTICS_CHART_DEFAULT_STRINGS, ...override };
+}

package/src/components/analytics-chart/types.ts

@@ -0,0 +1,220 @@
+/** Time-series point. `values` is keyed by layer id. */
+export type Point = {
+  ts: number,
+  values: Record<string, number>,
+};
+
+/** Missing or non-finite values become 0. */
+export function pointValue(p: Point, id: string): number {
+  const v = p.values[id];
+  return typeof v === "number" && Number.isFinite(v) ? v : 0;
+}
+
+/** Sanitize a string into a valid CSS `<ident>` token.
+ *  Replaces characters not allowed in CSS identifiers (like `$`, spaces,
+ *  slashes, dots) with underscores. Used to build safe `var(--color-xxx)`
+ *  custom property names from arbitrary segment keys. */
+export function cssIdent(raw: string): string {
+  // Replace everything that isn't a letter, digit, hyphen, or underscore.
+  // Prefix with `_` if the result starts with a digit (not valid as ident start).
+  const cleaned = raw.replace(/[^a-zA-Z0-9_-]/g, "_");
+  return /^\d/.test(cleaned) ? `_${cleaned}` : cleaned;
+}
+
+export type Annotation = {
+  index: number,
+  label: string,
+  description: string,
+};
+
+/** Breakdown category definition — `{ key, label }` tuple. */
+export type AnalyticsChartSeries = {
+  key: string,
+  label: string,
+};
+
+export type FormatKindType =
+  | "numeric"
+  | "short"
+  | "currency"
+  | "duration"
+  | "datetime"
+  | "percent";
+
+export type FormatKindNumeric = {
+  type: "numeric",
+  /** Locale used for grouping and digit separators. Defaults to "en-US". */
+  locale?: string,
+  /** Fixed decimal places (0-4). Defaults to 0. */
+  decimals?: number,
+};
+export type FormatKindShort = {
+  type: "short",
+  /** Decimal places after the unit suffix (1.2K vs 1.20K). Defaults to 1. */
+  precision?: number,
+  locale?: string,
+};
+export type FormatKindCurrency = {
+  type: "currency",
+  /** ISO 4217 code. Defaults to "USD". */
+  currency?: string,
+  /** Divisor applied before formatting — e.g. 100 for cents → dollars. Defaults to 1. */
+  divisor?: number,
+  locale?: string,
+};
+export type FormatKindDuration = {
+  type: "duration",
+  /** Source unit of the input value. Defaults to "s". */
+  unit?: "ms" | "s" | "m" | "h",
+  /** Show the smallest unit even when zero. Defaults to false. */
+  showZero?: boolean,
+};
+export type FormatKindDatetime = {
+  type: "datetime",
+  /** Render style. Defaults to "short". */
+  style?: "short" | "long" | "iso" | "relative",
+  locale?: string,
+};
+export type FormatKindPercent = {
+  type: "percent",
+  /** How to interpret the input value:
+   * - "fraction" → 0..1     → multiply by 100  (default)
+   * - "basis"    → 0..10000 → divide by 100
+   * - "whole"    → 0..100   → no scaling
+   */
+  source?: "fraction" | "basis" | "whole",
+  /** Decimal places. Defaults to 1. */
+  decimals?: number,
+};
+
+export type FormatKind =
+  | FormatKindNumeric
+  | FormatKindShort
+  | FormatKindCurrency
+  | FormatKindDuration
+  | FormatKindDatetime
+  | FormatKindPercent;
+
+export type AnalyticsChartView = "timeseries" | "pie";
+export type AnalyticsChartLayerType = "line" | "area" | "bar";
+export type AnalyticsChartStrokeStyle = "solid" | "dashed" | "dotted";
+
+type AnalyticsChartDataLayerCommon = {
+  id: string,
+  kind: "primary" | "compare",
+  label: string,
+  visible: boolean,
+  color: string,
+  segmented: boolean,
+  /** Per-day per-category values. Outer index is the day (matches the
+   * chart data array index); inner index is the category (matches
+   * `segmentSeries`). Rows should sum to `point.values[layer.id]`. */
+  segments?: readonly (readonly number[])[],
+  /** Breakdown category definitions ordered to match the inner index of
+   * `segments`. */
+  segmentSeries?: readonly AnalyticsChartSeries[],
+  /** Absolute index into the full data array at which this layer's values
+   * become "in progress" (incomplete and still changing). Points from this
+   * index onward render with a dashed overlay so users don't panic at a
+   * half-filled bucket. Applies to line and area rendering only. */
+  inProgressFromIndex?: number | null,
+};
+export type AnalyticsChartLineLayer = AnalyticsChartDataLayerCommon & {
+  type: "line",
+  strokeStyle: AnalyticsChartStrokeStyle,
+};
+export type AnalyticsChartAreaLayer = AnalyticsChartDataLayerCommon & {
+  type: "area",
+  strokeStyle: AnalyticsChartStrokeStyle,
+  fillOpacity: number,
+};
+export type AnalyticsChartBarLayer = AnalyticsChartDataLayerCommon & {
+  type: "bar",
+  fillOpacity: number,
+};
+
+export type AnalyticsChartDataLayer =
+  | AnalyticsChartLineLayer
+  | AnalyticsChartAreaLayer
+  | AnalyticsChartBarLayer;
+
+export type AnalyticsChartAnnotationsLayer = {
+  id: string,
+  kind: "annotations",
+  label: string,
+  visible: boolean,
+  color: string,
+};
+
+export type AnalyticsChartLayer =
+  | AnalyticsChartDataLayer
+  | AnalyticsChartAnnotationsLayer;
+
+export type AnalyticsChartLayers = readonly AnalyticsChartLayer[];
+
+export type AnalyticsChartTimeseriesState = {
+  view: "timeseries",
+  layers: AnalyticsChartLayers,
+  /** Format applied to every x-axis value. Defaults to `datetime / short`. */
+  xFormatKind: FormatKind,
+  /** Format applied to every y-axis value. Defaults to `short`. */
+  yFormatKind: FormatKind,
+  showGrid: boolean,
+  showXAxis: boolean,
+  showYAxis: boolean,
+  zoomRange: [number, number] | null,
+  pinnedIndex: number | null,
+};
+export type AnalyticsChartPieState = {
+  view: "pie",
+  layers: AnalyticsChartLayers,
+  xFormatKind: FormatKind,
+  yFormatKind: FormatKind,
+};
+export type AnalyticsChartState =
+  | AnalyticsChartTimeseriesState
+  | AnalyticsChartPieState;
+
+export type AnalyticsChartDelta = {
+  pct: number | null,
+  sign: "up" | "down" | "flat" | "na",
+};
+
+/** Grouped pie config — collapses the formerly-separate
+ * `pieInnerRadius` / `pieOuterRadius` / `pieCompareInnerRadius` /
+ * `pieCompareOuterRadius` / `pieContainerClassName` props into one object. */
+export type AnalyticsChartPieProps = {
+  innerRadius?: number,
+  outerRadius?: number,
+  compareInnerRadius?: number,
+  compareOuterRadius?: number,
+  className?: string,
+  showDateRange?: boolean,
+};
+
+export type AnalyticsChartSegmentRamp =
+  | {
+    kind: "procedural",
+    /** HSL hue (0-360). */
+    hue: number,
+    /** HSL saturation percent (0-100). */
+    sat: number,
+    /** Lightness range `[start, end]` for the light theme (0-100). */
+    shadeRangeLight: [number, number],
+    /** Lightness range `[start, end]` for the dark theme (0-100). */
+    shadeRangeDark: [number, number],
+  }
+  | {
+    kind: "explicit",
+    /** Concrete light-theme color list. Indexed by segment. */
+    light: readonly string[],
+    /** Concrete dark-theme color list. Indexed by segment. */
+    dark: readonly string[],
+  };
+
+export type AnalyticsChartPalette = {
+  /** Color ramp for the primary data layer (current period). */
+  primary: AnalyticsChartSegmentRamp,
+  /** Color ramp for the compare data layer (previous period). */
+  compare: AnalyticsChartSegmentRamp,
+};

package/src/components/badge.tsx

@@ -0,0 +1,108 @@
+"use client";
+
+import { cn } from "@hexclave/ui";
+
+export type DesignBadgeColor = "blue" | "cyan" | "purple" | "green" | "orange" | "red";
+export type DesignBadgeSize = "sm" | "md";
+
+const badgeStyles = new Map<DesignBadgeColor, string>([
+  ["blue", "text-blue-700 dark:text-blue-400 bg-blue-500/20 dark:bg-blue-500/10 ring-1 ring-blue-500/30 dark:ring-blue-500/20"],
+  ["cyan", "text-cyan-700 dark:text-cyan-400 bg-cyan-500/20 dark:bg-cyan-500/10 ring-1 ring-cyan-500/30 dark:ring-cyan-500/20"],
+  ["purple", "text-purple-700 dark:text-purple-400 bg-purple-500/20 dark:bg-purple-500/10 ring-1 ring-purple-500/30 dark:ring-purple-500/20"],
+  ["green", "text-emerald-700 dark:text-emerald-400 bg-emerald-500/20 dark:bg-emerald-500/10 ring-1 ring-emerald-500/30 dark:ring-emerald-500/20"],
+  ["orange", "text-amber-700 dark:text-amber-300 bg-amber-500/20 dark:bg-amber-500/10 ring-1 ring-amber-500/30 dark:ring-amber-500/20"],
+  ["red", "text-red-700 dark:text-red-400 bg-red-500/20 dark:bg-red-500/10 ring-1 ring-red-500/30 dark:ring-red-500/20"],
+]);
+
+function getMapValueOrThrow<TKey, TValue>(map: Map<TKey, TValue>, key: TKey, mapName: string) {
+  const value = map.get(key);
+  if (!value) {
+    throw new Error(`Missing ${mapName} entry for key "${String(key)}"`);
+  }
+  return value;
+}
+
+/** At least one of showLabel or showIcon must be true. */
+export type DesignBadgeContentMode = "both" | "text" | "icon";
+
+export type DesignBadgeProps = {
+  label: string,
+  color: DesignBadgeColor,
+  icon?: React.ElementType,
+  size?: DesignBadgeSize,
+  /** What to display: "both" (default), "text" (label only), or "icon" (icon only; requires icon prop). */
+  contentMode?: DesignBadgeContentMode,
+};
+
+function getShowLabelShowIcon(
+  contentMode: DesignBadgeContentMode,
+  hasIcon: boolean,
+): { showLabel: boolean, showIcon: boolean } {
+  switch (contentMode) {
+    case "both": {
+      return { showLabel: true, showIcon: hasIcon };
+    }
+    case "text": {
+      return { showLabel: true, showIcon: false };
+    }
+    case "icon": {
+      if (!hasIcon) {
+        throw new Error("DesignBadge contentMode 'icon' requires the icon prop to be provided.");
+      }
+      return { showLabel: false, showIcon: true };
+    }
+    default: {
+      const _exhaustive: never = contentMode;
+      throw new Error(`Unknown contentMode: ${String(_exhaustive)}`);
+    }
+  }
+}
+
+/**
+ * Small pill used for status tags, roles, categories, and other short
+ * labels. Not a variant-based component — pick a semantic `color` and
+ * optionally pass an `icon` (as a component type, not a rendered node).
+ *
+ * ```tsx
+ * <DesignBadge label="Verified" color="green" icon={CheckIcon} />
+ * <DesignBadge label="Beta" color="purple" />
+ * <DesignBadge label="Error" color="red" size="sm" />
+ * ```
+ *
+ * Notes:
+ * - Props are `label` + `color`, NOT `variant` + children.
+ * - `color` is one of: `"blue" | "cyan" | "purple" | "green" | "orange" | "red"`.
+ * - `icon` is optional but, if set via `contentMode: "icon"`, is required.
+ */
+export function DesignBadge({
+  label,
+  color,
+  icon,
+  size = "md",
+  contentMode = "both",
+}: DesignBadgeProps) {
+  const Icon = icon;
+  const { showLabel, showIcon } = getShowLabelShowIcon(contentMode, !!Icon);
+  if (!showLabel && !showIcon) {
+    throw new Error("DesignBadge must show at least label or icon.");
+  }
+  const sizeClasses = size === "sm"
+    ? "px-2 py-0.5 text-[10px]"
+    : "px-2.5 py-1 text-[11px]";
+  const colorClasses = getMapValueOrThrow(badgeStyles, color, "badgeStyles");
+
+  return (
+    <div
+      className={cn(
+        "inline-flex items-center gap-1.5 rounded-full font-medium",
+        colorClasses,
+        sizeClasses
+      )}
+      title={!showLabel ? label : undefined}
+      aria-label={label}
+    >
+      {showIcon && Icon && <Icon className="h-3 w-3" />}
+      {showLabel ? label : null}
+    </div>
+  );
+}

package/src/components/button.tsx

@@ -0,0 +1,104 @@
+import { Slot, Slottable } from "@radix-ui/react-slot";
+import { forwardRefIfNeeded } from "@hexclave/shared/dist/utils/react";
+import { cva, type VariantProps } from "class-variance-authority";
+import React from "react";
+
+import { cn, Spinner } from "@hexclave/ui";
+import { useAsyncCallback } from "@hexclave/shared/dist/hooks/use-async-callback";
+import { runAsynchronouslyWithAlert } from "@hexclave/shared/dist/utils/promises";
+
+const designButtonVariants = cva(
+  "stack-scope inline-flex items-center justify-center whitespace-nowrap rounded-md text-sm font-medium focus-visible:outline-none focus-visible:ring-1 focus-visible:ring-ring disabled:pointer-events-none disabled:opacity-50",
+  {
+    variants: {
+      variant: {
+        default:
+          "bg-primary text-primary-foreground hover:bg-primary/90",
+        destructive:
+          "bg-destructive text-destructive-foreground hover:bg-destructive/90",
+        outline:
+          "border border-input bg-white/85 dark:bg-background hover:bg-white dark:hover:bg-accent hover:text-accent-foreground",
+        secondary:
+          "bg-secondary text-secondary-foreground hover:bg-secondary/80",
+        ghost: "hover:bg-accent hover:text-accent-foreground",
+        link: "text-primary underline-offset-4 hover:underline",
+        plain: "",
+      },
+      size: {
+        default: "h-9 px-4 py-2",
+        sm: "h-8 rounded-md px-3 text-xs",
+        lg: "h-10 rounded-md px-8",
+        icon: "h-9 w-9",
+      },
+    },
+    defaultVariants: {
+      variant: "default",
+      size: "default",
+    },
+  }
+);
+
+export type DesignOriginalButtonProps = {
+  asChild?: boolean,
+} & React.ButtonHTMLAttributes<HTMLButtonElement> & VariantProps<typeof designButtonVariants>;
+
+const DesignOriginalButton = forwardRefIfNeeded<HTMLButtonElement, DesignOriginalButtonProps>(
+  ({ className, variant, size, asChild = false, ...props }, ref) => {
+    const Comp = asChild ? Slot : "button";
+    return (
+      <Comp
+        className={cn(designButtonVariants({ variant, size, className }))}
+        ref={ref}
+        {...props}
+      />
+    );
+  }
+);
+DesignOriginalButton.displayName = "DesignButton";
+
+export type DesignButtonProps = {
+  onClick?: (e: React.MouseEvent<HTMLButtonElement>) => void | Promise<void>,
+  loading?: boolean,
+  loadingStyle?: "spinner" | "disabled",
+} & DesignOriginalButtonProps;
+
+/**
+ * Standard button. Variants: `default | destructive | outline | secondary | ghost | link | plain`.
+ * Sizes: `default | sm | lg | icon`.
+ *
+ * ```tsx
+ * <DesignButton variant="default" onClick={handleSave}>Save</DesignButton>
+ * <DesignButton variant="outline" size="sm" onClick={handleCancel}>Cancel</DesignButton>
+ * <DesignButton variant="ghost" size="icon"><PlusIcon className="h-4 w-4" /></DesignButton>
+ * ```
+ *
+ * Pass an async `onClick` and the button will automatically show a spinner
+ * while the promise is pending (set `loadingStyle="disabled"` if you prefer
+ * a simple disabled state instead).
+ */
+export const DesignButton = forwardRefIfNeeded<HTMLButtonElement, DesignButtonProps>(
+  ({ onClick, loading: loadingProp, loadingStyle = "spinner", children, size, ...props }, ref) => {
+    const [handleClick, isLoading] = useAsyncCallback(async (e: React.MouseEvent<HTMLButtonElement>) => {
+      await onClick?.(e);
+    }, [onClick]);
+
+    const loading = loadingProp || isLoading;
+
+    return (
+      <DesignOriginalButton
+        {...props}
+        ref={ref}
+        disabled={props.disabled || loading}
+        onClick={(e) => runAsynchronouslyWithAlert(handleClick(e))}
+        size={size}
+        className={cn("relative", loading && "[&>:not(.stack-button-do-not-hide-when-siblings-are)]:invisible", props.className)}
+      >
+        {loadingStyle === "spinner" && <Spinner className={cn("absolute inset-0 flex items-center justify-center stack-button-do-not-hide-when-siblings-are", !loading && "invisible")} />}
+        <Slottable>
+          {typeof children === "string" ? <span>{children}</span> : children}
+        </Slottable>
+      </DesignOriginalButton>
+    );
+  }
+);
+DesignButton.displayName = "DesignButton";