@fragments-sdk/ui 0.13.0 → 0.14.0

package/src/components/Popover/index.tsx

@@ -25,10 +25,15 @@ export interface PopoverProps {
   modal?: boolean;
 }
 
-export interface PopoverTriggerProps extends React.ButtonHTMLAttributes<HTMLButtonElement> {
+type PopoverTriggerAsButtonProps = React.ButtonHTMLAttributes<HTMLButtonElement> & {
   children: React.ReactNode;
-  asChild?: boolean;
-}
+  asChild?: false;
+};
+type PopoverTriggerAsChildProps = Omit<React.HTMLAttributes<HTMLElement>, 'children'> & {
+  children: React.ReactElement;
+  asChild: true;
+};
+export type PopoverTriggerProps = PopoverTriggerAsButtonProps | PopoverTriggerAsChildProps;
 
 export interface PopoverContentProps extends React.HTMLAttributes<HTMLDivElement> {
   children: React.ReactNode;
@@ -55,10 +60,15 @@ export interface PopoverFooterProps extends React.HTMLAttributes<HTMLDivElement>
   children: React.ReactNode;
 }
 
-export interface PopoverCloseProps extends React.ButtonHTMLAttributes<HTMLButtonElement> {
+type PopoverCloseAsButtonProps = React.ButtonHTMLAttributes<HTMLButtonElement> & {
   children?: React.ReactNode;
-  asChild?: boolean;
-}
+  asChild?: false;
+};
+type PopoverCloseAsChildProps = Omit<React.HTMLAttributes<HTMLElement>, 'children'> & {
+  children: React.ReactElement;
+  asChild: true;
+};
+export type PopoverCloseProps = PopoverCloseAsButtonProps | PopoverCloseAsChildProps;
 
 // ============================================
 // Icons
