@mohasinac/appkit 3.2.7 → 3.2.9

package/dist/ui/components/Modal.js

@@ -73,7 +73,7 @@ export function Modal({ isOpen, open, onClose, title, children, size = "md", sho
 }
 export function ModalFooter({ children, className = "", }) {
     return (_jsx("div", { className: [
-            "flex items-center justify-end gap-3 border-t border-zinc-100 px-6 py-4 dark:border-slate-800",
+            "flex items-center justify-end gap-3 border-t border-zinc-100 px-6 py-4 border-[var(--appkit-color-border-subtle)]",
             className,
         ]
             .filter(Boolean)

package/dist/ui/components/NavbarChevron.js

@@ -7,7 +7,7 @@ import { jsx as _jsx } from "react/jsx-runtime";
 import { ChevronLeft, ChevronRight } from "lucide-react";
 // navbar's overflow-scroll fade — the gradient classes implement the
 // edge-fade affordance, not consumer styling.
-const BASE_CLS = "absolute top-0 bottom-0 z-10 flex items-center justify-center w-8 text-zinc-500 dark:text-zinc-400 hover:text-zinc-900 dark:hover:text-white transition-colors";
+const BASE_CLS = "absolute top-0 bottom-0 z-10 flex items-center justify-center w-8 text-[var(--appkit-color-text-muted)] hover:text-zinc-900 dark:hover:text-white transition-colors";
 const FADE_LEFT = "bg-gradient-to-r from-white/95 dark:from-slate-950/95 to-transparent";
 const FADE_RIGHT = "bg-gradient-to-l from-white/95 dark:from-slate-950/95 to-transparent";
 export function NavbarChevron({ direction, onClick }) {

package/dist/ui/components/PageLoader.js

@@ -13,10 +13,10 @@ export function PageLoader({ children }) {
     if (!children) {
         // No skeleton — simple centred spinner / timeout message
         if (timedOut) {
-            return (_jsxs("div", { className: "flex min-h-[60vh] flex-col items-center justify-center gap-4 p-8 text-center", children: [_jsx(Text, { className: "text-base font-medium text-zinc-700 dark:text-zinc-300", children: "Something went wrong. Please refresh the page." }), _jsx(Button, { variant: "secondary", onClick: () => window.location.reload(), children: "Refresh" })] }));
+            return (_jsxs("div", { className: "flex min-h-[60vh] flex-col items-center justify-center gap-4 p-8 text-center", children: [_jsx(Text, { className: "text-base font-medium text-[var(--appkit-color-text-muted)]", children: "Something went wrong. Please refresh the page." }), _jsx(Button, { variant: "secondary", onClick: () => window.location.reload(), children: "Refresh" })] }));
         }
-        return (_jsxs("div", { className: "flex min-h-[60vh] flex-col items-center justify-center gap-3", children: [_jsx(Spinner, { size: "lg" }), _jsx(Text, { className: "text-sm text-neutral-500 dark:text-neutral-400", children: "Loading\u2026" })] }));
+        return (_jsxs("div", { className: "flex min-h-[60vh] flex-col items-center justify-center gap-3", children: [_jsx(Spinner, { size: "lg" }), _jsx(Text, { className: "text-sm text-[var(--appkit-color-text-muted)]", children: "Loading\u2026" })] }));
     }
     // Skeleton provided — render it behind a floating overlay
-    return (_jsxs("div", { className: "relative", children: [_jsx("div", { "aria-hidden": "true", children: children }), _jsx("div", { className: "pointer-events-none fixed inset-0 z-50 flex flex-col items-center justify-center gap-4 bg-white/60 p-8 text-center backdrop-blur-sm dark:bg-zinc-900/60", children: timedOut ? (_jsxs(_Fragment, { children: [_jsx(Text, { className: "text-base font-medium text-zinc-700 dark:text-zinc-300", children: "Something went wrong. Please refresh the page." }), _jsx("div", { className: "pointer-events-auto", children: _jsx(Button, { variant: "secondary", onClick: () => window.location.reload(), children: "Refresh" }) })] })) : (_jsxs(_Fragment, { children: [_jsx(Spinner, { size: "lg" }), _jsx(Text, { className: "text-sm text-neutral-500 dark:text-neutral-400", children: "Loading\u2026" })] })) })] }));
+    return (_jsxs("div", { className: "relative", children: [_jsx("div", { "aria-hidden": "true", children: children }), _jsx("div", { className: "pointer-events-none fixed inset-0 z-50 flex flex-col items-center justify-center gap-4 bg-white/60 p-8 text-center backdrop-blur-sm bg-[var(--appkit-color-surface)]/60", children: timedOut ? (_jsxs(_Fragment, { children: [_jsx(Text, { className: "text-base font-medium text-[var(--appkit-color-text-muted)]", children: "Something went wrong. Please refresh the page." }), _jsx("div", { className: "pointer-events-auto", children: _jsx(Button, { variant: "secondary", onClick: () => window.location.reload(), children: "Refresh" }) })] })) : (_jsxs(_Fragment, { children: [_jsx(Spinner, { size: "lg" }), _jsx(Text, { className: "text-sm text-[var(--appkit-color-text-muted)]", children: "Loading\u2026" })] })) })] }));
 }

package/dist/ui/components/Radio.js

@@ -44,7 +44,7 @@ export function RadioGroup({ name, options, value, onChange, label, error, orien
                                             ].join(" ") }), _jsx("span", { className: [
                                                 UI_RADIO.classic.dot,
                                                 selected ? UI_RADIO.classic.dotSelected : "",
-                                            ].join(" ") })] }), _jsx(Span, { size: "sm", className: "text-zinc-700 dark:text-zinc-200", children: option.label })] }, option.value));
+                                            ].join(" ") })] }), _jsx(Span, { size: "sm", className: "text-[var(--appkit-color-text-muted)]", children: option.label })] }, option.value));
                     }
                     return (_jsxs("label", { className: [
                             UI_RADIO.toggle.base,

package/dist/ui/components/RichTextEditor.js

@@ -55,5 +55,5 @@ export function RichTextEditor({ value, onChange, disabled = false, className =
             editor.innerHTML = value;
         }
     }, [value]);
-    return (_jsxs("div", { className: `appkit-rich-text-editor rounded-lg border border-zinc-200 bg-white dark:border-slate-700 dark:bg-slate-900 ${className}`, "data-section": "richtexteditor-div-582", children: [_jsx("div", { className: "appkit-rich-text-editor__toolbar flex flex-wrap gap-1 border-b border-zinc-200 p-2 dark:border-slate-700", "data-section": "richtexteditor-div-583", children: toolbarActions.map((action) => (_jsx("button", { type: "button", title: action.title, onClick: action.run, disabled: disabled, className: "appkit-rich-text-editor__btn rounded px-2 py-1 text-xs font-medium text-zinc-700 transition hover:bg-zinc-50 disabled:cursor-not-allowed disabled:opacity-50 dark:text-zinc-200 dark:hover:bg-slate-800", children: action.label }, action.title))) }), _jsx("div", { ref: editorRef, role: "textbox", "aria-label": "Rich text editor", contentEditable: !disabled, suppressContentEditableWarning: true, "data-placeholder": placeholder, onInput: emitChange, onBlur: emitChange, className: `prose prose-sm max-w-none p-3 focus:outline-none dark:prose-invert ${minHeightClassName} ${disabled ? "cursor-not-allowed opacity-70" : ""}` })] }));
+    return (_jsxs("div", { className: `appkit-rich-text-editor rounded-lg border border-zinc-200 bg-[var(--appkit-color-surface)] border-[var(--appkit-color-border)] bg-[var(--appkit-color-surface)] ${className}`, "data-section": "richtexteditor-div-582", children: [_jsx("div", { className: "appkit-rich-text-editor__toolbar flex flex-wrap gap-1 border-b border-zinc-200 p-2 border-[var(--appkit-color-border)]", "data-section": "richtexteditor-div-583", children: toolbarActions.map((action) => (_jsx("button", { type: "button", title: action.title, onClick: action.run, disabled: disabled, className: "appkit-rich-text-editor__btn rounded px-2 py-1 text-xs font-medium text-zinc-700 transition hover:bg-zinc-50 disabled:cursor-not-allowed disabled:opacity-50 text-[var(--appkit-color-text-muted)] hover:bg-[var(--appkit-color-surface-elevated)]", children: action.label }, action.title))) }), _jsx("div", { ref: editorRef, role: "textbox", "aria-label": "Rich text editor", contentEditable: !disabled, suppressContentEditableWarning: true, "data-placeholder": placeholder, onInput: emitChange, onBlur: emitChange, className: `prose prose-sm max-w-none p-3 focus:outline-none dark:prose-invert ${minHeightClassName} ${disabled ? "cursor-not-allowed opacity-70" : ""}` })] }));
 }

package/dist/ui/components/Select.js

@@ -24,5 +24,5 @@ export function Select({ options, value, onChange, onValueChange, placeholder, l
                             className,
                         ]
                             .filter(Boolean)
-                            .join(" "), children: [placeholder ? (_jsx("option", { value: "", disabled: true, children: placeholder })) : null, options.map((option) => (_jsx("option", { value: option.value, disabled: option.disabled, children: option.label }, String(option.value))))] }), _jsx(Div, { className: "pointer-events-none absolute inset-y-0 right-3 flex items-center text-zinc-400 dark:text-zinc-400", "data-section": "select-div-594", children: _jsx("svg", { className: "h-4 w-4", viewBox: "0 0 20 20", fill: "currentColor", "aria-hidden": "true", children: _jsx("path", { fillRule: "evenodd", d: "M5.293 7.293a1 1 0 011.414 0L10 10.586l3.293-3.293a1 1 0 111.414 1.414l-4 4a1 1 0 01-1.414 0l-4-4a1 1 0 010-1.414z", clipRule: "evenodd" }) }) })] }), error ? (_jsx(Text, { size: "sm", variant: "error", className: "appkit-select__error", role: "alert", children: error })) : helperText ? (_jsx(Text, { size: "sm", variant: "secondary", className: "appkit-select__error", children: helperText })) : null] }));
+                            .join(" "), children: [placeholder ? (_jsx("option", { value: "", disabled: true, children: placeholder })) : null, options.map((option) => (_jsx("option", { value: option.value, disabled: option.disabled, children: option.label }, String(option.value))))] }), _jsx(Div, { className: "pointer-events-none absolute inset-y-0 right-3 flex items-center text-[var(--appkit-color-text-faint)]", "data-section": "select-div-594", children: _jsx("svg", { className: "h-4 w-4", viewBox: "0 0 20 20", fill: "currentColor", "aria-hidden": "true", children: _jsx("path", { fillRule: "evenodd", d: "M5.293 7.293a1 1 0 011.414 0L10 10.586l3.293-3.293a1 1 0 111.414 1.414l-4 4a1 1 0 01-1.414 0l-4-4a1 1 0 010-1.414z", clipRule: "evenodd" }) }) })] }), error ? (_jsx(Text, { size: "sm", variant: "error", className: "appkit-select__error", role: "alert", children: error })) : helperText ? (_jsx(Text, { size: "sm", variant: "secondary", className: "appkit-select__error", children: helperText })) : null] }));
 }

