@clicktap/ui 2.0.8 → 2.0.10

package/components/Badge/Badge.d.ts

@@ -1,3 +1,20 @@
 import { BadgeProps } from './Badge.types';
+/**
+ * ⚠️ Slot map — `classNames.badge` is the PILL (CTAP-1491).
+ *
+ * `@heroui/badge` rendered two elements, and its single badge element carried BOTH the absolute
+ * positioning and the whole visual treatment, so `classNames.badge` reached the thing that draws
+ * the badge. CTAP-1383 replaced it with this component, which splits that element in two — a
+ * positioning span and an animated pill — and the slot stayed on the positioning half. The pill
+ * then had no slot at all, so a consumer restyling "the badge" painted and sized a transparent
+ * wrapper while the pill kept its `variant` styling underneath: a coloured square behind the pill.
+ *
+ * Applying `badge` to both halves is not the fix — that is what paints the wrapper. So each element
+ * has its own slot:
+ *
+ *   base    the relative anchor (unchanged)
+ *   wrapper the absolutely-positioned span — placement and offset only
+ *   badge   the visible pill — colour, size, radius, typography
+ */
 export declare function Badge({ children, isInvisible, disableAnimation, placement, shape, className, classNames, showOutline, content, isDot, isOneChar, size, variant, ...props }: BadgeProps): import("react/jsx-runtime").JSX.Element;
 export default Badge;

package/components/Badge/Badge.js

