@mohasinac/appkit 3.5.3 → 3.5.5

package/dist/ui/components/Semantic.js

@@ -59,9 +59,9 @@ export function sectionBackgroundStyle(bg) {
             return {};
     }
 }
-export const Section = React.forwardRef(({ tone = "plain", background, color, layout, gap, align, justify, className = "", surface, padding, paddingX, paddingY, rounded, border, shadow, children, ...props }, ref) => (_jsxs("section", { className: [
+export const Section = React.forwardRef(({ tone = "plain", background, color, layout, gap, align, justify, className = "", surface, padding, paddingX, paddingY, rounded, roundedTop, roundedBottom, border, shadow, overflow, children, ...props }, ref) => (_jsxs("section", { className: [
         SECTION_TONE_MAP[tone],
-        buildSurfaceClasses({ surface, padding, paddingX, paddingY, rounded, border, shadow }),
+        buildSurfaceClasses({ surface, padding, paddingX, paddingY, rounded, roundedTop, roundedBottom, border, shadow, overflow }),
         color ? SEMANTIC_COLOR_MAP[color] : "",
         layout ? SECTION_LAYOUT_MAP[layout] : "",
         gap ? SECTION_GAP_MAP[gap] : "",
@@ -73,13 +73,13 @@ export const Section = React.forwardRef(({ tone = "plain", background, color, la
         .filter(Boolean)
         .join(" "), ref: ref, ...props, children: [background?.value && (_jsxs(_Fragment, { children: [_jsx("span", { "aria-hidden": true, className: "absolute inset-0 -z-10", style: sectionBackgroundStyle(background) }), background.overlay?.enabled && (_jsx("span", { "aria-hidden": true, className: "absolute inset-0 -z-10", style: { backgroundColor: background.overlay.color, opacity: background.overlay.opacity } }))] })), children] })));
 Section.displayName = "Section";
-export function Article({ className = "", surface, padding, rounded, border, shadow, color, children, ...props }) {
-    return (_jsx("article", { className: [buildSurfaceClasses({ surface, padding, rounded, border, shadow }), color ? SEMANTIC_COLOR_MAP[color] : "", className].filter(Boolean).join(" "), ...props, children: children }));
+export function Article({ className = "", surface, padding, paddingX, paddingY, rounded, roundedTop, roundedBottom, border, shadow, overflow, color, children, ...props }) {
+    return (_jsx("article", { className: [buildSurfaceClasses({ surface, padding, paddingX, paddingY, rounded, roundedTop, roundedBottom, border, shadow, overflow }), color ? SEMANTIC_COLOR_MAP[color] : "", className].filter(Boolean).join(" "), ...props, children: children }));
 }
-export function Main({ className = "", surface, padding, paddingX, paddingY, rounded, border, shadow, color, children, ...props }) {
-    return (_jsx("main", { className: [buildSurfaceClasses({ surface, padding, paddingX, paddingY, rounded, border, shadow }), color ? SEMANTIC_COLOR_MAP[color] : "", className].filter(Boolean).join(" "), ...props, children: children }));
+export function Main({ className = "", surface, padding, paddingX, paddingY, rounded, roundedTop, roundedBottom, border, shadow, overflow, color, children, ...props }) {
+    return (_jsx("main", { className: [buildSurfaceClasses({ surface, padding, paddingX, paddingY, rounded, roundedTop, roundedBottom, border, shadow, overflow }), color ? SEMANTIC_COLOR_MAP[color] : "", className].filter(Boolean).join(" "), ...props, children: children }));
 }
-export const Aside = React.forwardRef(({ className = "", surface, padding, rounded, border, shadow, color, children, ...props }, ref) => (_jsx("aside", { className: [buildSurfaceClasses({ surface, padding, rounded, border, shadow }), color ? SEMANTIC_COLOR_MAP[color] : "", className].filter(Boolean).join(" "), ref: ref, ...props, children: children })));
+export const Aside = React.forwardRef(({ className = "", surface, padding, paddingX, paddingY, rounded, roundedTop, roundedBottom, border, shadow, overflow, color, children, ...props }, ref) => (_jsx("aside", { className: [buildSurfaceClasses({ surface, padding, paddingX, paddingY, rounded, roundedTop, roundedBottom, border, shadow, overflow }), color ? SEMANTIC_COLOR_MAP[color] : "", className].filter(Boolean).join(" "), ref: ref, ...props, children: children })));
 Aside.displayName = "Aside";
 const NAV_TEXT_SIZE_MAP = {
     xs: "text-xs",
@@ -97,8 +97,8 @@ const NAV_SPACING_MAP = {
 };
 const NAV_GAP_MAP = {
     none: "",
-    "2xs": "gap-1.5",
-    xs: "gap-1",
+    "2xs": "gap-1",
+    xs: "gap-1.5",
     sm: "gap-2",
     md: "gap-3",
     lg: "gap-4",
@@ -114,9 +114,9 @@ const NAV_COLOR_MAP = {
     muted: "appkit-color--muted",
     faint: "appkit-color--faint",
 };
-export function Nav({ surface, padding, rounded, border, shadow, spacing, gap, layout, color, textSize, className = "", children, ...props }) {
+export function Nav({ surface, padding, paddingX, paddingY, rounded, roundedTop, roundedBottom, border, shadow, overflow, spacing, gap, layout, color, textSize, className = "", children, ...props }) {
     return (_jsx("nav", { className: [
-            buildSurfaceClasses({ surface, padding, rounded, border, shadow }),
+            buildSurfaceClasses({ surface, padding, paddingX, paddingY, rounded, roundedTop, roundedBottom, border, shadow, overflow }),
             spacing ? NAV_SPACING_MAP[spacing] : "",
             gap ? NAV_GAP_MAP[gap] : "",
             layout ? NAV_LAYOUT_MAP[layout] : "",
@@ -125,11 +125,11 @@ export function Nav({ surface, padding, rounded, border, shadow, spacing, gap, l
             className,
         ].filter(Boolean).join(" "), ...props, children: children }));
 }
-export function BlockHeader({ className = "", surface, padding, rounded, border, shadow, children, ...props }) {
-    return (_jsx("header", { className: [buildSurfaceClasses({ surface, padding, rounded, border, shadow }), className].filter(Boolean).join(" "), ...props, children: children }));
+export function BlockHeader({ className = "", surface, padding, paddingX, paddingY, rounded, roundedTop, roundedBottom, border, shadow, overflow, children, ...props }) {
+    return (_jsx("header", { className: [buildSurfaceClasses({ surface, padding, paddingX, paddingY, rounded, roundedTop, roundedBottom, border, shadow, overflow }), className].filter(Boolean).join(" "), ...props, children: children }));
 }
-export function BlockFooter({ className = "", surface, padding, rounded, border, shadow, children, ...props }) {
-    return (_jsx("footer", { className: [buildSurfaceClasses({ surface, padding, rounded, border, shadow }), className].filter(Boolean).join(" "), ...props, children: children }));
+export function BlockFooter({ className = "", surface, padding, paddingX, paddingY, rounded, roundedTop, roundedBottom, border, shadow, overflow, children, ...props }) {
+    return (_jsx("footer", { className: [buildSurfaceClasses({ surface, padding, paddingX, paddingY, rounded, roundedTop, roundedBottom, border, shadow, overflow }), className].filter(Boolean).join(" "), ...props, children: children }));
 }
 const LIST_MARKER_MAP = {
     disc: "appkit-list--marker-disc",
@@ -263,8 +263,8 @@ const TABLE_SIZE_MAP = {
     md: "appkit-table--md",
     lg: "appkit-table--lg",
 };
-export function Table({ variant = "default", size = "md", stickyHeader = false, className = "", surface, padding, rounded, border, shadow, children, ...props }) {
-    return (_jsx("table", { className: ["appkit-table", TABLE_VARIANT_MAP[variant], TABLE_SIZE_MAP[size], stickyHeader ? "appkit-table--sticky-header" : "", buildSurfaceClasses({ surface, padding, rounded, border, shadow }), className].filter(Boolean).join(" "), ...props, children: children }));
+export function Table({ variant = "default", size = "md", stickyHeader = false, className = "", surface, padding, paddingX, paddingY, rounded, roundedTop, roundedBottom, border, shadow, overflow, children, ...props }) {
+    return (_jsx("table", { className: ["appkit-table", TABLE_VARIANT_MAP[variant], TABLE_SIZE_MAP[size], stickyHeader ? "appkit-table--sticky-header" : "", buildSurfaceClasses({ surface, padding, paddingX, paddingY, rounded, roundedTop, roundedBottom, border, shadow, overflow }), className].filter(Boolean).join(" "), ...props, children: children }));
 }
 const THEAD_SURFACE_MAP = {
     none: "",
@@ -444,8 +444,8 @@ export function Code({ color = "default", weight, size, padding, rounded, surfac
             className,
         ].filter(Boolean).join(" "), ...props, children: children }));
 }
-export function Pre({ className = "", surface, padding, rounded, border, shadow, children, ...props }) {
-    return (_jsx("pre", { className: ["appkit-pre", buildSurfaceClasses({ surface, padding, rounded, border, shadow }), className].filter(Boolean).join(" "), ...props, children: children }));
+export function Pre({ className = "", surface, padding, paddingX, paddingY, rounded, roundedTop, roundedBottom, border, shadow, overflow, children, ...props }) {
+    return (_jsx("pre", { className: ["appkit-pre", buildSurfaceClasses({ surface, padding, paddingX, paddingY, rounded, roundedTop, roundedBottom, border, shadow, overflow }), className].filter(Boolean).join(" "), ...props, children: children }));
 }
 const BLOCKQUOTE_COLOR_MAP = {
     default: "appkit-blockquote--default",
@@ -453,22 +453,22 @@ const BLOCKQUOTE_COLOR_MAP = {
     info: "appkit-blockquote--info",
     warning: "appkit-blockquote--warning",
 };
-export function Blockquote({ color = "default", className = "", surface, padding, paddingX, paddingY, rounded, border, shadow, children, ...props }) {
-    return (_jsx("blockquote", { className: ["appkit-blockquote", BLOCKQUOTE_COLOR_MAP[color], buildSurfaceClasses({ surface, padding, paddingX, paddingY, rounded, border, shadow }), className].filter(Boolean).join(" "), ...props, children: children }));
+export function Blockquote({ color = "default", className = "", surface, padding, paddingX, paddingY, rounded, roundedTop, roundedBottom, border, shadow, overflow, children, ...props }) {
+    return (_jsx("blockquote", { className: ["appkit-blockquote", BLOCKQUOTE_COLOR_MAP[color], buildSurfaceClasses({ surface, padding, paddingX, paddingY, rounded, roundedTop, roundedBottom, border, shadow, overflow }), className].filter(Boolean).join(" "), ...props, children: children }));
 }
-export function Figure({ className = "", surface, padding, rounded, border, shadow, children, ...props }) {
-    return (_jsx("figure", { className: ["appkit-figure", buildSurfaceClasses({ surface, padding, rounded, border, shadow }), className].filter(Boolean).join(" "), ...props, children: children }));
+export function Figure({ className = "", surface, padding, paddingX, paddingY, rounded, roundedTop, roundedBottom, border, shadow, overflow, children, ...props }) {
+    return (_jsx("figure", { className: ["appkit-figure", buildSurfaceClasses({ surface, padding, paddingX, paddingY, rounded, roundedTop, roundedBottom, border, shadow, overflow }), className].filter(Boolean).join(" "), ...props, children: children }));
 }
 export function Figcaption({ className = "", children, ...props }) {
     return (_jsx("figcaption", { className: ["appkit-figcaption", className].filter(Boolean).join(" "), ...props, children: children }));
 }
-export function Dl({ variant = "stacked", divide, className = "", surface, padding, rounded, border, shadow, children, ...props }) {
+export function Dl({ variant = "stacked", divide, className = "", surface, padding, paddingX, paddingY, rounded, roundedTop, roundedBottom, border, shadow, overflow, children, ...props }) {
     const divideCls = divide
         ? divide === "subtle"
             ? "appkit-stack--divide-subtle"
             : "appkit-stack--divide"
         : "";
-    return (_jsx("dl", { className: ["appkit-dl", variant === "inline" ? "appkit-dl--inline" : "appkit-dl--stacked", divideCls, buildSurfaceClasses({ surface, padding, rounded, border, shadow }), className].filter(Boolean).join(" "), ...props, children: children }));
+    return (_jsx("dl", { className: ["appkit-dl", variant === "inline" ? "appkit-dl--inline" : "appkit-dl--stacked", divideCls, buildSurfaceClasses({ surface, padding, paddingX, paddingY, rounded, roundedTop, roundedBottom, border, shadow, overflow }), className].filter(Boolean).join(" "), ...props, children: children }));
 }
 const DT_DD_COLOR_MAP = {
     default: "",

package/dist/ui/components/SideDrawer.js

@@ -124,18 +124,20 @@ export function SideDrawer({ isOpen, onClose, title, children, footer, mode = "v
     }, [isOpen]);
     // Prevent body scroll when drawer is open
     useEffect(() => {
-        if (isOpen) {
-            const scrollbarWidth = window.innerWidth - document.documentElement.clientWidth;
-            document.body.style.overflow = "hidden";
-            document.body.style.paddingRight = `${scrollbarWidth}px`;
-        }
-        else {
-            document.body.style.overflow = "";
-            document.body.style.paddingRight = "";
-        }
+        if (!isOpen)
+            return;
+        // Capture and restore the PRIOR values rather than hard-coding "" —
+        // otherwise closing this drawer while another overlay (Modal,
+        // SideModal, a second SideDrawer) is still open underneath wipes out
+        // that overlay's own scroll lock too.
+        const previousOverflow = document.body.style.overflow;
+        const previousPaddingRight = document.body.style.paddingRight;
+        const scrollbarWidth = window.innerWidth - document.documentElement.clientWidth;
+        document.body.style.overflow = "hidden";
+        document.body.style.paddingRight = `${scrollbarWidth}px`;
         return () => {
-            document.body.style.overflow = "";
-            document.body.style.paddingRight = "";
+            document.body.style.overflow = previousOverflow;
+            document.body.style.paddingRight = previousPaddingRight;
         };
     }, [isOpen]);
     useSwipe(drawerRef, {

package/dist/ui/components/SideModal.js

@@ -40,14 +40,16 @@ export function SideModal({ isOpen, onClose, title, side = "right", children, cl
     }, [isOpen]);
     // Prevent body scroll while open
     useEffect(() => {
-        if (isOpen) {
-            document.body.style.overflow = "hidden";
-        }
-        else {
-            document.body.style.overflow = "";
-        }
+        if (!isOpen)
+            return;
+        // Capture and restore the PRIOR value rather than hard-coding "" —
+        // otherwise closing this modal while another overlay is still open
+        // underneath (Modal, SideDrawer, a second SideModal) wipes out that
+        // overlay's own scroll lock too.
+        const previousOverflow = document.body.style.overflow;
+        document.body.style.overflow = "hidden";
         return () => {
-            document.body.style.overflow = "";
+            document.body.style.overflow = previousOverflow;
         };
     }, [isOpen]);
     const reduced = useReducedMotion();

package/dist/ui/components/SlottedListingView.d.ts

@@ -46,11 +46,22 @@ export interface SlottedListingViewProps {
      * - `public`: no managed state by default
      */
     portal?: ViewPortal;
-    /** Enable managed search state (default driven by portal, otherwise false). */
+    /**
+     * Currently unused — `renderSearch` is always invoked when provided,
+     * regardless of this flag. Kept as a no-op accepted prop because real
+     * consumers (CategoryProductsView, StoreProductsView, FAQPageContent, …)
+     * already pass their own self-contained `renderSearch` closures that
+     * manage search state externally and would lose their search UI if this
+     * ever started gating the render call. Do not wire this up to gate
+     * `renderSearch` without auditing every consumer's `renderSearch` first.
+     */
     manageSearch?: boolean;
     /** Enable managed selection state (default driven by portal, otherwise false). */
     manageSelection?: boolean;
-    /** Enable managed sort state (default empty string). */
+    /**
+     * Currently unused — see `manageSearch` above; `renderSort` is always
+     * invoked when provided, regardless of this flag, for the same reason.
+     */
     manageSort?: boolean;
     /** Wrap search + sort slots in a flex row. */
     inlineToolbar?: boolean;

package/dist/ui/components/StickyToolbar.js

@@ -12,21 +12,25 @@ const PADDING_CLS = {
     lg: "px-4 py-3",
     toolbar: "px-3 py-1.5",
 };
-function resolveOffset(offset) {
+function resolveOffsetClass(offset) {
     if (offset === "header") {
         return "top-[var(--header-height,0px)]";
     }
     if (offset === "header+nav") {
         return "top-[calc(var(--header-height,0px)+var(--appkit-navbar-height,2.5rem))]";
     }
-    // Numeric pixel offset.
-    return `top-[${offset}px]`;
+    // Numeric offsets are applied via inline style instead (see below) —
+    // Tailwind's static scanner can never see a dynamically-interpolated
+    // `top-[${offset}px]` arbitrary value, so no CSS rule would ever be
+    // generated for it in the compiled stylesheet.
+    return "";
 }
 export function StickyToolbar({ children, offset = "header", tone = "translucent", border = true, padding = "toolbar", z = "above-content", role, }) {
-    const offsetCls = resolveOffset(offset);
+    const offsetCls = resolveOffsetClass(offset);
+    const offsetStyle = typeof offset === "number" ? { top: `${offset}px` } : undefined;
     const borderCls = border ? "border-b border-[var(--appkit-color-border)]" : "";
     const zCls = z === "above-content" ? "z-10" : "z-[5]";
-    return (_jsx("div", { role: role, 
+    return (_jsx("div", { role: role, style: offsetStyle, 
         // for the translucent sticky-toolbar pattern. The header offset is
         // sourced from --header-height (set by AppLayoutShell at runtime).
         className: `sticky ${offsetCls} ${zCls} ${TONE_CLS[tone]} ${borderCls} ${PADDING_CLS[padding]}`, children: children }));

package/dist/ui/components/TagInput.js

@@ -5,8 +5,9 @@ import { Label, Span } from "./Typography";
 export function TagInput({ value, onChange, disabled = false, label, placeholder = "Add a tag...", className = "", helperText = "Press Enter or comma to add a tag", }) {
     const [draft, setDraft] = useState("");
     const inputRef = useRef(null);
+    const normalizeTag = (raw) => raw.trim().replace(/,+$/, "").trim();
     const addTag = (raw) => {
-        const tag = raw.trim().replace(/,+$/, "").trim();
+        const tag = normalizeTag(raw);
         if (!tag || value.includes(tag)) {
             setDraft("");
             return;
@@ -32,7 +33,19 @@ export function TagInput({ value, onChange, disabled = false, label, placeholder
         if (inputValue.includes(",")) {
             const parts = inputValue.split(",");
             const last = parts.pop() ?? "";
-            parts.forEach((part) => addTag(part));
+            // Accumulate locally instead of calling addTag() in a loop — addTag
+            // always computes `[...value, tag]` off the current render's `value`
+            // prop, so multiple synchronous calls in the same paste each started
+            // from the SAME stale array and every onChange but the last one got
+            // silently overwritten (only the final comma-segment ever survived).
+            let next = value;
+            for (const part of parts) {
+                const tag = normalizeTag(part);
+                if (tag && !next.includes(tag))
+                    next = [...next, tag];
+            }
+            if (next !== value)
+                onChange(next);
             setDraft(last);
             return;
         }

package/dist/ui/components/Textarea.js

@@ -1,3 +1,4 @@
+"use client";
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import React from "react";
 import { Label, Text } from "./Typography";

package/dist/ui/components/Toggle.js

@@ -43,5 +43,12 @@ export function Toggle({ checked: checkedProp, defaultChecked = false, onChange,
                     .join(" "), children: _jsx(Span, { "aria-hidden": "true", className: [
                         UI_TOGGLE.thumb,
                         checked ? UI_TOGGLE.thumbOn : UI_TOGGLE.thumbOff,
-                    ].join(" ") }) }), label && (_jsx(Label, { id: `${toggleId}-label`, htmlFor: toggleId, className: disabled ? "cursor-not-allowed opacity-60" : "cursor-pointer", onClick: disabled ? undefined : handleToggle, children: label }))] }));
+                    ].join(" ") }) }), label && (
+            // No onClick here — `htmlFor` on a `<label>` already makes the
+            // browser forward a click on the label to the labelable `<button>`
+            // above natively. Also attaching handleToggle here fired it TWICE
+            // per click (once from this handler, once from the native
+            // label→button forwarding), both reading the same stale `checked`
+            // closure, so onChange(true) could fire twice for one click.
+            _jsx(Label, { id: `${toggleId}-label`, htmlFor: toggleId, className: disabled ? "cursor-not-allowed opacity-60" : "cursor-pointer", children: label }))] }));
 }

package/dist/ui/components/UnsavedChangesModal.js

@@ -18,7 +18,18 @@ export function UnsavedChangesModal({ labels = {} }) {
     useEffect(() => {
         const subscription = eventBus.on(UNSAVED_CHANGES_EVENT, (...args) => {
             const resolveFn = args[0];
-            setResolve(() => resolveFn);
+            setResolve((prevResolve) => {
+                // A second UNSAVED_CHANGES_EVENT arrived before the user answered
+                // the first — resolve that abandoned promise with `false` instead
+                // of silently overwriting it and leaving it pending forever.
+                prevResolve?.(false);
+                // Returning `resolveFn` directly (not `() => resolveFn`) is
+                // correct here — the double-wrap trick is only needed when
+                // passing setState a bare function *value* (to stop React from
+                // treating it as an updater); inside an updater callback the
+                // return value already becomes the next state as-is.
+                return resolveFn;
+            });
             setIsOpen(true);
         });
         return () => subscription.unsubscribe();

package/dist/ui/forms/ColorPickerField.js

@@ -31,6 +31,13 @@ export function ColorPickerField({ name, label, hint, required, swatchWidth = "f
     }
     function handleChange(e) {
         onChange?.(e.target.value);
+        // FieldInput/FieldTextarea/FieldSelect/FieldCheckbox all clear the
+        // FormShell error for this field on change — this was the only Field*
+        // wrapper that omitted it, so a picked (valid) color never cleared a
+        // previously-set error until something else called clearErrors/
+        // setFieldError.
+        if (showError)
+            ctx?.clearFieldError(name);
     }
     return (_jsxs(Span, { layout: "flex", gap: "sm", className: "flex-col", children: [label != null && (_jsx(Label, { htmlFor: inputId, required: required, children: label })), _jsx("input", { id: inputId, type: "color", name: name, className: `h-10 ${SWATCH_WIDTH_MAP[swatchWidth]} rounded border border-[var(--appkit-color-border)] cursor-pointer ${className ?? ""}`, "aria-invalid": showError ? true : undefined, "aria-describedby": showError ? errorId : undefined, onBlur: handleBlur, onChange: handleChange, ...inputProps }), hint != null && !showError && (_jsx(Text, { size: "xs", color: "muted", children: hint })), showError && (_jsx(Text, { id: errorId, role: "alert", size: "xs", color: "error", children: error }))] }));
 }

package/dist/ui/forms/FieldCheckbox.js

@@ -21,5 +21,5 @@ export function FieldCheckbox({ name, label, hint, checked, onChange, onBlur, di
         ctx?.setFieldTouched(name);
         onBlur?.();
     }
-    return (_jsxs("div", { className: ["appkit-form-field", className].filter(Boolean).join(" "), children: [_jsx(Checkbox, { id: inputId, name: name, checked: checked, onChange: handleChange, onBlur: handleBlur, label: label, disabled: disabled, error: showError ? error : undefined, "aria-describedby": showError ? errorId : undefined }), !showError && hint && (_jsx(Text, { size: "sm", variant: "secondary", className: "appkit-form-field__hint", children: hint })), showError && (_jsx(Text, { id: errorId, size: "sm", variant: "error", className: "appkit-form-field__error", role: "alert", children: error }))] }));
+    return (_jsxs("div", { className: ["appkit-form-field", className].filter(Boolean).join(" "), children: [_jsx(Checkbox, { id: inputId, name: name, checked: checked, onChange: handleChange, onBlur: handleBlur, label: label, disabled: disabled, "aria-describedby": showError ? errorId : undefined }), !showError && hint && (_jsx(Text, { size: "sm", variant: "secondary", className: "appkit-form-field__hint", children: hint })), showError && (_jsx(Text, { id: errorId, size: "sm", variant: "error", className: "appkit-form-field__error", role: "alert", children: error }))] }));
 }

package/dist/utils/id-generators.d.ts

@@ -270,10 +270,13 @@ export type MediaFilenameContext = ({
 export declare function generateMediaFilename(ctx: MediaFilenameContext): string;
 export declare function validateMediaFilename(filename: string): boolean;
 /**
- * Derives the `MediaFilenameContext["type"]` a filename was generated under
- * (e.g. "catalogue-image") by matching against the same prefix list
- * {@link validateMediaFilename} uses — the longest matching prefix wins so
- * "blog-content-image" isn't mis-derived as "blog-cover"'s sibling "blog-".
+ * Derives the `MediaFilenameContext["type"]` family a filename was
+ * generated under (e.g. "catalogue-image") by matching against the same
+ * shape patterns {@link validateMediaFilename} uses. Sibling context types
+ * that share one generator (e.g. blog-cover/blog-content-image/
+ * blog-additional-image all produce the same shape as blog-image) resolve
+ * to that shared family name — the dispatcher itself can't distinguish them
+ * from the filename alone, since it never encoded the sub-type into the name.
  * Used at /api/media/finalize time to stamp `MediaAssetDocument.contextType`
  * without changing the finalize request contract.
  */

package/dist/utils/id-generators.js

@@ -74,7 +74,8 @@ export function generateOrderId(input) {
 export function generateFAQId(input) {
     if (input.customId?.trim())
         return input.customId.trim();
-    return `faq-${slugify(input.category)}-${slugify(input.question).substring(0, 50)}`;
+    const questionSlug = slugify(input.question).substring(0, 50).replace(/-+$/, "");
+    return `faq-${slugify(input.category)}-${questionSlug}`;
 }
 // ─── Coupon ───────────────────────────────────────────────────────────────────
 export function generateCouponId(code, customId) {
@@ -427,53 +428,74 @@ export function generateMediaFilename(ctx) {
     }
 }
 /**
- * W1-51 — validate that a filename matches the canonical pattern produced
- * by {@link generateMediaFilename}. Called from /api/media/sign before a
+ * W1-51 (regex fixed 2026-08-15 — see bug notes below) — validate that a
+ * filename matches the canonical pattern produced by
+ * {@link generateMediaFilename}. Called from /api/media/sign before a
  * signed-URL is issued so malformed names can never enter storage.
  *
- * Pattern: `<prefix>-<slug parts>-<YYYYMMDD>(-<N>)?(-<rand>)?\.<ext>` where
- * the prefix is one of the known media type tokens.
+ * The generator functions above put the type word (image/video/logo/
+ * banner/avatar) at the END of the slug portion, e.g.
+ * `product-{name}-{category}-{store}-image-{n}.ext`, NOT as a literal
+ * compound prefix like `product-image-{...}`. The previous version of this
+ * validator anchored on the compound-prefix shape and rejected real output
+ * from every generator except invoice/payout-doc/shipping-proof/
+ * refund-proof/catalogue-image — causing /api/media/sign to 500 for
+ * product/review/auction/preorder/store/brand/blog/event/category/user/
+ * carousel/rich-text uploads. Each pattern below mirrors one generator
+ * function's actual output shape. blog-cover/blog-content-image/
+ * blog-additional-image all dispatch to the same generator as blog-image
+ * (and the four event-* variants likewise share one shape), so one pattern
+ * validates all sub-types of that family.
  *
  * Returns true when the filename is acceptable.
  */
-const MEDIA_FILENAME_PREFIXES = [
-    "product-image", "product-video",
-    "review-image", "review-video",
-    "auction-image", "preorder-image",
-    "store-logo", "store-banner",
-    "brand-logo", "brand-banner",
-    "blog-image", "blog-cover", "blog-content-image", "blog-additional-image",
-    "event-image", "event-cover", "event-winner-image", "event-additional-image",
-    "rich-text-image",
-    "category-image",
-    "user-avatar",
-    "carousel-image",
-    "catalogue-image",
-    "invoice", "payout-doc",
-    "shipping-proof", "refund-proof",
+const SLUG_PART = "[a-z0-9]+(?:-[a-z0-9]+)*";
+const EXT_PART = "[a-z0-9]+";
+const DATE_PART = "\\d{8}";
+const MEDIA_FILENAME_PATTERNS = [
+    { context: "product-image", pattern: new RegExp(`^product-${SLUG_PART}-image-\\d+\\.${EXT_PART}$`) },
+    { context: "product-video", pattern: new RegExp(`^product-${SLUG_PART}-video-\\d+\\.${EXT_PART}$`) },
+    { context: "review-image", pattern: new RegExp(`^review-${SLUG_PART}-image-\\d+\\.${EXT_PART}$`) },
+    { context: "review-video", pattern: new RegExp(`^review-${SLUG_PART}-video-1\\.${EXT_PART}$`) },
+    { context: "auction-image", pattern: new RegExp(`^auction-${SLUG_PART}-image-\\d+\\.${EXT_PART}$`) },
+    { context: "preorder-image", pattern: new RegExp(`^preorder-${SLUG_PART}-image-\\d+\\.${EXT_PART}$`) },
+    { context: "store-logo", pattern: new RegExp(`^store-${SLUG_PART}-logo\\.${EXT_PART}$`) },
+    { context: "store-banner", pattern: new RegExp(`^store-${SLUG_PART}-banner\\.${EXT_PART}$`) },
+    { context: "brand-logo", pattern: new RegExp(`^brand-${SLUG_PART}-logo\\.${EXT_PART}$`) },
+    { context: "brand-banner", pattern: new RegExp(`^brand-${SLUG_PART}-banner\\.${EXT_PART}$`) },
+    { context: "blog-image", pattern: new RegExp(`^blog-${SLUG_PART}-image-\\d+\\.${EXT_PART}$`) },
+    { context: "event-image", pattern: new RegExp(`^event-${SLUG_PART}-image-\\d+\\.${EXT_PART}$`) },
+    { context: "rich-text-image", pattern: new RegExp(`^rich-text-${SLUG_PART}-image-\\d+\\.${EXT_PART}$`) },
+    { context: "category-image", pattern: new RegExp(`^category-${SLUG_PART}-image\\.${EXT_PART}$`) },
+    { context: "user-avatar", pattern: new RegExp(`^user-${SLUG_PART}-avatar\\.${EXT_PART}$`) },
+    { context: "carousel-image", pattern: new RegExp(`^carousel-${SLUG_PART}-image\\.${EXT_PART}$`) },
+    { context: "catalogue-image", pattern: new RegExp(`^catalogue-image-${SLUG_PART}-\\d+\\.${EXT_PART}$`) },
+    { context: "invoice", pattern: new RegExp(`^invoice-${SLUG_PART}-${DATE_PART}\\.pdf$`) },
+    { context: "payout-doc", pattern: new RegExp(`^payout-doc-${SLUG_PART}-${DATE_PART}\\.pdf$`) },
+    { context: "shipping-proof", pattern: new RegExp(`^shipping-proof-${SLUG_PART}-${DATE_PART}\\.${EXT_PART}$`) },
+    { context: "refund-proof", pattern: new RegExp(`^refund-proof-${SLUG_PART}-${SLUG_PART}-${DATE_PART}\\.${EXT_PART}$`) },
+    { context: "payment-proof", pattern: new RegExp(`^payment-proof-${SLUG_PART}-${SLUG_PART}-${DATE_PART}\\.${EXT_PART}$`) },
 ];
-const MEDIA_FILENAME_REGEX = new RegExp(`^(?:${MEDIA_FILENAME_PREFIXES.join("|")})-[a-z0-9]([a-z0-9-]*[a-z0-9])?(?:-\\d+)?\\.[a-z0-9]+$`);
 export function validateMediaFilename(filename) {
     if (!filename || filename.length > 256)
         return false;
     if (filename.includes("..") || filename.includes("/") || filename.includes("\\"))
         return false;
-    return MEDIA_FILENAME_REGEX.test(filename);
+    return MEDIA_FILENAME_PATTERNS.some(({ pattern }) => pattern.test(filename));
 }
 /**
- * Derives the `MediaFilenameContext["type"]` a filename was generated under
- * (e.g. "catalogue-image") by matching against the same prefix list
- * {@link validateMediaFilename} uses — the longest matching prefix wins so
- * "blog-content-image" isn't mis-derived as "blog-cover"'s sibling "blog-".
+ * Derives the `MediaFilenameContext["type"]` family a filename was
+ * generated under (e.g. "catalogue-image") by matching against the same
+ * shape patterns {@link validateMediaFilename} uses. Sibling context types
+ * that share one generator (e.g. blog-cover/blog-content-image/
+ * blog-additional-image all produce the same shape as blog-image) resolve
+ * to that shared family name — the dispatcher itself can't distinguish them
+ * from the filename alone, since it never encoded the sub-type into the name.
  * Used at /api/media/finalize time to stamp `MediaAssetDocument.contextType`
  * without changing the finalize request contract.
  */
 export function deriveContextTypeFromFilename(filename) {
-    const stem = filename.replace(/\.[^.]+$/, "");
-    const matches = MEDIA_FILENAME_PREFIXES.filter((prefix) => stem.startsWith(`${prefix}-`) || stem === prefix);
-    if (matches.length === 0)
-        return undefined;
-    return matches.reduce((longest, candidate) => (candidate.length > longest.length ? candidate : longest));
+    return MEDIA_FILENAME_PATTERNS.find(({ pattern }) => pattern.test(filename))?.context;
 }
 /**
  * Generates a scannable barcode identifier for a product listing.

package/dist/utils/number.formatter.js

@@ -40,10 +40,20 @@ export function formatFileSize(bytes) {
 export function formatCompactNumber(num) {
     if (num < 1000)
         return num.toString();
-    if (num < 1000000)
-        return `${(num / 1000).toFixed(1)}K`;
-    if (num < 1000000000)
-        return `${(num / 1000000).toFixed(1)}M`;
+    if (num < 1000000) {
+        const kValue = (num / 1000).toFixed(1);
+        // Rounding can push a value right up to the next unit's boundary
+        // (e.g. 999950 -> "1000.0K") — escalate instead of displaying "1000.0K".
+        if (kValue === "1000.0")
+            return `${(num / 1000000).toFixed(1)}M`;
+        return `${kValue}K`;
+    }
+    if (num < 1000000000) {
+        const mValue = (num / 1000000).toFixed(1);
+        if (mValue === "1000.0")
+            return `${(num / 1000000000).toFixed(1)}B`;
+        return `${mValue}M`;
+    }
     return `${(num / 1000000000).toFixed(1)}B`;
 }
 export function formatDecimal(num, decimals = 2) {
@@ -73,7 +83,10 @@ export function parseFormattedNumber(str) {
     }
     else if (lastDotIndex > -1 && lastCommaIndex === -1) {
         const afterDot = cleaned.substring(lastDotIndex + 1);
-        const isThousands = dotCount > 1 || afterDot.length > 3;
+        // A single separator followed by exactly 3 digits is the standard
+        // thousands-grouping width (e.g. "3.500" -> 3500), not a decimal — only
+        // 1-2 trailing digits are treated as a genuine decimal fraction.
+        const isThousands = dotCount > 1 || afterDot.length >= 3;
         if (isThousands)
             cleaned = cleaned.replace(/\./g, "");
         decimalSeparator = ".";
@@ -81,7 +94,7 @@ export function parseFormattedNumber(str) {
     }
     else if (lastCommaIndex > -1 && lastDotIndex === -1) {
         const afterComma = cleaned.substring(lastCommaIndex + 1);
-        const commaIsThousands = commaCount > 1 || afterComma.length > 3;
+        const commaIsThousands = commaCount > 1 || afterComma.length >= 3;
         if (commaIsThousands) {
             cleaned = cleaned.replace(/,/g, "");
             decimalSeparator = ".";

package/dist/utils/string.formatter.js

@@ -76,7 +76,10 @@ function applyMark(text, mark) {
     }
     if (mark.type === "link") {
         const rawHref = String(mark.attrs?.href ?? "#").trim();
-        const safe = /^(https?:\/\/|mailto:|\/|#)/i.test(rawHref) ? rawHref : "#";
+        // `\/(?!\/)` allows a single leading slash (same-site relative path) but
+        // rejects `//host/...` protocol-relative URLs, which browsers resolve to
+        // an arbitrary external origin despite "looking" like a local path.
+        const safe = /^(https?:\/\/|mailto:|\/(?!\/)|#)/i.test(rawHref) ? rawHref : "#";
         const href = safe.replace(/[&"<>]/g, (c) => ({ "&": "&amp;", '"': "&quot;", "<": "&lt;", ">": "&gt;" })[c] ?? c);
         return `<a href="${href}" rel="noopener noreferrer">${text}</a>`;
     }

package/package.json

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