package/dist/ui/components/SettingsSection.js

@@ -13,11 +13,11 @@ import { Toggle } from "./Toggle";
 export function SettingsSection({ title, description, action, children, className, }) {
     return (_jsxs("section", { className: [
             "appkit-settings-section",
-            "space-y-3 rounded-lg border border-zinc-200 dark:border-zinc-700 p-4",
+            "space-y-3 rounded-lg border border-[var(--appkit-color-border)] p-4",
             className,
         ]
             .filter(Boolean)
-            .join(" "), children: [_jsxs("header", { className: "flex items-start justify-between gap-3", children: [_jsxs("div", { className: "flex-1 min-w-0", children: [_jsx(Heading, { level: 3, className: "text-base font-semibold text-zinc-900 dark:text-zinc-100", children: title }), description ? (_jsx(Text, { className: "mt-1 text-sm text-zinc-600 dark:text-zinc-400", children: description })) : null] }), action ? _jsx("div", { className: "flex-shrink-0", children: action }) : null] }), _jsx("div", { className: "space-y-3", children: children })] }));
+            .join(" "), children: [_jsxs("header", { className: "flex items-start justify-between gap-3", children: [_jsxs("div", { className: "flex-1 min-w-0", children: [_jsx(Heading, { level: 3, className: "text-base font-semibold text-[var(--appkit-color-text)]", children: title }), description ? (_jsx(Text, { className: "mt-1 text-sm text-[var(--appkit-color-text-muted)]", children: description })) : null] }), action ? _jsx("div", { className: "flex-shrink-0", children: action }) : null] }), _jsx("div", { className: "space-y-3", children: children })] }));
 }
 /**
  * `ToggleRow` — a labelled toggle with optional description, used wherever a
@@ -34,5 +34,5 @@ export function ToggleRow({ label, description, checked, onChange, disabled = fa
             className,
         ]
             .filter(Boolean)
-            .join(" "), children: [_jsxs("div", { className: "flex-1 min-w-0", children: [_jsx(Text, { className: "text-sm font-medium text-zinc-900 dark:text-zinc-100", children: label }), description ? (_jsx(Text, { className: "mt-0.5 text-xs text-zinc-500 dark:text-zinc-400", children: description })) : null] }), _jsx("div", { className: "flex-shrink-0 pt-0.5", children: _jsx(Toggle, { checked: checked, onChange: onChange, disabled: disabled, size: size }) })] }));
+            .join(" "), children: [_jsxs("div", { className: "flex-1 min-w-0", children: [_jsx(Text, { className: "text-sm font-medium text-[var(--appkit-color-text)]", children: label }), description ? (_jsx(Text, { className: "mt-0.5 text-xs text-[var(--appkit-color-text-muted)]", children: description })) : null] }), _jsx("div", { className: "flex-shrink-0 pt-0.5", children: _jsx(Toggle, { checked: checked, onChange: onChange, disabled: disabled, size: size }) })] }));
 }

package/dist/ui/components/SideModal.js

@@ -58,5 +58,5 @@ export function SideModal({ isOpen, onClose, title, side = "right", children, cl
                         className,
                     ]
                         .filter(Boolean)
-                        .join(" "), initial: reduced ? false : { x: slideX }, animate: { x: 0 }, exit: { x: slideX }, transition: SPRING_SNAPPY, children: [title && (_jsxs(Div, { className: "appkit-side-modal__header", children: [_jsx(Heading, { level: 2, id: titleId.current, className: "text-base font-semibold text-neutral-900 dark:text-neutral-100 dark:text-white truncate", children: title }), _jsx(Button, { variant: "ghost", size: "sm", onClick: onClose, "aria-label": "Close panel", className: "ml-2 flex-shrink-0", children: "\u2715" })] })), _jsx(Div, { className: "appkit-side-modal__body", children: children })] })] })) }));
+                        .join(" "), initial: reduced ? false : { x: slideX }, animate: { x: 0 }, exit: { x: slideX }, transition: SPRING_SNAPPY, children: [title && (_jsxs(Div, { className: "appkit-side-modal__header", children: [_jsx(Heading, { level: 2, id: titleId.current, className: "text-base font-semibold text-[var(--appkit-color-text)] dark:text-white truncate", children: title }), _jsx(Button, { variant: "ghost", size: "sm", onClick: onClose, "aria-label": "Close panel", className: "ml-2 flex-shrink-0", children: "\u2715" })] })), _jsx(Div, { className: "appkit-side-modal__body", children: children })] })] })) }));
 }

package/dist/ui/components/Slider.js

@@ -24,8 +24,8 @@ export function Slider({ value: controlledValue, defaultValue = 0, min = 0, max
     const handleChangeEnd = () => {
         onChangeEnd?.(value);
     };
-    return (_jsxs("div", { className: ["w-full", className].filter(Boolean).join(" "), "data-section": "slider-div-607", children: [(label || showValue) && (_jsxs("div", { className: "mb-2 flex items-center justify-between gap-3", "data-section": "slider-div-608", children: [label ? _jsx(Label, { htmlFor: inputId, children: label }) : _jsx("span", {}), showValue ? (_jsx(Span, { size: "sm", className: "tabular-nums text-zinc-600 dark:text-zinc-300", children: value })) : null] })), _jsxs("div", { className: "relative", "data-section": "slider-div-609", children: [_jsx("div", { "aria-hidden": "true", className: [
-                            "pointer-events-none absolute inset-x-0 top-1/2 -translate-y-1/2 overflow-hidden rounded-full bg-zinc-200 dark:bg-slate-700",
+    return (_jsxs("div", { className: ["w-full", className].filter(Boolean).join(" "), "data-section": "slider-div-607", children: [(label || showValue) && (_jsxs("div", { className: "mb-2 flex items-center justify-between gap-3", "data-section": "slider-div-608", children: [label ? _jsx(Label, { htmlFor: inputId, children: label }) : _jsx("span", {}), showValue ? (_jsx(Span, { size: "sm", className: "tabular-nums text-[var(--appkit-color-text-muted)]", children: value })) : null] })), _jsxs("div", { className: "relative", "data-section": "slider-div-609", children: [_jsx("div", { "aria-hidden": "true", className: [
+                            "pointer-events-none absolute inset-x-0 top-1/2 -translate-y-1/2 overflow-hidden rounded-full bg-zinc-200 bg-[var(--appkit-color-border)]",
                             SIZE_CLASSES[size],
                         ].join(" "), "data-section": "slider-div-610", children: _jsx("div", { className: [
                                 "h-full rounded-full bg-lime-600 dark:bg-pink-500",

package/dist/ui/components/StatsGrid.js

@@ -12,5 +12,5 @@ const variantClass = {
     flat: "appkit-stats-grid--flat",
 };
 export function StatsGrid({ stats, columns = 3, variant = "elevated", className, }) {
-    return (_jsx(Div, { className: classNames("appkit-stats-grid", columnsClass[columns], variantClass[variant], className), children: stats.map((stat, i) => (_jsx(Div, { className: "appkit-stats-grid__item", children: _jsxs(Div, { className: "appkit-stats-grid__item-inner", children: [_jsxs(Div, { children: [_jsx(Text, { className: "appkit-stats-grid__label", children: stat.label }), _jsx(Text, { className: "appkit-stats-grid__value", children: stat.value })] }), stat.icon && (_jsx(Div, { className: classNames("appkit-stats-grid__icon", stat.colorClass ?? "text-zinc-400 dark:text-zinc-400"), children: stat.icon }))] }) }, `${stat.label}-${i}`))) }));
+    return (_jsx(Div, { className: classNames("appkit-stats-grid", columnsClass[columns], variantClass[variant], className), children: stats.map((stat, i) => (_jsx(Div, { className: "appkit-stats-grid__item", children: _jsxs(Div, { className: "appkit-stats-grid__item-inner", children: [_jsxs(Div, { children: [_jsx(Text, { className: "appkit-stats-grid__label", children: stat.label }), _jsx(Text, { className: "appkit-stats-grid__value", children: stat.value })] }), stat.icon && (_jsx(Div, { className: classNames("appkit-stats-grid__icon", stat.colorClass ?? "text-[var(--appkit-color-text-faint)]"), children: stat.icon }))] }) }, `${stat.label}-${i}`))) }));
 }

package/dist/ui/components/Typography.js

@@ -215,9 +215,9 @@ export function Caption({ variant = "default", color, weight, className = "", ch
 }
 const SPAN_BORDER_MAP = {
     none: "",
-    default: "border border-zinc-200 dark:border-slate-700",
-    subtle: "border border-zinc-100 dark:border-zinc-800",
-    strong: "border border-zinc-300 dark:border-slate-600",
+    default: "border border-[var(--appkit-color-border)]",
+    subtle: "border border-[var(--appkit-color-border-subtle)]",
+    strong: "border border-[var(--appkit-color-border)]",
 };
 const SPAN_ROUNDED_MAP = {
     none: "",

package/dist/ui/components/surface-tokens.d.ts

@@ -26,8 +26,8 @@ export declare const SURFACE_MAP: {
     readonly "overlay-md": "bg-black/55";
     readonly "overlay-lg": "bg-black/60";
     readonly "overlay-xl": "bg-black/70";
-    readonly skeleton: "bg-zinc-300 dark:bg-slate-700";
-    readonly "skeleton-light": "bg-zinc-200 dark:bg-slate-800";
+    readonly skeleton: "bg-[var(--appkit-color-border)]";
+    readonly "skeleton-light": "bg-[var(--appkit-color-border-subtle)]";
 };
 export type SurfaceKey = keyof typeof SURFACE_MAP;
 export declare const PADDING_MAP: {
@@ -100,16 +100,16 @@ export declare const ROUNDED_MAP: {
 export type RoundedKey = keyof typeof ROUNDED_MAP;
 export declare const BORDER_MAP: {
     readonly none: "";
-    readonly default: "border border-zinc-200 dark:border-slate-700";
-    readonly subtle: "border border-zinc-100 dark:border-slate-800/60";
-    readonly strong: "border border-zinc-300 dark:border-slate-600";
-    readonly dashed: "border border-dashed border-zinc-300 dark:border-slate-600";
-    readonly bottom: "border-b border-zinc-200 dark:border-slate-700";
-    readonly "bottom-subtle": "border-b border-zinc-100 dark:border-slate-800/60";
-    readonly top: "border-t border-zinc-200 dark:border-slate-700";
-    readonly "top-subtle": "border-t border-zinc-100 dark:border-slate-800/60";
+    readonly default: "border border-[var(--appkit-color-border)]";
+    readonly subtle: "border border-[var(--appkit-color-border-subtle)]";
+    readonly strong: "border border-[var(--appkit-color-border)]";
+    readonly dashed: "border border-dashed border-[var(--appkit-color-border)]";
+    readonly bottom: "border-b border-[var(--appkit-color-border)]";
+    readonly "bottom-subtle": "border-b border-[var(--appkit-color-border-subtle)]";
+    readonly top: "border-t border-[var(--appkit-color-border)]";
+    readonly "top-subtle": "border-t border-[var(--appkit-color-border-subtle)]";
     /** 2px border for skeleton placeholder cards. */
