@box-kite/react 1.0.0 → 2.0.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@box-kite/react",
-  "version": "1.0.0",
+  "version": "2.0.1",
   "type": "module",
   "sideEffects": [
     "pages/**"
@@ -29,6 +29,11 @@
       "import": "./a11y.mjs",
       "require": "./a11y.cjs"
     },
+    "./anchor": {
+      "types": "./anchor.d.ts",
+      "import": "./anchor.mjs",
+      "require": "./anchor.cjs"
+    },
     "./ssg": {
       "types": "./ssg.d.ts",
       "import": "./ssg.mjs",
@@ -68,8 +73,15 @@
     "check:docs": "node scripts/check-docs-snippets.mjs",
     "check:props": "node scripts/check-props-api.mjs",
     "docs:props": "node scripts/check-props-api.mjs --fix",
+    "check:components": "node scripts/check-components-api.mjs",
+    "docs:components": "node scripts/check-components-api.mjs --fix",
+    "check:conventions": "node scripts/check-component-conventions.mjs",
+    "check:agents": "node scripts/check-agent-files.mjs",
+    "docs:agents": "node scripts/check-agent-files.mjs --fix",
     "check:package": "publint dist && attw --pack dist --ignore-rules false-esm cjs-resolves-to-esm internal-resolution-error && publint dist-core && attw --pack dist-core --ignore-rules false-esm cjs-resolves-to-esm internal-resolution-error",
-    "size": "size-limit"
+    "size": "size-limit",
+    "size:published": "node dev/published-size.mjs",
+    "release": "node scripts/release.mjs"
   },
   "size-limit": [
     {
@@ -80,7 +92,7 @@
         "react-dom"
       ],
       "gzip": true,
-      "limit": "26.20 KB"
+      "limit": "30.40 KB"
     },
     {
       "name": "Box in a Server Component (react-server entry)",
@@ -90,7 +102,7 @@
         "react-dom"
       ],
       "gzip": true,
-      "limit": "24.70 KB"
+      "limit": "28.90 KB"
     },
     {
       "name": "Behavior primitives (a11y entry)",
@@ -100,13 +112,113 @@
         "react-dom"
       ],
       "gzip": true,
-      "limit": "3.13 KB"
+      "limit": "3.2 KB"
+    },
+    {
+      "name": "Anchor positioning (anchor entry)",
+      "path": "dist/anchor.mjs",
+      "ignore": [
+        "react",
+        "react-dom"
+      ],
+      "gzip": true,
+      "limit": "2.25 KB"
     },
     {
       "name": "Core engine (@box-kite/core, no React)",
       "path": "dist-core/core.mjs",
       "gzip": true,
-      "limit": "24.10 KB"
+      "limit": "28.17 KB"
+    },
+    {
+      "name": "Dialog",
+      "path": "dist/components/dialog.mjs",
+      "ignore": [
+        "react",
+        "react-dom"
+      ],
+      "gzip": true,
+      "limit": "32.55 KB"
+    },
+    {
+      "name": "Popover",
+      "path": "dist/components/popover.mjs",
+      "ignore": [
+        "react",
+        "react-dom"
+      ],
+      "gzip": true,
+      "limit": "34.02 KB"
+    },
+    {
+      "name": "Menu",
+      "path": "dist/components/menu.mjs",
+      "ignore": [
+        "react",
+        "react-dom"
+      ],
+      "gzip": true,
+      "limit": "36.27 KB"
+    },
+    {
+      "name": "Accordion",
+      "path": "dist/components/accordion.mjs",
+      "ignore": [
+        "react",
+        "react-dom"
+      ],
+      "gzip": true,
+      "limit": "31.76 KB"
+    },
+    {
+      "name": "Tabs",
+      "path": "dist/components/tabs.mjs",
+      "ignore": [
+        "react",
+        "react-dom"
+      ],
+      "gzip": true,
+      "limit": "32.96 KB"
+    },
+    {
+      "name": "Slider",
+      "path": "dist/components/slider.mjs",
+      "ignore": [
+        "react",
+        "react-dom"
+      ],
+      "gzip": true,
+      "limit": "32.12 KB"
+    },
+    {
+      "name": "Progress",
+      "path": "dist/components/progress.mjs",
+      "ignore": [
+        "react",
+        "react-dom"
+      ],
+      "gzip": true,
+      "limit": "30.28 KB"
+    },
+    {
+      "name": "Toaster",
+      "path": "dist/components/toaster.mjs",
+      "ignore": [
+        "react",
+        "react-dom"
+      ],
+      "gzip": true,
+      "limit": "33.77 KB"
+    },
+    {
+      "name": "Combobox",
+      "path": "dist/components/combobox.mjs",
+      "ignore": [
+        "react",
+        "react-dom"
+      ],
+      "gzip": true,
+      "limit": "39.54 KB"
     },
     {
       "name": "DataGrid",
@@ -116,7 +228,17 @@
         "react-dom"
       ],
       "gzip": true,
