@nqlib/nqui 0.4.3 → 0.4.4

package/dist/sonner-CpmECDBk.js

@@ -0,0 +1,179 @@
+import { jsx as a } from "react/jsx-runtime";
+import * as i from "react";
+import { Toaster as T } from "sonner";
+import { HugeiconsIcon as s } from "@hugeicons/react";
+import { Loading03Icon as S, MultiplicationSignCircleIcon as I, Alert02Icon as E, InformationCircleIcon as C, CheckmarkCircle02Icon as N } from "@hugeicons/core-free-icons";
+var z = (t, n, p, c, l, r, u, f) => {
+  let e = document.documentElement, g = ["light", "dark"];
+  function d(o) {
+    (Array.isArray(t) ? t : [t]).forEach((m) => {
+      let v = m === "class", k = v && r ? l.map((x) => r[x] || x) : l;
+      v ? (e.classList.remove(...k), e.classList.add(r && r[o] ? r[o] : o)) : e.setAttribute(m, o);
+    }), w(o);
+  }
+  function w(o) {
+    f && g.includes(o) && (e.style.colorScheme = o);
+  }
+  function y() {
+    return window.matchMedia("(prefers-color-scheme: dark)").matches ? "dark" : "light";
+  }
+  if (c) d(c);
+  else try {
+    let o = localStorage.getItem(n) || p, m = u && o === "system" ? y() : o;
+    d(m);
+  } catch {
+  }
+}, W = i.createContext(void 0), A = { setTheme: (t) => {
+}, themes: [] }, L = () => {
+  var t;
+  return (t = i.useContext(W)) != null ? t : A;
+};
+i.memo(({ forcedTheme: t, storageKey: n, attribute: p, enableSystem: c, enableColorScheme: l, defaultTheme: r, value: u, themes: f, nonce: e, scriptProps: g }) => {
+  let d = JSON.stringify([p, n, r, t, f, u, c, l]).slice(1, -1);
+  return i.createElement("script", { ...g, suppressHydrationWarning: !0, nonce: typeof window > "u" ? e : "", dangerouslySetInnerHTML: { __html: `(${z.toString()})(${d})` } });
+});
+const b = "nqui-toast-styles-v2";
+function M() {
+  if (typeof document > "u" || document.getElementById(b)) return;
+  const t = document.createElement("style");
+  t.id = b, t.textContent = `
+      /* Pill toast — inverted surface: dark-on-light app, light-on-dark app */
+      [data-sonner-toast] .cn-toast {
+        border: 1px solid color-mix(in oklch, var(--normal-text) 18%, transparent) !important;
+        border-radius: 9999px !important;
+        box-shadow:
+          0 1px 0 0 color-mix(in oklch, var(--normal-text) 12%, transparent),
+          0 1px 2px 0 oklch(0.15 0 0 / 0.08);
+        transition: all 200ms ease-in-out !important;
+      }
+
+      .dark [data-sonner-toast] .cn-toast {
+        box-shadow:
+          0 1px 0 0 color-mix(in oklch, var(--normal-text) 14%, transparent),
+          0 1px 2px 0 oklch(0.15 0 0 / 0.12);
+      }
+
+      [data-sonner-toast] .cn-toast.toast-success {
+        border-left-width: 3px !important;
+        border-left-color: var(--success-500) !important;
+      }
+
+      [data-sonner-toast] .cn-toast.toast-error {
+        border-left-width: 3px !important;
+        border-left-color: var(--danger-500) !important;
+      }
+
+      [data-sonner-toast] .cn-toast.toast-warning {
+        border-left-width: 3px !important;
+        border-left-color: var(--warning-500) !important;
+      }
+
+      [data-sonner-toast] .cn-toast.toast-info {
+        border-left-width: 3px !important;
+        border-left-color: var(--info-500) !important;
+      }
+
+      [data-sonner-toast] .cn-toast.toast-loading {
+        border-left-width: 3px !important;
+        border-left-color: var(--primary-500) !important;
+      }
+
+      .cn-toast .toast-icon-success { color: var(--success); }
+      .cn-toast .toast-icon-error { color: var(--destructive); }
+      .cn-toast .toast-icon-warning { color: var(--warning); }
+      .cn-toast .toast-icon-info { color: var(--info); }
+      .cn-toast .toast-icon-loading { color: var(--primary); }
+    `, document.head.appendChild(t);
+}
+const h = ({ ...t }) => {
+  const { theme: n = "system" } = L();
+  return i.useEffect(() => {
+    M();
+  }, []), /* @__PURE__ */ a(
+    T,
+    {
+      theme: n,
+      className: "toaster group",
+      icons: {
+        success: /* @__PURE__ */ a(
+          s,
+          {
+            icon: N,
+            strokeWidth: 2,
+            className: "size-4 text-success toast-icon-success"
+          }
+        ),
+        info: /* @__PURE__ */ a(
+          s,
+          {
+            icon: C,
+            strokeWidth: 2,
+            className: "size-4 text-info toast-icon-info"
+          }
+        ),
+        warning: /* @__PURE__ */ a(
+          s,
+          {
+            icon: E,
+            strokeWidth: 2,
+            className: "size-4 text-warning toast-icon-warning"
+          }
+        ),
+        error: /* @__PURE__ */ a(
+          s,
+          {
+            icon: I,
+            strokeWidth: 2,
+            className: "size-4 text-destructive toast-icon-error"
+          }
+        ),
+        loading: /* @__PURE__ */ a(
+          s,
+          {
+            icon: S,
+            strokeWidth: 2,
+            className: "size-4 text-primary toast-icon-loading animate-spin"
+          }
+        )
+      },
+      style: {
+        /* Invert page chrome: light UI → dark toast; dark UI → light toast */
+        "--normal-bg": "var(--foreground)",
+        "--normal-text": "var(--background)",
+        "--normal-border": "color-mix(in oklch, var(--background) 25%, transparent)",
+        "--border-radius": "9999px",
+        "--success-bg": "var(--success)",
+        "--success-text": "var(--success-foreground)",
+        "--success-border": "var(--success-400)",
+        "--error-bg": "var(--destructive)",
+        "--error-text": "var(--destructive-foreground)",
+        "--error-border": "var(--danger-400)",
+        "--warning-bg": "var(--warning)",
+        "--warning-text": "var(--warning-foreground)",
+        "--warning-border": "var(--warning-400)",
+        "--info-bg": "var(--info)",
+        "--info-text": "var(--info-foreground)",
+        "--info-border": "var(--info-400)"
+      },
+      toastOptions: {
+        classNames: {
+          toast: "cn-toast",
+          success: "toast-success",
+          error: "toast-error",
+          warning: "toast-warning",
+          info: "toast-info",
+          loading: "toast-loading"
+        }
+      },
+      ...t
+    }
+  );
+};
+h.displayName = "Toaster";
+const j = h, P = h;
+export {
+  P as E,
+  h as T,
+  j as a,
+  L as z
+};