-    readonly skeleton: "border-2 border-zinc-100 dark:border-slate-700";
+    readonly skeleton: "border-2 border-[var(--appkit-color-border-subtle)]";
 };
 export type BorderKey = keyof typeof BORDER_MAP;
 export declare const SHADOW_MAP: {

package/dist/ui/components/surface-tokens.js

@@ -31,9 +31,9 @@ export const SURFACE_MAP = {
     "overlay-md": "bg-black/55",
     "overlay-lg": "bg-black/60",
     "overlay-xl": "bg-black/70",
-    // Skeleton loader presets — light grey + dark variant.
-    skeleton: "bg-zinc-300 dark:bg-slate-700",
-    "skeleton-light": "bg-zinc-200 dark:bg-slate-800",
+    // Skeleton loader presets — theme-adaptive via CSS variables.
+    skeleton: "bg-[var(--appkit-color-border)]",
+    "skeleton-light": "bg-[var(--appkit-color-border-subtle)]",
 };
 export const PADDING_MAP = {
     none: "",
@@ -132,16 +132,16 @@ const ROUNDED_BOTTOM_MAP = {
 };
 export const BORDER_MAP = {
     none: "",
-    default: "border border-zinc-200 dark:border-slate-700",
-    subtle: "border border-zinc-100 dark:border-slate-800/60",
-    strong: "border border-zinc-300 dark:border-slate-600",
-    dashed: "border border-dashed border-zinc-300 dark:border-slate-600",
-    bottom: "border-b border-zinc-200 dark:border-slate-700",
-    "bottom-subtle": "border-b border-zinc-100 dark:border-slate-800/60",
-    top: "border-t border-zinc-200 dark:border-slate-700",
-    "top-subtle": "border-t border-zinc-100 dark:border-slate-800/60",
+    default: "border border-[var(--appkit-color-border)]",
+    subtle: "border border-[var(--appkit-color-border-subtle)]",
+    strong: "border border-[var(--appkit-color-border)]",
+    dashed: "border border-dashed border-[var(--appkit-color-border)]",
+    bottom: "border-b border-[var(--appkit-color-border)]",
+    "bottom-subtle": "border-b border-[var(--appkit-color-border-subtle)]",
+    top: "border-t border-[var(--appkit-color-border)]",
+    "top-subtle": "border-t border-[var(--appkit-color-border-subtle)]",
     /** 2px border for skeleton placeholder cards. */
-    "skeleton": "border-2 border-zinc-100 dark:border-slate-700",
+    "skeleton": "border-2 border-[var(--appkit-color-border-subtle)]",
 };
 export const SHADOW_MAP = {
     none: "",

package/dist/utils/safe-fire-forget.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Runs a non-critical promise in the background without blocking the caller.
+ *
+ * Use instead of `.catch(console.error)` for fire-and-forget operations
+ * (view counters, audit logs, cache invalidations, RTDB cleanup) where the
+ * caller must not fail even if the operation does.
+ *
+ * The operation's failure is logged at WARN level with the provided context
+ * label so on-call engineers can find it in structured logs.
+ *
+ * @param promise  Already-started async operation.
+ * @param context  Short label identifying the operation for log search (e.g. "blog: incrementViews").
+ */
+export declare function safeFireAndForget(promise: Promise<unknown>, context: string): void;

package/dist/utils/safe-fire-forget.js

@@ -0,0 +1,23 @@
+import { normalizeError } from "../errors/normalize";
+import { serverLogger } from "../monitoring/server-logger";
+/**
+ * Runs a non-critical promise in the background without blocking the caller.
+ *
+ * Use instead of `.catch(console.error)` for fire-and-forget operations
+ * (view counters, audit logs, cache invalidations, RTDB cleanup) where the
+ * caller must not fail even if the operation does.
+ *
+ * The operation's failure is logged at WARN level with the provided context
+ * label so on-call engineers can find it in structured logs.
+ *
+ * @param promise  Already-started async operation.
+ * @param context  Short label identifying the operation for log search (e.g. "blog: incrementViews").
+ */
+export function safeFireAndForget(promise, context) {
+    promise.catch((err) => {
+        void normalizeError(err);
+        serverLogger.warn(`safeFireAndForget: ${context} failed (non-critical, caller unaffected)`, {
+            error: err instanceof Error ? err.message : String(err),
+        });
+    });
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mohasinac/appkit",
-  "version": "3.2.7",
+  "version": "3.2.9",
   "license": "MIT",
   "publishConfig": {
     "access": "public"