-      "limit": "54.55 KB"
+      "limit": "74.86 KB"
+    },
+    {
+      "name": "DataGrid export, the chunk fetched on the first press",
+      "path": "dist/gridExport.mjs",
+      "ignore": [
+        "react",
+        "react-dom"
+      ],
+      "gzip": true,
+      "limit": "3.8 KB"
     },
     {
       "name": "Full library (Box + ssg + every component)",
@@ -126,7 +248,7 @@
         "react-dom"
       ],
       "gzip": true,
-      "limit": "60.85 KB"
+      "limit": "96.82 KB"
     }
   ],
   "repository": {
@@ -154,13 +276,13 @@
     "url": "https://github.com/box-kite/box-kite/issues"
   },
   "homepage": "https://www.box-kite.dev",
-  "description": "One React component with 212 typed CSS props that generates atomic CSS at runtime — no CSS files, no build step, renders in a Server Component.",
+  "description": "One React component with 221 typed CSS props that generates atomic CSS at runtime — no CSS files, no build step, renders in a Server Component.",
   "peerDependencies": {
     "react": "^16.14.0 || ^17.0.0 || ^18.0.0 || ^19.0.0",
     "react-dom": "^16.14.0 || ^17.0.0 || ^18.0.0 || ^19.0.0"
   },
   "dependencies": {
-    "@box-kite/core": "1.0.0",
+    "@box-kite/core": "2.0.1",
     "csstype": "^3.2.3",
     "use-sync-external-store": "^1.6.0"
   },
@@ -190,9 +312,11 @@
     "eslint-plugin-prettier": "^5.5.6",
     "eslint-plugin-react-hooks": "^7.1.1",
     "eslint-plugin-react-refresh": "^0.5.3",
+    "exceljs": "^4.4.0",
     "globals": "^17.9.0",
     "happy-dom": "^20.11.1",
     "lucide-react": "^1.28.0",
+    "marked": "^18.0.11",
     "prettier": "^3.9.6",
     "prismjs": "^1.30.0",
     "publint": "^0.3.24",

package/placement.cjs