package/dist/sonner-nE9hIalJ.cjs

@@ -0,0 +1,48 @@
+"use strict";const c=require("react/jsx-runtime"),T=require("react"),j=require("sonner"),i=require("@hugeicons/react"),l=require("@hugeicons/core-free-icons");function E(t){const o=Object.create(null,{[Symbol.toStringTag]:{value:"Module"}});if(t){for(const r in t)if(r!=="default"){const n=Object.getOwnPropertyDescriptor(t,r);Object.defineProperty(o,r,n.get?n:{enumerable:!0,get:()=>t[r]})}}return o.default=t,Object.freeze(o)}const d=E(T);var N=(t,o,r,n,u,a,f,x)=>{let s=document.documentElement,h=["light","dark"];function m(e){(Array.isArray(t)?t:[t]).forEach(p=>{let v=p==="class",S=v&&a?u.map(b=>a[b]||b):u;v?(s.classList.remove(...S),s.classList.add(a&&a[e]?a[e]:e)):s.setAttribute(p,e)}),k(e)}function k(e){x&&h.includes(e)&&(s.style.colorScheme=e)}function I(){return window.matchMedia("(prefers-color-scheme: dark)").matches?"dark":"light"}if(n)m(n);else try{let e=localStorage.getItem(o)||r,p=f&&e==="system"?I():e;m(p)}catch{}},C=d.createContext(void 0),O={setTheme:t=>{},themes:[]},y=()=>{var t;return(t=d.useContext(C))!=null?t:O};d.memo(({forcedTheme:t,storageKey:o,attribute:r,enableSystem:n,enableColorScheme:u,defaultTheme:a,value:f,themes:x,nonce:s,scriptProps:h})=>{let m=JSON.stringify([r,o,a,t,x,f,n,u]).slice(1,-1);return d.createElement("script",{...h,suppressHydrationWarning:!0,nonce:typeof window>"u"?s:"",dangerouslySetInnerHTML:{__html:`(${N.toString()})(${m})`}})});const w="nqui-toast-styles-v2";function z(){if(typeof document>"u"||document.getElementById(w))return;const t=document.createElement("style");t.id=w,t.textContent=`
+      /* Pill toast — inverted surface: dark-on-light app, light-on-dark app */
+      [data-sonner-toast] .cn-toast {
+        border: 1px solid color-mix(in oklch, var(--normal-text) 18%, transparent) !important;
+        border-radius: 9999px !important;
+        box-shadow:
+          0 1px 0 0 color-mix(in oklch, var(--normal-text) 12%, transparent),
+          0 1px 2px 0 oklch(0.15 0 0 / 0.08);
+        transition: all 200ms ease-in-out !important;
+      }
+
+      .dark [data-sonner-toast] .cn-toast {
+        box-shadow:
+          0 1px 0 0 color-mix(in oklch, var(--normal-text) 14%, transparent),
+          0 1px 2px 0 oklch(0.15 0 0 / 0.12);
+      }
+
+      [data-sonner-toast] .cn-toast.toast-success {
+        border-left-width: 3px !important;
+        border-left-color: var(--success-500) !important;
+      }
+
+      [data-sonner-toast] .cn-toast.toast-error {
+        border-left-width: 3px !important;
+        border-left-color: var(--danger-500) !important;
+      }
+
+      [data-sonner-toast] .cn-toast.toast-warning {
+        border-left-width: 3px !important;
+        border-left-color: var(--warning-500) !important;
+      }
+
+      [data-sonner-toast] .cn-toast.toast-info {
+        border-left-width: 3px !important;
+        border-left-color: var(--info-500) !important;
+      }
+
+      [data-sonner-toast] .cn-toast.toast-loading {
+        border-left-width: 3px !important;
+        border-left-color: var(--primary-500) !important;
+      }
+
+      .cn-toast .toast-icon-success { color: var(--success); }
+      .cn-toast .toast-icon-error { color: var(--destructive); }
+      .cn-toast .toast-icon-warning { color: var(--warning); }
+      .cn-toast .toast-icon-info { color: var(--info); }
+      .cn-toast .toast-icon-loading { color: var(--primary); }
+    `,document.head.appendChild(t)}const g=({...t})=>{const{theme:o="system"}=y();return d.useEffect(()=>{z()},[]),c.jsx(j.Toaster,{theme:o,className:"toaster group",icons:{success:c.jsx(i.HugeiconsIcon,{icon:l.CheckmarkCircle02Icon,strokeWidth:2,className:"size-4 text-success toast-icon-success"}),info:c.jsx(i.HugeiconsIcon,{icon:l.InformationCircleIcon,strokeWidth:2,className:"size-4 text-info toast-icon-info"}),warning:c.jsx(i.HugeiconsIcon,{icon:l.Alert02Icon,strokeWidth:2,className:"size-4 text-warning toast-icon-warning"}),error:c.jsx(i.HugeiconsIcon,{icon:l.MultiplicationSignCircleIcon,strokeWidth:2,className:"size-4 text-destructive toast-icon-error"}),loading:c.jsx(i.HugeiconsIcon,{icon:l.Loading03Icon,strokeWidth:2,className:"size-4 text-primary toast-icon-loading animate-spin"})},style:{"--normal-bg":"var(--foreground)","--normal-text":"var(--background)","--normal-border":"color-mix(in oklch, var(--background) 25%, transparent)","--border-radius":"9999px","--success-bg":"var(--success)","--success-text":"var(--success-foreground)","--success-border":"var(--success-400)","--error-bg":"var(--destructive)","--error-text":"var(--destructive-foreground)","--error-border":"var(--danger-400)","--warning-bg":"var(--warning)","--warning-text":"var(--warning-foreground)","--warning-border":"var(--warning-400)","--info-bg":"var(--info)","--info-text":"var(--info-foreground)","--info-border":"var(--info-400)"},toastOptions:{classNames:{toast:"cn-toast",success:"toast-success",error:"toast-error",warning:"toast-warning",info:"toast-info",loading:"toast-loading"}},...t})};g.displayName="Toaster";const H=g,_=g;exports.EnhancedSonner=_;exports.EnhancedToaster=H;exports.Toaster=g;exports.z=y;