@@ -1 +1 @@
-"use client";import{jsxs as V,jsx as n}from"react/jsx-runtime";import{useId as v}from"react";import{AnimatePresence as z,m as C}from"framer-motion";import{cn as a}from"../../utils/cn.js";const S={hidden:{opacity:0,scale:0},show:{opacity:1,scale:1}};function P({children:h,isInvisible:f,disableAnimation:l,placement:t="top-right",shape:e="rectangle",className:g,classNames:d,showOutline:c=!1,content:o,isDot:i,isOneChar:x,size:s="md",variant:r="solid",...b}){const m=v(),u=l?{duration:0}:{type:"spring",bounce:.3},w=String(o)?.length===1||x,p={sm:"text-xs",md:"text-sm",lg:"text-sm"},y=w?{sm:"w-4 h-4",md:"w-5 h-5",lg:"w-6 h-6"}[s]:{sm:"min-w-4 h-4",md:"min-w-5 h-5",lg:"min-w-6 h-6"}[s];return V("div",{...b,className:a("relative","inline-flex shrink-0",g,d?.base),children:[h,n("span",{className:a("p-0","border-0","absolute z-10","flex",[t==="top-right"&&e==="rectangle"&&"top-0.5 right-px",t==="top-right"&&e==="circle"&&"top-1 right-1",t==="bottom-right"&&e==="rectangle"&&"bottom-0.5 right-px",t==="bottom-right"&&e==="circle"&&"bottom-1 right-1",t==="top-left"&&e==="rectangle"&&"top-0.5 left-px",t==="top-left"&&e==="circle"&&"top-1 left-1",t==="bottom-left"&&e==="rectangle"&&"bottom-0.5 left-px",t==="bottom-left"&&e==="circle"&&"bottom-1 left-1"],[t==="top-right"&&"translate-x-1/2 -translate-y-1/2",t==="bottom-right"&&"translate-x-1/2 translate-y-1/2",t==="bottom-left"&&"-translate-x-1/2 translate-y-1/2",t==="top-left"&&"-translate-x-1/2 -translate-y-1/2"],d?.badge),children:n(z,{children:!f&&n(C.span,{layout:!0,variants:S,initial:l?"show":"hidden",transition:u,animate:"show",exit:"hidden",className:a("flex flex-wrap","place-content-center","z-10","box-border","rounded-full","py-0 px-1","font-normal text-fg","select-none","whitespace-normal",r==="faded"?"text-slate-800":"text-white",!o||i?"w-3.5 h-3.5":y,typeof o=="string"&&o.length>1||i?"text-xs":p[s],[r==="solid"&&"bg-surface-inverse-hover",r==="shadow"&&"bg-surface-inverse-hover",r==="flat"&&"bg-surface-inverse-hover/55",r==="faded"&&"bg-white"],[r==="faded"&&"border-2 border-solid border-surface-inverse-hover",c&&r!=="faded"&&"border-2 border-solid border-white"]),children:!i&&o},`badge-${m}`)})})]})}export{P as Badge,P as default};
+"use client";import{jsxs as V,jsx as a}from"react/jsx-runtime";import{useId as v}from"react";import{AnimatePresence as z,m as C}from"framer-motion";import{cn as l}from"../../utils/cn.js";const S={hidden:{opacity:0,scale:0},show:{opacity:1,scale:1}};function P({children:h,isInvisible:f,disableAnimation:d,placement:t="top-right",shape:e="rectangle",className:g,classNames:i,showOutline:c=!1,content:o,isDot:s,isOneChar:x,size:n="md",variant:r="solid",...b}){const m=v(),p=d?{duration:0}:{type:"spring",bounce:.3},w=String(o)?.length===1||x,u={sm:"text-xs",md:"text-sm",lg:"text-sm"},y=w?{sm:"w-4 h-4",md:"w-5 h-5",lg:"w-6 h-6"}[n]:{sm:"min-w-4 h-4",md:"min-w-5 h-5",lg:"min-w-6 h-6"}[n];return V("div",{...b,className:l("relative","inline-flex shrink-0",g,i?.base),children:[h,a("span",{className:l("p-0","border-0","absolute z-10","flex",[t==="top-right"&&e==="rectangle"&&"top-0.5 right-px",t==="top-right"&&e==="circle"&&"top-1 right-1",t==="bottom-right"&&e==="rectangle"&&"bottom-0.5 right-px",t==="bottom-right"&&e==="circle"&&"bottom-1 right-1",t==="top-left"&&e==="rectangle"&&"top-0.5 left-px",t==="top-left"&&e==="circle"&&"top-1 left-1",t==="bottom-left"&&e==="rectangle"&&"bottom-0.5 left-px",t==="bottom-left"&&e==="circle"&&"bottom-1 left-1"],[t==="top-right"&&"translate-x-1/2 -translate-y-1/2",t==="bottom-right"&&"translate-x-1/2 translate-y-1/2",t==="bottom-left"&&"-translate-x-1/2 translate-y-1/2",t==="top-left"&&"-translate-x-1/2 -translate-y-1/2"],i?.wrapper),children:a(z,{children:!f&&a(C.span,{layout:!0,variants:S,initial:d?"show":"hidden",transition:p,animate:"show",exit:"hidden",className:l("flex flex-wrap","place-content-center","z-10","box-border","rounded-full","py-0 px-1","font-normal text-fg","select-none","whitespace-normal",r==="faded"?"text-slate-800":"text-white",!o||s?"w-3.5 h-3.5":y,typeof o=="string"&&o.length>1||s?"text-xs":u[n],[r==="solid"&&"bg-surface-inverse-hover",r==="shadow"&&"bg-surface-inverse-hover",r==="flat"&&"bg-surface-inverse-hover/55",r==="faded"&&"bg-white"],[r==="faded"&&"border-2 border-solid border-surface-inverse-hover",c&&r!=="faded"&&"border-2 border-solid border-white"],i?.badge),children:!s&&o},`badge-${m}`)})})]})}export{P as Badge,P as default};

package/components/Badge/Badge.types.d.ts

@@ -4,7 +4,13 @@ import { HTMLAttributes, ReactNode } from 'react';
  * The heroui component only contributed two wrapper elements while every
  * visual class already lived here — importing it cost the whole @heroui
  * system (~25 KiB gz) in the initial bundle of every page via the header's
