@geomak/ui 1.7.5 → 1.8.0

package/dist/index.d.cts

@@ -587,45 +587,82 @@ declare function useNotification(): {
     danger: (props: Omit<NotificationPayload, "type">) => void;
 };
 
+type LoadingSpinnerSize = 'sm' | 'md' | 'lg';
 interface LoadingSpinnerProps {
-    /** Text revealed letter-by-letter beneath the spinner. */
-    prompt: string;
+    /**
+     * Text revealed letter-by-letter beneath the spinner. Optional — pass
+     * `undefined` for a pure spinner with no caption (e.g. inline mode).
+     */
+    prompt?: string;
+    /** Spinner size variant. Defaults to `'md'`. */
+    size?: LoadingSpinnerSize;
+    /**
+     * When `true`, renders inline at the call site (no portal, no fullscreen
+     * overlay, no backdrop). Useful inside cards, table rows, drawers, or
+     * empty-state slots. Defaults to `false` (fullscreen overlay).
+     */
+    inline?: boolean;
     /**
      * Optional override for the spinner ring colour. Accepts any CSS colour.
-     * Defaults to the accent token so it picks up theme overrides.
+     * Defaults to the `--color-accent` token so it picks up theme overrides.
      */
     spinnerColor?: string;
     /**
      * Optional override for the prompt text colour.
-     * Defaults to the foreground token (light/dark aware).
+     * Defaults to the `--color-foreground` token (light/dark aware).
      */
     textColor?: string;
     /**
-     * Backdrop opacity (0 – 1). Defaults to 0.92 — close enough to opaque to
-     * block UI underneath while still hinting at the previous state.
+     * Backdrop opacity (0 – 1) for the fullscreen overlay. Defaults to 0.8 —
+     * close enough to opaque to block UI underneath while still hinting at the
+     * previous state. Ignored when `inline` is true.
      */
     backdropOpacity?: number;
 }
 /**
- * Full-screen loading overlay with a spinning ring and a staggered text
- * reveal. Portaled into `document.body` so it always covers the actual
- * viewport regardless of where it's rendered in the React tree.
- *
- * Honours `prefers-reduced-motion`: the spinner still rotates (continuous
- * spin is informative, not decorative) but the letter stagger collapses to
- * an instant reveal.
- *
- * @example
+ * Enterprise-grade loading indicator.
+ *
+ * Two concentric arcs counter-rotating around a breathing centre dot, with
+ * an optional staggered letter reveal beneath. Portaled to `document.body`
+ * for the fullscreen overlay so it always covers the actual viewport
+ * regardless of where it sits in the React tree.
+ *
+ * **Two modes:**
+ * - **Fullscreen overlay** (default): semi-opaque backdrop with
+ *   `backdrop-blur-sm` for a modern depth effect. Use during page-level
+ *   loading, route transitions, or critical mutations.
+ * - **Inline** (`inline`): just the spinner + optional caption rendered at
+ *   the call site. Use inside cards, table rows, drawers, empty states,
+ *   or anywhere a smaller loading affordance is appropriate.
+ *
+ * **Accessibility**: `role="status"` + `aria-label`/`aria-live` make the
+ * indicator announce-able to screen readers. `prefers-reduced-motion`
+ * collapses the letter stagger to instant reveal — the spinner rings keep
+ * rotating since a continuous spinner is informative, not decorative.
+ *
+ * @example Fullscreen overlay (page load)
+ * ```tsx
  * {isLoading && <LoadingSpinner prompt="Loading vessels…" />}
+ * ```
  *
- * @example
+ * @example Inline (inside a card)
+ * ```tsx
+ * <Card>
+ *   {data ? <Chart data={data} /> : <LoadingSpinner inline size="sm" />}
+ * </Card>
+ * ```
+ *
+ * @example Themed overlay
+ * ```tsx
  * <LoadingSpinner
  *   prompt="Saving"
+ *   size="lg"
  *   spinnerColor="#10b981"
  *   backdropOpacity={0.7}
  * />
+ * ```
  */