package/dist/sonner.cjs.js

@@ -1 +1 @@
-"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const e=require("./sonner-DbQhVp8m.cjs");exports.CoreToaster=e.Toaster;exports.EnhancedSonner=e.EnhancedToaster;exports.Toaster=e.EnhancedToaster;
+"use strict";Object.defineProperty(exports,Symbol.toStringTag,{value:"Module"});const e=require("./sonner-nE9hIalJ.cjs");exports.CoreToaster=e.Toaster;exports.EnhancedSonner=e.EnhancedSonner;exports.EnhancedToaster=e.EnhancedToaster;exports.Toaster=e.Toaster;

package/dist/sonner.es.js

@@ -1,6 +1,7 @@
-import { T as o, E as r, E as s } from "./sonner-Co6YpYVs.js";
+import { T as o, E as r, a as s, T as n } from "./sonner-CpmECDBk.js";
 export {
   o as CoreToaster,
   r as EnhancedSonner,
-  s as Toaster
+  s as EnhancedToaster,
+  n as Toaster
 };

package/dist/styles.css

@@ -12,6 +12,7 @@
  * - Light and dark mode support
  * - Base layer styles
  * - Utility animations
+ * - Hit-area @utility blocks (inlined from src/styles/hit-area.css)
  * - @source inline() directives for zero-config Tailwind utility generation
  *
  * Generated by: npm run build:lib
