@astryxdesign/core 0.1.1 → 0.1.2-canary.3893cd5

package/CHANGELOG.md

@@ -1,5 +1,110 @@
 # @xds/core
 
+# 0.1.2
+
+#### Breaking Changes
+
+- `Text`, `Heading`, `Link`, and `Timestamp` rename the `color="active"` value to `color="accent"`, now mapping to the dedicated `--color-text-accent` token (legible accent text ink) instead of `--color-accent`. Run `astryx upgrade` to migrate call sites automatically. (#2863)
+
+#### New Features
+
+- Button: add `isInterruptible` to keep the button clickable while a `clickAction` is pending — the spinner and `aria-busy` still show, but the button is not disabled or deduped, so a re-click interrupts the in-flight action. ToggleButton's async toggle now runs through this path, staying interruptible.
+- Add a prebuilt UMD bundle (`dist/astryx.umd.js`, global `Astryx`) plus `unpkg`/`jsdelivr` fields, so the library works directly from a CDN via a `<script>` tag with no bundler. React/ReactDOM stay as peer globals; the StyleX runtime is bundled in.
+- Add `useTableStickyColumns` — pin a contiguous run of `Table` columns to
+  the start and/or end edge with cumulative offsets and scroll-aware drop shadows.
+  Configure with `{ startKeys, endKeys }`; an empty config is a valid no-op.
+
+#### Fixes
+
+- AvatarGroupOverflow now forwards rest props (data-_, aria-_, event handlers, id, role, tabIndex) to the rendered element, matching the behavior of Avatar and AvatarGroup.
+- Fix HoverCard SSR hydration mismatch when used inside an SSR Client Component (#3107). The floating layer now renders inline instead of portaling to `document.body`, so server and client markup match. No API change.
+- Kbd: use the `--color-border-emphasized` token for its bottom border instead of `--color-border` (#2850)
+- useLayer now treats `anchor-name` as a comma-separated list, so multiple layers can anchor to the same element (e.g. two TopNavMegaMenus in one nav) without clobbering each other's anchor. Previously the second menu lost its anchor and rendered over the nav.
+- Fix mobile nav drawer not re-opening after it is closed (#3091)
+  The AppShell mobile drawer mounts `MobileNav` inside an `<Activity>` that
+  switches to `mode="hidden"` when the drawer closes. On close, React runs the
+  drawer effect's cleanup (with a stale `isOpen`) instead of re-running the
+  effect with `isOpen=false`, so the deferred `dialog.close()` never fired and
+  the native `<dialog>` was left `open` in the hidden subtree. The next open then
+  skipped `showModal()` (the dialog was already open), so the drawer could be
+  opened and closed once but never re-opened. The effect cleanup now closes the
+  dialog if it is still open, keeping the native dialog state in sync so a
+  subsequent open cleanly calls `showModal()` again.
+- Core components (`Banner`, `EmptyState`, `Markdown`) no longer render a `<p>` by default — they render `<div>` (appearance unchanged). This avoids hydration mismatches when block content lands in a `<p>`. `Markdown` paragraphs use `role="paragraph"`; pass `components={{paragraph: 'p'}}` to opt back into `<p>`.
+- `Pagination`'s `changeAction` is now interruptible — page changes run in a transition with optimistic page state, so rapid prev/next clicks advance through pages instead of being dropped. `Button`'s `clickAction` keeps its single-fire guard.
+- make the `Slider` default track color visible on muted backgrounds
+  The background track painted with `--color-background-muted` — the same token
+  used for muted surface fills — so the track disappeared on muted backgrounds.
+  The track now uses the dedicated `--color-track` channel token, which is
+  designed to stay legible against body/muted surfaces.
+- Polish `useTableStickyColumns` pinned-cell backgrounds so they match the
+  rest of the row:
+- Table: the header row no longer picks up the `hasHover` row highlight — hover (and striped) styling now applies to body rows only. Adds an internal `isHeaderRow` flag on the row component so the header row in `<thead>` opts out (#2734)
+- `Timestamp` now renders the current time (and small clock skew up to ~30s in the future) as "now" instead of "in a few seconds" (#3099).
+- ToggleButton onPressedChange receives the click event for preventDefault opt-out
+  `onPressedChange` now receives the originating click event as a second
+  argument. Calling `event.preventDefault()` skips `pressedChangeAction`, so a
+  consumer can handle the toggle entirely in `onPressedChange` without firing the
+  action — matching how `Switch`'s `onChange` and `Button`'s `onClick` already
+  gate their action props. Existing `(isPressed) => void` handlers keep working;
+  the event is an added trailing argument.
+- Tokenizer/PowerSearch: align end content (clear button, resultCount) with the field's inline padding instead of hugging the border (~3px). It now uses spacing-2 (8px) to match the text/start-icon inset (#2849)
+- Tooltip and HoverCard: add ARIA roles to the floating layers — `role="tooltip"` on Tooltip (completing the ARIA tooltip pattern; the trigger already links via `aria-describedby`) and `role="dialog"` on HoverCard. Plumbed via a new optional `role` on the layer render props. (#3240; Popover already exposes `role="dialog"`.)
+
+#### Documentation
+
+- Document Banner's `defaultIsExpanded` prop, which controls whether the collapsible content area starts expanded but was missing from the docsite properties tab
+- Rename the ClickableCard and SelectableCard examples to follow the "Component — Variant" title convention (`Clickable Card — Nested Button`, `Selectable Card — Multi-select`), and add playground defaults to both card docs so their docsite previews show realistic card content (#2877)
+- Declare playground scaffolds for the Chat sub-components so they preview at a realistic width (ChatComposer and ChatComposerDrawer wrap in a sized container, and the drawer seeds default content), and drop the redundant visible value label from the ChatComposerDrawer "With Progress" example while keeping the accessible label (#2877)
+- Document two public props missing from the docsite properties tab: List's `start` (ordered-list counter start) and CheckboxInput's `isReadOnly`
+- Restore the Icon and Skeleton properties-tab previews on the docsite. Icon now seeds a default `icon` (it was a required, non-generatable prop), and Skeleton renders with concrete preview dimensions instead of collapsing at `100%` (#2848, #2875)
+- Document Heading's `justify` prop, which was supported by the component but missing from the docsite properties tab (#2847)
+- OverflowList: seed example items via playground defaults so the docsite properties-tab preview renders a real list instead of an empty container (#2872)
+- Document Section's `paddingBlock` prop (block-axis padding override), which was supported by the component but missing from the docsite properties tab
+- Give the `Skeleton` properties-tab example explicit dimensions so it is visible
+  The `Skeleton` doc had no `playground` config, so the interactive
+  properties-tab preview fell back to the prop defaults of `width: '100%'` /
+  `height: '100%'`. With no sized parent, the skeleton collapsed to a zero-size
+  (invisible) element. The doc now sets a `playground.defaults` of
+  `width: 320` / `height: 80` so the shimmer placeholder renders visibly.
+- Update stale `facebookexperimental/xds` doc/JSDoc links to the current `facebook/astryx` namespace in source comments (theme/syntax `@see` references). The old org 301-redirects, so these weren't broken — just stale — and this matches the canonical org used elsewhere
+- Document Table's `verticalAlign` and `textOverflow` props, which were supported by the component but missing from the docsite properties tab
+- Document TabList's `layout` prop ('hug' | 'fill') for tab sizing, which was supported by the component but missing from the docsite properties tab
+- Document Text's `justify` prop, which was supported by the component but missing from the docsite properties tab (same omission previously fixed for Heading) (#2847-adjacent)
+- Restore the Timestamp properties-tab preview on the docsite. `value` is a required prop with no semantic default, so the preview rendered "Invalid time value"; it now seeds a valid ISO 8601 date (#2877)
+- Document ToggleButton's `isIconOnly` prop, which was a supported public prop but missing from the docsite properties tab
+- Make the Toolbar "Table Filter" example use real Selector controls for its Status and Priority filters instead of buttons styled to look like dropdowns, and add meaningful playground defaults plus richer slot options (buttons, icon buttons, tabs, segmented controls, selectors) to the Toolbar docs (#2877).
+
+#### Other Changes
+
+- Pinned cells paint an opaque base via the overridable
+  `--table-sticky-background` variable (defaults to `--color-background-card`),
+  fixing a grey mismatch in themes/modes where `surface !== card` (e.g. neutral
+  dark). Consumers on a different backdrop override the variable.
+- The row's overlay (striping and/or hover) is replayed on the pinned cell via
+  a background-image gradient. `TableRow` publishes its current overlay color as
+  the inheritable `--table-row-overlay` variable, so pinned columns mirror the
+  row exactly — striped when the table is striped, hover when enabled, nothing
+  otherwise (no phantom stripes) — transitioning in lockstep with the row.
+- `background-clip: padding-box` keeps the row divider visible on pinned cells.
+- New `transformScrollWrapper` hook (+ `ScrollWrapperRenderProps`) lets plugins attach a `ref`
+  to the horizontal scroll container and inject before/after chrome.
+- `transformHeaderCell` / `transformBodyCell` now receive `columnIndex` and the
+  full ordered `columns` list (also surfaced on the render props), enabling
+  position-aware plugins such as sticky columns. Existing plugins are unaffected
+  — the new args and methods are additive and optional.
+
+#### Contributors
+
+Thanks to everyone who contributed to this release:
+
+- @cixzhang
+- @durvesh1992
+- @ernesttien
+- @humbertovirtudes
+
+---
+
 # 0.1.1
 
 #### Breaking Changes

package/README.md

@@ -70,7 +70,57 @@ npm install @astryxdesign/core @astryxdesign/theme-neutral
 
 Then pick your setup below based on your framework and styling approach.
 
-### Next.js + Tailwind (simplest)
+### Next.js (simplest)
+
+The fastest way to get started. No build plugins, no PostCSS, no Babel config — Astryx ships pre-built CSS and JS, so you import three stylesheets (order matters) and wrap your app in a theme provider.
+
+**`src/app/globals.css`**
+
+```css
+@import '@astryxdesign/core/reset.css';
+@import '@astryxdesign/core/astryx.css';
+@import '@astryxdesign/theme-neutral/theme.css';
+```
+
+The import order maps to the layer cascade: `reset.css` (`@layer reset`) → `astryx.css` component styles (`@layer astryx-base`) → `theme.css` token overrides (`@layer astryx-theme`).
+
+**`src/app/providers.tsx`**
+
+```tsx
+'use client';
+
+import Link from 'next/link';
+import {Theme} from '@astryxdesign/core/theme';
+import {LinkProvider} from '@astryxdesign/core/Link';
+import {neutralTheme} from '@astryxdesign/theme-neutral/built';
+
+export function Providers({children}: {children: React.ReactNode}) {
+  return (
+    <Theme theme={neutralTheme}>
+      <LinkProvider component={Link}>{children}</LinkProvider>
+    </Theme>
+  );
+}
+```
+
+**`src/app/layout.tsx`**
+
+```tsx
+import './globals.css';
+import {Providers} from './providers';
+
+export default function RootLayout({children}: {children: React.ReactNode}) {
+  return (
+    <html lang="en">
+      <body>
+        <Providers>{children}</Providers>
+      </body>
+    </html>
+  );
+}
+```
+
+### Next.js + Tailwind
 
 No build plugins needed; XDS ships pre-built CSS that works alongside Tailwind.
 
@@ -183,3 +233,71 @@ npm install @astryxdesign/core @astryxdesign/theme-neutral
 ```
 
 Same CSS imports and providers as above. No build plugins needed; XDS ships pre-built.
+
+### No build step (CDN)
+
+For prototypes, embeds, or pages without a bundler, load the components straight
+from a public CDN. Two delivery options ship in the published package:
+
+**1. UMD global (`<script>` tag).** A single pre-bundled file exposes every export
+on `window.Astryx`. React and ReactDOM are peer dependencies — load them yourself.
+Pair it with the precompiled stylesheet.
+
+```html
+<!doctype html>
+<html data-astryx-theme="neutral">
+  <head>
+    <link
+      rel="stylesheet"
+      href="https://cdn.jsdelivr.net/npm/@astryxdesign/core/src/reset.css" />
+    <link
+      rel="stylesheet"
+      href="https://cdn.jsdelivr.net/npm/@astryxdesign/core/dist/astryx.css" />
+  </head>
+  <body>
+    <div id="root"></div>
+    <script
+      crossorigin
+      src="https://unpkg.com/react@19/umd/react.production.min.js"></script>
+    <script
+      crossorigin
+      src="https://unpkg.com/react-dom@19/umd/react-dom.production.min.js"></script>
+    <script src="https://cdn.jsdelivr.net/npm/@astryxdesign/core/dist/astryx.umd.js"></script>
+    <script>
+      const {Button, Card} = window.Astryx;
+      const e = React.createElement;
+      ReactDOM.createRoot(document.getElementById('root')).render(
+        e(Card, null, e(Button, {variant: 'primary'}, 'Hello from a CDN')),
+      );
+    </script>
+  </body>
+</html>
+```
+
+**2. ES modules (no UMD, no globals).** Use [esm.sh](https://esm.sh), which rewrites
+bare imports to browser-resolvable URLs. An import map keeps a single React instance.
+
+```html
+<link
+  rel="stylesheet"
+  href="https://cdn.jsdelivr.net/npm/@astryxdesign/core/dist/astryx.css" />
+<script type="importmap">
+  {
+    "imports": {
+      "react": "https://esm.sh/react@19",
+      "react-dom/client": "https://esm.sh/react-dom@19/client",
+      "@astryxdesign/core": "https://esm.sh/@astryxdesign/core?external=react,react-dom"
+    }
+  }
+</script>
+<script type="module">
+  import {createRoot} from 'react-dom/client';
+  import {Button} from '@astryxdesign/core';
+  // ...render as usual
+</script>
+```
+
+> Pin a version in production (e.g. `@astryxdesign/core@0.1.1`) — unversioned CDN URLs
+> resolve to the latest release and are cached aggressively. The raw ESM entry
+> (`dist/index.js`) uses bare `react` imports and will **not** run from a plain
+> `<script src>`; use the UMD global or esm.sh as shown above.

package/dist/AvatarGroup/AvatarGroupOverflow.d.ts

@@ -41,7 +41,7 @@ export interface AvatarGroupOverflowProps extends Omit<BaseProps<HTMLElement>, '
  * </AvatarGroup>
  * ```
  */
-export declare function AvatarGroupOverflow({ ref, count, onClick, children, xstyle, className, style, }: AvatarGroupOverflowProps): ReactNode;
+export declare function AvatarGroupOverflow({ ref, count, onClick, children, xstyle, className, style, ...rest }: AvatarGroupOverflowProps): ReactNode;
 export declare namespace AvatarGroupOverflow {
     var displayName: string;
 }

package/dist/AvatarGroup/AvatarGroupOverflow.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"AvatarGroupOverflow.d.ts","sourceRoot":"","sources":["../../src/AvatarGroup/AvatarGroupOverflow.tsx"],"names":[],"mappings":"AAGA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,EAAC,KAAK,SAAS,EAAC,MAAM,OAAO,CAAC;AAU5C,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AAM5C,MAAM,WAAW,wBAAyB,SAAQ,IAAI,CACpD,SAAS,CAAC,WAAW,CAAC,EACtB,SAAS,CACV;IACC,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC;IAC7B;;OAEG;IACH,KAAK,EAAE,MAAM,CAAC;IAEd;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,IAAI,CAAC;IAErB;;OAEG;IACH,QAAQ,CAAC,EAAE,SAAS,CAAC;CACtB;AA6DD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,mBAAmB,CAAC,EAClC,GAAG,EACH,KAAK,EACL,OAAO,EACP,QAAQ,EACR,MAAM,EACN,SAAS,EACT,KAAK,GACN,EAAE,wBAAwB,GAAG,SAAS,CAsDtC;yBA9De,mBAAmB"}
+{"version":3,"file":"AvatarGroupOverflow.d.ts","sourceRoot":"","sources":["../../src/AvatarGroup/AvatarGroupOverflow.tsx"],"names":[],"mappings":"AAGA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,EAAC,KAAK,SAAS,EAAC,MAAM,OAAO,CAAC;AAU5C,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AAM5C,MAAM,WAAW,wBAAyB,SAAQ,IAAI,CACpD,SAAS,CAAC,WAAW,CAAC,EACtB,SAAS,CACV;IACC,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,WAAW,CAAC,CAAC;IAC7B;;OAEG;IACH,KAAK,EAAE,MAAM,CAAC;IAEd;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,IAAI,CAAC;IAErB;;OAEG;IACH,QAAQ,CAAC,EAAE,SAAS,CAAC;CACtB;AA6DD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,mBAAmB,CAAC,EAClC,GAAG,EACH,KAAK,EACL,OAAO,EACP,QAAQ,EACR,MAAM,EACN,SAAS,EACT,KAAK,EACL,GAAG,IAAI,EACR,EAAE,wBAAwB,GAAG,SAAS,CAwDtC;yBAjEe,mBAAmB"}

package/dist/AvatarGroup/AvatarGroupOverflow.js

@@ -100,7 +100,8 @@ export function AvatarGroupOverflow({
   children,
   xstyle,
   className,
-  style
+  style,
+  ...rest
 }) {
   const group = useAvatarGroup();
   const numericSize = group?.numericSize ?? 36;
@@ -113,6 +114,7 @@ export function AvatarGroupOverflow({
       type: "button",
       onClick: onClick,
       "aria-label": label,
+      ...rest,
       ...mergeProps(themeProps('avatar-group-overflow'), stylex.props(styles.base, styles.button, styles.overlap, dynamicStyles.size(numericSize), dynamicStyles.fontSize(numericSize), dynamicStyles.overlap(-overlap), xstyle), className, style),
       children: content
     });
@@ -120,6 +122,7 @@ export function AvatarGroupOverflow({
   return /*#__PURE__*/_jsx("span", {
     ref: ref,
     "aria-label": label,
+    ...rest,
     ...mergeProps(themeProps('avatar-group-overflow'), stylex.props(styles.base, styles.overlap, dynamicStyles.size(numericSize), dynamicStyles.fontSize(numericSize), dynamicStyles.overlap(-overlap), xstyle), className, style),
     children: content
   });

package/dist/Banner/Banner.d.ts

@@ -12,6 +12,13 @@
  * - Each visual area owns its own border-radius (no overflow:clip on the container)
  * - When children are provided, a collapse/expand toggle button appears in the end area
  *
+ * Title and description render as <div> (not <p>): they accept arbitrary
+ * ReactNode content, and <p> cannot legally contain block-level children
+ * (the HTML parser reparents them, desyncing SSR markup from the hydrated
+ * DOM). Using <div> keeps these slots composable with any content. Their
+ * StyleX styles set margin: 0 and explicit typography, so the rendered
+ * appearance is identical to the previous <p>.
+ *
  * SYNC: When modified, update these files to stay in sync:
  * - /packages/core/src/Banner/Banner.doc.mjs (props table, features, implementation notes)
  * - /packages/core/src/Banner/Banner.test.tsx (tests for new/changed behavior)

package/dist/Banner/Banner.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Banner.d.ts","sourceRoot":"","sources":["../../src/Banner/Banner.tsx"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,EAAW,KAAK,SAAS,EAAC,MAAM,OAAO,CAAC;AAE/C,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AAsB5C;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,IAAI,CAAC;IACX,OAAO,EAAE,IAAI,CAAC;IACd,KAAK,EAAE,IAAI,CAAC;IACZ,OAAO,EAAE,IAAI,CAAC;CACf;AAED;;;GAGG;AACH,MAAM,MAAM,YAAY,GAAG,MAAM,eAAe,CAAC;AAEjD;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,IAAI,CAAC;IACX,OAAO,EAAE,IAAI,CAAC;CACf;AAED;;;;;;GAMG;AACH,MAAM,MAAM,eAAe,GAAG,MAAM,kBAAkB,CAAC;AAEvD,MAAM,WAAW,WAAY,SAAQ,SAAS,CAAC,cAAc,CAAC;IAC5D,wCAAwC;IACxC,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;IAChC;;OAEG;IACH,MAAM,EAAE,YAAY,CAAC;IACrB;;OAEG;IACH,KAAK,EAAE,SAAS,CAAC;IACjB;;OAEG;IACH,WAAW,CAAC,EAAE,SAAS,CAAC;IACxB;;OAEG;IACH,IAAI,CAAC,EAAE,SAAS,CAAC;IACjB;;;;;OAKG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,IAAI,CAAC;IACvB;;;;;;;;OAQG;IACH,UAAU,CAAC,EAAE,SAAS,CAAC;IACvB;;;;;OAKG;IACH,SAAS,CAAC,EAAE,eAAe,CAAC;IAC5B;;;;OAIG;IACH,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B;;;;OAIG;IACH,QAAQ,CAAC,EAAE,SAAS,CAAC;CACtB;AA2JD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AACH,wBAAgB,MAAM,CAAC,EACrB,MAAM,EACN,KAAK,EACL,WAAW,EACX,IAAI,EACJ,aAAqB,EACrB,SAAS,EACT,UAAU,EACV,SAAkB,EAClB,iBAAyB,EACzB,QAAQ,EACR,MAAM,EACN,SAAS,EACT,KAAK,EACL,GAAG,EACH,GAAG,IAAI,EACR,EAAE,WAAW,sCA0Hb;yBA1Ie,MAAM"}
+{"version":3,"file":"Banner.d.ts","sourceRoot":"","sources":["../../src/Banner/Banner.tsx"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAEH,OAAO,EAAW,KAAK,SAAS,EAAC,MAAM,OAAO,CAAC;AAE/C,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AAsB5C;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,IAAI,CAAC;IACX,OAAO,EAAE,IAAI,CAAC;IACd,KAAK,EAAE,IAAI,CAAC;IACZ,OAAO,EAAE,IAAI,CAAC;CACf;AAED;;;GAGG;AACH,MAAM,MAAM,YAAY,GAAG,MAAM,eAAe,CAAC;AAEjD;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,kBAAkB;IACjC,IAAI,EAAE,IAAI,CAAC;IACX,OAAO,EAAE,IAAI,CAAC;CACf;AAED;;;;;;GAMG;AACH,MAAM,MAAM,eAAe,GAAG,MAAM,kBAAkB,CAAC;AAEvD,MAAM,WAAW,WAAY,SAAQ,SAAS,CAAC,cAAc,CAAC;IAC5D,wCAAwC;IACxC,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;IAChC;;OAEG;IACH,MAAM,EAAE,YAAY,CAAC;IACrB;;OAEG;IACH,KAAK,EAAE,SAAS,CAAC;IACjB;;OAEG;IACH,WAAW,CAAC,EAAE,SAAS,CAAC;IACxB;;OAEG;IACH,IAAI,CAAC,EAAE,SAAS,CAAC;IACjB;;;;;OAKG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,IAAI,CAAC;IACvB;;;;;;;;OAQG;IACH,UAAU,CAAC,EAAE,SAAS,CAAC;IACvB;;;;;OAKG;IACH,SAAS,CAAC,EAAE,eAAe,CAAC;IAC5B;;;;OAIG;IACH,iBAAiB,CAAC,EAAE,OAAO,CAAC;IAC5B;;;;OAIG;IACH,QAAQ,CAAC,EAAE,SAAS,CAAC;CACtB;AA2JD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AACH,wBAAgB,MAAM,CAAC,EACrB,MAAM,EACN,KAAK,EACL,WAAW,EACX,IAAI,EACJ,aAAqB,EACrB,SAAS,EACT,UAAU,EACV,SAAkB,EAClB,iBAAyB,EACzB,QAAQ,EACR,MAAM,EACN,SAAS,EACT,KAAK,EACL,GAAG,EACH,GAAG,IAAI,EACR,EAAE,WAAW,sCA0Hb;yBA1Ie,MAAM"}

package/dist/Banner/Banner.js

@@ -16,6 +16,13 @@
  * - Each visual area owns its own border-radius (no overflow:clip on the container)
  * - When children are provided, a collapse/expand toggle button appears in the end area
  *
+ * Title and description render as <div> (not <p>): they accept arbitrary
+ * ReactNode content, and <p> cannot legally contain block-level children
+ * (the HTML parser reparents them, desyncing SSR markup from the hydrated
+ * DOM). Using <div> keeps these slots composable with any content. Their
+ * StyleX styles set margin: 0 and explicit typography, so the rendered
+ * appearance is identical to the previous <p>.
+ *
  * SYNC: When modified, update these files to stay in sync:
  * - /packages/core/src/Banner/Banner.doc.mjs (props table, features, implementation notes)
  * - /packages/core/src/Banner/Banner.test.tsx (tests for new/changed behavior)
@@ -291,12 +298,12 @@ export function Banner({
         ...{
           className: "x78zum5 xdt5ytf xxhr3t x98rzlu xeuugli"
         },
-        children: [/*#__PURE__*/_jsx("p", {
+        children: [/*#__PURE__*/_jsx("div", {
           ...{
             className: "x1ghz6dp xjb2p0i xcr08ib x2mo6ok x1kq96og x1tgivj0"
           },
           children: title
-        }), description != null && /*#__PURE__*/_jsx("p", {
+        }), description != null && /*#__PURE__*/_jsx("div", {
           ...{
             className: "x1ghz6dp xjb2p0i x141an7d x1sodnla x1ltkj2j xv1l7n4"
           },

package/dist/Button/Button.d.ts

@@ -11,7 +11,7 @@
  * - /apps/storybook/stories/Button.stories.tsx (storybook stories)
  * - /packages/cli/templates/blocks/components/Button/ (showcase blocks)
  *
- * Last synced props: label, variant, size, isDisabled, isLoading, clickAction, icon, isIconOnly, children, tooltip, endContent, href, as, target, rel
+ * Last synced props: label, variant, size, isDisabled, isLoading, isInterruptible, clickAction, icon, isIconOnly, children, tooltip, endContent, href, as, target, rel
  */
 import { type ReactNode } from 'react';
 import type { BaseProps } from '../BaseProps';
@@ -93,6 +93,16 @@ export interface ButtonProps extends BaseProps<HTMLButtonElement> {
      * @default false
      */
     isLoading?: boolean;
+    /**
+     * Keep the button interactive while a `clickAction` is pending. The loading
+     * state still renders the spinner and `aria-busy`, but the button is not
+     * disabled and the in-flight action is not deduped — so a re-click lands and
+     * interrupts the previous action with a fresh one. Use for interruptible
+     * actions (e.g. a toggle whose action can be re-triggered before the previous
+     * one settles), not fire-once actions (submit/save/pay).
+     * @default false
+     */
+    isInterruptible?: boolean;
     /**
      * Click handler. For async actions that should show a loading state,
      * use `clickAction` instead.
@@ -175,7 +185,7 @@ export interface ButtonProps extends BaseProps<HTMLButtonElement> {
  * <Button label="Open in new tab" href="https://example.com" target="_blank" rel="noopener noreferrer" />
  * ```
  */
-export declare function Button({ label, variant, size: sizeProp, type, isDisabled, isLoading, clickAction, icon, isIconOnly, children, endContent, tooltip, href, as, target, rel, xstyle, className, style, ref, ...props }: ButtonProps): ReactNode;
+export declare function Button({ label, variant, size: sizeProp, type, isDisabled, isLoading, isInterruptible, clickAction, icon, isIconOnly, children, endContent, tooltip, href, as, target, rel, xstyle, className, style, ref, ...props }: ButtonProps): ReactNode;
 export declare namespace Button {
     var displayName: string;
 }

package/dist/Button/Button.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Button.d.ts","sourceRoot":"","sources":["../../src/Button/Button.tsx"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAwB,KAAK,SAAS,EAAC,MAAM,OAAO,CAAC;AAC5D,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AAC5C,OAAO,KAAK,MAAM,MAAM,kBAAkB,CAAC;AAoB3C,OAAO,KAAK,EAAC,iBAAiB,EAAC,MAAM,eAAe,CAAC;AAoGrD,QAAA,MAAM,UAAU;;;;;;;;;;EAUd,CAAC;AAsGH;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,IAAI,CAAC;IACd,SAAS,EAAE,IAAI,CAAC;IAChB,KAAK,EAAE,IAAI,CAAC;IACZ,WAAW,EAAE,IAAI,CAAC;CACnB;AAED;;;GAGG;AACH,MAAM,MAAM,aAAa,GAAG,MAAM,gBAAgB,CAAC;AAEnD;;GAEG;AACH,MAAM,MAAM,UAAU,GAAG,MAAM,OAAO,UAAU,CAAC;AAEjD,MAAM,WAAW,WAAY,SAAQ,SAAS,CAAC,iBAAiB,CAAC;IAC/D,wCAAwC;IACxC,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,iBAAiB,CAAC,CAAC;IACnC,oDAAoD;IACpD,IAAI,CAAC,EAAE,QAAQ,GAAG,QAAQ,GAAG,OAAO,CAAC;IACrC,+CAA+C;IAC/C,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,gDAAgD;IAChD,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,aAAa,CAAC,MAAM,CAAC,CAAC;IAChD,uDAAuD;IACvD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;;OAIG;IACH,KAAK,EAAE,MAAM,CAAC;IACd;;;OAGG;IACH,OAAO,CAAC,EAAE,aAAa,CAAC;IACxB;;;OAGG;IACH,IAAI,CAAC,EAAE,UAAU,CAAC;IAClB;;;OAGG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB;;;OAGG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB;;;OAGG;IACH,OAAO,CAAC,EAAE,KAAK,CAAC,iBAAiB,CAAC,iBAAiB,CAAC,CAAC;IACrD;;OAEG;IACH,WAAW,CAAC,EAAE,CACZ,CAAC,EAAE,KAAK,CAAC,UAAU,CAAC,iBAAiB,CAAC,KACnC,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1B;;OAEG;IACH,IAAI,CAAC,EAAE,SAAS,CAAC;IACjB;;;;OAIG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB;;;OAGG;IACH,QAAQ,CAAC,EAAE,SAAS,CAAC;IACrB;;;;;;OAMG;IACH,UAAU,CAAC,EAAE,SAAS,CAAC;IACvB;;OAEG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;OAIG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;;OAIG;IACH,EAAE,CAAC,EAAE,iBAAiB,CAAC;IACvB;;OAEG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;OAEG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAmFD;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,MAAM,CAAC,EACrB,KAAK,EACL,OAAqB,EACrB,IAAI,EAAE,QAAQ,EACd,IAAe,EACf,UAAkB,EAClB,SAAiB,EACjB,WAAW,EACX,IAAI,EACJ,UAAkB,EAClB,QAAQ,EACR,UAAU,EACV,OAAO,EACP,IAAI,EACJ,EAAE,EACF,MAAM,EACN,GAAG,EACH,MAAM,EACN,SAAS,EACT,KAAK,EACL,GAAG,EACH,GAAG,KAAK,EACT,EAAE,WAAW,GAAG,SAAS,CAkLzB;yBAxMe,MAAM"}
+{"version":3,"file":"Button.d.ts","sourceRoot":"","sources":["../../src/Button/Button.tsx"],"names":[],"mappings":"AAIA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,EAAwB,KAAK,SAAS,EAAC,MAAM,OAAO,CAAC;AAC5D,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AAC5C,OAAO,KAAK,MAAM,MAAM,kBAAkB,CAAC;AAoB3C,OAAO,KAAK,EAAC,iBAAiB,EAAC,MAAM,eAAe,CAAC;AAoGrD,QAAA,MAAM,UAAU;;;;;;;;;;EAUd,CAAC;AAsGH;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,gBAAgB;IAC/B,OAAO,EAAE,IAAI,CAAC;IACd,SAAS,EAAE,IAAI,CAAC;IAChB,KAAK,EAAE,IAAI,CAAC;IACZ,WAAW,EAAE,IAAI,CAAC;CACnB;AAED;;;GAGG;AACH,MAAM,MAAM,aAAa,GAAG,MAAM,gBAAgB,CAAC;AAEnD;;GAEG;AACH,MAAM,MAAM,UAAU,GAAG,MAAM,OAAO,UAAU,CAAC;AAEjD,MAAM,WAAW,WAAY,SAAQ,SAAS,CAAC,iBAAiB,CAAC;IAC/D,wCAAwC;IACxC,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,iBAAiB,CAAC,CAAC;IACnC,oDAAoD;IACpD,IAAI,CAAC,EAAE,QAAQ,GAAG,QAAQ,GAAG,OAAO,CAAC;IACrC,+CAA+C;IAC/C,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,gDAAgD;IAChD,KAAK,CAAC,EAAE,MAAM,GAAG,MAAM,GAAG,aAAa,CAAC,MAAM,CAAC,CAAC;IAChD,uDAAuD;IACvD,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;;OAIG;IACH,KAAK,EAAE,MAAM,CAAC;IACd;;;OAGG;IACH,OAAO,CAAC,EAAE,aAAa,CAAC;IACxB;;;OAGG;IACH,IAAI,CAAC,EAAE,UAAU,CAAC;IAClB;;;OAGG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB;;;OAGG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB;;;;;;;;OAQG;IACH,eAAe,CAAC,EAAE,OAAO,CAAC;IAC1B;;;OAGG;IACH,OAAO,CAAC,EAAE,KAAK,CAAC,iBAAiB,CAAC,iBAAiB,CAAC,CAAC;IACrD;;OAEG;IACH,WAAW,CAAC,EAAE,CACZ,CAAC,EAAE,KAAK,CAAC,UAAU,CAAC,iBAAiB,CAAC,KACnC,IAAI,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1B;;OAEG;IACH,IAAI,CAAC,EAAE,SAAS,CAAC;IACjB;;;;OAIG;IACH,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB;;;OAGG;IACH,QAAQ,CAAC,EAAE,SAAS,CAAC;IACrB;;;;;;OAMG;IACH,UAAU,CAAC,EAAE,SAAS,CAAC;IACvB;;OAEG;IACH,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB;;;;OAIG;IACH,IAAI,CAAC,EAAE,MAAM,CAAC;IACd;;;;OAIG;IACH,EAAE,CAAC,EAAE,iBAAiB,CAAC;IACvB;;OAEG;IACH,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;OAEG;IACH,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAuHD;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,wBAAgB,MAAM,CAAC,EACrB,KAAK,EACL,OAAqB,EACrB,IAAI,EAAE,QAAQ,EACd,IAAe,EACf,UAAkB,EAClB,SAAiB,EACjB,eAAuB,EACvB,WAAW,EACX,IAAI,EACJ,UAAkB,EAClB,QAAQ,EACR,UAAU,EACV,OAAO,EACP,IAAI,EACJ,EAAE,EACF,MAAM,EACN,GAAG,EACH,MAAM,EACN,SAAS,EACT,KAAK,EACL,GAAG,EACH,GAAG,KAAK,EACT,EAAE,WAAW,GAAG,SAAS,CAuMzB;yBA9Ne,MAAM"}

package/dist/Button/Button.js

@@ -15,7 +15,7 @@
  * - /apps/storybook/stories/Button.stories.tsx (storybook stories)
  * - /packages/cli/templates/blocks/components/Button/ (showcase blocks)
  *
- * Last synced props: label, variant, size, isDisabled, isLoading, clickAction, icon, isIconOnly, children, tooltip, endContent, href, as, target, rel
+ * Last synced props: label, variant, size, isDisabled, isLoading, isInterruptible, clickAction, icon, isIconOnly, children, tooltip, endContent, href, as, target, rel
  */
 import { useRef, useTransition } from 'react';
 import * as stylex from '@stylexjs/stylex';
@@ -88,6 +88,10 @@ const styles = {
     kmuXW: "x2lah0s",
     $$css: true
   },
+  contentWrapper: {
+    k1xSpc: "xjp7ctv",
+    $$css: true
+  },
   link: {
     kybGjl: "x1hl2dhg",
     $$css: true
@@ -202,6 +206,27 @@ const variants = {
  * Button size type derived from the sizeStyles StyleX object
  */
 
+const spinnerReveal = "x18re5ia-B";
+const contentHide = "x188b6p3-B";
+
+// Hold the loading swap for a short delay so a fast action (e.g. clickAction)
+// that settles within the delay never flashes a spinner. The spinner fade-in
+// and the content hide share the same delay so the button never shows an empty
+// frame in between. Reduced motion is instant.
+const SPINNER_DELAY = durationVars['--duration-medium-min'];
+const loadingStyles = {
+  hiddenContent: {
+    kMwMTN: "x19co3pv",
+    $$css: true
+  },
+  hiddenContentDelayed: {
+    kKVMdj: "x1ffowhz",
+    k44tkh: "xjlvqhv",
+    kWV6AL: "x10e4vud",
+    kKxzle: "x17yabm6 x14q22ui",
+    $$css: true
+  }
+};
 const groupStyles = {
   horizontal: {
     krdFHd: "x15mokao x8eehn2",
@@ -265,6 +290,7 @@ export function Button({
   type = 'button',
   isDisabled = false,
   isLoading = false,
+  isInterruptible = false,
   clickAction,
   icon,
   isIconOnly = false,
@@ -284,10 +310,22 @@ export function Button({
   const size = useSize(sizeProp, 'md');
   const buttonGroup = useButtonGroup();
   const [isPending, startTransition] = useTransition();
+  // clickAction is normally fire-once (submit/save/pay), so a same-tick
+  // double-click must dedupe — which neither isPending nor useOptimistic do.
+  // Hence the ref guard. Interruptible callers (e.g. ToggleButton) opt out so a
+  // re-click can land and interrupt the in-flight action with a fresh one.
   const actionInFlightRef = useRef(false);
   const isLoadingState = isLoading || isPending;
+  // Delay the spinner reveal for action-driven loading (clickAction's own
+  // transition) so a fast action that settles within the delay does not flash
+  // a spinner. Interruptible loading is delayed too, so rapid re-clicks settle
+  // before any spinner shows. Explicit isLoading-only stays immediate, since
+  // the consumer is deliberately showing it.
+  const delaySpinner = isPending || isInterruptible;
   const groupDisabled = buttonGroup?.isDisabled ?? false;
-  const buttonDisabled = isDisabled || groupDisabled || isLoadingState;
+  // When interruptible, the loading state drives the spinner and aria-busy but
+  // not disabled, so clicks keep landing and can interrupt the in-flight action.
+  const buttonDisabled = isDisabled || groupDisabled || isLoadingState && !isInterruptible;
   // isIconOnly prop is the source of truth for icon-only rendering.
   // When false (default), label is always rendered as visible text.
 
@@ -301,7 +339,9 @@ export function Button({
   // for keyboard users to reach the tooltip. Otherwise use native disabled.
   const useAriaDisabled = tooltip != null && buttonDisabled;
   const handleClick = e => {
-    if (buttonDisabled || actionInFlightRef.current) {
+    // The ref guard dedupes fire-once actions. Interruptible callers skip it so
+    // a re-click while pending starts a fresh action that interrupts the prior.
+    if (buttonDisabled || actionInFlightRef.current && !isInterruptible) {
       e.preventDefault();
       return;
     }
@@ -344,22 +384,20 @@ export function Button({
   const buttonContent = /*#__PURE__*/_jsxs(_Fragment, {
     children: [isLoadingState && /*#__PURE__*/_jsx("span", {
       ...{
-        className: "x10l6tqk x13vifvy xu96u03 x3m8u43 x1ey2m1c xrvj5dj x1ku5rj1"
-      },
+        0: {
+          className: "x10l6tqk x13vifvy xu96u03 x3m8u43 x1ey2m1c xrvj5dj x1ku5rj1"
+        },
+        1: {
+          className: "x10l6tqk x13vifvy xu96u03 x3m8u43 x1ey2m1c xrvj5dj x1ku5rj1 xqcmdr3 xb2rp9n xskzprw x17yabm6 x14q22ui"
+        }
+      }[!!delaySpinner << 0],
       "aria-hidden": "true",
       children: /*#__PURE__*/_jsx(Spinner, {
         size: "sm",
         shade: "inherit"
       })
     }), /*#__PURE__*/_jsxs("span", {
-      ...{
-        0: {
-          className: "xjp7ctv"
-        },
-        1: {
-          className: "xjp7ctv x19co3pv"
-        }
-      }[!!isLoadingState << 0],
+      ...stylex.props(styles.contentWrapper, isLoadingState && (delaySpinner ? loadingStyles.hiddenContentDelayed : loadingStyles.hiddenContent)),
       "aria-hidden": isLoadingState || undefined,
       children: [icon && /*#__PURE__*/_jsx("span", {
         ...stylex.props(styles.iconWrapper, iconSizeStyles[size]),

package/dist/EmptyState/EmptyState.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"EmptyState.d.ts","sourceRoot":"","sources":["../../src/EmptyState/EmptyState.tsx"],"names":[],"mappings":"AAEA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAC,KAAK,SAAS,EAAgB,MAAM,OAAO,CAAC;AAQpD,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AA4D5C,MAAM,WAAW,eAAgB,SAAQ,SAAS,CAAC,cAAc,CAAC;IAChE,wCAAwC;IACxC,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;IAChC;;OAEG;IACH,KAAK,EAAE,MAAM,CAAC;IACd;;OAEG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;OAGG;IACH,IAAI,CAAC,EAAE,SAAS,CAAC;IACjB;;;OAGG;IACH,OAAO,CAAC,EAAE,SAAS,CAAC;IACpB;;;;OAIG;IACH,YAAY,CAAC,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IACrC;;;OAGG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,UAAU,CAAC,EACzB,KAAK,EACL,WAAW,EACX,IAAI,EACJ,OAAO,EACP,YAAgB,EAChB,SAAiB,EACjB,MAAM,EACN,SAAS,EACT,KAAK,EACL,GAAG,EACH,GAAG,KAAK,EACT,EAAE,eAAe,+BA0CjB;yBAtDe,UAAU"}
+{"version":3,"file":"EmptyState.d.ts","sourceRoot":"","sources":["../../src/EmptyState/EmptyState.tsx"],"names":[],"mappings":"AAEA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAC,KAAK,SAAS,EAAgB,MAAM,OAAO,CAAC;AAQpD,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AA4D5C,MAAM,WAAW,eAAgB,SAAQ,SAAS,CAAC,cAAc,CAAC;IAChE,wCAAwC;IACxC,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,cAAc,CAAC,CAAC;IAChC;;OAEG;IACH,KAAK,EAAE,MAAM,CAAC;IACd;;OAEG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;OAGG;IACH,IAAI,CAAC,EAAE,SAAS,CAAC;IACjB;;;OAGG;IACH,OAAO,CAAC,EAAE,SAAS,CAAC;IACpB;;;;OAIG;IACH,YAAY,CAAC,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IACrC;;;OAGG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;CACrB;AAED;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,UAAU,CAAC,EACzB,KAAK,EACL,WAAW,EACX,IAAI,EACJ,OAAO,EACP,YAAgB,EAChB,SAAiB,EACjB,MAAM,EACN,SAAS,EACT,KAAK,EACL,GAAG,EACH,GAAG,KAAK,EACT,EAAE,eAAe,+BA8CjB;yBA1De,UAAU"}

package/dist/EmptyState/EmptyState.js

@@ -96,7 +96,13 @@ export function EmptyState({
         1: {
           className: "x1ghz6dp xjb2p0i x2mo6ok xf74fhv x1tgivj0 xcr08ib"
         }
-      }[!!isCompact << 0], title), description != null && /*#__PURE__*/_jsx("p", {
+      }[!!isCompact << 0], title), description != null &&
+      /*#__PURE__*/
+      // Rendered as <div> (not <p>): description accepts ReactNode and a
+      // <p> cannot legally contain block children, which causes hydration
+      // mismatches. The StyleX style sets margin: 0, so appearance is
+      // unchanged.
+      _jsx("div", {
         ...{
           0: {
             className: "x1ghz6dp xjb2p0i xjm74w1 x1sodnla xw6l6zx xv1l7n4"

package/dist/HoverCard/HoverCard.d.ts

@@ -1,8 +1,8 @@
 /**
  * @file HoverCard.tsx
- * @input Uses React, ReactDOM createPortal, useHoverCard hook
+ * @input Uses React, useHoverCard hook
  * @output Exports HoverCard component for hover/focus triggered layers
- * @position Layer component; uses inline-safe trigger wrapper and portals floating layer
+ * @position Layer component; uses inline-safe trigger wrapper and renders the floating layer inline
  *
  * SYNC: When modified, update these files to stay in sync:
  * - /packages/core/src/HoverCard/HoverCard.test.tsx

package/dist/HoverCard/HoverCard.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"HoverCard.d.ts","sourceRoot":"","sources":["../../src/HoverCard/HoverCard.tsx"],"names":[],"mappings":"AAIA;;;;;;;;;;;GAWG;AAEH,OAAc,EAGZ,KAAK,YAAY,EACjB,KAAK,SAAS,EACf,MAAM,OAAO,CAAC;AAIf,OAAO,EAAe,KAAK,qBAAqB,EAAC,MAAM,gBAAgB,CAAC;AACxE,OAAO,KAAK,EAAC,cAAc,EAAE,cAAc,EAAC,MAAM,mBAAmB,CAAC;AACtE,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AAG5C,YAAY,EAAC,qBAAqB,EAAC,MAAM,gBAAgB,CAAC;AAiB1D,MAAM,WAAW,cAAe,SAAQ,IAAI,CAC1C,SAAS,EACT,QAAQ,GAAG,WAAW,GAAG,OAAO,CACjC;IACC;;OAEG;IACH,QAAQ,EAAE,SAAS,CAAC;IAEpB;;OAEG;IACH,OAAO,EAAE,SAAS,CAAC;IAEnB;;;OAGG;IACH,SAAS,CAAC,EAAE,cAAc,CAAC;IAE3B;;;OAGG;IACH,SAAS,CAAC,EAAE,cAAc,CAAC;IAE3B;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB;;;;;;;OAOG;IACH,YAAY,CAAC,EAAE,qBAAqB,CAAC;IAErC;;;;;OAKG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;IAEpB;;;OAGG;IACH,YAAY,CAAC,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,IAAI,CAAC;IAEzC;;;;;;;OAOG;IACH,kBAAkB,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;IAEtC;;;;;OAKG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;IAEjB;;;OAGG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAiBD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,SAAS,CAAC,EACxB,QAAQ,EACR,OAAO,EACP,SAAmB,EACnB,SAAoB,EACpB,KAAW,EACX,SAAe,EACf,YAAqB,EACrB,SAAgB,EAChB,YAAY,EACZ,kBAA2B,EAC3B,MAAM,EACN,aAAa,EACb,MAAM,EACN,SAAS,EACT,KAAK,GACN,EAAE,cAAc,GAAG,YAAY,CAsG/B;yBAtHe,SAAS"}
+{"version":3,"file":"HoverCard.d.ts","sourceRoot":"","sources":["../../src/HoverCard/HoverCard.tsx"],"names":[],"mappings":"AAIA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAsB,KAAK,YAAY,EAAE,KAAK,SAAS,EAAC,MAAM,OAAO,CAAC;AAG7E,OAAO,EAAe,KAAK,qBAAqB,EAAC,MAAM,gBAAgB,CAAC;AACxE,OAAO,KAAK,EAAC,cAAc,EAAE,cAAc,EAAC,MAAM,mBAAmB,CAAC;AACtE,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AAG5C,YAAY,EAAC,qBAAqB,EAAC,MAAM,gBAAgB,CAAC;AAiB1D,MAAM,WAAW,cAAe,SAAQ,IAAI,CAC1C,SAAS,EACT,QAAQ,GAAG,WAAW,GAAG,OAAO,CACjC;IACC;;OAEG;IACH,QAAQ,EAAE,SAAS,CAAC;IAEpB;;OAEG;IACH,OAAO,EAAE,SAAS,CAAC;IAEnB;;;OAGG;IACH,SAAS,CAAC,EAAE,cAAc,CAAC;IAE3B;;;OAGG;IACH,SAAS,CAAC,EAAE,cAAc,CAAC;IAE3B;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB;;;;;;;OAOG;IACH,YAAY,CAAC,EAAE,qBAAqB,CAAC;IAErC;;;;;OAKG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;IAEpB;;;OAGG;IACH,YAAY,CAAC,EAAE,CAAC,MAAM,EAAE,OAAO,KAAK,IAAI,CAAC;IAEzC;;;;;;;OAOG;IACH,kBAAkB,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;IAEtC;;;;;OAKG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;IAEjB;;;OAGG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;CACzB;AAiBD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,SAAS,CAAC,EACxB,QAAQ,EACR,OAAO,EACP,SAAmB,EACnB,SAAoB,EACpB,KAAW,EACX,SAAe,EACf,YAAqB,EACrB,SAAgB,EAChB,YAAY,EACZ,kBAA2B,EAC3B,MAAM,EACN,aAAa,EACb,MAAM,EACN,SAAS,EACT,KAAK,GACN,EAAE,cAAc,GAAG,YAAY,CAgH/B;yBAhIe,SAAS"}

package/dist/HoverCard/HoverCard.js

@@ -4,9 +4,9 @@
 
 /**
  * @file HoverCard.tsx
- * @input Uses React, ReactDOM createPortal, useHoverCard hook
+ * @input Uses React, useHoverCard hook
  * @output Exports HoverCard component for hover/focus triggered layers
- * @position Layer component; uses inline-safe trigger wrapper and portals floating layer
+ * @position Layer component; uses inline-safe trigger wrapper and renders the floating layer inline
  *
  * SYNC: When modified, update these files to stay in sync:
  * - /packages/core/src/HoverCard/HoverCard.test.tsx
@@ -14,8 +14,7 @@
  * - /apps/storybook/stories/HoverCard.stories.tsx
  * - /packages/cli/templates/blocks/components/HoverCard/ (showcase blocks)
  */
-import React, { useCallback, useRef } from 'react';
-import { createPortal } from 'react-dom';
+import { useCallback, useRef } from 'react';
 import { useIsomorphicLayoutEffect } from "../hooks/useIsomorphicLayoutEffect.js";
 import * as stylex from '@stylexjs/stylex';
 import { useHoverCard } from "./useHoverCard.js";
@@ -125,11 +124,24 @@ export function HoverCard({
       }
     };
   }, [textOnly, hoverCard.ref, hoverCard.describedBy]);
-  const renderedHoverCard = typeof document !== 'undefined' ? /*#__PURE__*/createPortal(hoverCard.renderHoverCard(content, {
+
+  // Render the floating layer inline, in the same place on the server and the
+  // client. The layer is a `popover` element opened via the Popover API, so the
+  // browser promotes it to the top layer when shown — that already escapes
+  // ancestor clipping, stacking, and transform containing-block traps, and CSS
+  // anchor positioning resolves the trigger reference regardless of where the
+  // element sits in the DOM, so no portal is needed to "escape" layout.
+  //
+  // The layer renders as inline-safe phrasing markup (a `<span>`, see
+  // useHoverCard), which stays put inside a `<p>` instead of being reparented
+  // by the HTML parser. That keeps the server markup and the first client
+  // render identical, so there is no hydration mismatch — and it preserves the
+  // inline-safety guarantee (no block elements injected into a paragraph).
+  const renderedHoverCard = hoverCard.renderHoverCard(content, {
     xstyle,
     className,
     style
-  }), document.body) : null;
+  });
 
   // For text-only children: use inline span with ref on wrapper
   if (textOnly) {

package/dist/HoverCard/useHoverCard.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"useHoverCard.d.ts","sourceRoot":"","sources":["../../src/HoverCard/useHoverCard.tsx"],"names":[],"mappings":"AAIA;;;;;;;;GAQG;AAEH,OAAO,EAKL,KAAK,SAAS,EACd,KAAK,WAAW,EACjB,MAAM,OAAO,CAAC;AAEf,OAAO,EAEL,KAAK,kBAAkB,EACvB,KAAK,cAAc,EACnB,KAAK,cAAc,EACpB,MAAM,mBAAmB,CAAC;AAyC3B;;GAEG;AACH,MAAM,MAAM,qBAAqB,GAAG,MAAM,GAAG,QAAQ,GAAG,OAAO,CAAC;AAEhE,MAAM,WAAW,gBAAgB;IAC/B;;;OAGG;IACH,SAAS,CAAC,EAAE,cAAc,CAAC;IAE3B;;;OAGG;IACH,SAAS,CAAC,EAAE,cAAc,CAAC;IAE3B;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB;;;;;;;OAOG;IACH,YAAY,CAAC,EAAE,qBAAqB,CAAC;IAErC;;;;;OAKG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;IAEpB;;;;;OAKG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;IAEjB;;;OAGG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;IAExB;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,IAAI,CAAC;IAEpB;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,IAAI,CAAC;CACrB;AAED,MAAM,WAAW,eAAe;IAC9B;;;OAGG;IACH,GAAG,EAAE,WAAW,CAAC,WAAW,CAAC,CAAC;IAE9B;;;OAGG;IACH,WAAW,EAAE,WAAW,CAAC,WAAW,CAAC,CAAC;IAEtC;;;;OAIG;IACH,cAAc,EAAE,WAAW,CAAC,WAAW,CAAC,CAAC;IAEzC;;;OAGG;IACH,QAAQ,EAAE,MAAM,CAAC;IAEjB;;;OAGG;IACH,WAAW,EAAE,MAAM,CAAC;IAEpB;;;OAGG;IACH,eAAe,EAAE,CACf,QAAQ,EAAE,SAAS,EACnB,KAAK,CAAC,EAAE,kBAAkB,KACvB,SAAS,CAAC;IAEf;;OAEG;IACH,IAAI,EAAE,MAAM,IAAI,CAAC;IAEjB;;OAEG;IACH,IAAI,EAAE,MAAM,IAAI,CAAC;CAClB;AAyBD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,YAAY,CAC1B,OAAO,GAAE,gBAAqB,GAC7B,eAAe,CA2RjB"}
+{"version":3,"file":"useHoverCard.d.ts","sourceRoot":"","sources":["../../src/HoverCard/useHoverCard.tsx"],"names":[],"mappings":"AAIA;;;;;;;;GAQG;AAEH,OAAO,EAKL,KAAK,SAAS,EACd,KAAK,WAAW,EACjB,MAAM,OAAO,CAAC;AAEf,OAAO,EAEL,KAAK,kBAAkB,EACvB,KAAK,cAAc,EACnB,KAAK,cAAc,EACpB,MAAM,mBAAmB,CAAC;AA6C3B;;GAEG;AACH,MAAM,MAAM,qBAAqB,GAAG,MAAM,GAAG,QAAQ,GAAG,OAAO,CAAC;AAEhE,MAAM,WAAW,gBAAgB;IAC/B;;;OAGG;IACH,SAAS,CAAC,EAAE,cAAc,CAAC;IAE3B;;;OAGG;IACH,SAAS,CAAC,EAAE,cAAc,CAAC;IAE3B;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IAEf;;;OAGG;IACH,SAAS,CAAC,EAAE,MAAM,CAAC;IAEnB;;;;;;;OAOG;IACH,YAAY,CAAC,EAAE,qBAAqB,CAAC;IAErC;;;;;OAKG;IACH,SAAS,CAAC,EAAE,OAAO,CAAC;IAEpB;;;;;OAKG;IACH,MAAM,CAAC,EAAE,OAAO,CAAC;IAEjB;;;OAGG;IACH,aAAa,CAAC,EAAE,OAAO,CAAC;IAExB;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,IAAI,CAAC;IAEpB;;;OAGG;IACH,MAAM,CAAC,EAAE,MAAM,IAAI,CAAC;CACrB;AAED,MAAM,WAAW,eAAe;IAC9B;;;OAGG;IACH,GAAG,EAAE,WAAW,CAAC,WAAW,CAAC,CAAC;IAE9B;;;OAGG;IACH,WAAW,EAAE,WAAW,CAAC,WAAW,CAAC,CAAC;IAEtC;;;;OAIG;IACH,cAAc,EAAE,WAAW,CAAC,WAAW,CAAC,CAAC;IAEzC;;;OAGG;IACH,QAAQ,EAAE,MAAM,CAAC;IAEjB;;;OAGG;IACH,WAAW,EAAE,MAAM,CAAC;IAEpB;;;OAGG;IACH,eAAe,EAAE,CACf,QAAQ,EAAE,SAAS,EACnB,KAAK,CAAC,EAAE,kBAAkB,KACvB,SAAS,CAAC;IAEf;;OAEG;IACH,IAAI,EAAE,MAAM,IAAI,CAAC;IAEjB;;OAEG;IACH,IAAI,EAAE,MAAM,IAAI,CAAC;CAClB;AAyBD;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,YAAY,CAAC,OAAO,GAAE,gBAAqB,GAAG,eAAe,CA4R5E"}

package/dist/HoverCard/useHoverCard.js

@@ -261,11 +261,15 @@ export function useHoverCard(options = {}) {
     const renderProps = {
       placement: renderPlacement,
       alignment: props?.alignment ?? alignment,
-      xstyle: [popoverXstyle, layerAnimations[renderPlacement]]
+      role: 'dialog',
+      xstyle: [popoverXstyle, layerAnimations[renderPlacement]],
+      // Render the layer as inline-safe phrasing markup so HoverCard stays
+      // valid (and hydration-stable) inside inline contexts like a `<p>`.
+      as: 'span'
     };
-    return layer.render(/*#__PURE__*/_jsx("div", {
+    return layer.render(/*#__PURE__*/_jsx("span", {
       ...mergeProps(themeProps('hovercard'), {
-        className: "x1vlblms xvmdzux x126nfab x1t818jl"
+        className: "x1lliihq x1vlblms xvmdzux x126nfab x1t818jl"
       }),
       onMouseEnter: () => {
         isHoveringContentRef.current = true;

package/dist/Kbd/Kbd.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Kbd.d.ts","sourceRoot":"","sources":["../../src/Kbd/Kbd.tsx"],"names":[],"mappings":"AAIA;;;;;;;;;GASG;AAEH,OAAO,KAA6B,MAAM,OAAO,CAAC;AAGlD,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AAiG5C,MAAM,WAAW,QAAS,SAAQ,SAAS,CAAC,eAAe,CAAC;IAC1D,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,eAAe,CAAC,CAAC;IACjC;;;;;;;;;;;;OAYG;IACH,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,GAAG,CAAC,EAClB,IAAI,EACJ,GAAG,EACH,MAAM,EACN,SAAS,EACT,KAAK,EACL,GAAG,IAAI,EACR,EAAE,QAAQ,qBA2BV;yBAlCe,GAAG"}
+{"version":3,"file":"Kbd.d.ts","sourceRoot":"","sources":["../../src/Kbd/Kbd.tsx"],"names":[],"mappings":"AAIA;;;;;;;;;GASG;AAEH,OAAO,KAA6B,MAAM,OAAO,CAAC;AAGlD,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,cAAc,CAAC;AAiG5C,MAAM,WAAW,QAAS,SAAQ,SAAS,CAAC,eAAe,CAAC;IAC1D,GAAG,CAAC,EAAE,KAAK,CAAC,GAAG,CAAC,eAAe,CAAC,CAAC;IACjC;;;;;;;;;;;;OAYG;IACH,IAAI,EAAE,MAAM,CAAC;CACd;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,GAAG,CAAC,EAAC,IAAI,EAAE,GAAG,EAAE,MAAM,EAAE,SAAS,EAAE,KAAK,EAAE,GAAG,IAAI,EAAC,EAAE,QAAQ,qBA2B3E;yBA3Be,GAAG"}