@fragments-sdk/ui 0.13.0 → 0.15.1

package/src/components/Form/index.tsx

@@ -8,9 +8,12 @@ import styles from './Form.module.scss';
 // Types
 // ============================================
 
-export interface FormProps extends Omit<React.HTMLAttributes<HTMLFormElement>, 'onSubmit'> {
+export interface FormProps extends Omit<React.FormHTMLAttributes<HTMLFormElement>, 'onSubmit'> {
   children: React.ReactNode;
   errors?: Record<string, string | string[]>;
+  /** Standard form submit handler */
+  onSubmit?: (event: React.FormEvent<HTMLFormElement>) => void;
+  /** @deprecated Use onSubmit */
   onFormSubmit?: (event: React.FormEvent<HTMLFormElement>) => void;
   onClearErrors?: (name: string) => void;
   validationMode?: 'onSubmit' | 'onBlur' | 'onChange';
@@ -23,6 +26,7 @@ export interface FormProps extends Omit<React.HTMLAttributes<HTMLFormElement>, '
 function FormRoot({
   children,
   errors,
+  onSubmit,
   onFormSubmit,
   onClearErrors,
   validationMode,
@@ -30,24 +34,16 @@ function FormRoot({
   ...htmlProps
 }: FormProps) {
   const classes = [styles.root, className].filter(Boolean).join(' ');
-
-  const baseProps: Record<string, unknown> = {
-    ...htmlProps,
-    errors,
-    validationMode,
-    className: classes,
-  };
-
-  if (onFormSubmit) {
-    baseProps.onSubmit = onFormSubmit;
-  }
-
-  if (onClearErrors) {
-    baseProps.onClearErrors = onClearErrors;
-  }
+  const submitHandler = onSubmit ?? onFormSubmit;
 
   return (
-    <BaseForm {...baseProps}>
+    <BaseForm
+      {...htmlProps}
+      errors={errors}
+      validationMode={validationMode}
+      onSubmit={submitHandler}
+      className={classes}
+    >
       {children}
     </BaseForm>
   );

package/src/components/Grid/Grid.module.scss

@@ -82,9 +82,9 @@
 // ============================================
 
 .paddingNone { padding: 0; }
-.paddingSm   { padding: var(--fui-padding-container-sm); }
-.paddingMd   { padding: var(--fui-padding-container-md); }
-.paddingLg   { padding: var(--fui-padding-container-lg); }
+.paddingSm   { padding: var(--fui-space-3); }
+.paddingMd   { padding: var(--fui-space-4); }
+.paddingLg   { padding: var(--fui-space-6); }
 
 // ============================================
 // Align items (cross-axis within cells)
@@ -140,3 +140,26 @@
 .selfAlignCenter  { align-self: center; }
 .selfAlignEnd     { align-self: end; }
 .selfAlignStretch { align-self: stretch; }
+
+// ============================================
+// Subgrid — item children align to parent tracks
+// ============================================
+// Usage: <Grid.Item subgrid colSpan={3}> or <Grid.Item subgrid="rows" rowSpan={3}>
+// Children of the item participate in the parent grid's tracks.
+// ~97% browser support (Chrome 117+, Firefox 71+, Safari 16+).
+
+.subgridRows {
+  display: grid;
+  grid-template-rows: subgrid;
+}
+
+.subgridColumns {
+  display: grid;
+  grid-template-columns: subgrid;
+}
+
+.subgridBoth {
+  display: grid;
+  grid-template-rows: subgrid;
+  grid-template-columns: subgrid;
+}

package/src/components/Grid/index.tsx

@@ -6,6 +6,7 @@ import styles from './Grid.module.scss';
 // ============================================
 
 type ColumnCount = 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 | 11 | 12;
+type GapScale = 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8;
 
 /** Responsive value — either a single value or per-breakpoint overrides */
 export interface ResponsiveColumns {
@@ -25,7 +26,7 @@ export interface ResponsiveColumns {
  * CSS Grid layout component with responsive columns.
  * @see https://usefragments.com/components/grid
  */
-export interface GridProps {
+export interface GridProps extends Omit<React.HTMLAttributes<HTMLDivElement>, 'children' | 'style' | 'className'> {
   children?: React.ReactNode;
   /**
    * Number of columns.
@@ -37,7 +38,7 @@ export interface GridProps {
   /** Minimum width for auto-fill columns (only used with columns="auto") */
   minChildWidth?: string;
   /** Gap between grid items. Accepts string tokens or numbers (1-8) mapping to the spacing scale */
-  gap?: 'none' | 'xs' | 'sm' | 'md' | 'lg' | 'xl' | number;
+  gap?: 'none' | 'xs' | 'sm' | 'md' | 'lg' | 'xl' | GapScale;
   /** Vertical alignment of items within their cells */
   alignItems?: 'start' | 'center' | 'end' | 'stretch';
   /** Horizontal alignment of items within their cells */
@@ -50,7 +51,7 @@ export interface GridProps {
   style?: React.CSSProperties;
 }
 
-export interface GridItemProps {
+export interface GridItemProps extends Omit<React.HTMLAttributes<HTMLDivElement>, 'children' | 'className'> {
   children?: React.ReactNode;
   /** Number of columns this item spans */
   colSpan?: ColumnCount | 'full';
@@ -58,8 +59,17 @@ export interface GridItemProps {
   rowSpan?: 1 | 2 | 3 | 4 | 5 | 6;
   /** Override alignment for this item */
   alignSelf?: 'start' | 'center' | 'end' | 'stretch';
+  /**
+   * Enable CSS subgrid so children align to parent grid tracks.
+   * - `true` or `"rows"` — children align to parent row tracks
+   * - `"columns"` — children align to parent column tracks
+   * - `"both"` — children align to both row and column tracks
+   * Requires the item to span multiple rows/columns for visible effect.
+   */
+  subgrid?: boolean | 'rows' | 'columns' | 'both';
   /** Additional class name */
   className?: string;
+  style?: React.CSSProperties;
 }
 
 // ============================================
@@ -72,7 +82,7 @@ function isResponsiveColumns(
   return typeof columns === 'object' && columns !== null;
 }
 
-const gapClasses: Record<NonNullable<GridProps['gap']>, string> = {
+const gapClasses: Record<Exclude<NonNullable<GridProps['gap']>, GapScale>, string> = {
   none: styles.gapNone,
   xs: styles.gapXs,
   sm: styles.gapSm,
@@ -104,6 +114,7 @@ export const Grid = React.forwardRef<HTMLDivElement, GridProps>(
       padding = 'none',
       className,
       style,
+      ...htmlProps
     },
     ref
   ) {
@@ -149,7 +160,7 @@ export const Grid = React.forwardRef<HTMLDivElement, GridProps>(
     const mergedStyle = inlineStyle ? { ...inlineStyle, ...style } : style;
 
     return (
-      <div ref={ref} className={classes} style={mergedStyle}>
+      <div {...htmlProps} ref={ref} className={classes} style={mergedStyle}>
         {children}
       </div>
     );
@@ -160,6 +171,12 @@ export const Grid = React.forwardRef<HTMLDivElement, GridProps>(
 // Grid.Item Sub-component
 // ============================================
 
+const subgridClasses: Record<string, string> = {
+  rows: styles.subgridRows,
+  columns: styles.subgridColumns,
+  both: styles.subgridBoth,
+};
+
 const GridItem = React.forwardRef<HTMLDivElement, GridItemProps>(
   function GridItem(
     {
@@ -167,22 +184,30 @@ const GridItem = React.forwardRef<HTMLDivElement, GridItemProps>(
       colSpan,
       rowSpan,
       alignSelf,
+      subgrid,
       className,
+      style,
+      ...htmlProps
     },
     ref
   ) {
+    const subgridClass = subgrid
+      ? subgridClasses[subgrid === true ? 'rows' : subgrid]
+      : undefined;
+
     const classes = [
       styles.item,
       colSpan && (colSpan === 'full' ? styles.colSpanFull : styles[`colSpan${colSpan}`]),
       rowSpan && styles[`rowSpan${rowSpan}`],
       alignSelf && styles[`selfAlign${cap(alignSelf)}`],
+      subgridClass,
       className,
     ]
       .filter(Boolean)
       .join(' ');
 
     return (
-      <div ref={ref} className={classes}>
+      <div {...htmlProps} ref={ref} className={classes} style={style}>
         {children}
       </div>
     );

package/src/components/Header/Header.module.scss

@@ -6,12 +6,15 @@
 // ============================================
 
 .header {
+  // Container query context: children respond to header width, not viewport
+  @include container(fui-header);
+
   display: flex;
   align-items: center;
   height: var(--header-height, var(--fui-appshell-header-height, $fui-appshell-header-height));
   min-height: var(--header-height, var(--fui-appshell-header-height, $fui-appshell-header-height));
   background-color: var(--fui-bg-primary, $fui-bg-primary);
-  padding: 0 var(--fui-padding-container-md, $fui-padding-container-md);
+  padding: 0 var(--fui-space-4, $fui-space-4);
   z-index: var(--fui-header-z-index, $fui-header-z-index);
 }
 
@@ -34,7 +37,8 @@
   width: 100%;
   max-width: 100%;
 
-  @include below-md {
+  // Compact gap when header container is narrow (replaces viewport media query)
+  @include container-max($fui-breakpoint-md, fui-header) {
     gap: var(--fui-space-1, $fui-space-1);
   }
 }
@@ -70,7 +74,8 @@
 .nav {
   display: none;
 
-  @include breakpoint-md {
+  // Show navigation when header has enough space
+  @include container-min($fui-breakpoint-md, fui-header) {
     display: flex;
     align-items: center;
   }
@@ -92,7 +97,7 @@
 
   display: flex;
   align-items: center;
-  padding: var(--fui-padding-item-xs, $fui-padding-item-xs) var(--fui-padding-item-md, $fui-padding-item-md);
+  padding: var(--fui-space-1, $fui-space-1) var(--fui-space-3, $fui-space-3);
   border-radius: var(--fui-radius-md, $fui-radius-md);
   color: var(--fui-text-secondary, $fui-text-secondary);
   text-decoration: none;
@@ -157,7 +162,7 @@
   @include surface-elevated;
 
   min-width: 10rem;
-  padding: var(--fui-padding-item-xs, $fui-padding-item-xs);
+  padding: var(--fui-space-1, $fui-space-1);
   box-shadow: var(--fui-shadow-md, $fui-shadow-md);
 
   opacity: 0;
@@ -186,7 +191,7 @@
   display: flex;
   align-items: center;
   width: 100%;
-  padding: var(--fui-padding-item-xs, $fui-padding-item-xs) var(--fui-padding-item-md, $fui-padding-item-md);
+  padding: var(--fui-space-1, $fui-space-1) var(--fui-space-3, $fui-space-3);
   border-radius: var(--fui-radius-sm, $fui-radius-sm);
   color: var(--fui-text-secondary, $fui-text-secondary);
   text-decoration: none;
@@ -235,7 +240,8 @@
 .search {
   display: none;
 
-  @include breakpoint-md {
+  // Show search when header has enough space
+  @include container-min($fui-breakpoint-md, fui-header) {
     display: flex;
     align-items: center;
   }
@@ -302,7 +308,7 @@
   top: var(--fui-space-2, $fui-space-2);
   left: var(--fui-space-2, $fui-space-2);
   z-index: 100;
-  padding: var(--fui-padding-item-sm, $fui-padding-item-sm) var(--fui-padding-item-lg, $fui-padding-item-lg);
+  padding: var(--fui-space-2, $fui-space-2) var(--fui-space-4, $fui-space-4);
   background-color: var(--fui-bg-primary, $fui-bg-primary);
   color: var(--fui-text-primary, $fui-text-primary);
   border: 2px solid var(--fui-color-accent, $fui-color-accent);
@@ -317,7 +323,7 @@
     clip: auto;
     white-space: normal;
     margin: 0;
-    padding: var(--fui-padding-item-sm, $fui-padding-item-sm) var(--fui-padding-item-lg, $fui-padding-item-lg);
+    padding: var(--fui-space-2, $fui-space-2) var(--fui-space-4, $fui-space-4);
     overflow: visible;
 
     @include focus-ring;

package/src/components/Header/index.tsx

@@ -10,31 +10,41 @@ import { useSidebar } from '../Sidebar';
 // Types
 // ============================================
 
+export interface HeaderIconRenderState {
+  slot: 'menu' | 'close' | 'navMenuChevron';
+  open?: boolean;
+  active?: boolean;
+}
+
+export type HeaderIconSlot =
+  | React.ReactNode
+  | ((state: HeaderIconRenderState) => React.ReactNode);
+
+export type HeaderIcons = Partial<Record<HeaderIconRenderState['slot'], HeaderIconSlot>>;
+
 export interface HeaderProps extends React.HTMLAttributes<HTMLElement> {
   children: React.ReactNode;
   /** Header height (default: '56px') */
   height?: string;
   /** Position behavior */
   position?: 'static' | 'fixed' | 'sticky';
+  /** Optional icon overrides for internal header controls (mobile trigger + nav menu chevron) */
+  icons?: HeaderIcons;
 }
 
-export interface HeaderBrandProps {
+export interface HeaderBrandProps extends React.HTMLAttributes<HTMLElement> {
   children: React.ReactNode;
   /** Link destination */
   href?: string;
-  /** Additional class name */
-  className?: string;
 }
 
-export interface HeaderNavProps {
+export interface HeaderNavProps extends React.HTMLAttributes<HTMLElement> {
   children: React.ReactNode;
   /** Accessible label for navigation */
   'aria-label'?: string;
-  /** Additional class name */
-  className?: string;
 }
 
-export interface HeaderNavItemProps {
+export interface HeaderNavItemProps extends Omit<React.HTMLAttributes<HTMLElement>, 'onClick'> {
   children: React.ReactNode;
   /** Whether this item is active/current */
   active?: boolean;
@@ -43,45 +53,35 @@ export interface HeaderNavItemProps {
   /** Render as child element (polymorphic) */
   asChild?: boolean;
   /** Click handler */
-  onClick?: () => void;
-  /** Additional class name */
-  className?: string;
+  onClick?: React.MouseEventHandler<HTMLElement>;
 }
 
-export interface HeaderSearchProps {
+export interface HeaderSearchProps extends React.HTMLAttributes<HTMLDivElement> {
   children: React.ReactNode;
   /** Whether search expands on mobile */
   expandable?: boolean;
-  /** Additional class name */
-  className?: string;
 }
 
-export interface HeaderActionsProps {
+export interface HeaderActionsProps extends React.HTMLAttributes<HTMLDivElement> {
   children: React.ReactNode;
-  /** Additional class name */
-  className?: string;
 }
 
-export interface HeaderTriggerProps {
+export interface HeaderTriggerProps extends React.ButtonHTMLAttributes<HTMLButtonElement> {
   /** Custom trigger content */
   children?: React.ReactNode;
   /** Accessible label */
   'aria-label'?: string;
-  /** Additional class name */
-  className?: string;
 }
 
-export interface HeaderNavMenuProps {
+export interface HeaderNavMenuProps extends React.HTMLAttributes<HTMLLIElement> {
   /** Trigger label text */
   label: string;
   /** Whether any child in the group is active */
   active?: boolean;
-  /** Additional class name */
-  className?: string;
   children: React.ReactNode;
 }
 
-export interface HeaderNavMenuItemProps {
+export interface HeaderNavMenuItemProps extends React.HTMLAttributes<HTMLElement> {
   children: React.ReactNode;
   /** Link destination */
   href?: string;
@@ -89,14 +89,34 @@ export interface HeaderNavMenuItemProps {
   active?: boolean;
   /** Render as child element (polymorphic) */
   asChild?: boolean;
-  /** Additional class name */
-  className?: string;
 }
 
 // ============================================
 // Hooks
 // ============================================
 
+const HeaderIconContext = React.createContext<HeaderIcons | undefined>(undefined);
+
+function useHeaderIcons(): HeaderIcons | undefined {
+  return React.useContext(HeaderIconContext);
+}
+
+function renderHeaderIcon(slot: HeaderIconSlot | undefined, state: HeaderIconRenderState): React.ReactNode {
+  if (slot === undefined) return undefined;
+  return typeof slot === 'function' ? slot(state) : slot;
+}
+
+function composeEventHandlers<E extends { defaultPrevented: boolean }>(
+  userHandler: ((event: E) => void) | undefined,
+  internalHandler: (event: E) => void,
+) {
+  return (event: E) => {
+    userHandler?.(event);
+    if (event.defaultPrevented) return;
+    internalHandler(event);
+  };
+}
+
 function useIsMobile() {
   const [isMobile, setIsMobile] = React.useState(false);
 
@@ -125,6 +145,7 @@ function HeaderRoot({
   children,
   height = '56px',
   position = 'static',
+  icons,
   className,
   style: styleProp,
   ...htmlProps
@@ -142,29 +163,31 @@ function HeaderRoot({
   } as React.CSSProperties;
 
   return (
-    <header {...htmlProps} className={classes} style={style} data-position={position}>
-      <div className={styles.container}>
-        {children}
-      </div>
-    </header>
+    <HeaderIconContext.Provider value={icons}>
+      <header {...htmlProps} className={classes} style={style} data-position={position}>
+        <div className={styles.container}>
+          {children}
+        </div>
+      </header>
+    </HeaderIconContext.Provider>
   );
 }
 
 /**
  * Header.Brand - Logo/brand slot
  */
-function HeaderBrand({ children, href, className }: HeaderBrandProps) {
+function HeaderBrand({ children, href, className, ...htmlProps }: HeaderBrandProps) {
   const classes = [styles.brand, className].filter(Boolean).join(' ');
 
   if (href) {
     return (
-      <a href={href} className={classes}>
+      <a {...htmlProps} href={href} className={classes}>
         {children}
       </a>
     );
   }
 
-  return <div className={classes}>{children}</div>;
+  return <div {...htmlProps} className={classes}>{children}</div>;
 }
 
 /**
@@ -174,11 +197,12 @@ function HeaderNav({
   children,
   'aria-label': ariaLabel = 'Main navigation',
   className,
+  ...htmlProps
 }: HeaderNavProps) {
   const classes = [styles.nav, className].filter(Boolean).join(' ');
 
   return (
-    <nav className={classes} aria-label={ariaLabel}>
+    <nav {...htmlProps} className={classes} aria-label={ariaLabel}>
       <ul className={styles.navList}>
         {children}
       </ul>
@@ -196,6 +220,7 @@ function HeaderNavItem({
   asChild = false,
   onClick,
   className,
+  ...htmlProps
 }: HeaderNavItemProps) {
   const classes = [
     styles.navItem,
@@ -210,11 +235,17 @@ function HeaderNavItem({
   };
 
   if (asChild && React.isValidElement(children)) {
+    const childProps = children.props as {
+      className?: string;
+      onClick?: React.MouseEventHandler<HTMLElement>;
+    };
     return (
       <li>
         {React.cloneElement(children, {
+          ...htmlProps,
           ...itemProps,
-          className: [classes, (children.props as { className?: string }).className].filter(Boolean).join(' '),
+          onClick: composeEventHandlers(childProps.onClick, onClick ?? (() => {})),
+          className: [classes, childProps.className].filter(Boolean).join(' '),
         } as React.HTMLAttributes<HTMLElement>)}
       </li>
     );
@@ -223,7 +254,7 @@ function HeaderNavItem({
   if (href) {
     return (
       <li>
-        <a {...itemProps} href={href}>
+        <a {...htmlProps} {...itemProps} href={href}>
           {children}
         </a>
       </li>
@@ -232,7 +263,7 @@ function HeaderNavItem({
 
   return (
     <li>
-      <button {...itemProps} type="button">
+      <button {...htmlProps} {...itemProps} type="button">
         {children}
       </button>
     </li>
@@ -246,6 +277,7 @@ function HeaderSearch({
   children,
   expandable = false,
   className,
+  ...htmlProps
 }: HeaderSearchProps) {
   const classes = [
     styles.search,
@@ -253,15 +285,15 @@ function HeaderSearch({
     className,
   ].filter(Boolean).join(' ');
 
-  return <div className={classes}>{children}</div>;
+  return <div {...htmlProps} className={classes}>{children}</div>;
 }
 
 /**
  * Header.Actions - Right-side actions container
  */
-function HeaderActions({ children, className }: HeaderActionsProps) {
+function HeaderActions({ children, className, ...htmlProps }: HeaderActionsProps) {
   const classes = [styles.actions, className].filter(Boolean).join(' ');
-  return <div className={classes}>{children}</div>;
+  return <div {...htmlProps} className={classes}>{children}</div>;
 }
 
 /**
@@ -271,9 +303,12 @@ function HeaderTrigger({
   children,
   'aria-label': ariaLabel = 'Toggle navigation',
   className,
+  onClick,
+  ...htmlProps
 }: HeaderTriggerProps) {
   const isMobile = useIsMobile();
   const { open, setOpen } = useSidebar();
+  const icons = useHeaderIcons();
 
   // Only render on mobile
   if (!isMobile) {
@@ -281,16 +316,20 @@ function HeaderTrigger({
   }
 
   const classes = [styles.trigger, className].filter(Boolean).join(' ');
+  const iconSlot = open ? icons?.close : icons?.menu;
+  const iconState: HeaderIconRenderState = { slot: open ? 'close' : 'menu', open };
+  const iconOverride = renderHeaderIcon(iconSlot, iconState);
 
   return (
     <button
+      {...htmlProps}
       type="button"
       className={classes}
-      onClick={() => setOpen(!open)}
+      onClick={composeEventHandlers(onClick, () => setOpen(!open))}
       aria-label={ariaLabel}
       aria-expanded={open}
     >
-      {children || (open ? <X size={24} aria-hidden /> : <List size={24} aria-hidden />)}
+      {children || iconOverride || (open ? <X size={24} aria-hidden /> : <List size={24} aria-hidden />)}
     </button>
   );
 }
@@ -311,20 +350,28 @@ function HeaderNavMenu({
   active = false,
   className,
   children,
+  ...htmlProps
 }: HeaderNavMenuProps) {
+  const icons = useHeaderIcons();
   const triggerClasses = [
     styles.navItem,
     styles.navMenuTrigger,
     active && styles.navItemActive,
     className,
   ].filter(Boolean).join(' ');
+  const chevronIcon = renderHeaderIcon(icons?.navMenuChevron, {
+    slot: 'navMenuChevron',
+    active,
+  });
 
   return (
-    <li>
+    <li {...htmlProps}>
       <BaseMenu.Root modal={false}>
         <BaseMenu.Trigger className={triggerClasses}>
           {label}
-          <CaretDown size={12} className={styles.navMenuChevron} aria-hidden />
+          {chevronIcon
+            ? <span className={styles.navMenuChevron} aria-hidden>{chevronIcon}</span>
+            : <CaretDown size={12} className={styles.navMenuChevron} aria-hidden />}
         </BaseMenu.Trigger>
         <BaseMenu.Portal>
           <BaseMenu.Positioner side="bottom" align="start" sideOffset={4} className={styles.navMenuPositioner}>
@@ -347,6 +394,7 @@ function HeaderNavMenuItem({
   active = false,
   asChild = false,
   className,
+  ...htmlProps
 }: HeaderNavMenuItemProps) {
   const classes = [
     styles.navMenuItem,
@@ -357,6 +405,7 @@ function HeaderNavMenuItem({
   if (asChild && React.isValidElement(children)) {
     return (
       <BaseMenu.Item
+        {...htmlProps}
         className={classes}
         render={children as React.ReactElement}
       />
@@ -365,14 +414,14 @@ function HeaderNavMenuItem({
 
   if (href) {
     return (
-      <BaseMenu.Item className={classes} render={<a href={href} />}>
+      <BaseMenu.Item {...htmlProps} className={classes} render={<a href={href} />}>
         {children}
       </BaseMenu.Item>
     );
   }
 
   return (
-    <BaseMenu.Item className={classes}>
+    <BaseMenu.Item {...htmlProps} className={classes}>
       {children}
     </BaseMenu.Item>
   );