@@ -68,9 +69,148 @@
 /* Z-index elevation utilities */
 @source inline("z-[var(--z-debug)] z-[var(--z-sticky-page)] z-[var(--z-background)] z-[var(--z-content)] z-[var(--z-popover)] z-[var(--z-modal-backdrop)] z-[var(--z-modal)] z-[var(--z-tooltip)] z-[var(--z-sticky-content)] z-[var(--z-floating)]");
 
+/* Hit-area utilities (referenced from TSX / docs; @utility defines behavior) */
+@source inline("hit-area-4 hit-area-6 hit-area-debug");
+
 
 
 /* Custom dark mode variant - matches when .dark class is on element or ancestor */
+/* Hit-area — https://bazza.dev/craft/2026/hit-area */
+/* Bazza hit-area utilities — https://bazza.dev/craft/2026/hit-area */
+
+@utility hit-area-debug {
+  position: relative;
+  &::before {
+    content: "";
+    position: absolute;
+    top: var(--hit-area-t, 0px);
+    right: var(--hit-area-r, 0px);
+    bottom: var(--hit-area-b, 0px);
+    left: var(--hit-area-l, 0px);
+    pointer-events: inherit;
+    @apply border border-dashed border-blue-500 bg-blue-500/10;
+  }
+  &:hover::before {
+    @apply border border-dashed border-green-500 bg-green-500/10;
+  }
+}
+
+@utility hit-area {
+  position: relative;
+  &::before {
+    content: "";
+    position: absolute;
+    top: var(--hit-area-t, 0px);
+    right: var(--hit-area-r, 0px);
+    bottom: var(--hit-area-b, 0px);
+    left: var(--hit-area-l, 0px);
+    pointer-events: inherit;
+  }
+}
+
+@utility hit-area-* {
+  position: relative;
+  --hit-area-t: --spacing(--value(number) * -1); --hit-area-t: calc(--value([*]) * -1);
+  --hit-area-b: --spacing(--value(number) * -1); --hit-area-b: calc(--value([*]) * -1);
+  --hit-area-l: --spacing(--value(number) * -1); --hit-area-l: calc(--value([*]) * -1);
+  --hit-area-r: --spacing(--value(number) * -1); --hit-area-r: calc(--value([*]) * -1);
+  &::before {
+    content: "";
+    position: absolute;
+    top: var(--hit-area-t, 0px);
+    right: var(--hit-area-r, 0px);
+    bottom: var(--hit-area-b, 0px);
+    left: var(--hit-area-l, 0px);
+    pointer-events: inherit;
+  }
+}
+
+@utility hit-area-l-* {
+  position: relative;
+  --hit-area-l: --spacing(--value(number) * -1); --hit-area-l: calc(--value([*]) * -1);
+  &::before {
+    content: "";
+    position: absolute;
+    top: var(--hit-area-t, 0px);
+    right: var(--hit-area-r, 0px);
+    bottom: var(--hit-area-b, 0px);
+    left: var(--hit-area-l, 0px);
+    pointer-events: inherit;
+  }
+}
+
+@utility hit-area-r-* {
+  position: relative;
+  --hit-area-r: --spacing(--value(number) * -1); --hit-area-r: calc(--value([*]) * -1);
+  &::before {
+    content: "";
+    position: absolute;
+    top: var(--hit-area-t, 0px);
+    right: var(--hit-area-r, 0px);
+    bottom: var(--hit-area-b, 0px);
+    left: var(--hit-area-l, 0px);
+    pointer-events: inherit;
+  }
+}
+
+@utility hit-area-t-* {
+  position: relative;
+  --hit-area-t: --spacing(--value(number) * -1); --hit-area-t: calc(--value([*]) * -1);
+  &::before {
+    content: "";
+    position: absolute;
+    top: var(--hit-area-t, 0px);
+    right: var(--hit-area-r, 0px);
+    bottom: var(--hit-area-b, 0px);
+    left: var(--hit-area-l, 0px);
+    pointer-events: inherit;
+  }
+}
+
+@utility hit-area-b-* {
+  position: relative;
+  --hit-area-b: --spacing(--value(number) * -1); --hit-area-b: calc(--value([*]) * -1);
+  &::before {
+    content: "";
+    position: absolute;
+    top: var(--hit-area-t, 0px);
+    right: var(--hit-area-r, 0px);
+    bottom: var(--hit-area-b, 0px);
+    left: var(--hit-area-l, 0px);
+    pointer-events: inherit;
+  }
+}
+
+@utility hit-area-x-* {
+  position: relative;
+  --hit-area-l: --spacing(--value(number) * -1); --hit-area-l: calc(--value([*]) * -1);
+  --hit-area-r: --spacing(--value(number) * -1); --hit-area-r: calc(--value([*]) * -1);
+  &::before {
+    content: "";
+    position: absolute;
+    top: var(--hit-area-t, 0px);
+    right: var(--hit-area-r, 0px);
+    bottom: var(--hit-area-b, 0px);
+    left: var(--hit-area-l, 0px);
+    pointer-events: inherit;
+  }
+}
+
+@utility hit-area-y-* {
+  position: relative;
+  --hit-area-t: --spacing(--value(number) * -1); --hit-area-t: calc(--value([*]) * -1);
+  --hit-area-b: --spacing(--value(number) * -1); --hit-area-b: calc(--value([*]) * -1);
+  &::before {
+    content: "";
+    position: absolute;
+    top: var(--hit-area-t, 0px);
+    right: var(--hit-area-r, 0px);
+    bottom: var(--hit-area-b, 0px);
+    left: var(--hit-area-l, 0px);
+    pointer-events: inherit;
+  }
+}
+
 @theme inline {
     --font-sans: 'Inter Variable', sans-serif;
     --color-sidebar-ring: var(--sidebar-ring);
@@ -455,6 +595,48 @@
     }
   }
 
