@ngrok/mantle 0.84.0 → 0.84.2

package/dist/pagination.d.ts

@@ -1,21 +1,50 @@
-import { t as ButtonGroup } from "./button-CRCNRnk6.js";
-import { t as Select } from "./select-DkFkSYBP.js";
+import { t as ButtonGroup } from "./button-DO53OA70.js";
+import { t as Select } from "./select-ouAW88jx.js";
 import { ComponentProps } from "react";
 //#region src/components/pagination/cursor-pagination.d.ts
-type CursorPaginationProps = ComponentProps<"div"> & {
+/**
+ * The page size owner: either the root, seeded by `defaultPageSize`, or the
+ * consumer, through `pageSize`. A union, so a call site passes exactly one.
+ */
+type CursorPaginationPageSizeProps = {
   /**
-   * The default number of items per page.
+   * The initial number of items per page. The root owns the value after
+   * mount, and `PageSizeSelect` changes it. Read the changes back through
+   * `onChangePageSize`.
    */
   defaultPageSize: number;
+  pageSize?: never;
+} | {
+  defaultPageSize?: never;
+  /**
+   * The controlled number of items per page. Pair it with
+   * `onChangePageSize`: `PageSizeSelect` calls that with the next value, and
+   * the select shows this prop until you change it. An external change, such
+   * as a browser history move that rewrites a URL param, updates the select.
+   */
+  pageSize: number;
+};
+type CursorPaginationProps = ComponentProps<"div"> & CursorPaginationPageSizeProps & {
+  /**
+   * Called with the next number of items per page when `PageSizeSelect`
+   * changes it. Required to change a controlled `pageSize`.
+   */
+  onChangePageSize?: (pageSize: number) => void;
 };
 /**
- * A pagination component for use with cursor-based pagination.
+ * The root container for cursor-based pagination. It owns the page size that
+ * `PageSizeSelect` and `PageSizeValue` read.
  *
- * Cursor-based pagination is a way of loading data in chunks by using a cursor
- * from the last item on the current page to know where to start the next set,
- * making sure nothing is missed or repeated. Like a linked list, but for chunks
- * of data. It doesn't let you jump to a specific page or know how many total pages
- * there are, but it's more efficient for large or real-time data sets.
+ * Pass `defaultPageSize` to let the root own the page size, or pass `pageSize`
+ * with `onChangePageSize` to own it yourself. The select shows the owner's
+ * value in both modes, so an external change to a controlled `pageSize` updates
+ * the select.
+ *
+ * Cursor-based pagination loads data in chunks. A cursor from the last item on
+ * the current page marks where the next chunk starts, so no item is missed or
+ * repeated. It cannot jump to a page or count the pages, but it stays efficient
+ * for large or real-time data sets. For a page count and jumps, use
+ * `useOffsetPagination`.
  *
  * @see https://mantle.ngrok.com/components/navigation/pagination#cursorpaginationroot
  *
@@ -31,8 +60,37 @@ type CursorPaginationProps = ComponentProps<"div"> & {
  *   <CursorPagination.PageSizeSelect />
  * </CursorPagination.Root>
  * ```
+ *
+ * @example
+ * Controlled page size, kept in the URL:
+ * ```tsx
+ * const pageSizes = [10, 20, 50, 100];
+ * const [searchParams, setSearchParams] = useSearchParams();
+ * const requestedPageSize = Number(searchParams.get("pageSize"));
+ * // A hand-edited URL can carry a size the select does not list, and
+ * // `PageSizeSelect` throws for one. Fall back to the default.
+ * const pageSize = pageSizes.includes(requestedPageSize) ? requestedPageSize : 10;
+ *
+ * <CursorPagination.Root
+ *   pageSize={pageSize}
+ *   onChangePageSize={(size) =>
+ *     setSearchParams((params) => {
+ *       params.set("pageSize", String(size));
+ *       return params;
+ *     })
+ *   }
+ * >
+ *   <CursorPagination.Buttons
+ *     hasNextPage={hasNext}
+ *     hasPreviousPage={hasPrevious}
+ *     onNextPage={handleNext}
+ *     onPreviousPage={handlePrevious}
+ *   />
+ *   <CursorPagination.PageSizeSelect pageSizes={pageSizes} />
+ * </CursorPagination.Root>
+ * ```
  */
-declare const Root: ({ className, children, defaultPageSize, ref, ...props }: CursorPaginationProps) => import("react").JSX.Element;
+declare const Root: ({ className, children, defaultPageSize, onChangePageSize, pageSize: pageSizeProp, ref, ...props }: CursorPaginationProps) => import("react").JSX.Element;
 type CursorButtonsProps = Omit<ComponentProps<typeof ButtonGroup>, "appearance"> & {
   /**
    * Whether there is a next page of data to load.
@@ -70,13 +128,16 @@ declare const Buttons: ({ hasNextPage, hasPreviousPage, onNextPage, onPreviousPa
 declare const defaultPageSizes: readonly [5, 10, 20, 50, 100];
 type CursorPageSizeSelectProps = Omit<ComponentProps<typeof Select.Trigger>, "children"> & {
   /**
-   * A list of page sizes to choose from. The default page size must be included in this list.
+   * The page sizes to choose from. The current page size must be in this list.
+   *
+   * @default [5, 10, 20, 50, 100]
    */
   pageSizes?: typeof defaultPageSizes | readonly number[];
   /**
-   * A callback that is called when the page size is changed.
+   * Called with the next number of items per page when the user picks one.
+   * `Root`'s `onChangePageSize` runs first with the same value.
    */
-  onChangePageSize?: (value: number) => void;
+  onChangePageSize?: (pageSize: number) => void;
 };
 /**
  * A select input for changing the number of items per page when using cursor-based pagination.
@@ -142,7 +203,13 @@ declare function PageSizeValue({ className, ...props }: CursorPageSizeValueProps
  */
 declare const CursorPagination: {
   /**
-   * The root container of the cursor pagination component.
+   * The root container for cursor-based pagination. It owns the page size that
+   * `PageSizeSelect` and `PageSizeValue` read.
+   *
+   * Pass `defaultPageSize` to let the root own the page size, or pass `pageSize`
+   * with `onChangePageSize` to own it yourself. The select shows the owner's
+   * value in both modes, so an external change to a controlled `pageSize` updates
+   * the select.
    *
    * @see https://mantle.ngrok.com/components/navigation/pagination#cursorpaginationroot
    *
@@ -158,6 +225,35 @@ declare const CursorPagination: {
    *   <CursorPagination.PageSizeSelect />
    * </CursorPagination.Root>
    * ```
+   *
+   * @example
+   * Controlled page size, kept in the URL:
+   * ```tsx
+   * const pageSizes = [10, 20, 50, 100];
+   * const [searchParams, setSearchParams] = useSearchParams();
+   * const requestedPageSize = Number(searchParams.get("pageSize"));
+   * // A hand-edited URL can carry a size the select does not list, and
+   * // `PageSizeSelect` throws for one. Fall back to the default.
+   * const pageSize = pageSizes.includes(requestedPageSize) ? requestedPageSize : 10;
+   *
+   * <CursorPagination.Root
+   *   pageSize={pageSize}
+   *   onChangePageSize={(size) =>
+   *     setSearchParams((params) => {
+   *       params.set("pageSize", String(size));
+   *       return params;
+   *     })
+   *   }
+   * >
+   *   <CursorPagination.Buttons
+   *     hasNextPage={hasNext}
+   *     hasPreviousPage={hasPrevious}
+   *     onNextPage={handleNext}
+   *     onPreviousPage={handlePrevious}
+   *   />
+   *   <CursorPagination.PageSizeSelect pageSizes={pageSizes} />
+   * </CursorPagination.Root>
+   * ```
    */
   readonly Root: typeof Root;
   /**
@@ -209,13 +305,44 @@ declare const CursorPagination: {
 //#region src/components/pagination/use-offset-pagination.d.ts
 type UseOffsetPaginationProps = {
   /**
-   * The total number of items in the list to be paginated.
+   * The total number of items in the list to paginate. A change resets the
+   * page to 1 unless `resetPageOnListSizeChange` is `false`.
    */
   listSize: number;
   /**
-   * The number of items per page.
+   * The number of items per page. A change resets the page to 1.
    */
   pageSize: number;
+  /**
+   * The 1-indexed page to start on when uncontrolled. The hook owns the page
+   * after mount.
+   *
+   * @default 1
+   */
+  defaultPage?: number;
+  /**
+   * The controlled 1-indexed page. Pair it with `onPageChange`: the hook calls
+   * that with the next page and reads the page back from this prop. The hook
+   * normalizes the value in `currentPage` without a callback: a page past the
+   * end clamps to the last page, a fraction rounds down, and `NaN` reads as 1.
+   */
+  page?: number;
+  /**
+   * Called with the next 1-indexed page when the hook changes it: a navigation
+   * call, `setPageSize`, a `pageSize` change, or a `listSize` reset. Not called
+   * when the next page equals the stored page (`page` or the internal page).
+   * A move that lands on a normalized `currentPage` still calls it, so a stale
+   * `page` catches up.
+   */
+  onPageChange?: (page: number) => void;
+  /**
+   * Whether a `listSize` change resets the page to 1. Set `false` to stay on
+   * the current page: `currentPage` clamps to the new `totalPages`, so a
+   * refetch that shrinks the list lands on its last page instead of page 1.
+   *
+   * @default true
+   */
+  resetPageOnListSizeChange?: boolean;
 };
 type OffsetPaginationState = {
   /**
@@ -268,7 +395,9 @@ type OffsetPaginationState = {
   totalPages: number;
 };
 /**
- * A headless hook for managing offset-based pagination state
+ * A headless hook for offset-based pagination state. It owns the page by
+ * default; pass `page` with `onPageChange` to own it yourself, for example in
+ * the URL.
  *
  * @example
  * ```tsx
@@ -289,8 +418,25 @@ type OffsetPaginationState = {
  *   </div>
  * );
  * ```
+ *
+ * @example
+ * Controlled page, kept in the URL, that survives a refetch:
+ * ```tsx
+ * const [searchParams, setSearchParams] = useSearchParams();
+ * const pagination = useOffsetPagination({
+ *   listSize: items.length,
+ *   pageSize: 10,
+ *   page: Number(searchParams.get("page") ?? 1),
+ *   onPageChange: (page) =>
+ *     setSearchParams((params) => {
+ *       params.set("page", String(page));
+ *       return params;
+ *     }),
+ *   resetPageOnListSizeChange: false,
+ * });
+ * ```
  */
-declare function useOffsetPagination({ listSize, pageSize }: UseOffsetPaginationProps): OffsetPaginationState;
+declare function useOffsetPagination({ defaultPage, listSize, onPageChange, page: pageProp, pageSize, resetPageOnListSizeChange }: UseOffsetPaginationProps): OffsetPaginationState;
 /**
  * Get a paginated slice of a list based on the current offset pagination state.
  *

package/dist/pagination.js

@@ -1 +1 @@
-import{t as e}from"./cx-IiQEAKf5.js";import{t}from"./button-CC10rP6X.js";import{t as n}from"./button-DmJkYfyl.js";import{n as r}from"./separator-D0D6VyyM.js";import{t as i}from"./select-BK6n6OIK.js";import{createContext as a,useContext as o,useEffect as s,useMemo as c,useState as l}from"react";import u from"tiny-invariant";import{jsx as d,jsxs as f}from"react/jsx-runtime";import{CaretRightIcon as p}from"@phosphor-icons/react/CaretRight";import{CaretLeftIcon as m}from"@phosphor-icons/react/CaretLeft";const h=a(void 0),g=({className:t,children:n,defaultPageSize:r,ref:i,...a})=>{let[o,s]=l(r),u=c(()=>({defaultPageSize:r,pageSize:o,setPageSize:s}),[r,o]);return d(h.Provider,{value:u,children:d(`div`,{"data-slot":`cursor-pagination`,className:e(`inline-flex items-center justify-between gap-2`,t),ref:i,...a,children:n})})},_=({hasNextPage:e,hasPreviousPage:i,onNextPage:a,onPreviousPage:o,ref:s,...c})=>f(n,{"data-slot":`cursor-pagination-buttons`,appearance:`panel`,ref:s,...c,children:[d(t,{"data-slot":`cursor-pagination-previous`,appearance:`ghost`,disabled:!i,icon:d(m,{}),intent:`neutral`,label:`Previous page`,onClick:o,size:`sm`,type:`button`}),d(r,{"data-slot":`cursor-pagination-separator`,orientation:`vertical`,className:`min-h-5`}),d(t,{"data-slot":`cursor-pagination-next`,appearance:`ghost`,disabled:!e,icon:d(p,{}),intent:`neutral`,label:`Next page`,onClick:a,size:`sm`,type:`button`})]}),v=[5,10,20,50,100],y=({className:t,pageSizes:n=v,onChangePageSize:r,ref:a,...s})=>{let c=o(h);return u(c,`CursorPageSizeSelect must be used as a child of a CursorPagination component`),u(n.includes(c.defaultPageSize),`CursorPagination.defaultPageSize must be included in CursorPageSizeSelect.pageSizes`),u(n.includes(c.pageSize),`CursorPagination.pageSize must be included in CursorPageSizeSelect.pageSizes`),f(i.Root,{defaultValue:`${c.pageSize}`,onValueChange:e=>{let t=Number.parseInt(e,10);Number.isNaN(t)&&(t=c.defaultPageSize),c.setPageSize(t),r?.(t)},children:[d(i.Trigger,{ref:a,"data-slot":`cursor-pagination-page-size-select`,className:e(`w-auto min-w-36`,t),value:c.pageSize,...s,children:d(i.Value,{})}),d(i.Content,{width:`trigger`,children:n.map(e=>f(i.Item,{value:`${e}`,children:[e,` per page`]},e))})]})};function b({className:t,...n}){let r=o(h);return u(r,`CursorPageSizeValue must be used as a child of a CursorPagination component`),f(`span`,{"data-slot":`cursor-pagination-page-size-value`,className:e(`text-muted text-sm font-normal`,t),...n,children:[r.pageSize,` per page`]})}const x={Root:g,Buttons:_,PageSizeSelect:y,PageSizeValue:b};function S({listSize:e,pageSize:t}){let[n,r]=l(1),[i,a]=l(t);s(()=>{a(t),r(1)},[t]),s(()=>{r(1)},[e]);let o=Math.ceil(e/i),c=(n-1)*i,u=n>1,d=n<o;function f(e){r(Math.max(1,Math.min(e,o)))}function p(){d&&r(e=>Math.min(e+1,o))}function m(){u&&r(e=>Math.max(e-1,1))}function h(e){a(e),r(1)}function g(){r(o)}function _(){r(1)}return{currentPage:n,goToFirstPage:_,goToLastPage:g,goToPage:f,hasNextPage:d,hasPreviousPage:u,nextPage:p,offset:c,pageSize:i,previousPage:m,setPageSize:h,totalPages:o}}function C(e,t){return e.slice(t.offset,t.offset+t.pageSize)}export{x as CursorPagination,C as getOffsetPaginatedSlice,S as useOffsetPagination};
+import{t as e}from"./cx-0HCjnNv1.js";import{t}from"./button-CaM-ZAH5.js";import{t as n}from"./button-Wn-yt0c_.js";import{n as r}from"./separator-Da8lDnio.js";import{t as i}from"./select-Dov9H2CX.js";import{createContext as a,useCallback as o,useContext as s,useEffect as c,useMemo as l,useRef as u,useState as d}from"react";import f from"tiny-invariant";import{jsx as p,jsxs as m}from"react/jsx-runtime";import{CaretRightIcon as h}from"@phosphor-icons/react/CaretRight";import{CaretLeftIcon as g}from"@phosphor-icons/react/CaretLeft";const _=a(void 0),v=({className:t,children:n,defaultPageSize:r,onChangePageSize:i,pageSize:a,ref:o,...s})=>{let c=a!=null,[u,m]=d(r),h=c?a:u;f(h!=null,"CursorPagination.Root requires either `defaultPageSize` or `pageSize`");let g=l(()=>({pageSize:h,setPageSize:e=>{c||m(e),i?.(e)}}),[c,i,h]);return p(_.Provider,{value:g,children:p(`div`,{"data-slot":`cursor-pagination`,className:e(`inline-flex items-center justify-between gap-2`,t),ref:o,...s,children:n})})},y=({hasNextPage:e,hasPreviousPage:i,onNextPage:a,onPreviousPage:o,ref:s,...c})=>m(n,{"data-slot":`cursor-pagination-buttons`,appearance:`panel`,ref:s,...c,children:[p(t,{"data-slot":`cursor-pagination-previous`,appearance:`ghost`,disabled:!i,icon:p(g,{}),intent:`neutral`,label:`Previous page`,onClick:o,size:`sm`,type:`button`}),p(r,{"data-slot":`cursor-pagination-separator`,orientation:`vertical`,className:`min-h-5`}),p(t,{"data-slot":`cursor-pagination-next`,appearance:`ghost`,disabled:!e,icon:p(h,{}),intent:`neutral`,label:`Next page`,onClick:a,size:`sm`,type:`button`})]}),b=[5,10,20,50,100],x=({className:t,pageSizes:n=b,onChangePageSize:r,ref:a,...o})=>{let c=s(_);return f(c,`CursorPageSizeSelect must be used as a child of a CursorPagination component`),f(n.includes(c.pageSize),`CursorPagination.pageSize must be included in CursorPageSizeSelect.pageSizes`),m(i.Root,{value:`${c.pageSize}`,onValueChange:e=>{let t=Number.parseInt(e,10);f(!Number.isNaN(t),`CursorPageSizeSelect.pageSizes must contain only numbers`),c.setPageSize(t),r?.(t)},children:[p(i.Trigger,{ref:a,"aria-label":`Items per page`,"data-slot":`cursor-pagination-page-size-select`,className:e(`w-auto min-w-36`,t),...o,children:m(i.Value,{children:[c.pageSize,` per page`]})}),p(i.Content,{width:`trigger`,children:n.map(e=>m(i.Item,{value:`${e}`,children:[e,` per page`]},e))})]})};function S({className:t,...n}){let r=s(_);return f(r,`CursorPageSizeValue must be used as a child of a CursorPagination component`),m(`span`,{"data-slot":`cursor-pagination-page-size-value`,className:e(`text-muted text-sm font-normal`,t),...n,children:[r.pageSize,` per page`]})}const C={Root:v,Buttons:y,PageSizeSelect:x,PageSizeValue:S};function w(e,t){return Math.max(1,Math.min(Number.isNaN(e)?1:Math.floor(e),t))}function T({defaultPage:e=1,listSize:t,onPageChange:n,page:r,pageSize:i,resetPageOnListSizeChange:a=!0}){let s=r!=null,[l,f]=d(e),[p,m]=d(i),h=Math.ceil(t/p),g=s?r:l,_=w(g,h),v=(_-1)*p,y=_>1,b=_<h,x=o(e=>{e!==g&&(s||f(e),n?.(e))},[s,n,g]),S=u(i),C=u(t);c(()=>{let e=S.current!==i,n=C.current!==t;S.current=i,C.current=t,e&&m(i),(e||n&&a)&&x(1)},[t,i,a,x]);function T(e){x(w(e,h))}function E(){b&&x(_+1)}function D(){y&&x(_-1)}function O(e){m(e),x(1)}function k(){x(w(h,h))}function A(){x(1)}return{currentPage:_,goToFirstPage:A,goToLastPage:k,goToPage:T,hasNextPage:b,hasPreviousPage:y,nextPage:E,offset:v,pageSize:p,previousPage:D,setPageSize:O,totalPages:h}}function E(e,t){return e.slice(t.offset,t.offset+t.pageSize)}export{C as CursorPagination,E as getOffsetPaginatedSlice,T as useOffsetPagination};

package/dist/{popover-D6x6Bq-G.js → popover-Bp-9B3GR.js}

@@ -1 +1 @@
-import{t as e}from"./cx-IiQEAKf5.js";import{r as t}from"./layer-container-CglTh9-6.js";import{jsx as n,jsxs as r}from"react/jsx-runtime";import*as i from"@radix-ui/react-popover";const a=i.Root,o=i.Trigger,s={Root:a,Anchor:i.Anchor,Arrow:({className:t,height:a=7,width:o=14,...s})=>n(i.Arrow,{"aria-hidden":`true`,asChild:!0,"data-slot":`popover-arrow`,height:a,width:o,...s,children:r(`svg`,{className:e(`fill-[var(--background-color-popover)]`,`[clip-path:inset(0_-200%_-200%_-200%)]`,`[filter:drop-shadow(0_0_4px_color-mix(in_oklab,var(--shadow-color)_var(--shadow-first-opacity),transparent))]`,t),children:[n(`polygon`,{points:`0,0 30,0 15,10`}),n(`polyline`,{className:`stroke-[color:var(--border-color-popover)]`,fill:`none`,points:`0,0 15,10 30,0`,strokeWidth:1.5,vectorEffect:`non-scaling-stroke`})]})}),Close:i.Close,Content:({align:r=`center`,className:a,onClick:o,preferredWidth:s=`max-w-72`,ref:c,sideOffset:l=4,...u})=>{let d=t();return n(i.Portal,{container:d,children:n(i.Content,{align:r,"data-slot":`popover-content`,className:e(`relative`,`text-popover-foreground border-popover bg-popover data-side-bottom:slide-in-from-top-2 data-side-left:slide-in-from-right-2 data-side-right:slide-in-from-left-2 data-side-top:slide-in-from-bottom-2 data-state-closed:animate-out data-state-closed:fade-out-0 data-state-closed:zoom-out-95 data-state-open:animate-in data-state-open:fade-in-0 data-state-open:zoom-in-95 z-50 rounded-md border p-4 shadow-md outline-hidden`,s,a),onClick:e=>{e.stopPropagation(),o?.(e)},ref:c,sideOffset:l,...u})})},Trigger:o};export{s as t};
+import{t as e}from"./cx-0HCjnNv1.js";import{r as t}from"./layer-container-BTcQpd4K.js";import{jsx as n,jsxs as r}from"react/jsx-runtime";import*as i from"@radix-ui/react-popover";const a=i.Root,o=i.Trigger,s={Root:a,Anchor:i.Anchor,Arrow:({className:t,height:a=7,width:o=14,...s})=>n(i.Arrow,{"aria-hidden":`true`,asChild:!0,"data-slot":`popover-arrow`,height:a,width:o,...s,children:r(`svg`,{className:e(`fill-[var(--background-color-popover)]`,`[clip-path:inset(0_-200%_-200%_-200%)]`,`[filter:drop-shadow(0_0_4px_color-mix(in_oklab,var(--shadow-color)_var(--shadow-first-opacity),transparent))]`,t),children:[n(`polygon`,{points:`0,0 30,0 15,10`}),n(`polyline`,{className:`stroke-[color:var(--border-color-popover)]`,fill:`none`,points:`0,0 15,10 30,0`,strokeWidth:1.5,vectorEffect:`non-scaling-stroke`})]})}),Close:i.Close,Content:({align:r=`center`,className:a,onClick:o,preferredWidth:s=`max-w-72`,ref:c,sideOffset:l=4,...u})=>{let d=t();return n(i.Portal,{container:d,children:n(i.Content,{align:r,"data-slot":`popover-content`,className:e(`relative`,`text-popover-foreground border-popover bg-popover data-side-bottom:slide-in-from-top-2 data-side-left:slide-in-from-right-2 data-side-right:slide-in-from-left-2 data-side-top:slide-in-from-bottom-2 data-state-closed:animate-out data-state-closed:fade-out-0 data-state-closed:zoom-out-95 data-state-open:animate-in data-state-open:fade-in-0 data-state-open:zoom-in-95 z-50 rounded-md border p-4 shadow-md outline-hidden`,s,a),onClick:e=>{e.stopPropagation(),o?.(e)},ref:c,sideOffset:l,...u})})},Trigger:o};export{s as t};

package/dist/{popover-DDuw1UaJ.d.ts → popover-s2LhmzfQ.d.ts}

@@ -148,7 +148,7 @@ declare const Popover: {
    */
   readonly Root: import("react").FC<PopoverPrimitive.PopoverProps>;
   /**
-   * An optional element to position the PopoverContent against. If not used, content positions alongside the trigger.
+   * An optional element to position the PopoverContent against. If this part is not used, the content will position alongside the PopoverTrigger.
    *
    * @see https://mantle.ngrok.com/components/overlays/popover#popoveranchor
    *
@@ -199,7 +199,7 @@ declare const Popover: {
    */
   readonly Arrow: typeof Arrow;
   /**
-   * A button that closes an open popover. Can be placed anywhere within the popover content.
+   * A button that closes an open popover.
    *
    * @see https://mantle.ngrok.com/components/overlays/popover#popoverclose
    *
@@ -223,7 +223,7 @@ declare const Popover: {
    */
   readonly Close: import("react").ForwardRefExoticComponent<PopoverPrimitive.PopoverCloseProps & import("react").RefAttributes<HTMLButtonElement>>;
   /**
-   * The content to render inside the popover. Appears in a portal with rich styling and animations.
+   * The content to render inside the popover.
    *
    * `Popover.Content` renders at Tailwind `z-50`, Mantle's float tier. When
    * composed inside an open `Dialog`, `AlertDialog`, or `Sheet`, it portals into
@@ -232,6 +232,10 @@ declare const Popover: {
    * (`z-60`). When sibling floats share a container, the most recently mounted
    * float paints on top.
    *
+   * It sets `position: relative`, so `Popover.Arrow`'s absolutely-positioned
+   * wrapper keeps one containing block through the open animation. An
+   * absolutely-positioned child of the content therefore anchors to the content.
+   *
    * @see https://mantle.ngrok.com/components/overlays/popover#popovercontent
    *
    * @example
@@ -252,7 +256,7 @@ declare const Popover: {
    */
   readonly Content: typeof Content;
   /**
-   * The trigger button that opens the popover when clicked or focused.
+   * The trigger button that opens the popover.
    *
    * @see https://mantle.ngrok.com/components/overlays/popover#popovertrigger
    *

package/dist/popover.d.ts

@@ -1,2 +1,2 @@
-import { t as Popover } from "./popover-DDuw1UaJ.js";
+import { t as Popover } from "./popover-s2LhmzfQ.js";
 export { Popover };

package/dist/popover.js

@@ -1 +1 @@
-import{t as e}from"./popover-D6x6Bq-G.js";export{e as Popover};
+import{t as e}from"./popover-Bp-9B3GR.js";export{e as Popover};

package/dist/primitive-CejGAoGb.js

@@ -0,0 +1 @@
+import{t as e}from"./slot-C3gII_9c.js";import{t}from"./booleanish-BfvnW6vy.js";import{n,r}from"./layer-container-BTcQpd4K.js";import{jsx as i}from"react/jsx-runtime";import*as a from"@radix-ui/react-dialog";function o(e){e.target instanceof Element&&e.target.closest(`.overlay-prompt`)&&e.preventDefault()}const s=a.Root,c=a.Trigger,l=({container:e,...t})=>{let o=r(),s=e??o;return i(n.Provider,{value:s,children:i(a.Portal,{container:s,...t})})},u=a.Close,d=e=>i(a.Overlay,{"data-overlay":!0,...e}),f=({onEscapeKeyDown:e,onInteractOutside:t,onPointerDownOutside:n,ref:r,...s})=>i(a.Content,{ref:r,onEscapeKeyDown:t=>{g(t),e?.(t)},onInteractOutside:e=>{o(e),t?.(e)},onPointerDownOutside:e=>{o(e),n?.(e)},...s}),p=a.Title,m=({asChild:t,children:n,ref:r,...o})=>{let s=t?e:`div`;return i(a.Description,{ref:r,asChild:!0,children:i(s,{...o,children:n})})};function h(e){return e instanceof HTMLElement&&e.hasAttribute(`data-overlay`)}function g(e){if(!b(e.currentTarget))return;let n=e.currentTarget,r=n instanceof Document?n.activeElement:n.ownerDocument?.activeElement??null,i=_(e.target)??_(r),a=i?v(i):null;i!=null&&t(i.getAttribute(`aria-expanded`))&&a!=null&&n.contains(i)&&n.contains(a)&&(a.getAttribute(`data-open`)===`true`||a.getAttribute(`data-state`)===`open`)&&e.preventDefault()}function _(e){return y(e)?e.closest(`[aria-expanded='true'][aria-controls]`):null}function v(e){let t=e.getAttribute(`aria-controls`);if(!t)return null;let n=e.ownerDocument.getElementById(t);return n instanceof HTMLElement?n:null}function y(e){return e instanceof HTMLElement}function b(e){return e instanceof Node&&`querySelector`in e}export{l as a,c,d as i,h as l,f as n,s as o,m as r,p as s,u as t};

package/dist/progress.d.ts

@@ -17,9 +17,7 @@ type Props = SvgAttributes & {
    */
   max?: number | undefined;
   /**
-   * The width of the progress bar stroke.
-   * Note, we clamp the stroke width to a minimum of 1px and max of 12px since
-   * it is proportional to the viewbox size (0 0 32 32).
+   * The width of the progress bar stroke, clamped between 1px and 12px.
    *
    * @default 0.25rem (4px)
    */
@@ -29,6 +27,7 @@ type Props = SvgAttributes & {
    * This attribute specifies how much of the task is complete.
    * It must be a valid floating point number between 0 and `max`, or, when `max` is omitted, between 0 and 100.
    * If set to `"indeterminate"`, the progress bar is considered indeterminate.
+   * A value outside `0..max` also renders as indeterminate.
    *
    * @default 0
    */
@@ -49,16 +48,28 @@ type Props = SvgAttributes & {
  * The indicator color is inherited via `currentColor`. Override the default
  * (`accent-600`) by setting the `ProgressDonut.Indicator`'s text color.
  *
+ * **Accessibility.** Renders `role="progressbar"` with `aria-valuemin`,
+ * `aria-valuemax`, and `aria-valuenow` (omitted while indeterminate). The role
+ * needs a name: pass `aria-label`, or `aria-labelledby` that points at a visible
+ * label.
+ *
+ * | Data Attribute | Value               | Description                 |
+ * | -------------- | ------------------- | --------------------------- |
+ * | `data-slot`    | `"progress-donut"`  | The root `<svg>`.           |
+ * | `data-value`   | the current value   | Absent while indeterminate. |
+ * | `data-min`     | `0`                 |                             |
+ * | `data-max`     | the maximum         |                             |
+ *
  * @see https://mantle.ngrok.com/components/feedback/progress-donut#progressdonutroot
  *
  * @example
  * ```tsx
- * <ProgressDonut.Root value={60}>
+ * <ProgressDonut.Root aria-label="Data transfer out" value={60}>
  *   <ProgressDonut.Indicator />
  * </ProgressDonut.Root>
  *
- * <ProgressDonut.Root value={60}>
- *   <ProgressDonut.Indicator color="text-danger-600" />
+ * <ProgressDonut.Root aria-label="Data transfer out" value={60}>
+ *   <ProgressDonut.Indicator className="text-danger-600" />
  * </ProgressDonut.Root>
  * ```
  */
@@ -71,12 +82,12 @@ type ProgressDonutIndicatorProps = Omit<ComponentProps<"g">, "children">;
  *
  * @example
  * ```tsx
- * <ProgressDonut.Root value={60}>
+ * <ProgressDonut.Root aria-label="Data transfer out" value={60}>
  *   <ProgressDonut.Indicator />
  * </ProgressDonut.Root>
  *
- * <ProgressDonut.Root value={60}>
- *   <ProgressDonut.Indicator color="text-danger-600" />
+ * <ProgressDonut.Root aria-label="Data transfer out" value={60}>
+ *   <ProgressDonut.Indicator className="text-danger-600" />
  * </ProgressDonut.Root>
  * ```
  */
@@ -98,12 +109,12 @@ declare const Indicator$1: ({ className, ...props }: ProgressDonutIndicatorProps
  *
  * @example
  * ```tsx
- * <ProgressDonut.Root value={60}>
+ * <ProgressDonut.Root aria-label="Data transfer out" value={60}>
  *   <ProgressDonut.Indicator />
  * </ProgressDonut.Root>
  *
- * <ProgressDonut.Root value={60}>
- *   <ProgressDonut.Indicator color="text-danger-600" />
+ * <ProgressDonut.Root aria-label="Data transfer out" value={60}>
+ *   <ProgressDonut.Indicator className="text-danger-600" />
  * </ProgressDonut.Root>
  * ```
  */
@@ -114,16 +125,21 @@ declare const ProgressDonut: {
    * The indicator color is inherited via `currentColor`. Override the default
    * (`accent-600`) by setting the `ProgressDonut.Indicator`'s text color.
    *
+   * **Accessibility.** Renders `role="progressbar"` with `aria-valuemin`,
+   * `aria-valuemax`, and `aria-valuenow` (omitted while indeterminate). The role
+   * needs a name: pass `aria-label`, or `aria-labelledby` that points at a visible
+   * label.
+   *
    * @see https://mantle.ngrok.com/components/feedback/progress-donut#progressdonutroot
    *
    * @example
    * ```tsx
-   * <ProgressDonut.Root value={60}>
+   * <ProgressDonut.Root aria-label="Data transfer out" value={60}>
    *   <ProgressDonut.Indicator />
    * </ProgressDonut.Root>
    *
-   * <ProgressDonut.Root value={60}>
-   *   <ProgressDonut.Indicator color="text-danger-600" />
+   * <ProgressDonut.Root aria-label="Data transfer out" value={60}>
+   *   <ProgressDonut.Indicator className="text-danger-600" />
    * </ProgressDonut.Root>
    * ```
    */
@@ -135,12 +151,12 @@ declare const ProgressDonut: {
    *
    * @example
    * ```tsx
-   * <ProgressDonut.Root value={60}>
+   * <ProgressDonut.Root aria-label="Data transfer out" value={60}>
    *   <ProgressDonut.Indicator />
    * </ProgressDonut.Root>
    *
-   * <ProgressDonut.Root value={60}>
-   *   <ProgressDonut.Indicator color="text-danger-600" />
+   * <ProgressDonut.Root aria-label="Data transfer out" value={60}>
+   *   <ProgressDonut.Indicator className="text-danger-600" />
    * </ProgressDonut.Root>
    * ```
    */
@@ -162,6 +178,7 @@ type RootProps = ComponentProps<"div"> & {
    * This attribute specifies how much of the task is complete.
    * It must be a valid floating point number between 0 and `max`, or, when `max` is omitted, between 0 and 100.
    * If set to `"indeterminate"`, the progress bar is considered indeterminate. (for now there is no visual difference than 0)
+   * A value outside `0..max` also renders as indeterminate.
    *
    * @default 0
    */
@@ -173,20 +190,32 @@ type RootProps = ComponentProps<"div"> & {
  * A horizontal progress bar that shows the completion progress of a task.
  * Use this component for linear progress indication.
  *
+ * **Accessibility.** Renders `role="progressbar"` with `aria-valuemin`,
+ * `aria-valuemax`, and `aria-valuenow` (omitted while indeterminate). The role
+ * needs a name: pass `aria-label`, or `aria-labelledby` that points at a visible
+ * label.
+ *
+ * | Data Attribute | Value                                                  | Description                                  |
+ * | -------------- | ------------------------------------------------------ | -------------------------------------------- |
+ * | `data-slot`    | `"progress-bar"`                                       | The root element.                            |
+ * | `data-state`   | `"complete"` \| `"indeterminate"` \| `"loading"`       | Set by Radix from `value` and `max`.         |
+ * | `data-value`   | the current value                                      | Absent while indeterminate.                  |
+ * | `data-max`     | the maximum                                            |                                              |
+ *
  * @see https://mantle.ngrok.com/components/feedback/progress-bar#progressbarroot
  *
  * @example
  * ```tsx
- * <ProgressBar.Root value={60}>
+ * <ProgressBar.Root aria-label="Upload progress" value={60}>
  *   <ProgressBar.Indicator />
  * </ProgressBar.Root>
  *
- * <ProgressBar.Root value={75} max={100}>
+ * <ProgressBar.Root aria-label="Upload progress" value={75} max={100}>
  *   <ProgressBar.Indicator />
  * </ProgressBar.Root>
  *
  * // Indeterminate progress
- * <ProgressBar.Root value="indeterminate">
+ * <ProgressBar.Root aria-label="Upload progress" value="indeterminate">
  *   <ProgressBar.Indicator />
  * </ProgressBar.Root>
  * ```
@@ -203,12 +232,12 @@ type IndicatorProps = ComponentProps<typeof ProgressPrimitive.Indicator>;
  *
  * @example
  * ```tsx
- * <ProgressBar.Root value={60}>
+ * <ProgressBar.Root aria-label="Upload progress" value={60}>
  *   <ProgressBar.Indicator />
  * </ProgressBar.Root>
  *
  * // Custom styled indicator
- * <ProgressBar.Root value={60}>
+ * <ProgressBar.Root aria-label="Upload progress" value={60}>
  *   <ProgressBar.Indicator className="bg-success-600" />
  * </ProgressBar.Root>
  * ```
@@ -231,16 +260,16 @@ declare function Indicator({ className, style, ...props }: IndicatorProps): impo
  *
  * @example
  * ```tsx
- * <ProgressBar.Root value={60}>
+ * <ProgressBar.Root aria-label="Upload progress" value={60}>
  *   <ProgressBar.Indicator />
  * </ProgressBar.Root>
  *
- * <ProgressBar.Root value={75} max={100}>
+ * <ProgressBar.Root aria-label="Upload progress" value={75} max={100}>
  *   <ProgressBar.Indicator />
  * </ProgressBar.Root>
  *
  * // Indeterminate progress
- * <ProgressBar.Root value="indeterminate">
+ * <ProgressBar.Root aria-label="Upload progress" value="indeterminate">
  *   <ProgressBar.Indicator />
  * </ProgressBar.Root>
  * ```
@@ -252,20 +281,25 @@ declare const ProgressBar: {
    * A horizontal progress bar that shows the completion progress of a task.
    * Use this component for linear progress indication.
    *
+   * **Accessibility.** Renders `role="progressbar"` with `aria-valuemin`,
+   * `aria-valuemax`, and `aria-valuenow` (omitted while indeterminate). The role
+   * needs a name: pass `aria-label`, or `aria-labelledby` that points at a visible
+   * label.
+   *
    * @see https://mantle.ngrok.com/components/feedback/progress-bar#progressbarroot
    *
    * @example
    * ```tsx
-   * <ProgressBar.Root value={60}>
+   * <ProgressBar.Root aria-label="Upload progress" value={60}>
    *   <ProgressBar.Indicator />
    * </ProgressBar.Root>
    *
-   * <ProgressBar.Root value={75} max={100}>
+   * <ProgressBar.Root aria-label="Upload progress" value={75} max={100}>
    *   <ProgressBar.Indicator />
    * </ProgressBar.Root>
    *
    * // Indeterminate progress
-   * <ProgressBar.Root value="indeterminate">
+   * <ProgressBar.Root aria-label="Upload progress" value="indeterminate">
    *   <ProgressBar.Indicator />
    * </ProgressBar.Root>
    * ```
@@ -281,12 +315,12 @@ declare const ProgressBar: {
    *
    * @example
    * ```tsx
-   * <ProgressBar.Root value={60}>
+   * <ProgressBar.Root aria-label="Upload progress" value={60}>
    *   <ProgressBar.Indicator />
    * </ProgressBar.Root>
    *
    * // Custom styled indicator
-   * <ProgressBar.Root value={60}>
+   * <ProgressBar.Root aria-label="Upload progress" value={60}>
    *   <ProgressBar.Indicator className="bg-success-600" />
    * </ProgressBar.Root>
    * ```

package/dist/progress.js

@@ -1 +1 @@
-import{t as e}from"./cx-IiQEAKf5.js";import{t}from"./types-D85fCNV3.js";import{t as n}from"./clsx-DUGZgXfJ.js";import{createContext as r,useContext as i,useId as a,useMemo as o}from"react";import{jsx as s,jsxs as c}from"react/jsx-runtime";import*as l from"@radix-ui/react-progress";function u(e,{min:t,max:n}){return Math.min(n,Math.max(t,e))}function d(e){return typeof e==`number`}function f(e,t){return d(e)&&!Number.isNaN(e)&&e<=t&&e>=0}function p(e){return d(e)&&!Number.isNaN(e)&&e>0}const m={max:100,strokeWidth:`0.25rem`,value:0},h=r(m),g={Root:({children:n,className:r,max:i=100,strokeWidth:a=4,value:l,indeterminateRotationSpeed:u,...g})=>{let y=p(i)?i:100,b=f(l,y)?l:l==null?0:`indeterminate`,x=_(a??m.strokeWidth),S=d(b)?b:void 0,C=v(x),w=o(()=>({max:y,strokeWidth:x,value:b}),[y,x,b]);return s(h.Provider,{value:w,children:c(`svg`,{"data-slot":`progress-donut`,"aria-valuemax":y,"aria-valuemin":0,"aria-valuenow":S,className:e(`size-6 text-gray-200 dark:text-gray-300`,b===`indeterminate`&&[`animate-spin`,u??`animation-duration-[15s]`],r),"data-max":y,"data-min":0,"data-value":S,height:`100%`,role:`progressbar`,width:`100%`,...g,children:[s(`circle`,{className:`[r:var(--radius)]`,cx:`50%`,cy:`50%`,fill:`transparent`,stroke:`currentColor`,strokeWidth:x,style:t({"--radius":C})}),n]})})},Indicator:({className:r,...o})=>{let l=a(),u=i(h)??m,d=(u.value===`indeterminate`?.6:u.value/u.max)*100,f=_(u.strokeWidth),p=v(f);return c(`g`,{"data-slot":`progress-donut-indicator`,className:e(`text-accent-600`,r),...o,children:[u.value===`indeterminate`&&s(`defs`,{children:c(`linearGradient`,{id:l,children:[s(`stop`,{className:`stop-opacity-100 stop-color-current`,offset:`0%`}),s(`stop`,{className:`stop-opacity-0 stop-color-current`,offset:`95%`})]})}),s(`circle`,{className:n(`[r:var(--radius)]`,`origin-center`),cx:`50%`,cy:`50%`,fill:`transparent`,pathLength:100,stroke:u.value===`indeterminate`?`url(#${l})`:`currentColor`,strokeDasharray:100,strokeDashoffset:100-d,strokeLinecap:`round`,strokeWidth:f,style:t({"--radius":p}),transform:`rotate(-90)`})]})}};function _(e){let t=4;return e==null?t:(t=typeof e==`number`?e:e.endsWith(`rem`)?Number(e.replace(`rem`,``))*16:Number(e),u(Number.isNaN(t)?4:t,{min:1,max:12}))}function v(e){return`calc(50% - ${e/2}px)`}const y=r({max:100,value:0});function b({className:t,children:n,max:r=100,value:i,...a}){let c=p(r)?r:100,u=f(i,c)?i:i==null?0:`indeterminate`,m=d(u)?u:void 0,h=o(()=>({max:c,value:u}),[c,u]);return s(y.Provider,{value:h,children:s(l.Root,{"data-slot":`progress-bar`,className:e(`bg-base-hover dark:bg-base shadow-inner relative h-3 w-full overflow-hidden rounded-md`,t),value:m,max:c,...a,children:n})})}function x({className:t,style:n,...r}){let a=i(y),{max:o}=a,c=(o-(a.value===`indeterminate`?0:a.value))/o*100;return s(l.Indicator,{"data-slot":`progress-bar-indicator`,className:e(`bg-accent-600 h-full w-full flex-1 transition-all`,t),style:{...n,transform:`translateX(-${c}%)`},...r})}const S={Root:b,Indicator:x};export{S as ProgressBar,g as ProgressDonut};
+import{t as e}from"./cx-0HCjnNv1.js";import{t}from"./types-D85fCNV3.js";import{t as n}from"./clsx-DUGZgXfJ.js";import{createContext as r,useContext as i,useId as a,useMemo as o}from"react";import{jsx as s,jsxs as c}from"react/jsx-runtime";import*as l from"@radix-ui/react-progress";function u(e,{min:t,max:n}){return Math.min(n,Math.max(t,e))}function d(e){return typeof e==`number`}function f(e,t){return d(e)&&!Number.isNaN(e)&&e<=t&&e>=0}function p(e){return d(e)&&!Number.isNaN(e)&&e>0}const m={max:100,strokeWidth:`0.25rem`,value:0},h=r(m),g={Root:({children:n,className:r,max:i=100,strokeWidth:a=4,value:l,indeterminateRotationSpeed:u,...g})=>{let y=p(i)?i:100,b=f(l,y)?l:l==null?0:`indeterminate`,x=_(a??m.strokeWidth),S=d(b)?b:void 0,C=v(x),w=t({"--radius":C}),T=o(()=>({max:y,strokeWidth:x,value:b}),[y,x,b]);return s(h.Provider,{value:T,children:c(`svg`,{"data-slot":`progress-donut`,"aria-valuemax":y,"aria-valuemin":0,"aria-valuenow":S,className:e(`size-6 text-gray-200 dark:text-gray-300`,b===`indeterminate`&&[`animate-spin`,u??`animation-duration-[15s]`],r),"data-max":y,"data-min":0,"data-value":S,height:`100%`,role:`progressbar`,width:`100%`,...g,children:[s(`circle`,{className:`[r:var(--radius)]`,cx:`50%`,cy:`50%`,fill:`transparent`,stroke:`currentColor`,strokeWidth:x,style:w}),n]})})},Indicator:({className:r,...o})=>{let l=a(),u=i(h)??m,d=(u.value===`indeterminate`?.6:u.value/u.max)*100,f=_(u.strokeWidth),p=v(f);return c(`g`,{"data-slot":`progress-donut-indicator`,className:e(`text-accent-600`,r),...o,children:[u.value===`indeterminate`&&s(`defs`,{children:c(`linearGradient`,{id:l,children:[s(`stop`,{className:`stop-opacity-100 stop-color-current`,offset:`0%`}),s(`stop`,{className:`stop-opacity-0 stop-color-current`,offset:`95%`})]})}),s(`circle`,{className:n(`[r:var(--radius)]`,`origin-center`),cx:`50%`,cy:`50%`,fill:`transparent`,pathLength:100,stroke:u.value===`indeterminate`?`url(#${l})`:`currentColor`,strokeDasharray:100,strokeDashoffset:100-d,strokeLinecap:`round`,strokeWidth:f,style:t({"--radius":p}),transform:`rotate(-90)`})]})}};function _(e){let t=4;return e==null?t:(t=typeof e==`number`?e:e.endsWith(`rem`)?Number(e.replace(`rem`,``))*16:Number(e),u(Number.isNaN(t)?4:t,{min:1,max:12}))}function v(e){return`calc(50% - ${e/2}px)`}const y=r({max:100,value:0});function b({className:t,children:n,max:r=100,value:i,...a}){let c=p(r)?r:100,u=f(i,c)?i:i==null?0:`indeterminate`,m=d(u)?u:void 0,h=o(()=>({max:c,value:u}),[c,u]);return s(y.Provider,{value:h,children:s(l.Root,{"data-slot":`progress-bar`,className:e(`bg-base-hover dark:bg-base shadow-inner relative h-3 w-full overflow-hidden rounded-md`,t),value:m,max:c,...a,children:n})})}function x({className:t,style:n,...r}){let a=i(y),{max:o}=a,c=(o-(a.value===`indeterminate`?0:a.value))/o*100;return s(l.Indicator,{"data-slot":`progress-bar-indicator`,className:e(`bg-accent-600 h-full w-full flex-1 transition-all`,t),style:{...n,transform:`translateX(-${c}%)`},...r})}const S={Root:b,Indicator:x};export{S as ProgressBar,g as ProgressDonut};

package/dist/qr-code.d.ts

@@ -60,14 +60,19 @@ type QrCodeRootProps = ComponentProps<"div"> & WithAsChild & {
 declare const Root: ({ value, ecc, pixelSize, quietZone, asChild, className, children, ref, ...props }: QrCodeRootProps) => import("react").JSX.Element;
 /**
  * Props for `QrCode.Frame`, the fixed SVG element that sizes the encoded QR
- * pattern with its `viewBox`.
+ * pattern with its `viewBox`. `role` is locked to `"img"`.
  */
-type QrCodeFrameProps = ComponentProps<"svg">;
+type QrCodeFrameProps = Omit<ComponentProps<"svg">, "role">;
 /**
  * The `svg` frame that holds the QR `Pattern`. Defaults to a square `size-48`
  * and scales the encoded pattern to fit via its `viewBox`, so resize the whole
  * code by passing a different size to `className` (e.g. `className="size-64"`).
  *
+ * The frame is the image a screen reader meets: it always carries
+ * `role="img"`. Pass `aria-label` (or `aria-labelledby`) that says what the
+ * code encodes, such as "QR code for the ngrok dashboard". When neither is
+ * set, the name falls back to "QR code".
+ *
  * Does not support `asChild`: the QR pattern must live inside an `svg`, so the
  * frame element is fixed and cannot be swapped.
  *
@@ -85,7 +90,7 @@ type QrCodeFrameProps = ComponentProps<"svg">;
  * </QrCode.Root>
  * ```
  */
-declare const Frame: ({ className, children, ref, ...props }: QrCodeFrameProps) => import("react").JSX.Element;
+declare const Frame: ({ "aria-label": ariaLabel, "aria-labelledby": ariaLabelledBy, className, children, ref, ...props }: QrCodeFrameProps) => import("react").JSX.Element;
 /**
  * Props for `QrCode.Pattern`, the fixed SVG `path` element that renders the
  * encoded dark modules.
@@ -94,7 +99,8 @@ type QrCodePatternProps = ComponentProps<"path">;
 /**
  * The encoded QR modules, rendered as a single `path` inside the `Frame`.
  * Defaults to black fill (`fill-static-black`) so the code stays scannable in
- * every theme.
+ * every theme. A consumer `className` can override the fill, but a light or
+ * inverted fill makes the code unreliable for many scanners.
  *
  * Does not support `asChild`: the modules are a fixed `path` and cannot be
  * swapped for another element.