@@ -0,0 +1 @@
+const e=require("./platform.cjs"),t=require("./effects.cjs"),n=require("./identity.cjs");let r=require("react");var i={top:`bottom`,bottom:`top`,start:`end`,end:`start`};function a(e){return e===`top`||e===`bottom`}function o(e,t){let n=a(e),r=n?e===`top`?`block-start`:`block-end`:e===`start`?`inline-start`:`inline-end`,i=t===`center`?`span-all`:`span-${n?`inline`:`block`}-${t===`start`?`end`:`start`}`;return n?`${r} ${i}`:`${i} ${r}`}function s(e){let[t,n]=e.trim().split(` `);return n===void 0?t===`block-start`?`top`:t===`block-end`?`bottom`:t===`inline-start`?`start`:t===`inline-end`?`end`:null:t===`start`?`top`:t===`end`?`bottom`:n===`start`?`start`:n===`end`?`end`:null}function c(e){return a(e)?`flip-block, flip-inline, flip-block flip-inline`:`flip-inline, flip-block, flip-inline flip-block`}function l(e,t,n,r){let i=u(t,r);return i===`top`?e.top-n.top:i===`bottom`?n.top+n.height-(e.top+e.height):i===`left`?e.left-n.left:n.left+n.width-(e.left+e.width)}function u(e,t){return e===`top`||e===`bottom`?e:e===`start`===t?`right`:`left`}function d(e,t,n,r){return Math.max(n,Math.min(e,n+r-t))}function f(e,t,n,r){let{align:o,offset:s,flip:c,rtl:f}=r,p=(a(r.side)?t.height:t.width)+s,m=c&&l(e,r.side,n,f)<p&&l(e,i[r.side],n,f)>=p?i[r.side]:r.side,h=u(m,f),g={top:e.top-t.height-s,bottom:e.top+e.height+s,left:e.left-t.width-s,right:e.left+e.width+s}[h],_=a(m),v=_?e.left:e.top,y=_?e.width:e.height,b=_?t.width:t.height,x=o===`center`?v+y/2-b/2:o===`start`===(_&&f)?v+y-b:v,S=_?d(x,t.width,n.left,n.width):d(x,t.height,n.top,n.height);return _?{top:g,left:S,side:m}:{top:S,left:g,side:m}}var p=4,m=16,h={top:`mb`,bottom:`mt`,start:`me`,end:`ms`};function g(){return typeof CSS<`u`&&typeof CSS.supports==`function`&&CSS.supports(`anchor-name: --a`)}function _(){let e=typeof document>`u`?null:document.documentElement,t=e?parseFloat(getComputedStyle(e).fontSize):NaN;return Number.isFinite(t)&&t>0?t:m}function v(e){let{top:t,left:n,width:r,height:i}=e.getBoundingClientRect();return{top:t,left:n,width:r,height:i}}function y(e,t){return e!==null&&e.top===t.top&&e.left===t.left&&e.side===t.side&&e.anchorWidth===t.anchorWidth}function b(i={}){let{side:a=`bottom`,align:l=`center`,offset:u=0,flip:d=!0,matchWidth:m=!1,name:b,anchor:x,trackSide:S=!1}=i,C=n.t(`anchor`),w=`--${(b??C).replace(/^--/,``)}`,[T,E]=(0,r.useState)(!0),[D,O]=(0,r.useState)(null),[k,A]=(0,r.useState)(null),[j,M]=(0,r.useState)(null),[N,P]=(0,r.useState)(null);t.n(()=>{g()||E(!1)},[]),t.n(()=>{let t=e.c(x);if(t)return t.style.setProperty(`anchor-name`,w),()=>{t.style.removeProperty(`anchor-name`)}},[x,w]),t.n(()=>{!T||!S||!k||P(s(getComputedStyle(k).getPropertyValue(`position-area`)))},[T,S,k,a,l,d]),t.n(()=>{let t=e.c(x)??D;if(T||!t||!k)return;let n=()=>{let n=v(t),r=v(k),i={top:0,left:0,width:window.innerWidth,height:window.innerHeight},o=m?Math.max(r.width,n.width):r.width,s={...f(n,{...r,width:o},i,{side:a,align:l,offset:u/p*_(),flip:d,rtl:e.u(t)}),anchorWidth:n.width};M(e=>y(e,s)?e:s)};n();let r=new AbortController;return document.addEventListener(`scroll`,n,{signal:r.signal,capture:!0,passive:!0}),window.addEventListener(`resize`,n,{signal:r.signal,passive:!0}),()=>r.abort()},[T,x,D,k,a,l,u,d,m]);let F=(0,r.useCallback)(e=>O(e),[]),I=(0,r.useCallback)(e=>A(e),[]),L={ref:T?void 0:F,style:{anchorName:w}};return T?{css:T,side:N??a,anchorProps:L,layerProps:{...S?{ref:I}:{},position:`fixed`,positionArea:o(a,l),...d?{positionTryFallbacks:c(a)}:{},...m?{minWidth:`anchor-size(width)`}:{},...u?{[h[a]]:u}:{},style:{positionAnchor:w}}}:{css:T,side:j?.side??a,anchorProps:L,layerProps:{ref:I,position:`fixed`,style:j?{top:`${j.top}px`,left:`${j.left}px`,...m?{minWidth:`${j.anchorWidth}px`}:{}}:{top:0,left:0,visibility:`hidden`}}}}Object.defineProperty(exports,"t",{enumerable:!0,get:function(){return b}});