+  /* Spinner — dual arc (Uiverse-style), primary gradient */
+  @keyframes nqui-spinner-rotate {
+    from {
+      transform: rotate(0deg);
+    }
+    to {
+      transform: rotate(360deg);
+    }
+  }
+
+  @keyframes nqui-spinner-dash-first {
+    0%,
+    100% {
+      stroke-dashoffset: 50;
+    }
+    50% {
+      stroke-dashoffset: 625;
+    }
+  }
+
+  @keyframes nqui-spinner-dash-second {
+    0%,
+    100% {
+      stroke-dashoffset: -625;
+    }
+    50% {
+      stroke-dashoffset: -50;
+    }
+  }
+
+  .nqui-spinner-rotate {
+    animation: nqui-spinner-rotate 2s linear infinite;
+  }
+
+  .nqui-spinner-arc-first circle {
+    animation: nqui-spinner-dash-first 3s ease-in-out infinite;
+  }
+
+  .nqui-spinner-arc-second circle {
+    animation: nqui-spinner-dash-second 3s ease-in-out infinite;
+  }
+
   /* Toast Icon Animations */
   .toast-icon-success {
     animation: toast-checkmark 0.4s cubic-bezier(0.68, -0.55, 0.265, 1.55);
@@ -541,6 +723,7 @@
     position: absolute;
     z-index: 0;
     pointer-events: none;
+    overflow: visible;
     transition:
       left 0.3s ease-in-out,
       top 0.3s ease-in-out,
@@ -550,6 +733,8 @@
 
   .sliding-indicator-container {
     position: relative;
+    overflow: hidden;
+    min-width: 0;
   }
 
   .sliding-indicator-target {
@@ -979,4 +1164,4 @@
     --sidebar-accent-foreground: oklch(0.92 0 0);
     --sidebar-border: oklch(1 0 0 / 10%);
     --sidebar-ring: oklch(0.556 0 0);
-}
+}

