@usefragments/ui 1.0.2 → 1.1.1

package/src/components/Header/index.tsx

@@ -25,12 +25,26 @@ export type HeaderIconSlot =
 
 export type HeaderIcons = Partial<Record<HeaderIconRenderState['slot'], HeaderIconSlot>>;
 
+export type HeaderNavAlign = 'start' | 'center';
+export type HeaderContainer = 'full' | 'page';
+
+export interface HeaderElevatedOnScrollOptions {
+  /** Scroll offset before the elevated surface is applied */
+  threshold?: number;
+}
+
 export interface HeaderProps extends React.HTMLAttributes<HTMLElement> {
   children: React.ReactNode;
   /** Header height (default: '56px') */
   height?: string;
   /** Position behavior */
   position?: 'static' | 'fixed' | 'sticky';
+  /** Apply the elevated header surface after scroll */
+  elevatedOnScroll?: boolean | HeaderElevatedOnScrollOptions;
+  /** Navigation alignment inside the header */
+  navAlign?: HeaderNavAlign;
+  /** Header content width */
+  container?: HeaderContainer;
   /** Optional icon overrides for internal header controls (mobile trigger + nav menu chevron) */
   icons?: HeaderIcons;
 }
@@ -39,6 +53,8 @@ export interface HeaderBrandProps extends React.HTMLAttributes<HTMLElement> {
   children: React.ReactNode;
   /** Link destination */
   href?: string;
+  /** Render as child element (polymorphic) */
+  asChild?: boolean;
 }
 
 export interface HeaderNavProps extends React.HTMLAttributes<HTMLElement> {
@@ -101,6 +117,10 @@ export interface HeaderMobileNavProps {
   className?: string;
 }
 
+export interface HeaderMobileNavActionsProps extends React.HTMLAttributes<HTMLDivElement> {
+  children: React.ReactNode;
+}
+
 // ============================================
 // Internal Context
 // ============================================
@@ -175,17 +195,37 @@ function HeaderRoot({
   children,
   height = '56px',
   position = 'static',
+  elevatedOnScroll = false,
+  navAlign = 'start',
+  container = 'full',
   icons,
   className,
   style: styleProp,
   ...htmlProps
 }: HeaderProps) {
   const [mobileOpen, setMobileOpen] = React.useState(false);
+  const [scrolled, setScrolled] = React.useState(false);
+  const shouldElevateOnScroll = Boolean(elevatedOnScroll);
+  const scrollThreshold =
+    typeof elevatedOnScroll === 'object' ? (elevatedOnScroll.threshold ?? 16) : 16;
+
+  React.useEffect(() => {
+    if (!shouldElevateOnScroll) return;
+
+    const updateScrolled = () => setScrolled(window.scrollY > scrollThreshold);
+    updateScrolled();
+    window.addEventListener('scroll', updateScrolled, { passive: true });
+    return () => window.removeEventListener('scroll', updateScrolled);
+  }, [scrollThreshold, shouldElevateOnScroll]);
 
   const classes = [
     styles.header,
     position === 'fixed' && styles.fixed,
     position === 'sticky' && styles.sticky,
+    shouldElevateOnScroll && styles.elevatedOnScroll,
+    shouldElevateOnScroll && scrolled && styles.scrolled,
+    navAlign === 'center' && styles.navCentered,
+    container === 'page' && styles.containerPage,
     className,
   ].filter(Boolean).join(' ');
 
@@ -202,7 +242,13 @@ function HeaderRoot({
   return (
     <HeaderContext.Provider value={contextValue}>
       <HeaderIconContext.Provider value={icons}>
-        <header {...htmlProps} className={classes} style={style} data-position={position}>
+        <header
+          {...htmlProps}
+          className={classes}
+          style={style}
+          data-position={position}
+          data-scrolled={shouldElevateOnScroll ? scrolled : undefined}
+        >
           <div className={styles.container}>
             {children}
           </div>
@@ -215,9 +261,30 @@ function HeaderRoot({
 /**
  * Header.Brand - Logo/brand slot
  */
-function HeaderBrand({ children, href, className, ...htmlProps }: HeaderBrandProps) {
+function HeaderBrand({
+  children,
+  href,
+  asChild = false,
+  className,
+  ...htmlProps
+}: HeaderBrandProps) {
   const classes = [styles.brand, className].filter(Boolean).join(' ');
 
+  if (asChild && React.isValidElement(children)) {
+    const childProps = children.props as {
+      className?: string;
+      onClick?: React.MouseEventHandler<HTMLElement>;
+    };
+    const { onClick, ...restHtmlProps } = htmlProps as React.HTMLAttributes<HTMLElement>;
+
+    return React.cloneElement(children, {
+      ...restHtmlProps,
+      ...(href ? { href } : {}),
+      className: [classes, childProps.className].filter(Boolean).join(' '),
+      onClick: onClick ? composeEventHandlers(childProps.onClick, onClick) : childProps.onClick,
+    } as React.HTMLAttributes<HTMLElement>);
+  }
+
   if (href) {
     return (
       <a {...htmlProps} href={href} className={classes}>
@@ -604,6 +671,23 @@ function HeaderMobileNavLink({
   );
 }
 
+/**
+ * Header.MobileNavActions - Action row inside the mobile drawer
+ */
+function HeaderMobileNavActions({
+  children,
+  className,
+  ...htmlProps
+}: HeaderMobileNavActionsProps) {
+  const classes = [styles.mobileNavActions, className].filter(Boolean).join(' ');
+
+  return (
+    <div {...htmlProps} className={classes}>
+      {children}
+    </div>
+  );
+}
+
 /**
  * Header.SkipLink - Skip to main content link (accessibility)
  */
@@ -641,6 +725,7 @@ export const Header = Object.assign(HeaderRoot, {
   SkipLink: HeaderSkipLink,
   MobileNav: HeaderMobileNav,
   MobileNavLink: HeaderMobileNavLink,
+  MobileNavActions: HeaderMobileNavActions,
 });
 
 export {
@@ -657,4 +742,5 @@ export {
   HeaderSkipLink,
   HeaderMobileNav,
   HeaderMobileNavLink,
+  HeaderMobileNavActions,
 };

package/src/components/IconButton/IconButton.contract.json

@@ -0,0 +1,120 @@
+{
+  "$schema": "https://usefragments.com/schemas/contract.v1.json",
+  "name": "IconButton",
+  "description": "Compact square button for icon-only actions in dense toolbars, top bars, and row controls.",
+  "category": "forms",
+  "tags": ["action", "button", "icon", "toolbar", "interactive"],
+  "status": "stable",
+  "sourcePath": "src/components/IconButton/index.tsx",
+  "exportName": "IconButton",
+  "propsSummary": [
+    "children: node (required)",
+    "variant: ghost|subtle|outlined (default: ghost)",
+    "size: sm|md|lg (default: md)",
+    "pressed: boolean",
+    "aria-label: string",
+    "aria-labelledby: string"
+  ],
+  "props": {
+    "children": {
+      "type": "node",
+      "description": "Icon element rendered inside the button",
+      "required": true
+    },
+    "variant": {
+      "type": "enum",
+      "description": "Visual treatment for the icon-only action",
+      "default": "ghost",
+      "required": false,
+      "values": ["ghost", "subtle", "outlined"]
+    },
+    "size": {
+      "type": "enum",
+      "description": "Control size aligned with adjacent fields and toolbar actions",
+      "default": "md",
+      "required": false,
+      "values": ["sm", "md", "lg"]
+    },
+    "pressed": {
+      "type": "boolean",
+      "description": "Marks a toggle-style action as pressed and sets aria-pressed",
+      "required": false
+    },
+    "aria-label": {
+      "type": "string",
+      "description": "Accessible action name when no labelled-by relationship is available",
+      "required": false
+    },
+    "aria-labelledby": {
+      "type": "string",
+      "description": "ID reference for an external accessible action label",
+      "required": false
+    }
+  },
+  "usage": {
+    "when": [
+      "Compact icon-only actions in toolbars or top bars",
+      "Row actions where a text button would be too wide",
+      "Toggle-style icon actions with a visible pressed state"
+    ],
+    "whenNot": [
+      "The action needs a visible text label (use Button)",
+      "The control changes a persistent boolean setting (use Switch)",
+      "The icon is decorative and not interactive (use Icon)"
+    ],
+    "guidelines": [
+      "Always provide aria-label or aria-labelledby",
+      "Use ghost for ordinary toolbar actions and outlined when more separation is needed",
+      "Use pressed only when the button represents a persistent toggle state"
+    ],
+    "accessibility": [
+      "Every icon-only button must have an accessible name",
+      "The accessible name should describe the action, not the icon",
+      "Pressed state must be exposed with aria-pressed"
+    ]
+  },
+  "examples": [
+    {
+      "name": "Toolbar action",
+      "description": "A named icon-only toolbar action",
+      "code": "<IconButton aria-label=\"Add item\">\n  <PlusIcon aria-hidden />\n</IconButton>"
+    },
+    {
+      "name": "Pressed state",
+      "description": "A toggle-style action with its state exposed",
+      "code": "import { PushPin as PinIcon } from '@phosphor-icons/react';\n\n<IconButton aria-label=\"Pin item\" pressed>\n  <PinIcon aria-hidden />\n</IconButton>"
+    }
+  ],
+  "relations": [
+    {
+      "component": "Button",
+      "relationship": "sibling",
+      "note": "Use Button when the action should have a visible text label or broader layout variants"
+    },
+    {
+      "component": "Icon",
+      "relationship": "complementary",
+      "note": "Icon supplies the visual glyph rendered inside IconButton"
+    }
+  ],
+  "contract": {
+    "propsSummary": [
+      "children: ReactNode - icon element (required)",
+      "variant: ghost|subtle|outlined - visual treatment",
+      "size: sm|md|lg - square control size",
+      "pressed: boolean - toggle state exposed with aria-pressed",
+      "aria-label or aria-labelledby - required accessible name"
+    ],
+    "a11yRules": ["A11Y_BTN_LABEL", "A11Y_BTN_FOCUS", "A11Y_TARGET_SIZE_MIN"]
+  },
+  "ai": {
+    "compositionPattern": "compound",
+    "subComponents": ["Root"]
+  },
+  "provenance": {
+    "source": "migrated",
+    "verified": false,
+    "frameworkSupport": "native",
+    "extractedAt": "2026-07-14T00:00:00.000Z"
+  }
+}

package/src/components/Listbox/Listbox.module.scss

@@ -1,5 +1,5 @@
-@use '../../tokens/variables' as *;
-@use '../../tokens/mixins' as *;
+@use "../../tokens/variables" as *;
+@use "../../tokens/mixins" as *;
 
 // ============================================
 // Listbox container
@@ -10,7 +10,7 @@
   @include popup-container;
 
   // Item height derived from text-base font + vertical padding (matches Select/Combobox)
-  --_item-h: calc(
+  --_listbox-item-h: calc(
     var(--fui-font-size-sm, #{$fui-font-size-sm}) *
       var(--fui-line-height-normal, #{$fui-line-height-normal}) +
       var(--fui-space-2, #{$fui-space-2}) * 2
@@ -19,7 +19,8 @@
   min-width: 12rem;
   // Show N items + half-peek scroll hint (default 4.5 items)
   max-height: calc(
-    var(--_item-h) * var(--fui-select-max-items, 4.5) + var(--fui-space-1, #{$fui-space-1}) * 2
+    var(--_listbox-item-h) * var(--fui-select-max-items, 4.5) +
+      var(--fui-space-1, #{$fui-space-1}) * 2
   );
   overflow-y: auto;
   border-color: var(--fui-form-group-border, $fui-border);

package/src/components/Menu/Menu.module.scss

@@ -8,6 +8,7 @@ $fui-arrow-size: 10px !default;
 .positioner {
   z-index: 52;
   outline: none;
+  pointer-events: auto;
 }
 
 // Popup container
@@ -19,23 +20,21 @@ $fui-arrow-size: 10px !default;
   margin: 0;
   min-width: 12rem;
 
-  // Animation
-  opacity: 0;
-  transform: scale(0.95);
+  // Menus must be fully hit-testable as soon as they open. A fade/scale
+  // entrance can let fast clicks pass through to page links under the portal.
+  opacity: 1;
+  transform: none;
   transform-origin: var(--transform-origin);
-  transition:
-    opacity var(--fui-transition-fast, $fui-transition-fast),
-    transform var(--fui-transition-fast, $fui-transition-fast);
 
   &[data-open] {
     opacity: 1;
-    transform: scale(1);
+    transform: none;
   }
 
   &[data-starting-style],
   &[data-ending-style] {
-    opacity: 0;
-    transform: scale(0.95);
+    opacity: 1;
+    transform: none;
   }
 }
 
@@ -204,7 +203,6 @@ $fui-arrow-size: 10px !default;
 
 @media (prefers-reduced-motion: reduce) {
   .popup {
-    transition: none;
     transform: none;
 
     &[data-starting-style],

package/src/components/Popover/index.tsx

@@ -110,6 +110,28 @@ function CloseIcon() {
   );
 }
 
+// ============================================
+// Helpers
+// ============================================
+
+/**
+ * Base UI's button-like triggers default `nativeButton` to `true`. When an
+ * `asChild` trigger renders something other than a native `<button>` (an
+ * anchor, or a component rendered `as="a"`), that default is wrong and Base UI
+ * warns that native button semantics were removed. Resolve the correct value
+ * from the child so the trigger stays honest and the warning goes away.
+ */
+function resolveNativeButton(child: React.ReactElement): boolean {
+  const type = child.type;
+  // Intrinsic elements: only `<button>` is a native button.
+  if (typeof type === 'string') return type === 'button';
+  // Custom components render a native `<button>` by default; treat anchors
+  // (via `as="a"` or an `href`) as non-native.
+  const props = (child.props ?? {}) as Record<string, unknown>;
+  if (props.as === 'a' || props.href != null) return false;
+  return true;
+}
+
 // ============================================
 // Components
 // ============================================
@@ -139,7 +161,12 @@ function PopoverTrigger({ children, asChild, className, ...htmlProps }: PopoverT
       throw new Error('Popover.Trigger with asChild requires a single valid React element child.');
     }
     return (
-      <BasePopover.Trigger {...htmlProps} className={className} render={children as React.ReactElement}>
+      <BasePopover.Trigger
+        {...htmlProps}
+        nativeButton={resolveNativeButton(children as React.ReactElement)}
+        className={className}
+        render={children as React.ReactElement}
+      >
         {null}
       </BasePopover.Trigger>
     );
@@ -240,7 +267,12 @@ function PopoverClose({ children, asChild, className, ...htmlProps }: PopoverClo
       throw new Error('Popover.Close with asChild requires a single valid React element child.');
     }
     return (
-      <BasePopover.Close {...htmlProps} className={className} render={children as React.ReactElement}>
+      <BasePopover.Close
+        {...htmlProps}
+        nativeButton={resolveNativeButton(children as React.ReactElement)}
+        className={className}
+        render={children as React.ReactElement}
+      >
         {null}
       </BasePopover.Close>
     );

package/src/components/RadioGroup/RadioGroup.contract.json

@@ -3,12 +3,7 @@
   "name": "RadioGroup",
   "description": "Single selection from a list of mutually exclusive options",
   "category": "forms",
-  "tags": [
-    "form",
-    "radio",
-    "selection",
-    "options"
-  ],
+  "tags": ["form", "radio", "selection", "options"],
   "status": "stable",
   "sourcePath": "src/components/RadioGroup/index.tsx",
   "exportName": "RadioGroup",
@@ -26,6 +21,7 @@
     "size: sm|md|lg (default: md)",
     "wrapperClassName: string",
     "groupClassName: string",
+    "groupId: string",
     "children: node (required)"
   ],
   "props": {
@@ -54,10 +50,7 @@
       "description": "Layout orientation",
       "default": "vertical",
       "required": false,
-      "values": [
-        "horizontal",
-        "vertical"
-      ]
+      "values": ["horizontal", "vertical"]
     },
     "disabled": {
       "type": "boolean",
@@ -90,21 +83,14 @@
       "description": "Size variant",
       "default": "md",
       "required": false,
-      "values": [
-        "sm",
-        "md",
-        "lg"
-      ]
+      "values": ["sm", "md", "lg"]
     },
     "variant": {
       "type": "enum",
       "description": "Visual variant. 'default' is the inline radio, 'card' renders each item as a full-width clickable card with the radio tucked inside.",
       "default": "default",
       "required": false,
-      "values": [
-        "default",
-        "card"
-      ]
+      "values": ["default", "card"]
     },
     "wrapperClassName": {
       "type": "string",
@@ -116,6 +102,11 @@
       "description": "Class name for the inner radio group element",
       "required": false
     },
+    "groupId": {
+      "type": "string",
+      "description": "ID for the inner element with role=radiogroup; the inherited id remains on the outer field wrapper",
+      "required": false
+    },
     "children": {
       "type": "node",
       "description": "RadioGroup.Item elements",
@@ -213,19 +204,14 @@
       "error: boolean | string - error styling and message",
       "disabled: boolean - disable all options",
       "wrapperClassName/groupClassName - explicit styling targets for wrapper and group",
+      "groupId: string - ID forwarded to the inner radiogroup while id remains on the wrapper",
       "RadioGroup.Item supports helperText (preferred) and description (legacy alias) plus controlClassName/contentClassName for item-level styling"
     ],
-    "a11yRules": [
-      "A11Y_RADIO_GROUP",
-      "A11Y_LABEL_REQUIRED",
-      "A11Y_TARGET_SIZE_MIN"
-    ]
+    "a11yRules": ["A11Y_RADIO_GROUP", "A11Y_LABEL_REQUIRED", "A11Y_TARGET_SIZE_MIN"]
   },
   "ai": {
     "compositionPattern": "compound",
-    "subComponents": [
-      "Item"
-    ]
+    "subComponents": ["Item"]
   },
   "provenance": {
     "source": "migrated",

package/src/components/RadioGroup/index.tsx

@@ -61,6 +61,8 @@ export interface RadioGroupProps extends Omit<
   wrapperClassName?: string;
   /** Class applied to the inner radio group container */
   groupClassName?: string;
+  /** ID applied to the inner element with `role="radiogroup"`. The inherited `id` remains on the outer field wrapper for compatibility. */
+  groupId?: string;
   /** Children (Radio.Item components) */
   children: React.ReactNode;
 }
@@ -216,6 +218,7 @@ const RadioGroupRoot = React.forwardRef<HTMLDivElement, RadioGroupProps>(functio
     variant = "default",
     wrapperClassName,
     groupClassName,
+    groupId,
     children,
     className,
     "aria-label": ariaLabel,
@@ -252,6 +255,7 @@ const RadioGroupRoot = React.forwardRef<HTMLDivElement, RadioGroupProps>(functio
             </span>
           )}
           <BaseRadioGroup
+            id={groupId}
             value={value}
             defaultValue={defaultValue}
             onValueChange={handleValueChange}

package/src/components/Select/Select.module.scss

@@ -1,5 +1,5 @@
-@use '../../tokens/variables' as *;
-@use '../../tokens/mixins' as *;
+@use "../../tokens/variables" as *;
+@use "../../tokens/mixins" as *;
 
 // Form field wrapper (label + helper + error)
 @include form-field-wrapper;
@@ -10,7 +10,7 @@
   @include interactive-base;
   @include text-base;
   @include field-shell;
-  @include control-size('md', 'input');
+  @include control-size("md", "input");
 
   display: inline-flex;
   align-items: center;
@@ -27,11 +27,11 @@
 
 // Trigger size variants
 .triggerSm {
-  @include control-size('sm', 'input');
+  @include control-size("sm", "input");
 }
 
 .triggerLg {
-  @include control-size('lg', 'input');
+  @include control-size("lg", "input");
 }
 
 // Value display
@@ -86,17 +86,18 @@
   border-color: var(--fui-form-group-border, $fui-border);
 
   // Item height derived from text-base font + vertical padding
-  --_item-h: calc(
-    var(--fui-font-size-sm, #{$fui-font-size-sm}) * var(--fui-line-height-normal, #{$fui-line-height-normal}) +
-    var(--fui-space-2, #{$fui-space-2}) * 2
+  --_select-item-h: calc(
+    var(--fui-font-size-sm, #{$fui-font-size-sm}) *
+      var(--fui-line-height-normal, #{$fui-line-height-normal}) +
+      var(--fui-space-2, #{$fui-space-2}) * 2
   );
 
   min-width: var(--anchor-width);
   // Show N items + half-peek scroll hint (default 4.5 items)
   // !important needed to override Base UI's inline max-height: 100%
   max-height: calc(
-    var(--_item-h) * var(--fui-select-max-items, 4.5) +
-    var(--fui-space-1, #{$fui-space-1}) * 2
+    var(--_select-item-h) * var(--fui-select-max-items, 4.5) + var(--fui-space-1, #{$fui-space-1}) *
+      2
   ) !important;
   overflow-y: auto !important;
 
@@ -214,12 +215,12 @@
   background-color: var(--fui-bg-elevated, $fui-bg-elevated);
   border: 1px solid var(--fui-border, $fui-border);
 
-  &[data-side='top'] {
+  &[data-side="top"] {
     border-top: none;
     border-left: none;
   }
 
-  &[data-side='bottom'] {
+  &[data-side="bottom"] {
     border-bottom: none;
     border-right: none;
   }

package/src/components/TableOfContents/TableOfContents.module.scss

@@ -176,6 +176,15 @@ $rail-from-item-1: $rail-x-1 - $rail-pad; //  3px
 // Item link
 // ============================================
 
+// ── Plain index (design-system default) ──────────────────────────────────────
+// The "on this page" index reads as a quiet list — the active row is signalled
+// by ink + medium weight (see .active), not a coloured rail. Drop the per-row
+// rail and elbow pseudo-elements the snake geometry above would otherwise draw.
+.root [data-depth]::before,
+.root [data-depth]::after {
+  content: none;
+}
+
 .link {
   display: flex;
   align-items: center;
@@ -231,7 +240,7 @@ $rail-from-item-1: $rail-x-1 - $rail-pad; //  3px
 }
 
 .active {
-  color: var(--fui-color-accent, $fui-color-accent);
+  color: var(--fui-text-primary, $fui-text-primary);
   font-weight: var(--fui-font-weight-medium, $fui-font-weight-medium);
 }
 

package/src/components/Toast/Toast.module.scss

@@ -63,7 +63,9 @@
 
 .toast {
   display: flex;
-  align-items: flex-start;
+  // Single-line toasts (title only) read best vertically centered; toasts
+  // with a description are multi-line and top-align — see `:has(.description)`.
+  align-items: center;
   gap: var(--fui-space-1, $fui-space-1);
   padding: var(--fui-space-2, $fui-space-2) var(--fui-space-3, $fui-space-3);
   background-color: var(--fui-bg-elevated, $fui-bg-elevated);
@@ -76,6 +78,12 @@
   animation: toastEnter var(--fui-transition-normal, $fui-transition-normal);
 }
 
+// With a description the toast is multi-line: top-align icon/close to the
+// first line rather than the block centre.
+.toast:has(.description) {
+  align-items: flex-start;
+}
+
 @keyframes toastEnter {
   from {
     opacity: 0;
@@ -177,7 +185,6 @@
   flex-shrink: 0;
   width: 1.25rem;
   height: 1.25rem;
-  margin-top: 1px;
 
   svg {
     width: 100%;
@@ -185,6 +192,12 @@
   }
 }
 
+// Nudge the icon to meet the first line only in multi-line toasts; centered
+// single-line toasts need no offset.
+.toast:has(.description) .icon {
+  margin-top: 1px;
+}
+
 .content {
   flex: 1;
   min-width: 0;

package/src/components/ToggleGroup/ToggleGroup.module.scss

@@ -37,7 +37,10 @@
   .item {
     background-color: transparent;
     border: 1px solid transparent;
-    border-radius: var(--fui-radius-sm, $fui-radius-sm);
+    // Match the container's radius (form-group-surface = --fui-radius-lg),
+    // less its 1px inset border, so the selected fill nests inside the
+    // container corners instead of poking past them.
+    border-radius: calc(var(--fui-radius-lg, #{$fui-radius-lg}) - 1px);
 
     &.selected {
       background-color: var(--fui-toggle-group-selected-bg, var(--fui-bg-hover, #{$fui-bg-hover}));