package/placement.mjs

@@ -0,0 +1,180 @@
+import { c as e, u as t } from "./platform.mjs";
+import { n } from "./effects.mjs";
+import { t as r } from "./identity.mjs";
+import { useCallback as i, useState as a } from "react";
+//#region src/utils/anchor/anchorUtils.ts
+var o = {
+	top: "bottom",
+	bottom: "top",
+	start: "end",
+	end: "start"
+};
+function s(e) {
+	return e === "top" || e === "bottom";
+}
+function c(e, t) {
+	let n = s(e), r = n ? e === "top" ? "block-start" : "block-end" : e === "start" ? "inline-start" : "inline-end", i = t === "center" ? "span-all" : `span-${n ? "inline" : "block"}-${t === "start" ? "end" : "start"}`;
+	return n ? `${r} ${i}` : `${i} ${r}`;
+}
+function l(e) {
+	let [t, n] = e.trim().split(" ");
+	return n === void 0 ? t === "block-start" ? "top" : t === "block-end" ? "bottom" : t === "inline-start" ? "start" : t === "inline-end" ? "end" : null : t === "start" ? "top" : t === "end" ? "bottom" : n === "start" ? "start" : n === "end" ? "end" : null;
+}
+function u(e) {
+	return s(e) ? "flip-block, flip-inline, flip-block flip-inline" : "flip-inline, flip-block, flip-inline flip-block";
+}
+function d(e, t, n, r) {
+	let i = f(t, r);
+	return i === "top" ? e.top - n.top : i === "bottom" ? n.top + n.height - (e.top + e.height) : i === "left" ? e.left - n.left : n.left + n.width - (e.left + e.width);
+}
+function f(e, t) {
+	return e === "top" || e === "bottom" ? e : e === "start" === t ? "right" : "left";
+}
+function p(e, t, n, r) {
+	return Math.max(n, Math.min(e, n + r - t));
+}
+function m(e, t, n, r) {
+	let { align: i, offset: a, flip: c, rtl: l } = r, u = (s(r.side) ? t.height : t.width) + a, m = c && d(e, r.side, n, l) < u && d(e, o[r.side], n, l) >= u ? o[r.side] : r.side, h = f(m, l), g = {
+		top: e.top - t.height - a,
+		bottom: e.top + e.height + a,
+		left: e.left - t.width - a,
+		right: e.left + e.width + a
+	}[h], _ = s(m), v = _ ? e.left : e.top, y = _ ? e.width : e.height, b = _ ? t.width : t.height, x = i === "center" ? v + y / 2 - b / 2 : i === "start" === (_ && l) ? v + y - b : v, S = _ ? p(x, t.width, n.left, n.width) : p(x, t.height, n.top, n.height);
+	return _ ? {
+		top: g,
+		left: S,
+		side: m
+	} : {
+		top: S,
+		left: g,
+		side: m
+	};
+}
+//#endregion
+//#region src/react/anchor/useAnchorPosition.ts
+var h = 4, g = 16, _ = {
+	top: "mb",
+	bottom: "mt",
+	start: "me",
+	end: "ms"
+};
+function v() {
+	return typeof CSS < "u" && typeof CSS.supports == "function" && CSS.supports("anchor-name: --a");
+}
+function y() {
+	let e = typeof document > "u" ? null : document.documentElement, t = e ? parseFloat(getComputedStyle(e).fontSize) : NaN;
+	return Number.isFinite(t) && t > 0 ? t : g;
+}
+function b(e) {
+	let { top: t, left: n, width: r, height: i } = e.getBoundingClientRect();
+	return {
+		top: t,
+		left: n,
+		width: r,
+		height: i
+	};
+}
+function x(e, t) {
+	return e !== null && e.top === t.top && e.left === t.left && e.side === t.side && e.anchorWidth === t.anchorWidth;
+}
+function S(o = {}) {
+	let { side: s = "bottom", align: d = "center", offset: f = 0, flip: p = !0, matchWidth: g = !1, name: S, anchor: C, trackSide: w = !1 } = o, T = r("anchor"), E = `--${(S ?? T).replace(/^--/, "")}`, [D, O] = a(!0), [k, A] = a(null), [j, M] = a(null), [N, P] = a(null), [F, I] = a(null);
+	n(() => {
+		v() || O(!1);
+	}, []), n(() => {
+		let t = e(C);
+		if (t) return t.style.setProperty("anchor-name", E), () => {
+			t.style.removeProperty("anchor-name");
+		};
+	}, [C, E]), n(() => {
+		!D || !w || !j || I(l(getComputedStyle(j).getPropertyValue("position-area")));
+	}, [
+		D,
+		w,
+		j,
+		s,
+		d,
+		p
+	]), n(() => {
+		let n = e(C) ?? k;
+		if (D || !n || !j) return;
+		let r = () => {
+			let e = b(n), r = b(j), i = {
+				top: 0,
+				left: 0,
+				width: window.innerWidth,
+				height: window.innerHeight
+			}, a = g ? Math.max(r.width, e.width) : r.width, o = {
+				...m(e, {
+					...r,
+					width: a
+				}, i, {
+					side: s,
+					align: d,
+					offset: f / h * y(),
+					flip: p,
+					rtl: t(n)
+				}),
+				anchorWidth: e.width
+			};
+			P((e) => x(e, o) ? e : o);
+		};
+		r();
+		let i = new AbortController();
+		return document.addEventListener("scroll", r, {
+			signal: i.signal,
+			capture: !0,
+			passive: !0
+		}), window.addEventListener("resize", r, {
+			signal: i.signal,
+			passive: !0
+		}), () => i.abort();
+	}, [
+		D,
+		C,
+		k,
+		j,
+		s,
+		d,
+		f,
+		p,
+		g
+	]);
+	let L = i((e) => A(e), []), R = i((e) => M(e), []), z = {
+		ref: D ? void 0 : L,
+		style: { anchorName: E }
+	};
+	return D ? {
+		css: D,
+		side: F ?? s,
+		anchorProps: z,
+		layerProps: {
+			...w ? { ref: R } : {},
+			position: "fixed",
+			positionArea: c(s, d),
+			...p ? { positionTryFallbacks: u(s) } : {},
+			...g ? { minWidth: "anchor-size(width)" } : {},
+			...f ? { [_[s]]: f } : {},
+			style: { positionAnchor: E }
+		}
+	} : {
+		css: D,
+		side: N?.side ?? s,
+		anchorProps: z,
+		layerProps: {
+			ref: R,
+			position: "fixed",
+			style: N ? {
+				top: `${N.top}px`,
+				left: `${N.left}px`,
+				...g ? { minWidth: `${N.anchorWidth}px` } : {}
+			} : {
+				top: 0,
+				left: 0,
+				visibility: "hidden"
+			}
+		}
+	};
+}
+//#endregion
+export { S as t };

