@cosxai/ui 0.4.11 → 0.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosxai/ui",
-  "version": "0.4.11",
+  "version": "0.5.0",
   "description": "COSX design system — React 19 component primitives shared across product-meta and other consumers",
   "license": "UNLICENSED",
   "type": "module",

package/src/primitives/Button.tsx

@@ -1,30 +1,67 @@
-import type { ButtonHTMLAttributes, ReactNode } from "react";
+import { forwardRef, type ButtonHTMLAttributes, type ReactNode } from "react";
 import { cn } from "../lib/cn";
 
-// Minimal Phase-0 stub so the docs app has something concrete to
-// import — proves the workspace bridge + hot-reload. Phase 3
-// replaces this with the full variant + size + loading-state
-// implementation backed by the .rd-btn styles.
+/**
+ * Button — primitive interactive element. Variants `primary`
+ * (filled) / `secondary` (outlined) / `ghost` (transparent) /
+ * `icon` (square 32×32).
+ *
+ * The `loading` prop is the canonical way to show that an async
+ * action triggered by the button is in flight. When true:
+ *
+ *   - a small ring spinner renders before the children (inherits
+ *     `currentColor` so it reads on every variant),
+ *   - the button is `disabled` natively so clicks are dropped,
+ *   - `aria-busy="true"` is set for AT consumers.
+ *
+ * `loading` and `disabled` are distinct states. `disabled` says
+ * "you can't take this action right now" (form invalid, no
+ * selection, etc.). `loading` says "we're already taking this
+ * action — wait". Callers typically wire both:
+ *
+ *     <Button disabled={!name.trim()} loading={submitting}>
+ *       {submitting ? "Saving…" : "Save"}
+ *     </Button>
+ *
+ * Visual: see docs/components/button.
+ *
+ * Forwards ref to the underlying <button>. Spreads `...rest` so
+ * consumers can pass data-* / aria-* / className.
+ */
 
 export type ButtonVariant = "primary" | "secondary" | "ghost" | "icon";
 
 export interface ButtonProps extends ButtonHTMLAttributes<HTMLButtonElement> {
-  variant?: ButtonVariant;
+  variant?: ButtonVariant | undefined;
+  /**
+   * When true, the button renders a leading spinner, sets
+   * `aria-busy="true"`, and becomes natively `disabled` so click
+   * handlers no longer fire. Use this for any async submit so the
+   * user sees the click landed AND can't double-fire the action.
+   */
+  loading?: boolean | undefined;
   children?: ReactNode;
 }
 
-export function Button({
-  variant = "primary",
-  className,
-  children,
-  ...rest
-}: ButtonProps) {
-  return (
-    <button
-      {...rest}
-      className={cn("ck-btn", `ck-btn--${variant}`, className)}
-    >
-      {children}
-    </button>
-  );
-}
+export const Button = forwardRef<HTMLButtonElement, ButtonProps>(
+  function Button(
+    { variant = "primary", className, children, loading, disabled, ...rest },
+    ref,
+  ) {
+    return (
+      <button
+        ref={ref}
+        {...rest}
+        className={cn("ck-btn", `ck-btn--${variant}`, className)}
+        disabled={disabled || loading}
+        aria-busy={loading || undefined}
+        data-loading={loading || undefined}
+      >
+        {loading ? (
+          <span className="ck-btn-spinner" aria-hidden="true" />
+        ) : null}
+        {children}
+      </button>
+    );
+  },
+);

package/src/styles/index.css

@@ -39,6 +39,30 @@
 
 .ck-btn:disabled { opacity: 0.5; cursor: not-allowed; }
 
+/* Loading spinner — rendered inside a Button when its `loading`
+   prop is true. CSS-only ring (1.5px stroke, 720ms linear spin).
+   `currentColor` inherits the variant's foreground so the spinner
+   reads on primary / secondary / ghost / icon without per-variant
+   overrides. Reduced-motion users get a slower spin instead of a
+   frozen ring (which would read as broken). */
+.ck-btn-spinner {
+  width: 0.85em;
+  height: 0.85em;
+  border: 1.5px solid currentColor;
+  border-right-color: transparent;
+  border-radius: 50%;
+  display: inline-block;
+  vertical-align: -0.1em;
+  flex-shrink: 0;
+  animation: ck-btn-spin 720ms linear infinite;
+}
+@keyframes ck-btn-spin {
+  to { transform: rotate(360deg); }
+}
+@media (prefers-reduced-motion: reduce) {
+  .ck-btn-spinner { animation-duration: 2400ms; }
+}
+
 .ck-btn--primary {
   background: var(--ck-accent);
   color: var(--ck-text-inverse);