@usefragments/ui 1.0.2 → 1.2.0

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/Main/Main.contract.json

@@ -0,0 +1,79 @@
+{
+  "$schema": "https://usefragments.com/schemas/contract.v1.json",
+  "name": "Main",
+  "description": "Canonical page composition owning gutter, measure, and vertical rhythm.",
+  "category": "layout",
+  "tags": ["main", "page", "layout", "compound"],
+  "status": "stable",
+  "sourcePath": "src/components/Main/index.tsx",
+  "exportName": "Main",
+  "propsSummary": [
+    "children: node (required)",
+    "measure: full|narrow (default: full)",
+    "as: semantic element (default: main)"
+  ],
+  "props": {
+    "children": {
+      "type": "node",
+      "description": "Page regions composed from Main.Header, Main.Description, Main.Content, and Main.Footer",
+      "required": true
+    },
+    "measure": {
+      "type": "enum",
+      "description": "Maximum width applied to the page composition",
+      "default": "full",
+      "required": false,
+      "values": ["full", "narrow"]
+    },
+    "as": {
+      "type": "enum",
+      "description": "Semantic HTML element rendered by the root",
+      "default": "main",
+      "required": false,
+      "values": [
+        "div",
+        "section",
+        "nav",
+        "article",
+        "aside",
+        "header",
+        "footer",
+        "main",
+        "ul",
+        "ol"
+      ]
+    }
+  },
+  "usage": {
+    "when": ["Composing a page header, description, content, and footer"],
+    "whenNot": ["Application shell navigation (use AppShell)"],
+    "guidelines": [
+      "Use one Main gutter owner per page",
+      "Compose page regions with Main.Header, Main.Description, Main.Content, and Main.Footer"
+    ],
+    "accessibility": [
+      "Use the default main element unless an existing shell already owns the main landmark"
+    ]
+  },
+  "examples": [
+    {
+      "name": "Full Measure",
+      "description": "Page composition that uses the full available canvas",
+      "code": "<Main measure=\"full\">\n  <Main.Header>Page statement</Main.Header>\n  <Main.Description>Supporting page context.</Main.Description>\n  <Main.Content>Page content</Main.Content>\n  <Main.Footer>Page actions</Main.Footer>\n</Main>"
+    },
+    {
+      "name": "Narrow Measure",
+      "description": "Readable page composition constrained to the canonical 800px measure",
+      "code": "<Main measure=\"narrow\">\n  <Main.Header>Settings</Main.Header>\n  <Main.Description>Manage the workspace contract.</Main.Description>\n  <Main.Content>Settings content</Main.Content>\n  <Main.Footer>Save changes</Main.Footer>\n</Main>"
+    }
+  ],
+  "ai": {
+    "compositionPattern": "compound",
+    "subComponents": ["Header", "Description", "Content", "Footer"]
+  },
+  "provenance": {
+    "source": "manual",
+    "verified": true,
+    "frameworkSupport": "native"
+  }
+}

package/src/components/Main/Main.module.scss

@@ -0,0 +1,31 @@
+@use "../../tokens/variables" as *;
+
+$fui-main-measure-narrow: 57.143rem !default;
+
+.root {
+  box-sizing: border-box;
+  width: 100%;
+  min-width: 0;
+  min-height: 100%;
+  margin-inline: auto;
+  padding: var(--fui-space-3, $fui-space-3);
+}
+
+.full {
+  max-width: none;
+}
+
+.narrow {
+  max-width: $fui-main-measure-narrow;
+}
+
+.header,
+.description,
+.content,
+.footer {
+  min-width: 0;
+}
+
+.description {
+  max-width: 68ch;
+}

package/src/components/Main/index.tsx

@@ -0,0 +1,124 @@
+import * as React from "react";
+import { Stack, type StackProps } from "../Stack";
+import styles from "./Main.module.scss";
+
+export type MainMeasure = "full" | "narrow";
+
+export interface MainProps extends Omit<StackProps, "as" | "children" | "direction" | "gap"> {
+  as?: StackProps["as"];
+  children: React.ReactNode;
+  /** Maximum readable width for the page content. */
+  measure?: MainMeasure;
+}
+
+export type MainRegionProps = StackProps;
+
+function joinClasses(...classes: Array<string | false | undefined>) {
+  return classes.filter(Boolean).join(" ");
+}
+
+const MainRoot = React.forwardRef<HTMLElement, MainProps>(function MainRoot(
+  { as = "main", children, className, measure = "full", ...htmlProps },
+  ref
+) {
+  return (
+    <Stack
+      {...htmlProps}
+      ref={ref}
+      as={as}
+      direction="column"
+      gap="lg"
+      className={joinClasses(
+        styles.root,
+        measure === "narrow" ? styles.narrow : styles.full,
+        className
+      )}
+      data-main-measure={measure}
+    >
+      {children}
+    </Stack>
+  );
+});
+
+function MainHeader({
+  as = "header",
+  direction = "column",
+  gap = "sm",
+  className,
+  ...props
+}: MainRegionProps) {
+  return (
+    <Stack
+      {...props}
+      as={as}
+      direction={direction}
+      gap={gap}
+      className={joinClasses(styles.header, className)}
+    />
+  );
+}
+
+function MainDescription({
+  as = "div",
+  direction = "column",
+  gap = "xs",
+  className,
+  ...props
+}: MainRegionProps) {
+  return (
+    <Stack
+      {...props}
+      as={as}
+      direction={direction}
+      gap={gap}
+      className={joinClasses(styles.description, className)}
+    />
+  );
+}
+
+function MainContent({
+  as = "div",
+  direction = "column",
+  gap = "lg",
+  className,
+  ...props
+}: MainRegionProps) {
+  return (
+    <Stack
+      {...props}
+      as={as}
+      direction={direction}
+      gap={gap}
+      className={joinClasses(styles.content, className)}
+    />
+  );
+}
+
+function MainFooter({
+  as = "footer",
+  direction = "row",
+  gap = "sm",
+  justify = "end",
+  wrap = true,
+  className,
+  ...props
+}: MainRegionProps) {
+  return (
+    <Stack
+      {...props}
+      as={as}
+      direction={direction}
+      gap={gap}
+      justify={justify}
+      wrap={wrap}
+      className={joinClasses(styles.footer, className)}
+    />
+  );
+}
+
+export const Main = Object.assign(MainRoot, {
+  Header: MainHeader,
+  Description: MainDescription,
+  Content: MainContent,
+  Footer: MainFooter,
+});

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>
     );