package/platform.cjs

@@ -1 +1 @@
-function e(e){return e?`current`in e?e.current:e:null}function t(t){let n=e(t);return n instanceof HTMLElement?n:null}function n(t,n){let r=typeof t.composedPath==`function`?t.composedPath():[];return n.some(n=>{let i=e(n);return i?r.includes(i)||t.target instanceof Node&&i.contains(t.target):!1})}function r(t){let n=e(t),r=n?.ownerDocument?.defaultView;return!!n&&!!r&&r.getComputedStyle(n).direction===`rtl`}function i(){return typeof window<`u`&&window.document!==void 0}function a(){return typeof document<`u`}function o(){return a()?document:null}Object.defineProperty(exports,"a",{enumerable:!0,get:function(){return n}}),Object.defineProperty(exports,"i",{enumerable:!0,get:function(){return t}}),Object.defineProperty(exports,"n",{enumerable:!0,get:function(){return i}}),Object.defineProperty(exports,"o",{enumerable:!0,get:function(){return r}}),Object.defineProperty(exports,"r",{enumerable:!0,get:function(){return e}}),Object.defineProperty(exports,"t",{enumerable:!0,get:function(){return o}});
+function e(e){return e?`current`in e?e.current:e:null}function t(t){let n=e(t);return n instanceof HTMLElement?n:null}function n(t,n){let r=typeof t.composedPath==`function`?t.composedPath():[];return n.some(n=>{let i=e(n);return i?r.includes(i)||t.target instanceof Node&&i.contains(t.target):!1})}function r(t){let n=e(t),r=n?.ownerDocument?.defaultView;return!!n&&!!r&&r.getComputedStyle(n).direction===`rtl`}function i(t){let n=e(t)?.ownerDocument?.defaultView?.getSelection();n&&!n.isCollapsed&&n.removeAllRanges()}function a(){return typeof window<`u`&&window.document!==void 0}function o(){return typeof document<`u`}function s(){return o()?document:null}function c(){return s()?.documentElement??null}function l(){return typeof HTMLElement<`u`&&typeof HTMLElement.prototype.showPopover==`function`}function u(){return typeof HTMLDialogElement<`u`&&`closedBy`in HTMLDialogElement.prototype}Object.defineProperty(exports,"a",{enumerable:!0,get:function(){return l}}),Object.defineProperty(exports,"c",{enumerable:!0,get:function(){return t}}),Object.defineProperty(exports,"i",{enumerable:!0,get:function(){return u}}),Object.defineProperty(exports,"l",{enumerable:!0,get:function(){return n}}),Object.defineProperty(exports,"n",{enumerable:!0,get:function(){return c}}),Object.defineProperty(exports,"o",{enumerable:!0,get:function(){return i}}),Object.defineProperty(exports,"r",{enumerable:!0,get:function(){return a}}),Object.defineProperty(exports,"s",{enumerable:!0,get:function(){return e}}),Object.defineProperty(exports,"t",{enumerable:!0,get:function(){return s}}),Object.defineProperty(exports,"u",{enumerable:!0,get:function(){return r}});

