@fragments-sdk/ui 0.13.0 → 0.15.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fragments-sdk/ui",
-  "version": "0.13.0",
+  "version": "0.15.1",
   "license": "MIT",
   "description": "Customizable UI components built on Base UI headless primitives",
   "author": "Conan McNicholl",
@@ -230,18 +230,26 @@
     "vite": "^6.0.0",
     "vitest": "^2.1.8",
     "vitest-axe": "^0.1.0",
-    "@fragments-sdk/cli": "0.10.1"
+    "@fragments-sdk/core": "0.3.0"
   },
   "files": [
     "src",
+    "!src/**/*.test.ts",
+    "!src/**/*.test.tsx",
+    "!src/test/",
+    "!src/**/*.fragment.tsx",
+    "!src/**/*.block.ts",
+    "!src/blocks/",
+    "!src/assets/*.svg",
     "dist",
     "fragments.json"
   ],
   "scripts": {
-    "dev": "node ../../packages/cli/dist/bin.js dev",
-    "build": "node ../../packages/cli/dist/bin.js build && vite build && tsc -p tsconfig.build.json",
+    "cli:ensure": "test -f ../../packages/cli/dist/bin.js || pnpm --filter @fragments-sdk/cli build",
+    "dev": "pnpm run cli:ensure && node ../../packages/cli/dist/bin.js dev",
+    "build": "pnpm run cli:ensure && node ../../packages/cli/dist/bin.js build && vite build && tsc -p tsconfig.build.json",
     "lint": "eslint src",
-    "validate": "node ../../packages/cli/dist/bin.js validate",
+    "validate": "pnpm run cli:ensure && node ../../packages/cli/dist/bin.js validate",
     "test": "vitest run"
   },
   "module": "dist/index.js"

package/src/components/Accordion/Accordion.module.scss

@@ -38,7 +38,7 @@
   align-items: center;
   justify-content: space-between;
   width: 100%;
-  padding: var(--fui-padding-item-sm, $fui-padding-item-sm) 0;
+  padding: var(--fui-space-2, $fui-space-2) 0;
   font-size: var(--fui-font-size-sm, $fui-font-size-sm);
   font-weight: var(--fui-font-weight-medium, $fui-font-weight-medium);
   color: var(--fui-text-primary, $fui-text-primary);