-declare function LoadingSpinner({ prompt, spinnerColor, textColor, backdropOpacity, }: LoadingSpinnerProps): react_jsx_runtime.JSX.Element;
+declare function LoadingSpinner({ prompt, size, inline, spinnerColor, textColor, backdropOpacity, }: LoadingSpinnerProps): react_jsx_runtime.JSX.Element;
 
 interface FadingBaseProps {
     className?: string;

package/dist/index.d.ts

@@ -587,45 +587,82 @@ declare function useNotification(): {
     danger: (props: Omit<NotificationPayload, "type">) => void;
 };
 
+type LoadingSpinnerSize = 'sm' | 'md' | 'lg';
 interface LoadingSpinnerProps {
-    /** Text revealed letter-by-letter beneath the spinner. */
-    prompt: string;
+    /**
+     * Text revealed letter-by-letter beneath the spinner. Optional — pass
+     * `undefined` for a pure spinner with no caption (e.g. inline mode).
+     */
+    prompt?: string;
+    /** Spinner size variant. Defaults to `'md'`. */
+    size?: LoadingSpinnerSize;
+    /**
+     * When `true`, renders inline at the call site (no portal, no fullscreen
+     * overlay, no backdrop). Useful inside cards, table rows, drawers, or
+     * empty-state slots. Defaults to `false` (fullscreen overlay).
+     */
+    inline?: boolean;
     /**
      * Optional override for the spinner ring colour. Accepts any CSS colour.
-     * Defaults to the accent token so it picks up theme overrides.
+     * Defaults to the `--color-accent` token so it picks up theme overrides.
      */
     spinnerColor?: string;
     /**
      * Optional override for the prompt text colour.
-     * Defaults to the foreground token (light/dark aware).
+     * Defaults to the `--color-foreground` token (light/dark aware).
      */
     textColor?: string;
     /**
-     * Backdrop opacity (0 – 1). Defaults to 0.92 — close enough to opaque to
-     * block UI underneath while still hinting at the previous state.
+     * Backdrop opacity (0 – 1) for the fullscreen overlay. Defaults to 0.8 —
+     * close enough to opaque to block UI underneath while still hinting at the
+     * previous state. Ignored when `inline` is true.
      */
     backdropOpacity?: number;
 }
 /**
- * Full-screen loading overlay with a spinning ring and a staggered text
- * reveal. Portaled into `document.body` so it always covers the actual
- * viewport regardless of where it's rendered in the React tree.
- *
- * Honours `prefers-reduced-motion`: the spinner still rotates (continuous
- * spin is informative, not decorative) but the letter stagger collapses to
- * an instant reveal.
- *
- * @example
+ * Enterprise-grade loading indicator.
+ *
+ * Two concentric arcs counter-rotating around a breathing centre dot, with
+ * an optional staggered letter reveal beneath. Portaled to `document.body`
+ * for the fullscreen overlay so it always covers the actual viewport
+ * regardless of where it sits in the React tree.
+ *
+ * **Two modes:**
+ * - **Fullscreen overlay** (default): semi-opaque backdrop with
+ *   `backdrop-blur-sm` for a modern depth effect. Use during page-level
+ *   loading, route transitions, or critical mutations.
+ * - **Inline** (`inline`): just the spinner + optional caption rendered at
+ *   the call site. Use inside cards, table rows, drawers, empty states,
+ *   or anywhere a smaller loading affordance is appropriate.
+ *
+ * **Accessibility**: `role="status"` + `aria-label`/`aria-live` make the
+ * indicator announce-able to screen readers. `prefers-reduced-motion`
+ * collapses the letter stagger to instant reveal — the spinner rings keep
+ * rotating since a continuous spinner is informative, not decorative.
+ *
+ * @example Fullscreen overlay (page load)
+ * ```tsx
  * {isLoading && <LoadingSpinner prompt="Loading vessels…" />}
+ * ```
  *
- * @example
+ * @example Inline (inside a card)
+ * ```tsx
+ * <Card>
+ *   {data ? <Chart data={data} /> : <LoadingSpinner inline size="sm" />}
+ * </Card>
+ * ```
+ *
+ * @example Themed overlay
+ * ```tsx
  * <LoadingSpinner
  *   prompt="Saving"
+ *   size="lg"
  *   spinnerColor="#10b981"
  *   backdropOpacity={0.7}
  * />
+ * ```
  */
-declare function LoadingSpinner({ prompt, spinnerColor, textColor, backdropOpacity, }: LoadingSpinnerProps): react_jsx_runtime.JSX.Element;
+declare function LoadingSpinner({ prompt, size, inline, spinnerColor, textColor, backdropOpacity, }: LoadingSpinnerProps): react_jsx_runtime.JSX.Element;
 
 interface FadingBaseProps {
     className?: string;