package/platform.mjs

@@ -17,16 +17,29 @@ function r(t) {
 	let n = e(t), r = n?.ownerDocument?.defaultView;
 	return !!n && !!r && r.getComputedStyle(n).direction === "rtl";
 }
+function i(t) {
+	let n = e(t)?.ownerDocument?.defaultView?.getSelection();
+	n && !n.isCollapsed && n.removeAllRanges();
+}
 //#endregion
 //#region src/utils/environment/environmentUtils.ts
-function i() {
+function a() {
 	return typeof window < "u" && window.document !== void 0;
 }
-function a() {
+function o() {
 	return typeof document < "u";
 }
-function o() {
-	return a() ? document : null;
+function s() {
+	return o() ? document : null;
+}
+function c() {
+	return s()?.documentElement ?? null;
+}
+function l() {
+	return typeof HTMLElement < "u" && typeof HTMLElement.prototype.showPopover == "function";
+}
+function u() {
+	return typeof HTMLDialogElement < "u" && "closedBy" in HTMLDialogElement.prototype;
 }
 //#endregion
-export { n as a, t as i, i as n, r as o, e as r, o as t };
+export { l as a, t as c, u as i, n as l, c as n, i as o, a as r, e as s, s as t, r as u };

package/react/anchor/useAnchorPosition.d.ts

@@ -0,0 +1,79 @@
+import { CSSProperties } from 'react';
+import { BoxStyleProps } from '@box-kite/core/types';
+import { AnchorAlign, AnchorSide } from '../../utils/anchor/anchorUtils';
+import { ElementLike } from '../../utils/dom/domUtils';
+export interface AnchorPositionOptions {
+    /** Which side of the anchor to sit on. `top`/`bottom` are the block axis, `start`/`end` the inline one. Default `'bottom'`. */
+    side?: AnchorSide;
+    /** Which of the anchor's edges to line up with along the other axis. Default `'center'`. */
+    align?: AnchorAlign;
+    /** The gap between anchor and layer, on the ÷4 spacing scale — `offset: 2` is 8px. Default `0`. */
+    offset?: number;
+    /**
+     * Whether the browser may move the layer where it does not fit: the side swapped for its opposite, the
+     * alignment mirrored, or both — three candidates, since a candidate has to fit on both axes. Default `true`.
+     */
+    flip?: boolean;
+    /** Whether the layer is at least as wide as its anchor, the way a select popup is. Default `false`. */
+    matchWidth?: boolean;
+    /** The anchor's name. Generated per instance when omitted, which is what keeps two layers apart. */
+    name?: string;
+    /**
+     * The anchor as an element rather than props to spread — for a caller handed a trigger it does not
+     * render itself. The name is written onto it in a layout effect, so a ref is read when the layer mounts.
+     */
+    anchor?: ElementLike;
+    /**
+     * Whether `side` reports where the layer ended up rather than where it was asked to go. Off by default,
+     * because on the CSS path it costs the one thing that path otherwise never does: a read after layout.
+     */
+    trackSide?: boolean;
+}
+/** The two anchor-positioning properties, which csstype does not know yet. An inline style, deliberately — see the hook. */
+type AnchorStyle = CSSProperties & {
+    anchorName?: string;
+    positionAnchor?: string;
+};
+/** What goes on the anchor: its name, and — where the browser cannot place the layer — a ref to measure it by. */
+export interface AnchorElementProps {
+    ref?: (element: HTMLElement | null) => void;
+    style: AnchorStyle;
+}
+/** What goes on the floating layer. The geometry is shared props; only the identity and the fallback's coordinates are inline. */
+export interface AnchorLayerProps extends Pick<BoxStyleProps, 'position' | 'positionArea' | 'positionTryFallbacks' | 'minWidth' | 'mt' | 'mb' | 'ms' | 'me'> {
+    ref?: (element: HTMLElement | null) => void;
+    style: AnchorStyle;
+}
+export interface AnchorPosition {
+    /** Whether the browser is placing the layer. `false` means this hook measured it instead. */
+    css: boolean;
+    /** The side the layer is on: the requested one, unless `trackSide` is on and a flip moved it. */
+    side: AnchorSide;
+    anchorProps: AnchorElementProps;
+    layerProps: AnchorLayerProps;
+}
+/**
+ * A floating layer placed against an anchor — in CSS where the browser has anchor positioning, and by
+ * measurement where it does not. Spread `anchorProps` on the trigger and `layerProps` on the layer;
+ * nothing else is needed, and on the CSS path nothing runs at all: no scroll listener, no state, no
+ * measurement, because `position-area` and `position-try-fallbacks` are the flip a positioning library
+ * ships JS for.
+ *
+ * ```tsx
+ * const { anchorProps, layerProps } = useAnchorPosition({ side: 'bottom', offset: 2, matchWidth: true });
+ *
+ * <Button {...anchorProps} onClick={toggle}>Options</Button>
+ * {open && <Box {...layerProps} component="menu">…</Box>}
+ * ```
+ *
+ * Two things worth knowing. The layer is `position: fixed`, so it escapes every `overflow: hidden`
+ * ancestor without a portal — but not a *transformed* one, which is a fixed element's containing block in
+ * either path, and not the stacking order, which is still the page's. And the anchor's **name is an inline
+ * style rather than a prop**: an identity is per-instance, so a class for it would be a rule per instance
+ * that is never freed — the same rule that makes a sparkline's `d` an attribute and its stroke a class.
+ *
+ * @a11y None of it. A layer is not a pattern: the role, the dismissal and the focus belong to whatever
+ * renders one — `useDismiss` and `useFocusReturn` from `@box-kite/react/a11y` are the other half.
+ */
+export default function useAnchorPosition(options?: AnchorPositionOptions): AnchorPosition;
+export {};

package/react/dialog/useScrollLock.d.ts

@@ -0,0 +1,12 @@
+import { default as React } from 'react';
+/**
+ * Stop the page behind a layer from scrolling, with a class rather than an inline style — so it is one
+ * shared rule like every other value this library writes, and a consumer can see what did it. Returns
+ * the style elements to render, which is element mode's way of getting a rule onto the page at all.
+ *
+ * `overflow: hidden` on `<html>` is the whole mechanism, which means two things worth knowing: the
+ * scrollbar's width leaves the page as it is applied, so a document that wants no shift should carry
+ * `scrollbarGutter="stable"`; and iOS Safari scrolls anyway, where nothing short of `position: fixed`
+ * on the body holds it.
+ */
+export default function useScrollLock(enabled: boolean): React.ReactElement[] | undefined;

package/react/hooks/usePortalContainer.d.ts

@@ -1 +1,6 @@
-export default function usePortalContainer(): HTMLElement | null;
+/**
+ * The container every portalled layer shares, created on first use. Pass `false` on the top-layer path,
+ * where nothing is portalled: the container is a DOM node plus a theme-class subscription, and a layer
+ * that stays where it was declared inherits the theme instead of needing one copied onto it.
+ */
+export default function usePortalContainer(enabled?: boolean): HTMLElement | null;

package/react/hooks/useVirtualization.d.ts

@@ -1,43 +1,32 @@
+import { VirtualWindow } from '../../utils/virtual/virtualUtils';
 export interface UseVirtualizationOptions {
-    /** Total number of items */
-    itemCount: number;
-    /** Height of each item in pixels */
-    itemHeight: number;
-    /** Height of the visible container in pixels */
-    containerHeight: number;
-    /** Number of items to render outside visible area (default: 3) */
+    /** How many rows there are in total — not how many are rendered. */
+    count: number;
+    /** The scrolling element: what it shows at once is the viewport, and its own rows are the pitch. */
+    scrollerRef: React.RefObject<HTMLElement | null>;
+    /** The pitch of a row, when it should be declared rather than measured. */
+    itemHeight?: number;
+    /** What the scroller shows, when it should be declared rather than measured. */
+    viewHeight?: number;
     overscan?: number;
-    /** Whether virtualization is enabled (default: true when itemCount > threshold) */
-    enabled?: boolean;
-    /** Threshold for enabling virtualization (default: 50) */
     threshold?: number;
+    /** Forces windowing on or off. Left off, it follows the row count against `threshold`. */
+    enabled?: boolean;
+    /** The row the keyboard is on. Always rendered, whatever the scroll position says. */
+    activeIndex?: number;
 }
-export interface UseVirtualizationResult {
-    /** First item index to render */
-    startIndex: number;
-    /** Last item index to render (inclusive) */
-    endIndex: number;
-    /** Total height of all items (for scroll container) */
-    totalHeight: number;
-    /** Y offset for positioning visible items */
-    offsetY: number;
-    /** Number of visible items */
-    visibleCount: number;
-    /** Whether virtualization is active */
-    isVirtualized: boolean;
-    /** Scroll event handler - attach to container's onScroll */
-    handleScroll: (e: React.UIEvent<HTMLElement>) => void;
-    /** Current scroll position */
-    scrollTop: number;
-    /** Container style for the scroll area */
-    containerStyle: React.CSSProperties;
-    /** Inner wrapper style (total height) */
-    innerStyle: React.CSSProperties;
-    /** Content style (transform offset) */
-    contentStyle: React.CSSProperties;
+export interface UseVirtualizationResult extends VirtualWindow {
+    /** Whether the list is being windowed at all. `false` means render every row and ignore the rest. */
+    virtualized: boolean;
+    /** Goes on the element that holds the rendered rows — the one the pitch is measured from. */
+    contentRef: (element: HTMLElement | null) => void;
+    /** Goes on the scrolling element. */
+    onScroll: (event: React.UIEvent<HTMLElement>) => void;
 }
 /**
- * Hook for virtualizing large lists.
- * Only renders items that are visible in the viewport plus overscan buffer.
+ * Renders a window of a long list instead of all of it, over the framework-free arithmetic in
+ * `VirtualUtils`. The two measurements it needs are taken from the DOM rather than declared, so a row
+ * restyled by the caller still windows correctly; until something has been laid out (a first render, or
+ * a test environment that computes none) the defaults in the model stand in.
  */
 export default function useVirtualization(options: UseVirtualizationOptions): UseVirtualizationResult;