package/docs/components/README.md

@@ -17,7 +17,7 @@ Implementation guides for each component. **AI Skill:** Optimized for AI/LLM con
 | Dependency | Version | Notes |
 |------------|---------|-------|
 | **React** | 18+ or 19 | nqui supports React 18 and 19 via `^18.0.0 \|\| ^19.0.0` peer. |
-| **Tailwind CSS** | ^4.x | Required. Vite: `@tailwindcss/vite`. Next.js: `@source` directives in CSS. |
+| **Tailwind CSS** | ^4.x | Required. Vite: `@tailwindcss/vite`. Both Vite and Next.js need `@source` for `node_modules/@nqlib/nqui/dist` (Tailwind does not scan node_modules). |
 | **tw-animate-css** | — | `@import "tw-animate-css"` in your CSS (added by init-css). |
 | **Radix UI** | — | Bundled (Dialog, Select, etc.). |
 | **Hugeicons** | @hugeicons/react, @hugeicons/core-free-icons | Required for icon display in components. |
@@ -28,16 +28,115 @@ Implementation guides for each component. **AI Skill:** Optimized for AI/LLM con
 
 ## Shared Conventions (AI Implementation Rules)
 
-- **Control sizes:** `sm`=h-6, `default`=h-7, `lg`=h-8. Button, Toggle, ToggleGroup, Input, Select use this scale. See `.cursor/skills/nqui-design-system/SKILL.md`.
+- **Control sizes:** `sm`=h-6, `default`=h-7, `lg`=h-8. Button, Toggle, ToggleGroup, Input, Select, Switch, Slider use this scale. See `packages/nqui/docs/nqui-skills/design-system.md` or `.cursor/skills/nqui-design-system/SKILL.md`.
 - **CSS vars required:** nqui uses `--primary`, `--background`, `--foreground`, etc. Run `npx @nqlib/nqui init-css`.
-- **Enhanced vs Core:** Button, Badge, Checkbox, Select, etc. default to enhanced (3D, animations). Use `CoreButton`, `CoreBadge`, etc. for base shadcn. Separator: single component with `variant` prop (no CoreSeparator).
-- **Grouped controls:** ButtonGroup, ToggleGroup share border; ToggleGroup uses item dividers (`border-foreground/20`) or `ToggleGroupSeparator`.
+- **Enhanced vs Core:** Default exports (`Button`, `Badge`, `Checkbox`, `Select`, etc.) are the polished/3D variants. Implementations live in **`packages/nqui/src/components/ui/*.tsx`** (single file per concern). Use `CoreButton`, `CoreBadge`, `CoreCheckbox`, etc. for base Radix/shadcn-style behavior. Separator: single component with `variant` prop (no CoreSeparator).
+- **Grouped controls:** ButtonGroup, ToggleGroup share border; outer container uses **pill** radius (`rounded-full`). ToggleGroup uses item dividers (`border-foreground/20`) or `ToggleGroupSeparator`.
 - **Toolbar context:** Always show Toggle/ToggleGroup in realistic context (document toolbar, chart settings, etc.). Reference: `src/pages/ComponentShowcase.tsx`.
-- **Style injection:** Checkbox, Rating, Combobox inject `<style>` at mount → client-only guard for SSR.
+- **Style injection:** Some components inject `<style>` once at mount (e.g. **Combobox** input chrome in `ui/combobox.tsx`) → safe for SSR if the component is client-only (`"use client"`).
 - **OKLCH:** ColorPicker expects OKLCH strings (`oklch(0.5 0.15 240)`), not hex.
 - **SidebarProvider:** Must wrap entire layout (sidebar + content).
 - **Z-index:** Use CSS vars from `styles/elevation.css` (e.g. `z-[var(--z-modal)]`). Never hardcode `z-10`, `z-50`, etc.
 - **Keyboard:** Use `Keys`, `isMod`, `shouldIgnoreKeyboardShortcut` from `@/lib/keyboard` for custom shortcuts.
