@geomak/ui 1.7.5 → 1.9.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;
@@ -1420,11 +1457,14 @@ interface TextInputProps {
 declare function TextInput({ value, onChange, disabled, label, htmlFor, placeholder, name, inputStyle, style, layout, onBlur, errorMessage, labelColor, }: TextInputProps): react_jsx_runtime.JSX.Element;
 
 interface NumberInputProps {
+    /** Step size for the up/down buttons and native arrow-key handling. Default `1`. */
     step?: number;
-    value?: any;
+    /** Current value. `undefined` renders an empty field; a number renders that value. */
+    value?: number | '';
+    /** Fires with the next number. Empty input resolves to `undefined`. */
     onChange?: (e: {
         target: {
-            value: number;
+            value: number | undefined;
             id?: string;
             name?: string;
         };
@@ -1433,8 +1473,8 @@ interface NumberInputProps {
     htmlFor?: string;
     name?: string;
     disabled?: boolean;
-    /** 'horizontal' | 'vertical' */
-    layout?: string;
+    /** Label/input orientation. Defaults to `'horizontal'`. */
+    layout?: 'horizontal' | 'vertical';
     errorMessage?: React$1.ReactNode;
     inputStyle?: React$1.CSSProperties;
     labelStyle?: React$1.CSSProperties;
@@ -1443,12 +1483,42 @@ interface NumberInputProps {
     min?: number;
     max?: number;
     readOnly?: boolean;
-    [key: string]: any;
+    /** Optional precision for floating-point steps (number of decimal places to round to). */
+    precision?: number;
 }
 /**
- * Number input with increment / decrement controls.
+ * Numeric input with keyboard-accessible increment / decrement buttons.
+ *
+ * **What's improved over the previous version**
+ * - Step buttons are real `<button>` elements with `aria-label`, focus rings,
+ *   and proper keyboard activation (Enter / Space). The previous version used
+ *   `<span onClick>` which keyboard-only users could not reach.
+ * - Floating-point drift on decimal steps (`0.1 + 0.2 = 0.30000000000000004`)
+ *   is rounded out via a `precision` prop or auto-inferred from the step.
+ * - Empty input resolves to `undefined` instead of `NaN` — works with form
+ *   libraries (RHF, Formik) that treat empty as "no value".
+ * - The decrement chevron actually points down (the previous SVG was the up
+ *   chevron rotated, with the up chevron itself wrongly using the same path).
+ * - Width is a prop, not hardcoded `w-60`. Default is `w-full` so the input
+ *   flows with its parent.
+ *
+ * @example
+ * ```tsx
+ * const [qty, setQty] = useState<number | undefined>(1)
+ * <NumberInput
+ *   label="Quantity"
+ *   value={qty ?? ''}
+ *   onChange={({ target }) => setQty(target.value)}
+ *   min={0} max={99}
+ * />
+ * ```
+ *
+ * @example Decimal step
+ * ```tsx
+ * <NumberInput label="Tonnage" step={0.25} precision={2} />
+ * ```
  */
-declare function NumberInput({ step, value, onChange, label, htmlFor, name, disabled, layout, errorMessage, inputStyle, labelStyle, placeholder, style, min, max, readOnly, }: NumberInputProps): react_jsx_runtime.JSX.Element;
+declare function NumberInput({ step, value, onChange, label, htmlFor, name, disabled, layout, errorMessage, inputStyle, labelStyle, placeholder, style, min, max, readOnly, precision, }: NumberInputProps): react_jsx_runtime.JSX.Element;
 
 interface PasswordProps {
     value?: 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;
@@ -1420,11 +1457,14 @@ interface TextInputProps {
 declare function TextInput({ value, onChange, disabled, label, htmlFor, placeholder, name, inputStyle, style, layout, onBlur, errorMessage, labelColor, }: TextInputProps): react_jsx_runtime.JSX.Element;
 
 interface NumberInputProps {
+    /** Step size for the up/down buttons and native arrow-key handling. Default `1`. */
     step?: number;
-    value?: any;
+    /** Current value. `undefined` renders an empty field; a number renders that value. */
+    value?: number | '';
+    /** Fires with the next number. Empty input resolves to `undefined`. */
     onChange?: (e: {
         target: {
-            value: number;
+            value: number | undefined;
             id?: string;
             name?: string;
         };
@@ -1433,8 +1473,8 @@ interface NumberInputProps {
     htmlFor?: string;
     name?: string;
     disabled?: boolean;
-    /** 'horizontal' | 'vertical' */
-    layout?: string;
+    /** Label/input orientation. Defaults to `'horizontal'`. */
+    layout?: 'horizontal' | 'vertical';
     errorMessage?: React$1.ReactNode;
     inputStyle?: React$1.CSSProperties;
     labelStyle?: React$1.CSSProperties;
@@ -1443,12 +1483,42 @@ interface NumberInputProps {
     min?: number;
     max?: number;
     readOnly?: boolean;
-    [key: string]: any;
+    /** Optional precision for floating-point steps (number of decimal places to round to). */
+    precision?: number;
 }
 /**
- * Number input with increment / decrement controls.
+ * Numeric input with keyboard-accessible increment / decrement buttons.
+ *
+ * **What's improved over the previous version**
+ * - Step buttons are real `<button>` elements with `aria-label`, focus rings,
+ *   and proper keyboard activation (Enter / Space). The previous version used
+ *   `<span onClick>` which keyboard-only users could not reach.
+ * - Floating-point drift on decimal steps (`0.1 + 0.2 = 0.30000000000000004`)
+ *   is rounded out via a `precision` prop or auto-inferred from the step.
+ * - Empty input resolves to `undefined` instead of `NaN` — works with form
+ *   libraries (RHF, Formik) that treat empty as "no value".
+ * - The decrement chevron actually points down (the previous SVG was the up
+ *   chevron rotated, with the up chevron itself wrongly using the same path).
+ * - Width is a prop, not hardcoded `w-60`. Default is `w-full` so the input
+ *   flows with its parent.
+ *
+ * @example
+ * ```tsx
+ * const [qty, setQty] = useState<number | undefined>(1)
+ * <NumberInput
+ *   label="Quantity"
+ *   value={qty ?? ''}
+ *   onChange={({ target }) => setQty(target.value)}
+ *   min={0} max={99}
+ * />
+ * ```
+ *
+ * @example Decimal step
+ * ```tsx
+ * <NumberInput label="Tonnage" step={0.25} precision={2} />
+ * ```
  */
-declare function NumberInput({ step, value, onChange, label, htmlFor, name, disabled, layout, errorMessage, inputStyle, labelStyle, placeholder, style, min, max, readOnly, }: NumberInputProps): react_jsx_runtime.JSX.Element;
+declare function NumberInput({ step, value, onChange, label, htmlFor, name, disabled, layout, errorMessage, inputStyle, labelStyle, placeholder, style, min, max, readOnly, precision, }: NumberInputProps): react_jsx_runtime.JSX.Element;
 
 interface PasswordProps {
     value?: string;