- * cart badge. Same prop names and defaults as before.
+ * cart badge.
+ *
+ * ⚠️ Prop names and defaults match the heroui version, but `classNames` does NOT map one-to-one and
+ * an earlier revision of this comment claimed it did. heroui rendered a single badge element that
+ * carried both positioning and appearance; this component splits it into a positioning wrapper and
+ * a pill, so there are three slots rather than two. `classNames.badge` still means the visible pill
+ * — see {@link BadgeProps.classNames} (CTAP-1491).
  */
 export type BadgeProps = Omit<HTMLAttributes<HTMLDivElement>, 'content'> & {
     children?: ReactNode;
@@ -15,8 +21,21 @@ export type BadgeProps = Omit<HTMLAttributes<HTMLDivElement>, 'content'> & {
     disableAnimation?: boolean;
     placement?: 'top-right' | 'top-left' | 'bottom-right' | 'bottom-left';
     shape?: 'rectangle' | 'circle';
+    /**
+     * Per-element class slots.
+     *
+     * ⚠️ `badge` is the visible PILL, not the positioning wrapper. Between CTAP-1383 and CTAP-1491 it
+     * landed on the wrapper, which has no background or radius of its own — so classes meant for the
+     * pill painted and sized a transparent box around it instead. If you worked around that with
+     * child variants (`[&>span]:bg-…`), drop the `[&>span]:` prefix: those classes now belong on
+     * `badge` directly, and left as-is they would target a child of the pill that does not exist.
+     */
     classNames?: {
+        /** The relative anchor wrapping `children`. */
         base?: string;
+        /** The absolutely-positioned span — placement and offset only; has no visual styling. */
+        wrapper?: string;
+        /** The visible pill — colour, size, radius, typography. */
         badge?: string;
     };
     showOutline?: boolean;

package/docs/migrations/2026/08/ui-2026-08-26-badge-classnames-badge-targets-the-pill.md

@@ -0,0 +1,116 @@
+# BUGFIX: Badge `classNames.badge` targets the pill again, and the wrapper gets its own slot
+
+**Date:** 2026-08-26
+**Package:** `@clicktap/ui`
+**Affects:** `src/components/Badge/Badge.tsx`, `Badge.types.ts`
+**Classification:** BUGFIX
+**Breaking:** ⚠️ Yes for anyone who worked around the CTAP-1383 behaviour — see Consumer Impact.
+**Ticket:** CTAP-1491
+
+## Summary
+
+`@heroui/badge` rendered **two** elements:
+
+```jsx
+<div className={slots.base(classNames.base)}>
+  {children}
+  <Component {...getBadgeProps()}>{content}</Component>   // slots.badge + classNames.badge
+</div>
+```
+
+That second element *was* the badge: it carried the absolute positioning **and** the whole visual
+treatment. So `classNames.badge` reached the thing that draws the badge.
+
+CTAP-1383 replaced heroui with an in-house Badge — worth doing, since importing heroui pulled ~25 KiB
+gz into every page's initial bundle via the header's cart badge. But it splits that one element into
+**three**:
+
+```
+<div>       base     relative anchor
+  <span>    —        absolute positioning: placement, translate
+    <m.span> —       the visible pill: rounded-full, bg, size, text, variant
+```
+
+…and `classNames.badge` stayed on the **middle** one. The pill had no slot at all, so its appearance
+was reachable only through `variant` and `size`.
+
+⚠️ A consumer restyling "the badge" therefore painted and sized a wrapper that has no background and
+no `rounded-full` of its own, while the pill kept its `variant` styling underneath — rendering a
+coloured square behind the pill.
+
+⚠️ **Nothing could catch this.** The prop still existed with the same name and type, so consumer code
+compiled, typechecked and linted clean; only the runtime element differed. `Badge.types.ts` also
+asserted "Same prop names and defaults as before", which was true of the signature and false of the
+behaviour — that sentence is now corrected.
+
+## What changed
+
+Three slots, one per element:
+
+| slot | element | what belongs there |
+|---|---|---|
+| `base` | the relative anchor | unchanged |
+| `wrapper` | **new** — the absolutely-positioned span | placement, offset |
+| `badge` | the visible pill | colour, size, radius, typography |
+
+⚠️ Applying `badge` to both halves was considered and rejected — painting the wrapper is the bug.
+
+`classNames.badge` is merged **last** on the pill, so `cn` (tailwind-merge) reconciles a consumer's
+size or colour against the computed `sizeVariant`/`variant` classes rather than leaving the outcome
+to specificity or stylesheet order.
+
+## Consumer Impact
+
+**If you never passed `classNames` to a Badge, nothing changes.** No component in this repo does,
+which is why the regression went unnoticed upstream in the first place.
+
+**If you have pre-CTAP-1383 (heroui-era) code**, your `classNames.badge` starts working again with no
+edit — that is the point of restoring the meaning.
+
+⚠️ **If you worked around CTAP-1383 with child variants, you must undo it.** The known shape is:
+
+```tsx
+// BEFORE — targeting the pill through the wrapper
+badge: cn(
+  'top-px',
+  '[&>span]:bg-brand-red [&>span]:text-white [&>span]:border-0',
+  '[&>span]:min-w-5 [&>span]:h-5',
+),
+```
+
+```tsx
+// AFTER — the pill has its own slot; positioning moves to `wrapper`
+wrapper: 'top-px',
+badge: cn(
+  'bg-brand-red text-white border-0',
+  'min-w-5 h-5',
+),
+```
+
+Left unchanged, `[&>span]:` now targets a `span` child *of the pill*, which does not exist — so every
+one of those declarations silently stops applying and the badge reverts to its `variant` styling.
+⚠️ Same failure shape as the original bug, so grep for `[&>span]:` near a Badge before upgrading.
+
+That workaround was always brittle for a second reason worth retiring: it depended on the pill
+remaining a direct `span` child of the wrapper, so any future wrapper element inside that span would
+have detached it silently.
+
+## Verification
+
+`src/components/Badge/Badge.spec.tsx` — 6 tests, the first exerciser `classNames` has had.
+
+**Mutation-tested.** Reverting to the CTAP-1383 wiring fails **5 of 6**. The sixth (`base` on the
+anchor) passes either way, correctly — `base` was never broken.
+
+Pinned deliberately: `badge` lands on the pill; `badge` does **not** also land on the wrapper (a
+positive-only assertion would pass if it were applied to both — the other wrong answer, and the one
+that reproduces the coloured square); `wrapper` lands on the wrapper and not the pill; `base` on the
+anchor only; the three slots resolve to three **different** elements (one element carrying all three
+would satisfy each assertion taken alone); and a consumer's `h-6` beats the computed `h-5` with no
+`h-5` left behind, which is what the merge-last ordering buys.
+
+A `ClassNameSlots` story tints each slot so the mapping is visible in Storybook.
+
+⚠️ **Not verified visually against a real brand theme.** The tests assert which element each class
+lands on, in jsdom. That the resulting badge *looks* right on a consumer's storefront is not
+something this suite can show.

package/docs/migrations/index.json

@@ -1,4 +1,14 @@
 [
+  {
+    "path": "2026/08/ui-2026-08-26-badge-classnames-badge-targets-the-pill.md",
+    "module": "libs/frontend-modules/ui",
+    "package": "@clicktap/ui",
+    "date": "2026-08-26",
+    "title": "BUGFIX: Badge `classNames.badge` targets the pill again, and the wrapper gets its own slot",
+    "classification": "BUGFIX",
+    "breaking": "⚠️ Yes for anyone who worked around the CTAP-1383 behaviour — see Consumer Impact.",
+    "affects": "`src/components/Badge/Badge.tsx`, `Badge.types.ts`"
+  },
   {
     "path": "2026/08/ui-2026-08-24-production-jsx-runtime-guard.md",
     "module": "libs/frontend-modules/ui",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@clicktap/ui",
-  "version": "2.0.8",
+  "version": "2.0.10",
   "private": false,
   "author": "Clicktap",
   "description": "A library of React UI components and low-level hooks.",

package/utils/collection/filterSearchParams.d.ts

@@ -5,9 +5,4 @@ import { CollectionFilterAppliedInterface } from '../../types/collection';
  * Boolean filters: ?is_new=true
  */
 export declare function filtersToSearchParams(appliedFilters: CollectionFilterAppliedInterface[]): URLSearchParams;
-/**
- * Deserialize URL search params into a minimal applied filters structure.
- * Returns partial filter objects with code + options/value — enough for
- * buildFilterGroups to construct the GraphQL query.
- */
-export declare function searchParamsToFilters(params: Record<string, string | string[] | undefined>): CollectionFilterAppliedInterface[];
+export declare function searchParamsToFilters(params: Record<string, string | string[] | undefined>, validAttributeCodes?: Iterable<string>): CollectionFilterAppliedInterface[];

package/utils/collection/filterSearchParams.js

@@ -1 +1 @@
-function p(r){const o=new URLSearchParams;for(const e of r){const i="__typename"in e?e.__typename:void 0;if(i==="CollectionFilterAppliedOption"&&"options"in e){const l=e.options.filter(n=>n.isApplied).map(n=>n.code);l.length>0&&o.set(e.code,l.join(","))}else if(i==="CollectionFilterAppliedBoolean"&&"appliedValue"in e){const t=e;o.set(e.code,t.appliedValue?"true":"false")}}return o}function a(r){const o=[];for(const[e,i]of Object.entries(r)){if(!i)continue;const t=Array.isArray(i)?i[0]:i;if(t)if(t==="true"||t==="false")o.push({__typename:"CollectionFilterAppliedBoolean",code:e,label:e,renderer:"boolean",type:"boolean",includeInFilters:!0,appliedValue:t==="true"});else{const l=t.split(",").filter(Boolean);l.length>0&&o.push({__typename:"CollectionFilterAppliedOption",code:e,label:e,renderer:"option",type:"option",includeInFilters:!0,isSearchable:!1,options:l.map(n=>({id:"",code:n,label:"",isApplied:!0}))})}}return o}export{p as filtersToSearchParams,a as searchParamsToFilters};
+function c(r){const i=new URLSearchParams;for(const e of r){const n="__typename"in e?e.__typename:void 0;if(n==="CollectionFilterAppliedOption"&&"options"in e){const l=e.options.filter(o=>o.isApplied).map(o=>o.code);l.length>0&&i.set(e.code,l.join(","))}else if(n==="CollectionFilterAppliedBoolean"&&"appliedValue"in e){const t=e;i.set(e.code,t.appliedValue?"true":"false")}}return i}const p=r=>r.replace(/-/g,"_");function d(r,i){const e=i?new Set([...i].map(p)):null,n=[];for(const[t,l]of Object.entries(r)){if(!l||e&&!e.has(p(t)))continue;const o=Array.isArray(l)?l[0]:l;if(o)if(o==="true"||o==="false")n.push({__typename:"CollectionFilterAppliedBoolean",code:t,label:t,renderer:"boolean",type:"boolean",includeInFilters:!0,appliedValue:o==="true"});else{const a=o.split(",").filter(Boolean);a.length>0&&n.push({__typename:"CollectionFilterAppliedOption",code:t,label:t,renderer:"option",type:"option",includeInFilters:!0,isSearchable:!1,options:a.map(s=>({id:"",code:s,label:"",isApplied:!0}))})}}return n}export{c as filtersToSearchParams,d as searchParamsToFilters};