+- **Bounded content:** Chips, pills, and inline controls should stay inside their box (ellipsis / line-clamp / scroll-by-design). See **Bounded content** in `packages/nqui/docs/nqui-skills/design-system.md`. Portals and tooltips are explicit exceptions.
+
+---
+
+## Layout & Scroll Patterns
+
+This section documents the CSS patterns used in the showcase app to ensure proper scroll behavior and prevent sticky element issues.
+
+### Sticky Elements & Momentum Scroll
+
+**The problem:** When using default body scroll, sticky elements can exhibit "momentum push" behavior during fast scrolling - they appear to float or lag before snapping back. This happens because sticky positioning is relative to the viewport, not the scroll container.
+
+**The solution:** Use a custom scroll container instead of body/html scroll.
+
+```tsx
+// App layout structure - prevents momentum push on sticky elements
+<div className="h-screen overflow-hidden">
+  <header className="sticky top-0 z-[var(--z-sticky-page)]">
+    {/* Page header */}
+  </header>
+  <main className="flex-1 min-h-0 overflow-y-auto">
+    {/* Scrollable content */}
+  </main>
+</div>
+```
+
+### Z-Index Layering for Sticky Elements
+
+Use the correct z-index variables to prevent sticky element conflicts:
+
+| Element | CSS Variable | Value |
+|---------|-------------|-------|
+| Page headers, navigation bars | `z-[var(--z-sticky-page)]` | 20 |
+| Card headers, table headers | `z-[var(--z-sticky-content)]` | 15 |
+
+**Rule:** Page-level sticky elements (20) must be above container-level sticky elements (15) to prevent scroll conflicts.
+
+### Flex Scroll Pattern
+
+For nested scrolling to work correctly, flex children must have `min-height: 0` (or `min-h-0` in Tailwind):
+
+```tsx
+// Correct - flex child can shrink and scroll
+<div className="flex flex-col h-screen">
+  <header className="flex-shrink-0">...</header>
+  <main className="flex-1 min-h-0 overflow-y-auto">
+    {/* This will scroll */}
+  </main>
+</div>
+
+// Wrong - flex child cannot shrink below content height
+<div className="flex flex-col h-screen">
+  <header>...</header>
+  <main className="flex-1 overflow-y-auto">
+    {/* May not scroll - overflows instead */}
+  </main>
+</div>
+```
+
+### Body Scroll Prevention
+
+For app-like experiences, disable body/html scroll:
+
+```tsx
+useEffect(() => {
+  // Disable browser scroll restoration
+  if ('scrollRestoration' in history) {
+    history.scrollRestoration = 'manual'
+  }
+
+  // Prevent body/html from scrolling
+  document.body.style.overflow = 'hidden'
+  document.documentElement.style.overflow = 'hidden'
+
+  return () => {
+    document.body.style.overflow = ''
+    document.documentElement.style.overflow = ''
+  }
+}, [])
+```
+
+### Sliding Indicator Containers
+
+Components with sliding indicators (Tabs, RadioGroup `sliding` variant) need specific container styling:
+
+```tsx
+// Required CSS for sliding indicator containers
+.sliding-indicator-container {
+  position: relative;
+  overflow: hidden;
+  min-width: 0;
+}
+
+.sliding-indicator {
+  position: absolute;
+  overflow: visible;
+  /* transitions for smooth sliding */
+}
+```
 
 ---
 
@@ -67,7 +166,7 @@ Use these rules to choose the right component. **Selection** = user picks from o
 |-------|-----|
 | 2–5 options, inline (e.g. bold/italic/underline) | **ToggleGroup** `type="multiple"` |
 | Form context, list of options | **Checkbox** (each option) |
-| Many options, need search | **Combobox** `multiSelect` |
+| Many options, need search | **Combobox** with `multiple` (see `nqui-combobox.md`) |
 
 ### Actions (trigger, not select)
 
@@ -108,7 +207,7 @@ Use these rules to choose the right component. **Selection** = user picks from o
 | Single choice, 5+ options or no space | **Select** |
 | Single choice, need search | **Combobox** (single) |
 | Single choice, form, small option set | **RadioGroup** |
-| Multiple choice, need search | **Combobox** `multiSelect` |
+| Multiple choice, need search | **Combobox** with `multiple` (see `nqui-combobox.md`) |
 | One boolean (agree, subscribe) | **Checkbox** |
 | On/off setting (dark mode, notifications) | **Switch** |
 | Numeric range (volume, opacity) | **Slider** |