@@ -109,6 +119,9 @@ function PopoverRoot({
 
 function PopoverTrigger({ children, asChild, className, ...htmlProps }: PopoverTriggerProps) {
   if (asChild) {
+    if (!React.isValidElement(children)) {
+      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}>
         {null}
@@ -117,7 +130,11 @@ function PopoverTrigger({ children, asChild, className, ...htmlProps }: PopoverT
   }
 
   return (
-    <BasePopover.Trigger {...htmlProps} className={className}>
+    <BasePopover.Trigger
+      {...htmlProps}
+      type={(htmlProps as React.ButtonHTMLAttributes<HTMLButtonElement>).type ?? 'button'}
+      className={className}
+    >
       {children}
     </BasePopover.Trigger>
   );
@@ -186,6 +203,7 @@ function PopoverClose({ children, asChild, className, ...htmlProps }: PopoverClo
     return (
       <BasePopover.Close
         {...htmlProps}
+        type={(htmlProps as React.ButtonHTMLAttributes<HTMLButtonElement>).type ?? 'button'}
         aria-label="Close popover"
         className={[styles.close, className].filter(Boolean).join(' ')}
       >
@@ -195,6 +213,9 @@ function PopoverClose({ children, asChild, className, ...htmlProps }: PopoverClo
   }
 
   if (asChild) {
+    if (!React.isValidElement(children)) {
+      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}>
         {null}
@@ -203,7 +224,11 @@ function PopoverClose({ children, asChild, className, ...htmlProps }: PopoverClo
   }
 
   return (
-    <BasePopover.Close {...htmlProps} className={className}>
+    <BasePopover.Close
+      {...htmlProps}
+      type={(htmlProps as React.ButtonHTMLAttributes<HTMLButtonElement>).type ?? 'button'}
+      className={className}
+    >
       {children}
     </BasePopover.Close>
   );

package/src/components/Progress/Progress.fragment.tsx

@@ -1,5 +1,5 @@
 import React from 'react';
-import { defineFragment } from '@fragments-sdk/cli/core';
+import { defineFragment } from '@fragments-sdk/core';
 import { Progress, CircularProgress } from '.';
 
 export default defineFragment({
@@ -31,6 +31,7 @@ export default defineFragment({
       'Use indeterminate for unknown durations',
       'Include a label for context when the purpose isnt obvious',
       'Use appropriate color variants for success/warning/danger states',
+      'Determinate values are clamped to the min/max range for display',
     ],
     accessibility: [
       'Uses role="progressbar" with aria-valuenow',
@@ -93,6 +94,7 @@ export default defineFragment({
       'variant: default|success|warning|danger - color',
       'label: string - descriptive label',
       'showValue: boolean - display percentage',
+      'Determinate display values are clamped (and invalid min/max ranges render as 0%)',
     ],
     scenarioTags: [
       'feedback.progress',

package/src/components/Progress/Progress.test.tsx

@@ -43,6 +43,14 @@ describe('Progress', () => {
     const { container } = render(<Progress value={60} label="Loading" />);
     await expectNoA11yViolations(container);
   });
+
+  it('clamps displayed percentage and handles invalid ranges safely', () => {
+    const { rerender } = render(<Progress value={150} showValue />);
+    expect(screen.getByText('100%')).toBeInTheDocument();
+
+    rerender(<Progress value={50} min={100} max={100} showValue />);
+    expect(screen.getByText('0%')).toBeInTheDocument();
+  });
 });
 
 describe('CircularProgress', () => {

package/src/components/Progress/index.tsx

@@ -59,7 +59,15 @@ function ProgressRoot({
   ...htmlProps
 }: ProgressProps) {
   const isIndeterminate = value === null;
-  const percentage = isIndeterminate ? 0 : Math.round(((value - min) / (max - min)) * 100);
+  const range = max - min;
+  const normalizedPercentage = isIndeterminate
+    ? 0
+    : range <= 0
+      ? 0
+      : ((value - min) / range) * 100;
+  const percentage = isIndeterminate
+    ? 0
+    : Math.round(Math.min(100, Math.max(0, normalizedPercentage)));
 
   const trackClasses = [
     styles.track,

package/src/components/Prompt/Prompt.fragment.tsx

@@ -1,5 +1,5 @@
 import React from 'react';
-import { defineFragment } from '@fragments-sdk/cli/core';
+import { defineFragment } from '@fragments-sdk/core';
 import { Prompt } from '.';
 
 export default defineFragment({
@@ -27,6 +27,8 @@ export default defineFragment({
     guidelines: [
       'Always provide an onSubmit handler',
       'Use loading state during API calls',
+      'Prompt.Textarea forwards native textarea props (autoComplete, inputMode, aria-*, data-*, handlers)',
+      'Prompt.Textarea composes your onChange/onKeyDown handlers with built-in submit and auto-resize behavior',
       'Consider showing usage/token limits for AI contexts',
     ],
     accessibility: [
@@ -123,6 +125,7 @@ export default defineFragment({
       'loading: boolean - shows loading state',
       'minRows/maxRows: number - row constraints (default: 1/8)',
       'submitOnEnter: boolean - Enter key behavior (default: true)',
+      'Prompt.Textarea accepts native textarea props and optional aria-label override',
     ],
     scenarioTags: [
       'form.prompt',

package/src/components/Prompt/Prompt.module.scss

@@ -60,7 +60,7 @@
   display: block;
   width: 100%;
   min-height: 2.857rem; // ~40px
-  padding: var(--fui-padding-inline-sm) var(--fui-padding-inline-md);
+  padding: var(--fui-space-2) var(--fui-space-3);
   background: transparent;
   border: none;
   resize: none;
@@ -90,7 +90,7 @@
   align-items: center;
   justify-content: space-between;
   gap: var(--fui-space-2, $fui-space-2);
-  padding: var(--fui-padding-item-xs) var(--fui-padding-item-sm);
+  padding: var(--fui-space-1) var(--fui-space-2);
   background-color: var(--fui-bg-secondary, $fui-bg-secondary);
   border-top: 1px solid var(--fui-border, $fui-border);
 }
@@ -155,7 +155,7 @@
   display: flex;
   align-items: center;
   gap: var(--fui-space-1, $fui-space-1);
-  padding: var(--fui-padding-item-xs) var(--fui-padding-item-sm);
+  padding: var(--fui-space-1) var(--fui-space-2);
   border-radius: var(--fui-radius-md, $fui-radius-md);
   background-color: transparent;
   color: var(--fui-text-secondary, $fui-text-secondary);

package/src/components/Prompt/Prompt.test.tsx

@@ -34,6 +34,25 @@ describe('Prompt', () => {
     expect(screen.getByPlaceholderText('Type here...')).toBeInTheDocument();
   });
 
+  it('forwards textarea props and composes textarea handlers', async () => {
+    const user = userEvent.setup();
+    const onKeyDown = vi.fn();
+    const onChange = vi.fn();
+
+    render(
+      <Prompt defaultValue="" onSubmit={() => {}}>
+        <Prompt.Textarea data-testid="prompt-textarea" onKeyDown={onKeyDown} onChange={onChange} />
+        <Prompt.Submit />
+      </Prompt>
+    );
+
+    const textarea = screen.getByTestId('prompt-textarea');
+    await user.type(textarea, 'Hi');
+    expect(onChange).toHaveBeenCalled();
+    await user.keyboard('{Enter}');
+    expect(onKeyDown).toHaveBeenCalled();
+  });
+
   it('renders compound sub-components (Toolbar, Actions)', () => {
     renderPrompt();
     expect(screen.getByRole('button', { name: /attach file/i })).toBeInTheDocument();

package/src/components/Prompt/index.tsx

@@ -38,10 +38,16 @@ export interface PromptProps extends Omit<React.HTMLAttributes<HTMLDivElement>,
   variant?: PromptVariant;
 }
 
-export interface PromptTextareaProps {
+export interface PromptTextareaProps extends Omit<
+  React.TextareaHTMLAttributes<HTMLTextAreaElement>,
+  'value' | 'defaultValue' | 'onChange' | 'rows' | 'disabled' | 'children'
+> {
   /** Override placeholder from context */
   placeholder?: string;
-  className?: string;
+  /** Composed with internal state update logic */
+  onChange?: React.ChangeEventHandler<HTMLTextAreaElement>;
+  /** Composed with internal submit-on-enter logic */
+  onKeyDown?: React.KeyboardEventHandler<HTMLTextAreaElement>;
 }
 
 export interface PromptToolbarProps {
@@ -64,7 +70,7 @@ export interface PromptActionButtonProps {
   /** Accessible label for the button */
   'aria-label': string;
   /** Click handler */
-  onClick?: () => void;
+  onClick?: React.MouseEventHandler<HTMLButtonElement>;
   /** Disabled state */
   disabled?: boolean;
   className?: string;
@@ -73,7 +79,7 @@ export interface PromptActionButtonProps {
 export interface PromptModeButtonProps {
   children: React.ReactNode;
   /** Click handler */
-  onClick?: () => void;
+  onClick?: React.MouseEventHandler<HTMLButtonElement>;
   /** Whether this mode is currently active */
   active?: boolean;
   /** Disabled state */
@@ -239,7 +245,14 @@ function PromptRoot({
   );
 }
 
-function PromptTextarea({ placeholder: overridePlaceholder, className }: PromptTextareaProps) {
+function PromptTextarea({
+  placeholder: overridePlaceholder,
+  className,
+  onChange,
+  onKeyDown,
+  'aria-label': ariaLabel,
+  ...htmlProps
+}: PromptTextareaProps) {
   const {
     value,
     setValue,
@@ -280,10 +293,14 @@ function PromptTextarea({ placeholder: overridePlaceholder, className }: PromptT
   }, [value, adjustHeight]);
 
   const handleChange = (e: React.ChangeEvent<HTMLTextAreaElement>) => {
+    onChange?.(e);
+    if (e.defaultPrevented) return;
     setValue(e.target.value);
   };
 
   const handleKeyDown = (e: React.KeyboardEvent<HTMLTextAreaElement>) => {
+    onKeyDown?.(e);
+    if (e.defaultPrevented) return;
     if (submitOnEnter && e.key === 'Enter' && !e.shiftKey) {
       e.preventDefault();
       handleSubmit();
@@ -295,6 +312,7 @@ function PromptTextarea({ placeholder: overridePlaceholder, className }: PromptT
   return (
     <textarea
       ref={textareaRef}
+      {...htmlProps}
       className={classes}
       value={value}
       onChange={handleChange}
@@ -302,7 +320,7 @@ function PromptTextarea({ placeholder: overridePlaceholder, className }: PromptT
       placeholder={overridePlaceholder ?? placeholder}
       disabled={disabled || loading}
       rows={minRows}
-      aria-label={overridePlaceholder ?? placeholder}
+      aria-label={ariaLabel ?? overridePlaceholder ?? placeholder}
     />
   );
 }

package/src/components/RadioGroup/RadioGroup.fragment.tsx

@@ -1,5 +1,5 @@
 import React from 'react';
-import { defineFragment } from '@fragments-sdk/cli/core';
+import { defineFragment } from '@fragments-sdk/core';
 import { RadioGroup } from '.';
 
 export default defineFragment({
@@ -57,6 +57,10 @@ export default defineFragment({
       type: 'function',
       description: 'Callback when selection changes',
     },
+    onChange: {
+      type: 'function',
+      description: 'Alias for onValueChange',
+    },
     orientation: {
       type: 'enum',
       values: ['horizontal', 'vertical'],
@@ -82,6 +86,14 @@ export default defineFragment({
       type: 'string',
       description: 'Error message',
     },
+    wrapperClassName: {
+      type: 'string',
+      description: 'Class name for the outer wrapper element',
+    },
+    groupClassName: {
+      type: 'string',
+      description: 'Class name for the inner radio group element',
+    },
   },
 
   relations: [
@@ -106,9 +118,12 @@ export default defineFragment({
     propsSummary: [
       'value: string - selected value',
       'onValueChange: (value: string) => void',
+      'onChange: (value: string) => void - alias for onValueChange',
       'orientation: horizontal|vertical (default: vertical)',
       'size: sm|md|lg (default: md)',
       'disabled: boolean - disable all options',
+      'wrapperClassName/groupClassName - explicit styling targets for wrapper and group',
+      'RadioGroup.Item supports controlClassName/contentClassName for item-level styling',
     ],
     scenarioTags: [
       'form.selection',
@@ -190,5 +205,20 @@ export default defineFragment({
         </RadioGroup>
       ),
     },
+    {
+      name: 'Styling Targets',
+      description: 'Use explicit class names for wrapper/group/item styling hooks',
+      render: () => (
+        <RadioGroup
+          defaultValue="a"
+          label="Display mode"
+          wrapperClassName="demo-radio-wrapper"
+          groupClassName="demo-radio-group"
+        >
+          <RadioGroup.Item value="a" label="Compact" controlClassName="demo-radio-control" contentClassName="demo-radio-content" />
+          <RadioGroup.Item value="b" label="Comfortable" />
+        </RadioGroup>
+      ),
+    },
   ],
 });

package/src/components/RadioGroup/index.tsx

@@ -20,6 +20,8 @@ export interface RadioGroupProps extends Omit<React.HTMLAttributes<HTMLDivElemen
   defaultValue?: string;
   /** Callback when value changes */
   onValueChange?: (value: string) => void;
+  /** Alias for onValueChange */
+  onChange?: (value: string) => void;
   /** Orientation of the radio group */
   orientation?: 'horizontal' | 'vertical';
   /** Whether the group is disabled */
@@ -32,6 +34,10 @@ export interface RadioGroupProps extends Omit<React.HTMLAttributes<HTMLDivElemen
   error?: string;
   /** Size variant */
   size?: 'sm' | 'md' | 'lg';
+  /** Class applied to the outer wrapper (label + group + error) */
+  wrapperClassName?: string;
+  /** Class applied to the inner radio group container */
+  groupClassName?: string;
   /** Children (Radio.Item components) */
   children: React.ReactNode;
 }
@@ -53,6 +59,10 @@ export interface RadioItemProps {
   'aria-describedby'?: string;
   /** Additional class name */
   className?: string;
+  /** Class applied directly to the radio control */
+  controlClassName?: string;
+  /** Class applied to the item text content wrapper */
+  contentClassName?: string;
 }
 
 function mergeAriaIds(...ids: Array<string | undefined>): string | undefined {
@@ -79,6 +89,8 @@ function RadioItem({
   'aria-labelledby': ariaLabelledBy,
   'aria-describedby': ariaDescribedBy,
   className,
+  controlClassName,
+  contentClassName,
 }: RadioItemProps) {
   const size = React.useContext(RadioSizeContext);
   const id = React.useId();
@@ -89,6 +101,7 @@ function RadioItem({
     styles.radio,
     size === 'sm' && styles.radioSm,
     size === 'lg' && styles.radioLg,
+    controlClassName,
   ].filter(Boolean).join(' ');
 
   const labelClasses = [
@@ -131,7 +144,7 @@ function RadioItem({
       >
         <BaseRadio.Indicator className={styles.indicator} />
       </BaseRadio.Root>
-      <div className={styles.content}>
+      <div className={[styles.content, contentClassName].filter(Boolean).join(' ')}>
         <span id={labelId} className={labelClasses}>{label}</span>
         {description && (
           <span id={descriptionId} className={styles.description}>{description}</span>
@@ -149,12 +162,15 @@ function RadioGroupRoot({
   value,
   defaultValue,
   onValueChange,
+  onChange,
   orientation = 'vertical',
   disabled = false,
   name,
   label,
   error,
   size = 'md',
+  wrapperClassName,
+  groupClassName,
   children,
   className,
   'aria-label': ariaLabel,
@@ -170,16 +186,19 @@ function RadioGroupRoot({
     styles.group,
     styles[orientation],
     className,
+    groupClassName,
   ].filter(Boolean).join(' ');
 
+  const handleValueChange = onChange ?? onValueChange;
+
   return (
     <RadioSizeContext.Provider value={size}>
-      <div {...htmlProps} className={styles.wrapper}>
+      <div {...htmlProps} className={[styles.wrapper, wrapperClassName].filter(Boolean).join(' ')}>
         {label && <span id={labelId} className={styles.groupLabel}>{label}</span>}
         <BaseRadioGroup
           value={value}
           defaultValue={defaultValue}
-          onValueChange={onValueChange}
+          onValueChange={handleValueChange}
           disabled={disabled}
           name={name}
           aria-label={ariaLabel}

package/src/components/ScrollArea/ScrollArea.fragment.tsx

@@ -1,5 +1,5 @@
 import React from 'react';
-import { defineFragment } from '@fragments-sdk/cli/core';
+import { defineFragment } from '@fragments-sdk/core';
 import { ScrollArea } from '.';
 
 const tags = ['Tag 1', 'Tag 2', 'Tag 3', 'Tag 4', 'Tag 5', 'Tag 6', 'Tag 7', 'Tag 8', 'Tag 9', 'Tag 10', 'Tag 11', 'Tag 12', 'Tag 13', 'Tag 14', 'Tag 15'];

package/src/components/Select/Select.fragment.tsx

@@ -1,5 +1,5 @@
 import React, { useState } from 'react';
-import { defineFragment } from '@fragments-sdk/cli/core';
+import { defineFragment } from '@fragments-sdk/core';
 import { Select } from '.';
 
 // Stateful wrapper for interactive demos
@@ -72,6 +72,10 @@ export default defineFragment({
       type: 'function',
       description: 'Called when selection changes',
     },
+    onChange: {
+      type: 'function',
+      description: 'Alias for onValueChange',
+    },
     open: {
       type: 'boolean',
       description: 'Controlled open state of the dropdown',
@@ -94,6 +98,10 @@ export default defineFragment({
       description: 'Disable the select',
       default: 'false',
     },
+    options: {
+      type: 'array',
+      description: 'Convenience options array for simple selects (alternative to compound Select.Item children)',
+    },
   },
 
   relations: [
@@ -104,10 +112,12 @@ export default defineFragment({
 
   contract: {
     propsSummary: [
-      'value: string - controlled selected value',
-      'onValueChange: (value) => void - selection handler',
+      'value: string | null - controlled selected value',
+      'onValueChange: (value: string | null) => void - selection handler',
+      'onChange: (value: string | null) => void - alias for onValueChange',
       'placeholder: string - placeholder text',
       'disabled: boolean - disable select',
+      'options: SelectOption[] - convenience API for simple option lists',
       'maxVisibleItems: number - max visible options before scrolling (default 4)',
     ],
     scenarioTags: [
@@ -234,5 +244,22 @@ export default defineFragment({
         </Select>
       ),
     },
+    {
+      name: 'Options Prop',
+      description: 'Convenience API for simple lists without manual Select.Item composition',
+      render: () => (
+        <StatefulSelect
+          placeholder="Select a team"
+          options={[
+            { value: 'eng', label: 'Engineering' },
+            { value: 'design', label: 'Design' },
+            { value: 'pm', label: 'Product' },
+          ]}
+        >
+          <Select.Trigger />
+          <Select.Content />
+        </StatefulSelect>
+      ),
+    },
   ],
 });

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

@@ -96,7 +96,7 @@
     var(--fui-space-1, #{$fui-space-1}) * 2
   ) !important;
   overflow-y: auto !important;
-  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);
 
   // Animation
@@ -128,7 +128,7 @@
   align-items: center;
   gap: var(--fui-space-2, $fui-space-2);
   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);
   cursor: pointer;
   outline: none;
@@ -178,7 +178,7 @@
 
 // Group label
 .groupLabel {
-  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);
   font-size: var(--fui-font-size-xs, $fui-font-size-xs);
   font-weight: var(--fui-font-weight-medium, $fui-font-weight-medium);
   color: var(--fui-text-tertiary, $fui-text-tertiary);