@@ -91,7 +91,7 @@
 }
 
 .contentInner {
-  padding-bottom: var(--fui-padding-item-xs, $fui-padding-item-xs);
+  padding-bottom: var(--fui-space-1, $fui-space-1);
   font-size: var(--fui-font-size-sm, $fui-font-size-sm);
   color: var(--fui-text-secondary, $fui-text-secondary);
   line-height: var(--fui-line-height-normal, $fui-line-height-normal);

package/src/components/Accordion/index.tsx

@@ -10,16 +10,8 @@ import styles from './Accordion.module.scss';
 
 export type AccordionValue = string | string[];
 
-export interface AccordionProps extends Omit<React.HTMLAttributes<HTMLDivElement>, 'defaultValue'> {
+interface AccordionSharedProps extends Omit<React.HTMLAttributes<HTMLDivElement>, 'defaultValue'> {
   children: React.ReactNode;
-  /** Allow multiple items to be open at once */
-  type?: 'single' | 'multiple';
-  /** Controlled value - string for single, string[] for multiple */
-  value?: AccordionValue;
-  /** Default value for uncontrolled usage */
-  defaultValue?: AccordionValue;
-  /** Callback when value changes */
-  onValueChange?: (value: AccordionValue | undefined) => void;
   /** Whether items can be fully collapsed (only for type="single") */
   collapsible?: boolean;
   /**
@@ -30,6 +22,30 @@ export interface AccordionProps extends Omit<React.HTMLAttributes<HTMLDivElement
   headingLevel?: 2 | 3 | 4 | 5 | 6;
 }
 
+export interface AccordionSingleProps extends AccordionSharedProps {
+  /** Allow multiple items to be open at once */
+  type?: 'single';
+  /** Controlled value for single mode */
+  value?: string;
+  /** Default value for uncontrolled usage */
+  defaultValue?: string;
+  /** Callback when value changes */
+  onValueChange?: (value: string | undefined) => void;
+}
+
+export interface AccordionMultipleProps extends AccordionSharedProps {
+  /** Allow multiple items to be open at once */
+  type: 'multiple';
+  /** Controlled values for multiple mode */
+  value?: string[];
+  /** Default values for uncontrolled usage */
+  defaultValue?: string[];
+  /** Callback when value changes */
+  onValueChange?: (value: string[]) => void;
+}
+
+export type AccordionProps = AccordionSingleProps | AccordionMultipleProps;
+
 export interface AccordionItemProps extends React.HTMLAttributes<HTMLDivElement> {
   children: React.ReactNode;
   /** Unique value for this item */
@@ -38,7 +54,7 @@ export interface AccordionItemProps extends React.HTMLAttributes<HTMLDivElement>
   disabled?: boolean;
 }
 
-export interface AccordionTriggerProps extends React.HTMLAttributes<HTMLButtonElement> {
+export interface AccordionTriggerProps extends React.ButtonHTMLAttributes<HTMLButtonElement> {
   children: React.ReactNode;
 }
 
@@ -136,8 +152,10 @@ function AccordionRoot({
       setOpenItems(newItems);
     }
 
-    if (onValueChange) {
-      onValueChange(type === 'single' ? newItems[0] : newItems);
+    if (type === 'single') {
+      (onValueChange as AccordionSingleProps['onValueChange'] | undefined)?.(newItems[0]);
+    } else {
+      (onValueChange as AccordionMultipleProps['onValueChange'] | undefined)?.(newItems);
     }
   }, [type, currentOpenItems, collapsible, controlledOpenItems, onValueChange]);
 
@@ -145,7 +163,7 @@ function AccordionRoot({
 
   return (
     <AccordionContext.Provider value={{ type, openItems: currentOpenItems, toggle, collapsible, headingLevel }}>
-      <div {...htmlProps} className={classes} data-orientation="vertical" role="region">
+      <div {...htmlProps} className={classes} data-orientation="vertical">
         {children}
       </div>
     </AccordionContext.Provider>
@@ -186,6 +204,7 @@ function AccordionItem({
 function AccordionTrigger({
   children,
   className,
+  type: buttonType,
   onClick,
   ...htmlProps
 }: AccordionTriggerProps) {
@@ -209,6 +228,7 @@ function AccordionTrigger({
     <HeadingTag className={styles.heading}>
       <BaseCollapsible.Trigger
         {...htmlProps}
+        type={buttonType ?? 'button'}
         id={triggerId}
         className={classes}
         onClick={handleClick}

package/src/components/Alert/Alert.module.scss

@@ -5,7 +5,7 @@
   display: flex;
   align-items: flex-start;
   gap: var(--fui-space-3, $fui-space-3);
-  padding: var(--fui-padding-inline-sm, $fui-padding-inline-sm) var(--fui-padding-inline-md, $fui-padding-inline-md);
+  padding: var(--fui-space-2, $fui-space-2) var(--fui-space-3, $fui-space-3);
   border-radius: var(--fui-radius-lg, $fui-radius-lg);
   font-family: var(--fui-font-sans, $fui-font-sans);
   font-size: var(--fui-font-size-sm, $fui-font-size-sm);

package/src/components/Alert/index.tsx

@@ -22,40 +22,33 @@ export interface AlertProps extends React.HTMLAttributes<HTMLDivElement> {
   severity?: AlertSeverity;
 }
 
-export interface AlertIconProps {
+export interface AlertIconProps extends React.HTMLAttributes<HTMLSpanElement> {
   children?: React.ReactNode;
-  className?: string;
 }
 
-export interface AlertTitleProps {
+export interface AlertTitleProps extends React.HTMLAttributes<HTMLDivElement> {
   children: React.ReactNode;
-  className?: string;
 }
 
-export interface AlertContentProps {
+export interface AlertContentProps extends React.HTMLAttributes<HTMLDivElement> {
   children: React.ReactNode;
-  className?: string;
 }
 
-export interface AlertActionsProps {
+export interface AlertActionsProps extends React.HTMLAttributes<HTMLDivElement> {
   children: React.ReactNode;
-  className?: string;
 }
 
-export interface AlertActionProps {
+export interface AlertActionProps extends Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, 'onClick'> {
   children: React.ReactNode;
-  onClick: () => void;
-  className?: string;
+  onClick?: React.MouseEventHandler<HTMLButtonElement>;
 }
 
-export interface AlertCloseProps {
+export interface AlertCloseProps extends Omit<React.ButtonHTMLAttributes<HTMLButtonElement>, 'children'> {
   children?: React.ReactNode;
-  className?: string;
 }
 
-export interface AlertBodyProps {
+export interface AlertBodyProps extends React.HTMLAttributes<HTMLDivElement> {
   children: React.ReactNode;
-  className?: string;
 }
 
 // ============================================
@@ -79,6 +72,17 @@ function useAlertContext() {
   return context;
 }
 
+function composeEventHandlers<E extends { defaultPrevented: boolean }>(
+  userHandler?: (event: E) => void,
+  internalHandler?: (event: E) => void
+) {
+  return (event: E) => {
+    userHandler?.(event);
+    if (event.defaultPrevented) return;
+    internalHandler?.(event);
+  };
+}
+
 // ============================================
 // Severity Icons
 // ============================================
@@ -136,64 +140,79 @@ function AlertRoot({
   );
 }
 
-function AlertIcon({ children, className }: AlertIconProps) {
+function AlertIcon({ children, className, ...htmlProps }: AlertIconProps) {
   const { severity } = useAlertContext();
   const classes = [styles.icon, className].filter(Boolean).join(' ');
 
   return (
-    <span className={classes} aria-hidden="true">
+    <span {...htmlProps} className={classes} aria-hidden="true">
       {children ?? severityIcons[severity]}
     </span>
   );
 }
 
-function AlertBody({ children, className }: AlertBodyProps) {
+function AlertBody({ children, className, ...htmlProps }: AlertBodyProps) {
   const classes = [styles.body, className].filter(Boolean).join(' ');
-  return <div className={classes}>{children}</div>;
+  return <div {...htmlProps} className={classes}>{children}</div>;
 }
 
-function AlertTitle({ children, className }: AlertTitleProps) {
+function AlertTitle({ children, className, ...htmlProps }: AlertTitleProps) {
   const { titleId } = useAlertContext();
   const classes = [styles.title, className].filter(Boolean).join(' ');
   return (
-    <div id={titleId} className={classes}>
+    <div {...htmlProps} id={htmlProps.id ?? titleId} className={classes}>
       {children}
     </div>
   );
 }
 
-function AlertContent({ children, className }: AlertContentProps) {
+function AlertContent({ children, className, ...htmlProps }: AlertContentProps) {
   const { descId } = useAlertContext();
   const classes = [styles.content, className].filter(Boolean).join(' ');
   return (
-    <div id={descId} className={classes}>
+    <div {...htmlProps} id={htmlProps.id ?? descId} className={classes}>
       {children}
     </div>
   );
 }
 
-function AlertActions({ children, className }: AlertActionsProps) {
+function AlertActions({ children, className, ...htmlProps }: AlertActionsProps) {
   const classes = [styles.actions, className].filter(Boolean).join(' ');
-  return <div className={classes}>{children}</div>;
+  return <div {...htmlProps} className={classes}>{children}</div>;
 }
 
-function AlertAction({ children, onClick, className }: AlertActionProps) {
+function AlertAction({
+  children,
+  onClick,
+  type = 'button',
+  className,
+  ...htmlProps
+}: AlertActionProps) {
   const classes = [styles.action, className].filter(Boolean).join(' ');
   return (
-    <BaseButton onClick={onClick} className={classes}>
+    <BaseButton {...htmlProps} onClick={onClick} type={type} className={classes}>
       {children}
     </BaseButton>
   );
 }
 
-function AlertClose({ children, className }: AlertCloseProps) {
+function AlertClose({
+  children,
+  className,
+  onClick,
+  type = 'button',
+  'aria-label': ariaLabel = 'Dismiss alert',
+  ...htmlProps
+}: AlertCloseProps) {
   const { dismiss } = useAlertContext();
   const classes = [styles.close, className].filter(Boolean).join(' ');
 
   return (
     <BaseButton
-      onClick={dismiss}
-      aria-label="Dismiss alert"
+      {...htmlProps}
+      onClick={composeEventHandlers(onClick, dismiss)}
+      type={type}
+      aria-label={ariaLabel}
       className={classes}
     >
       {children ?? '\u00D7'}

package/src/components/AppShell/AppShell.module.scss

@@ -173,22 +173,22 @@
 
 // Padding variants
 .paddingSm {
-  padding: var(--fui-padding-container-sm);
+  padding: var(--fui-space-3);
 }
 
 .paddingMd {
-  padding: var(--fui-padding-container-md);
+  padding: var(--fui-space-4);
 
   @include breakpoint-md {
-    padding: var(--fui-padding-container-lg);
+    padding: var(--fui-space-6);
   }
 }
 
 .paddingLg {
-  padding: var(--fui-padding-container-lg);
+  padding: var(--fui-space-6);
 
   @include breakpoint-md {
-    padding: var(--fui-padding-container-xl);
+    padding: var(--fui-space-8);
   }
 }
 

package/src/components/AppShell/index.tsx

@@ -190,6 +190,7 @@ function AppShellInner({
   children,
   className,
   layout,
+  style: styleProp,
   ...htmlProps
 }: {
   children: React.ReactNode;
@@ -221,6 +222,7 @@ function AppShellInner({
     '--appshell-sidebar-expanded-width': appShell.sidebarWidth,
     '--appshell-sidebar-collapsed-width': appShell.sidebarCollapsedWidth,
     '--appshell-aside-width': appShell.asideVisible ? appShell.asideWidth : '0px',
+    ...styleProp,
   } as React.CSSProperties;
 
   return (

package/src/components/Avatar/index.tsx

@@ -32,6 +32,11 @@ export interface AvatarProps extends Omit<React.HTMLAttributes<HTMLDivElement>,
   color?: string;
   /** Inline style for the underlying image element */
   imageStyle?: React.CSSProperties;
+  /** Additional props for the underlying img element */
+  imageProps?: Omit<
+    React.ImgHTMLAttributes<HTMLImageElement>,
+    'src' | 'alt' | 'className' | 'style'
+  >;
 }
 
 export interface AvatarGroupProps extends React.HTMLAttributes<HTMLDivElement> {
@@ -113,6 +118,7 @@ const AvatarBase = React.forwardRef<HTMLDivElement, AvatarProps>(
       shape = 'circle',
       color,
       imageStyle,
+      imageProps,
       className,
       style: styleProp,
       ...htmlProps
@@ -175,10 +181,16 @@ const AvatarBase = React.forwardRef<HTMLDivElement, AvatarProps>(
         {!showFallback && (
           <img
             ref={imgRef}
+            {...imageProps}
             src={src}
             alt={alt}
             className={styles.image}
-            onError={() => setImageError(true)}
+            onError={(event) => {
+              imageProps?.onError?.(event);
+              if (!event.defaultPrevented) {
+                setImageError(true);
+              }
+            }}
             style={{ ...imageStyle }}
           />
         )}

package/src/components/Badge/index.tsx

@@ -23,6 +23,9 @@ export interface BadgeProps extends React.HTMLAttributes<HTMLSpanElement> {
   icon?: React.ReactNode;
   /** Makes the badge removable. Called when dismiss button is clicked. */
   onRemove?: () => void;
+  /** Announce badge content as status to assistive tech (opt-in).
+   * @default false */
+  announce?: boolean;
 }
 
 const BadgeRoot = React.forwardRef<HTMLSpanElement, BadgeProps>(
@@ -34,8 +37,10 @@ const BadgeRoot = React.forwardRef<HTMLSpanElement, BadgeProps>(
       dot = false,
       icon,
       onRemove,
+      announce = false,
       className,
       'aria-label': ariaLabel,
+      role,
       ...htmlProps
     },
     ref
@@ -46,7 +51,7 @@ const BadgeRoot = React.forwardRef<HTMLSpanElement, BadgeProps>(
 
     // For status badges, include the status in the aria-label if not provided
     const effectiveAriaLabel = ariaLabel || (
-      variant !== 'default' && variant !== 'outline'
+      announce && variant !== 'default' && variant !== 'outline'
         ? `${variant}: ${typeof children === 'string' ? children : ''}`
         : undefined
     );
@@ -56,7 +61,7 @@ const BadgeRoot = React.forwardRef<HTMLSpanElement, BadgeProps>(
         ref={ref}
         {...htmlProps}
         className={classes}
-        role={effectiveAriaLabel ? 'status' : undefined}
+        role={role ?? (announce ? 'status' : undefined)}
         aria-label={effectiveAriaLabel}
       >
         {dot && <span className={styles.dot} aria-hidden="true" />}

package/src/components/BentoGrid/BentoGrid.module.scss

@@ -1,5 +1,5 @@
-@use '../../tokens/variables' as *;
-@use '../../tokens/mixins' as *;
+@use "../../tokens/variables" as *;
+@use "../../tokens/mixins" as *;
 
 // ============================================
 // BentoGrid Container
@@ -15,9 +15,15 @@
 // Column counts
 // ============================================
 
-.columns2 { grid-template-columns: repeat(2, 1fr); }
-.columns3 { grid-template-columns: repeat(3, 1fr); }
-.columns4 { grid-template-columns: repeat(4, 1fr); }
+.columns2 {
+  grid-template-columns: repeat(2, 1fr);
+}
+.columns3 {
+  grid-template-columns: repeat(3, 1fr);
+}
+.columns4 {
+  grid-template-columns: repeat(4, 1fr);
+}
 
 // ============================================
 // Responsive collapse
@@ -42,12 +48,24 @@
 // Gap
 // ============================================
 
-.gapNone { gap: 0; }
-.gapXs   { gap: var(--fui-space-1, $fui-space-1); }
-.gapSm   { gap: var(--fui-space-2, $fui-space-2); }
-.gapMd   { gap: var(--fui-space-4, $fui-space-4); }
-.gapLg   { gap: var(--fui-space-6, $fui-space-6); }
-.gapXl   { gap: var(--fui-space-8, $fui-space-8); }
+.gapNone {
+  gap: 0;
+}
+.gapXs {
+  gap: var(--fui-space-1, $fui-space-1);
+}
+.gapSm {
+  gap: var(--fui-space-2, $fui-space-2);
+}
+.gapMd {
+  gap: var(--fui-space-4, $fui-space-4);
+}
+.gapLg {
+  gap: var(--fui-space-6, $fui-space-6);
+}
+.gapXl {
+  gap: var(--fui-space-8, $fui-space-8);
+}
 
 // ============================================
 // BentoGrid Item
@@ -57,7 +75,7 @@
   @include surface-elevated;
 
   min-width: 0;
-  padding: var(--fui-padding-container-md, $fui-padding-container-md);
+  padding: var(--fui-space-2, $fui-space-2);
   transition:
     box-shadow var(--fui-transition-fast, $fui-transition-fast),
     border-color var(--fui-transition-fast, $fui-transition-fast),
@@ -87,13 +105,31 @@
   }
 
   @include breakpoint-lg {
-    --_col-span: var(--bento-col-span-lg, var(--bento-col-span-md, var(--bento-col-span-sm, var(--bento-col-span, 1))));
-    --_row-span: var(--bento-row-span-lg, var(--bento-row-span-md, var(--bento-row-span-sm, var(--bento-row-span, 1))));
+    --_col-span: var(
+      --bento-col-span-lg,
+      var(--bento-col-span-md, var(--bento-col-span-sm, var(--bento-col-span, 1)))
+    );
+    --_row-span: var(
+      --bento-row-span-lg,
+      var(--bento-row-span-md, var(--bento-row-span-sm, var(--bento-row-span, 1)))
+    );
   }
 
   @include breakpoint-xl {
-    --_col-span: var(--bento-col-span-xl, var(--bento-col-span-lg, var(--bento-col-span-md, var(--bento-col-span-sm, var(--bento-col-span, 1)))));
-    --_row-span: var(--bento-row-span-xl, var(--bento-row-span-lg, var(--bento-row-span-md, var(--bento-row-span-sm, var(--bento-row-span, 1)))));
+    --_col-span: var(
+      --bento-col-span-xl,
+      var(
+        --bento-col-span-lg,
+        var(--bento-col-span-md, var(--bento-col-span-sm, var(--bento-col-span, 1)))
+      )
+    );
+    --_row-span: var(
+      --bento-row-span-xl,
+      var(
+        --bento-row-span-lg,
+        var(--bento-row-span-md, var(--bento-row-span-sm, var(--bento-row-span, 1)))
+      )
+    );
   }
 }
 
@@ -121,3 +157,23 @@
     border-color: var(--fui-text-primary, $fui-text-primary);
   }
 }
+
+// ============================================
+// Subgrid — item children align to parent tracks
+// ============================================
+
+.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/BentoGrid/index.tsx

@@ -20,26 +20,28 @@ export interface ResponsiveSpan {
   xl?: SpanValue;
 }
 
-export interface BentoGridProps {
+export interface BentoGridProps extends React.HTMLAttributes<HTMLDivElement> {
   children?: React.ReactNode;
   /** Number of columns (default: 3) — auto-collapses responsively */
   columns?: 2 | 3 | 4;
   /** Gap between grid items */
   gap?: 'none' | 'xs' | 'sm' | 'md' | 'lg' | 'xl';
-  /** Additional class name */
-  className?: string;
-  /** Inline styles */
-  style?: React.CSSProperties;
 }
 
-export interface BentoGridItemProps {
+export interface BentoGridItemProps extends React.HTMLAttributes<HTMLDivElement> {
   children?: React.ReactNode;
   /** Columns to span — number for all breakpoints, object for per-breakpoint */
   colSpan?: SpanValue | ResponsiveSpan;
   /** Rows to span — number for all breakpoints, object for per-breakpoint */
   rowSpan?: SpanValue | ResponsiveSpan;
-  /** Additional class name */
-  className?: string;
+  /**
+   * 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';
 }
 
 // ============================================
@@ -82,6 +84,7 @@ export const BentoGrid = React.forwardRef<HTMLDivElement, BentoGridProps>(
       gap = 'md',
       className,
       style,
+      ...htmlProps
     },
     ref
   ) {
@@ -95,7 +98,7 @@ export const BentoGrid = React.forwardRef<HTMLDivElement, BentoGridProps>(
       .join(' ');
 
     return (
-      <div ref={ref} className={classes} style={style}>
+      <div ref={ref} {...htmlProps} className={classes} style={style}>
         {children}
       </div>
     );
@@ -106,13 +109,22 @@ export const BentoGrid = React.forwardRef<HTMLDivElement, BentoGridProps>(
 // BentoGrid.Item Sub-component
 // ============================================
 
+const subgridClasses: Record<string, string> = {
+  rows: styles.subgridRows,
+  columns: styles.subgridColumns,
+  both: styles.subgridBoth,
+};
+
 const BentoGridItem = React.forwardRef<HTMLDivElement, BentoGridItemProps>(
   function BentoGridItem(
     {
       children,
       colSpan,
       rowSpan,
+      subgrid,
       className,
+      style,
+      ...htmlProps
     },
     ref
   ) {
@@ -123,13 +135,17 @@ const BentoGridItem = React.forwardRef<HTMLDivElement, BentoGridItemProps>(
 
     const hasVars = Object.keys(spanVars).length > 0;
     const inlineStyle = hasVars
-      ? (spanVars as unknown as React.CSSProperties)
+      ? ({ ...(spanVars as unknown as React.CSSProperties), ...style } as React.CSSProperties)
+      : style;
+
+    const subgridClass = subgrid
+      ? subgridClasses[subgrid === true ? 'rows' : subgrid]
       : undefined;
 
-    const classes = [styles.item, className].filter(Boolean).join(' ');
+    const classes = [styles.item, subgridClass, className].filter(Boolean).join(' ');
 
     return (
-      <div ref={ref} className={classes} style={inlineStyle}>
+      <div ref={ref} {...htmlProps} className={classes} style={inlineStyle}>
         {children}
       </div>
     );