@@ -135,7 +234,7 @@ Use these rules to choose the right component. **Selection** = user picks from o
 | Rating | [nqui-rating.md](./nqui-rating.md) | Star/score (1–5). |
 | InputOTP | [nqui-input-otp.md](./nqui-input-otp.md) | OTP/verification. |
 | Field | [nqui-field.md](./nqui-field.md) | Label + description + error wrapper. |
-| Combobox | [nqui-combobox.md](./nqui-combobox.md) | **Searchable** select. Single or `multiSelect`. Use when user types to filter. |
+| Combobox | [nqui-combobox.md](./nqui-combobox.md) | **Searchable** select. Single or `multiple`. Use when user types to filter. |
 | ColorPicker | [nqui-color-picker.md](./nqui-color-picker.md) | Color selection. OKLCH. |
 | ColorSlider | [nqui-color-slider.md](./nqui-color-slider.md) | Hue/saturation (used in ColorPicker). |
 | Label | [nqui-label.md](./nqui-label.md) | Form label. |

package/docs/components/nqui-badge.md

@@ -38,5 +38,6 @@ import { Badge } from "@nqlib/nqui"
 
 ## Notes
 
+- Implementation: **`packages/nqui/src/components/ui/badge.tsx`** (enhanced + core in one module).
 - ghost/link route to CoreBadge (different styling).
 - Use `CoreBadge` for plain shadcn badge.

package/docs/components/nqui-button.md

@@ -1,6 +1,6 @@
 # nqui Button
 
-> Enhanced button with 9 variants, gradients, active scale. Default import is EnhancedButton.
+> Default **Button** is the enhanced variant (gradients, depth, active scale). Implemented in **`ui/button.tsx`** with **`CoreButton`** for the plain primitive.
 
 ## Import
 
@@ -52,5 +52,7 @@ Render as `<a>` or custom element:
 
 ## Notes
 
+- **Shape:** full pill (`rounded-full`) for all sizes.
+- **Bounded label:** string/number children are wrapped so **`truncate`** + **`min-w-0`** apply in narrow layouts. Same pattern is used across **Toggle**, **Tabs**, **Badge**, **Combobox** chips; **Select** value uses **line-clamp**. Custom markup with one long inner node may still need its own `min-w-0 truncate` or a **`title`**.
 - Active state uses `scale-95`; avoid parent `transform` overrides.
 - Use `CoreButton` from `@nqlib/nqui` for base shadcn style.

package/docs/components/nqui-card.md

@@ -29,3 +29,11 @@ import { Card, CardHeader, CardTitle, CardDescription, CardContent, CardFooter }
   <CardContent>Scrollable content</CardContent>
 </Card>
 ```
+
+## Notes
+
+- **Layout / bounds:** Root **Card**, **CardHeader**, **CardContent**, and **CardFooter** include **`min-w-0`** so nested flex/grid layouts can shrink and children are less likely to spill horizontally. **Card** stays **`overflow-visible`** on purpose so popovers, menus, and focus rings are not clipped—pair with bounded components (buttons, carousel insets, `truncate`, etc.) instead of `overflow-hidden` on the card by default.
+- **stickyHeader:** Use `stickyHeader` prop on Card for scrollable content with sticky header. The header uses `--z-sticky-content` (z-index: 15).
+- **Z-index layering:** Card sticky headers (15) are below page headers (20). If using in a page with sticky header, ensure proper z-index layering.
+- **Height required:** Card needs a defined height (e.g., `h-[400px]` or `h-full`) for sticky behavior to work.
+- **Content scroll:** The CardContent becomes scrollable when Card has `stickyHeader` and a defined height.

package/docs/components/nqui-carousel.md

@@ -20,3 +20,9 @@ import { Carousel, CarouselContent, CarouselItem, CarouselPrevious, CarouselNext
   <CarouselNext />
 </Carousel>
 ```
+
+## Notes
+
+- **Prev/Next** are positioned **inside** the carousel region (`left-2` / `right-2`, or `top-2` / `bottom-2` when vertical) so arrows stay within parents like **Card** instead of using negative offsets that sat outside the viewport (`-left-12` / `-right-12` previously).
+- **Visibility:** Arrows are **dim by default** (`opacity-35`), ramp up on **carousel hover** (`group-hover/carousel`), and go **full opacity** on **button** `:hover`, `:focus-visible`, and `:active` (tap). Disabled controls stay faint.
+- Override with `className` on `CarouselPrevious` / `CarouselNext` if you need edge-aligned or external controls.