@mohasinac/appkit 4.64.0 → 4.65.0

package/dist/ui/components/Button.js

@@ -143,7 +143,7 @@ const ACTION_ICON_SIZE = {
     md: "md",
     lg: "lg",
 };
-function ActionIcon({ action, confirmationBody, size, }) {
+function ActionIcon({ action, size, }) {
     const Glyph = resolveIcon(action?.iconKey);
     if (!Glyph)
         return null;

package/dist/ui/components/Chart.js

@@ -91,7 +91,6 @@ function useChartPalette(ref) {
         const series = Array.from({ length: CHART_MAX_SERIES }, (_, i) => v(`--chart-${i + 1}`));
         if (!series[0] && !warnedMissingStylesheet) {
             warnedMissingStylesheet = true;
-            // eslint-disable-next-line no-console
             console.warn("[appkit] <Chart> found no --chart-* custom properties. " +
                 'Import the stylesheet once at your app root: import "@mohasinac/appkit/styles". ' +
                 "Rendering with recharts' default colours until then.");

package/dist/ui/rich-text/RichText.js

@@ -215,7 +215,5 @@ export function RichText({ html, className = "", proseClass = "prose max-w-none
     if (segments.length === 1 && segments[0].type === "html") {
         return (_jsx(Div, { ref: ref, className: `appkit-rich-text ${proseClass} ${className}`, dangerouslySetInnerHTML: { __html: segments[0].html } }));
     }
-    return (_jsx(Div, { ref: ref, className: `appkit-rich-text ${proseClass} ${className}`, children: segments.map((seg, i) => seg.type === "html" ? (_jsx("div", { className: "appkit-rich-text__seg", dangerouslySetInnerHTML: { __html: seg.html } }, `h${i}`)) : (
-        // eslint-disable-next-line react/no-array-index-key
-        _jsx(ChartFromJson, { json: seg.json }, `c${i}`))) }));
+    return (_jsx(Div, { ref: ref, className: `appkit-rich-text ${proseClass} ${className}`, children: segments.map((seg, i) => seg.type === "html" ? (_jsx("div", { className: "appkit-rich-text__seg", dangerouslySetInnerHTML: { __html: seg.html } }, `h${i}`)) : (_jsx(ChartFromJson, { json: seg.json }, `c${i}`))) }));
 }

package/dist/ui/rich-text/RichTextRenderer.js

@@ -41,7 +41,5 @@ export function RichTextRenderer({ html, className = "", proseClass = "prose max
     if (segments.length === 1 && segments[0].type === "html") {
         return (_jsx("div", { className: wrapperClass, dangerouslySetInnerHTML: { __html: segments[0].html } }));
     }
-    return (_jsx("div", { className: wrapperClass, children: segments.map((seg, i) => seg.type === "html" ? (_jsx("div", { className: "appkit-rich-text__seg", dangerouslySetInnerHTML: { __html: seg.html } }, `h${i}`)) : (
-        // eslint-disable-next-line react/no-array-index-key
-        _jsx(ChartFromJson, { json: seg.json }, `c${i}`))) }));
+    return (_jsx("div", { className: wrapperClass, children: segments.map((seg, i) => seg.type === "html" ? (_jsx("div", { className: "appkit-rich-text__seg", dangerouslySetInnerHTML: { __html: seg.html } }, `h${i}`)) : (_jsx(ChartFromJson, { json: seg.json }, `c${i}`))) }));
 }

package/dist/utils/browser-storage.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Guest-state storage access.
+ *
+ * The guest cart, guest wishlist and guest history each carried a byte-identical private
+ * copy of this before 2026-10-24. All three are `"use client"` modules that are nonetheless
+ * imported into module graphs the server renders, which is why the `typeof window` guard is
+ * the entire point: reading `window.localStorage` during SSR throws, and the three features
+ * that need it are the three a signed-out visitor touches on first paint.
+ *
+ * Returns `null` rather than throwing or returning a stub — a caller must decide what "no
+ * storage" means for it, and a silent no-op stub would make a failed write indistinguishable
+ * from a successful one (Root Cause #59).
+ */
+export declare function getDefaultStorage(): Storage | null;

package/dist/utils/browser-storage.js

@@ -0,0 +1,18 @@
+/**
+ * Guest-state storage access.
+ *
+ * The guest cart, guest wishlist and guest history each carried a byte-identical private
+ * copy of this before 2026-10-24. All three are `"use client"` modules that are nonetheless
+ * imported into module graphs the server renders, which is why the `typeof window` guard is
+ * the entire point: reading `window.localStorage` during SSR throws, and the three features
+ * that need it are the three a signed-out visitor touches on first paint.
+ *
+ * Returns `null` rather than throwing or returning a stub — a caller must decide what "no
+ * storage" means for it, and a silent no-op stub would make a failed write indistinguishable
+ * from a successful one (Root Cause #59).
+ */
+export function getDefaultStorage() {
+    if (typeof window === "undefined")
+        return null;
+    return window.localStorage;
+}

package/dist/utils/classnames.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Join class names, dropping falsy entries.
+ *
+ * 🛑 This is deliberately NOT named `cn`, and it is deliberately not the same function as
+ * the `cn` exported from `style/tailwind`. That one runs `twMerge`, which DEDUPLICATES
+ * conflicting Tailwind utilities and therefore picks a winner between them. Both Tailwind
+ * configs here set `important: true`, and Root Cause #79 and #106 are both about which of
+ * two competing classes wins — so quietly moving twenty components from a plain join onto
+ * `twMerge` is a behaviour change in exactly the area that has already cost this project
+ * two incidents.
+ *
+ * Three features had a byte-identical private copy of the plain join before 2026-10-24
+ * (`features/filters/filterUtils.ts`, `features/forms/utils.ts`,
+ * `features/media/MediaLightbox.tsx`). This is that copy, once.
+ *
+ * Use `cn` from `style/tailwind` when conflict resolution is wanted; use this when the
+ * caller is simply assembling a list.
+ */
+export declare function joinClasses(...classes: Array<string | undefined | null | false>): string;

package/dist/utils/classnames.js

@@ -0,0 +1,21 @@
+/**
+ * Join class names, dropping falsy entries.
+ *
+ * 🛑 This is deliberately NOT named `cn`, and it is deliberately not the same function as
+ * the `cn` exported from `style/tailwind`. That one runs `twMerge`, which DEDUPLICATES
+ * conflicting Tailwind utilities and therefore picks a winner between them. Both Tailwind
+ * configs here set `important: true`, and Root Cause #79 and #106 are both about which of
+ * two competing classes wins — so quietly moving twenty components from a plain join onto
+ * `twMerge` is a behaviour change in exactly the area that has already cost this project
+ * two incidents.
+ *
+ * Three features had a byte-identical private copy of the plain join before 2026-10-24
+ * (`features/filters/filterUtils.ts`, `features/forms/utils.ts`,
+ * `features/media/MediaLightbox.tsx`). This is that copy, once.
+ *
+ * Use `cn` from `style/tailwind` when conflict resolution is wanted; use this when the
+ * caller is simply assembling a list.
+ */
+export function joinClasses(...classes) {
+    return classes.filter(Boolean).join(" ");
+}

package/dist/utils/search-params.d.ts

@@ -0,0 +1,44 @@
+/**
+ * URL search-param readers for route handlers.
+ *
+ * These were hand-copied into 27 route files before 2026-10-24 — `numParam` into 18
+ * (16 byte-identical) and `param` into 9 (all 9 identical). They are here so there is one
+ * definition, per the Duplication Decision Framework's "≥3 copies" and "same prop surface"
+ * triggers; `audit-duplicate-helpers` keeps it that way.
+ *
+ * Import this module directly (Root Cause #18) — these are deliberately NOT re-exported
+ * from `appkit/src/index.ts`, which is already 10k lines and is what the cold build parses.
+ */
+/** Read a raw search param. `null` when absent — never `""` for a missing key. */
+export declare function param(url: URL, key: string): string | null;
+/**
+ * Read a numeric search param, falling back when absent or unparseable.
+ *
+ * 🛑 Uses `Number`, not `parseInt`, so `"12abc"` is rejected to the fallback rather than
+ * silently read as 12. That is the behaviour all 16 identical copies had, and a page size
+ * of 12 derived from a typo'd param is worse than the default.
+ */
+export declare function numParam(url: URL, key: string, fallback: number): number;
+/**
+ * Read an integer search param where "absent" and "zero" must stay distinguishable.
+ *
+ * Separate from `numParam` on purpose: a caller that needs to know whether the param was
+ * supplied at all cannot get that from a fallback. `parseInt` here is also deliberate —
+ * this one is for tier/depth values where a trailing fragment is tolerable.
+ */
+/**
+ * Next's `searchParams` prop shape — a repeated query key arrives as an array.
+ *
+ * Six index page views declared this identically before 2026-10-24.
+ */
+export type SearchParamsRecord = Record<string, string | string[]>;
+/**
+ * Read one value out of Next's `searchParams`, taking the first of a repeated key.
+ *
+ * 🛑 Returns `""` for absent, NOT `null` — unlike `param` above, which reads a `URL`. The
+ * asymmetry is deliberate and matches what all six copies did: these feed filter builders
+ * that treat empty string as "no filter", and a `null` there would print as "null" in a
+ * Sieve clause and match nothing (Root Cause #62's shape).
+ */
+export declare function firstParam(params: SearchParamsRecord, key: string): string;
+export declare function intParamOrNull(url: URL, key: string): number | null;

package/dist/utils/search-params.js

@@ -0,0 +1,46 @@
+/**
+ * URL search-param readers for route handlers.
+ *
+ * These were hand-copied into 27 route files before 2026-10-24 — `numParam` into 18
+ * (16 byte-identical) and `param` into 9 (all 9 identical). They are here so there is one
+ * definition, per the Duplication Decision Framework's "≥3 copies" and "same prop surface"
+ * triggers; `audit-duplicate-helpers` keeps it that way.
+ *
+ * Import this module directly (Root Cause #18) — these are deliberately NOT re-exported
+ * from `appkit/src/index.ts`, which is already 10k lines and is what the cold build parses.
+ */
+/** Read a raw search param. `null` when absent — never `""` for a missing key. */
+export function param(url, key) {
+    return url.searchParams.get(key);
+}
+/**
+ * Read a numeric search param, falling back when absent or unparseable.
+ *
+ * 🛑 Uses `Number`, not `parseInt`, so `"12abc"` is rejected to the fallback rather than
+ * silently read as 12. That is the behaviour all 16 identical copies had, and a page size
+ * of 12 derived from a typo'd param is worse than the default.
+ */
+export function numParam(url, key, fallback) {
+    const v = url.searchParams.get(key);
+    const n = v !== null ? Number(v) : NaN;
+    return Number.isFinite(n) ? n : fallback;
+}
+/**
+ * Read one value out of Next's `searchParams`, taking the first of a repeated key.
+ *
+ * 🛑 Returns `""` for absent, NOT `null` — unlike `param` above, which reads a `URL`. The
+ * asymmetry is deliberate and matches what all six copies did: these feed filter builders
+ * that treat empty string as "no filter", and a `null` there would print as "null" in a
+ * Sieve clause and match nothing (Root Cause #62's shape).
+ */
+export function firstParam(params, key) {
+    const v = params[key];
+    return Array.isArray(v) ? (v[0] ?? "") : (v ?? "");
+}
+export function intParamOrNull(url, key) {
+    const v = url.searchParams.get(key);
+    if (v === null)
+        return null;
+    const n = Number.parseInt(v, 10);
+    return Number.isFinite(n) ? n : null;
+}

package/dist/utils/sieve-builder.d.ts

@@ -34,3 +34,16 @@ export declare function expandSieveParam(field: string, value: string | null, op
 /** Join Sieve clauses with comma (AND) — drops falsy values */
 export declare function sieveAnd(...clauses: (string | null | undefined | false)[]): string;
 export { sortBy } from "../constants/sort";
+/**
+ * Keep only the Sieve clauses whose field is allow-listed, dropping the rest silently.
+ *
+ * 🛑 "Silently" is the correct behaviour here and is not Root Cause #59. `sieve.ts` sets
+ * `throwExceptions: false`, so an un-allowlisted field is *already* dropped one layer down —
+ * this function exists so the drop happens where the allow-list is declared rather than
+ * inside the query adapter, where Root Cause #62 showed it turns a scoped page into an
+ * unfiltered one. A raw `f=` is attacker-controlled input, so rejecting the request would
+ * also make a probe distinguishable from a valid query.
+ *
+ * Three route files carried a byte-identical private copy before 2026-10-24.
+ */
+export declare function validateSieveFilters(raw: string, allowedFields: ReadonlySet<string>): string;

package/dist/utils/sieve-builder.js

@@ -63,3 +63,25 @@ export function sieveAnd(...clauses) {
     return clauses.filter(Boolean).join(",");
 }
 export { sortBy } from "../constants/sort.js";
+/**
+ * Keep only the Sieve clauses whose field is allow-listed, dropping the rest silently.
+ *
+ * 🛑 "Silently" is the correct behaviour here and is not Root Cause #59. `sieve.ts` sets
+ * `throwExceptions: false`, so an un-allowlisted field is *already* dropped one layer down —
+ * this function exists so the drop happens where the allow-list is declared rather than
+ * inside the query adapter, where Root Cause #62 showed it turns a scoped page into an
+ * unfiltered one. A raw `f=` is attacker-controlled input, so rejecting the request would
+ * also make a probe distinguishable from a valid query.
+ *
+ * Three route files carried a byte-identical private copy before 2026-10-24.
+ */
+export function validateSieveFilters(raw, allowedFields) {
+    return raw
+        .split(",")
+        .map((c) => c.trim())
+        .filter((c) => {
+        const m = c.match(/^([^<>=!@]+)\s*(?:==|!=|<=|>=|<|>|@=\*?)/);
+        return m ? allowedFields.has(m[1].trim()) : false;
+    })
+        .join(",");
+}

package/dist/utils/string.formatter.d.ts

@@ -19,3 +19,15 @@ export declare function proseMirrorToHtml(value: string): string;
  * Supports ProseMirror JSON strings, existing HTML, and plain text.
  */
 export declare function normalizeRichTextHtml(value: string): string;
+/**
+ * Normalize a description field of unknown shape into HTML, for a detail page.
+ *
+ * Every listing-type detail view reads `product.description`, which is typed loosely
+ * because the field holds a plain string on older documents and ProseMirror JSON on newer
+ * ones. Seven views had a byte-identical private copy of this before 2026-10-24.
+ *
+ * 🛑 `JSON.stringify` on a non-string is the fallback, not the intent — it exists so a
+ * document carrying an unexpected shape renders *something* legible instead of
+ * `[object Object]`. `normalizeRichTextHtml` then decides whether that is already markup.
+ */
+export declare function toDescriptionHtml(raw: unknown): string;

package/dist/utils/string.formatter.js

@@ -161,3 +161,20 @@ export function normalizeRichTextHtml(value) {
     }
     return `<p>${escapeHtml(normalized).replace(/\r?\n/g, "<br />")}</p>`;
 }
+/**
+ * Normalize a description field of unknown shape into HTML, for a detail page.
+ *
+ * Every listing-type detail view reads `product.description`, which is typed loosely
+ * because the field holds a plain string on older documents and ProseMirror JSON on newer
+ * ones. Seven views had a byte-identical private copy of this before 2026-10-24.
+ *
+ * 🛑 `JSON.stringify` on a non-string is the fallback, not the intent — it exists so a
+ * document carrying an unexpected shape renders *something* legible instead of
+ * `[object Object]`. `normalizeRichTextHtml` then decides whether that is already markup.
+ */
+export function toDescriptionHtml(raw) {
+    if (!raw)
+        return "";
+    const s = typeof raw === "string" ? raw : JSON.stringify(raw);
+    return normalizeRichTextHtml(s);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mohasinac/appkit",
-  "version": "4.64.0",
+  "version": "4.65.0",
   "license": "MIT",
   "publishConfig": {
     "access": "public"
@@ -234,7 +234,7 @@
   "scripts": {
     "postinstall": "node scripts/dedupe-peer-deps.mjs",
     "build": "node scripts/dedupe-peer-deps.mjs && node -e \"const fs=require('fs');for(const t of ['tsconfig.build.tsbuildinfo','dist']){try{fs.rmSync(t,{recursive:true})}catch(e){}}\" && tsc -p tsconfig.build.json && node scripts/copy-assets.mjs && node scripts/fix-esm-extensions.mjs && tailwindcss -i src/tailwind-input.css -o dist/tailwind-utilities.css --minify && node scripts/bundle-css.mjs && node scripts/verify-css-build.mjs && node scripts/verify-esm-dist.mjs --quick && node scripts/write-build-stamp.mjs",
-    "prepublishOnly": "npm run build",
+    "prepublishOnly": "node scripts/prepublish-gate.mjs && npm run build",
     "watch": "concurrently --kill-others --restart-tries 0 --names \"ts,css\" \"tsc -p tsconfig.build.json --watch\" \"npm run watch:css\"",
     "watch:css": "tailwindcss -i src/tailwind-input.css -o dist/tailwind-utilities.css --watch",
     "audit": "node scripts/audit-violations.mjs",