@bubbasfw/ui 0.0.0-stage → 0.2.0

package/src/components/Button.tsx

@@ -0,0 +1,105 @@
+'use client';
+
+import { forwardRef, type ElementRef, type ReactNode } from 'react';
+import { ActivityIndicator, Pressable, Text, type PressableProps } from 'react-native';
+import { cn, focusRing } from '../internal/utils';
+import { useTheme } from '../theme';
+
+export type ButtonVariant = 'primary' | 'secondary' | 'outline' | 'ghost';
+export type ButtonSize = 'sm' | 'md' | 'lg';
+
+export interface ButtonProps extends Omit<PressableProps, 'children' | 'className'> {
+  /** Text content, or inline React Native Text content. */
+  children: ReactNode;
+  variant?: ButtonVariant;
+  size?: ButtonSize;
+  loading?: boolean;
+  loadingLabel?: string;
+  className?: string;
+  textClassName?: string;
+}
+
+const containerVariants: Record<ButtonVariant, string> = {
+  primary: 'border-ui-action-border bg-bubba-red',
+  secondary: 'border-ui-border bg-ui-selected',
+  outline: 'border-ui-border bg-transparent',
+  ghost: 'border-transparent bg-transparent',
+};
+const textVariants: Record<ButtonVariant, string> = {
+  primary: 'text-ui-action-text',
+  secondary: 'text-ui-text',
+  outline: 'text-ui-text',
+  ghost: 'text-ui-link',
+};
+const containerSizes: Record<ButtonSize, string> = {
+  sm: 'min-h-[44px] px-3 py-2',
+  md: 'min-h-[48px] px-5 py-3',
+  lg: 'min-h-[56px] px-6 py-4',
+};
+const textSizes: Record<ButtonSize, string> = {
+  sm: 'text-sm',
+  md: 'text-base',
+  lg: 'text-lg',
+};
+
+/** One native Pressable and Text implementation on iOS, Android, and web. */
+export const Button = forwardRef<ElementRef<typeof Pressable>, ButtonProps>(
+  function Button(
+    {
+      children,
+      variant = 'primary',
+      size = 'md',
+      loading = false,
+      loadingLabel,
+      disabled = false,
+      className,
+      textClassName,
+      accessibilityState,
+      'aria-busy': ariaBusy,
+      'aria-disabled': ariaDisabled,
+      ...props
+    },
+    ref,
+  ) {
+    const { colors } = useTheme();
+    const explicitlyDisabled = disabled || (ariaDisabled ?? accessibilityState?.disabled ?? false);
+    const isDisabled = explicitlyDisabled || loading;
+    const isBusy = loading || (ariaBusy ?? accessibilityState?.busy ?? false);
+    const spinnerColor = explicitlyDisabled
+      ? colors['disabled-text']
+      : variant === 'primary' ? colors['action-text'] : colors.text;
+
+    return (
+      <Pressable
+        {...props}
+        ref={ref}
+        accessibilityRole="button"
+        accessibilityState={{ ...accessibilityState, disabled: isDisabled, busy: isBusy }}
+        aria-busy={isBusy}
+        aria-disabled={isDisabled}
+        disabled={isDisabled}
+        className={cn(
+          'min-w-[44px] flex-row items-center justify-center gap-2 rounded-[4px] border active:opacity-80',
+          focusRing,
+          containerVariants[variant],
+          containerSizes[size],
+          explicitlyDisabled && 'border-ui-disabled-surface bg-ui-disabled-surface',
+          className,
+        )}
+      >
+        {loading ? <ActivityIndicator size="small" color={spinnerColor} accessible={false} /> : null}
+        <Text
+          className={cn(
+            'font-bold text-center',
+            textVariants[variant],
+            textSizes[size],
+            explicitlyDisabled && 'text-ui-disabled-text',
+            textClassName,
+          )}
+        >
+          {loading && loadingLabel ? loadingLabel : children}
+        </Text>
+      </Pressable>
+    );
+  },
+);

package/src/components/actions.tsx

@@ -0,0 +1,39 @@
+'use client';
+
+import { forwardRef, type ElementRef, type ReactNode } from 'react';
+import { Linking, Platform, Pressable, type PressableProps } from 'react-native';
+import { cn, focusRing } from '../internal/utils';
+import { Text } from './typography';
+
+export interface IconButtonProps extends Omit<PressableProps, 'children' | 'accessibilityLabel'> {
+  accessibilityLabel: string;
+  children: ReactNode;
+  variant?: 'primary' | 'outline' | 'ghost';
+  className?: string;
+}
+const iconVariants = { primary: 'bg-bubba-red border-bubba-red', outline: 'border-ui-border bg-transparent', ghost: 'border-transparent bg-transparent' };
+export const IconButton = forwardRef<ElementRef<typeof Pressable>, IconButtonProps>(function IconButton({ accessibilityLabel, children, variant = 'ghost', className, disabled, accessibilityState, 'aria-disabled': ariaDisabled, ...props }, ref) {
+  const isDisabled = disabled || (ariaDisabled ?? accessibilityState?.disabled ?? false);
+  return <Pressable {...props} ref={ref} accessibilityRole="button" accessibilityLabel={accessibilityLabel} disabled={isDisabled} aria-disabled={isDisabled} accessibilityState={{ ...accessibilityState, disabled: isDisabled }} className={cn('h-12 w-12 items-center justify-center rounded border active:opacity-80', focusRing, iconVariants[variant], isDisabled && 'opacity-50', className)}>{children}</Pressable>;
+});
+
+export interface LinkProps extends Omit<PressableProps, 'children'> {
+  href: string;
+  children: ReactNode;
+  external?: boolean;
+  className?: string;
+  textClassName?: string;
+  /** Called when the operating system cannot open a native URL. */
+  onOpenError?: (error: unknown) => void;
+}
+type WebLinkProps = PressableProps & { href?: string; hrefAttrs?: { target?: string; rel?: string } };
+const LinkPressable = Pressable as typeof Pressable & ((props: WebLinkProps) => ReactNode);
+
+export const Link = forwardRef<ElementRef<typeof Pressable>, LinkProps>(function Link({ href, children, external = false, className, textClassName, disabled, onPress, onOpenError, accessibilityState, 'aria-disabled': ariaDisabled, ...props }, ref) {
+  const isDisabled = disabled || (ariaDisabled ?? accessibilityState?.disabled ?? false);
+  const webProps = Platform.OS === 'web' && !isDisabled ? { href, hrefAttrs: external ? { target: '_blank', rel: 'noopener noreferrer' } : undefined } : {};
+  return <LinkPressable {...props} {...webProps} ref={ref} accessibilityRole="link" disabled={isDisabled} aria-disabled={isDisabled} accessibilityState={{ ...accessibilityState, disabled: isDisabled }} className={cn('min-h-[44px] min-w-[44px] justify-center self-start', focusRing, isDisabled && 'opacity-50', className)} onPress={(event) => {
+    onPress?.(event);
+    if (Platform.OS !== 'web' && !event.isDefaultPrevented()) void Linking.openURL(href).catch((error: unknown) => onOpenError?.(error));
+  }}><Text className={cn('text-ui-link underline', textClassName)}>{children}</Text></LinkPressable>;
+});

package/src/components/content.tsx

@@ -0,0 +1,55 @@
+'use client';
+
+import { forwardRef, useState, type ElementRef, type ReactNode } from 'react';
+import { Image, Pressable, View, type ImageSourcePropType, type ViewProps, type PressableProps } from 'react-native';
+import { cn, focusRing } from '../internal/utils';
+import { Text } from './typography';
+
+export type StatusTone = 'neutral' | 'info' | 'success' | 'warning' | 'error';
+const toneClasses = {
+  neutral: 'bg-ui-selected', info: 'bg-ui-info-surface', success: 'bg-ui-success-surface', warning: 'bg-ui-warning-surface', error: 'bg-ui-error-surface',
+};
+const toneText = { neutral: 'text-ui-text', info: 'text-ui-info', success: 'text-ui-success', warning: 'text-ui-warning', error: 'text-ui-error' };
+export interface BadgeProps extends ViewProps { children: ReactNode; tone?: StatusTone; className?: string; textClassName?: string }
+export function Badge({ children, tone = 'neutral', className, textClassName, ...props }: BadgeProps) {
+  return <View {...props} className={cn('self-start rounded-full px-3 py-1', toneClasses[tone], className)}><Text variant="small" className={cn('font-semibold', toneText[tone], textClassName)}>{children}</Text></View>;
+}
+
+export interface AvatarProps extends ViewProps {
+  source?: ImageSourcePropType;
+  name: string;
+  size?: 'sm' | 'md' | 'lg';
+  className?: string;
+}
+const avatarSizes = { sm: 'h-8 w-8', md: 'h-12 w-12', lg: 'h-16 w-16' };
+export function Avatar({ source, name, size = 'md', className, ...props }: AvatarProps) {
+  const [failedSource, setFailedSource] = useState<ImageSourcePropType>();
+  const initials = name.trim().split(/\s+/).slice(0, 2).map((part) => part[0]).join('').toUpperCase() || '?';
+  return <View {...props} accessible accessibilityRole="image" accessibilityLabel={name} className={cn('items-center justify-center overflow-hidden rounded-full bg-ui-selected', avatarSizes[size], className)}>
+    {source && source !== failedSource ? <Image source={source} resizeMode="cover" accessible={false} className="h-full w-full" onError={() => setFailedSource(source)} /> : <Text accessible={false} className="font-bold">{initials}</Text>}
+  </View>;
+}
+
+export interface EmptyStateProps extends ViewProps { title: string; description?: string; children?: ReactNode; className?: string }
+export function EmptyState({ title, description, children, className, ...props }: EmptyStateProps) {
+  return <View {...props} className={cn('items-start gap-3 py-8', className)}>
+    <Text className="text-lg font-bold">{title}</Text>
+    {description ? <Text tone="muted">{description}</Text> : null}
+    {children}
+  </View>;
+}
+
+export interface ListItemProps extends Omit<ViewProps, 'children'> {
+  title: string;
+  description?: string;
+  leading?: ReactNode;
+  trailing?: ReactNode;
+  className?: string;
+  onPress?: PressableProps['onPress'];
+  disabled?: boolean;
+}
+export const ListItem = forwardRef<ElementRef<typeof View>, ListItemProps>(function ListItem({ title, description, leading, trailing, className, disabled = false, onPress, accessibilityState, ...props }, ref) {
+  const content = <>{leading}<View className="min-w-0 flex-1 gap-1"><Text className="font-semibold">{title}</Text>{description ? <Text variant="small" tone="muted">{description}</Text> : null}</View>{trailing}</>;
+  const classes = cn('min-h-[48px] min-w-[44px] flex-row items-center gap-3 border-b border-ui-line py-3', onPress && focusRing, disabled && 'opacity-50', className);
+  return onPress ? <Pressable {...props} ref={ref} onPress={onPress} disabled={disabled} aria-disabled={disabled} accessibilityRole="button" accessibilityState={{ ...accessibilityState, disabled }} className={classes}>{content}</Pressable> : <View {...props} ref={ref} accessibilityState={accessibilityState} className={classes}>{content}</View>;
+});

package/src/components/disclosure.tsx

@@ -0,0 +1,33 @@
+'use client';
+
+import { useId, type ReactNode } from 'react';
+import { Pressable, View, type ViewProps } from 'react-native';
+import { cn, focusRing, useControllableState } from '../internal/utils';
+import { Text } from './typography';
+
+export interface AccordionItem { value: string; title: string; content: ReactNode; disabled?: boolean }
+export interface AccordionProps extends ViewProps {
+  items: AccordionItem[];
+  value?: string;
+  defaultValue?: string;
+  onValueChange?: (value: string) => void;
+  className?: string;
+}
+
+/** Single-open disclosure. An empty value collapses every section. */
+export function Accordion({ items, value, defaultValue = '', onValueChange, className, ...props }: AccordionProps) {
+  const [selected, setSelected] = useControllableState({ value, defaultValue, onChange: onValueChange });
+  const id = useId();
+  return <View {...props} className={className}>{items.map((item, index) => {
+    const expanded = selected === item.value;
+    const triggerID = `${id}-trigger-${index}`;
+    const panelID = `${id}-panel-${index}`;
+    return <View key={item.value} className="border-b border-ui-line">
+      <Pressable nativeID={triggerID} accessibilityRole="button" accessibilityLabel={item.title} accessibilityState={{ expanded, disabled: item.disabled }} aria-expanded={expanded} aria-disabled={item.disabled} {...{ 'aria-controls': expanded ? panelID : undefined }} disabled={item.disabled} onPress={() => setSelected(expanded ? '' : item.value)} className={cn('min-h-[48px] min-w-[44px] flex-row items-center justify-between gap-4 py-3', focusRing, item.disabled && 'opacity-50')}>
+        <Text className="flex-1 font-semibold">{item.title}</Text>
+        <View accessible={false} className={cn('mr-1 h-2 w-2 border-b-2 border-r-2 border-ui-text', expanded ? 'rotate-[225deg]' : 'rotate-45')} />
+      </Pressable>
+      {expanded ? <View nativeID={panelID} aria-labelledby={triggerID} className="gap-3 pb-4">{item.content}</View> : null}
+    </View>;
+  })}</View>;
+}

package/src/components/feedback.tsx

@@ -0,0 +1,68 @@
+'use client';
+
+import { useEffect, type ReactNode } from 'react';
+import { ActivityIndicator, Pressable, View, type ViewProps } from 'react-native';
+import { cn, focusRing, useControllableState } from '../internal/utils';
+import { useTheme } from '../theme';
+import { Text } from './typography';
+import type { StatusTone } from './content';
+
+const paints = { neutral: 'bg-ui-selected', info: 'bg-ui-info-surface', success: 'bg-ui-success-surface', warning: 'bg-ui-warning-surface', error: 'bg-ui-error-surface' };
+const texts = { neutral: 'text-ui-text', info: 'text-ui-info', success: 'text-ui-success', warning: 'text-ui-warning', error: 'text-ui-error' };
+export interface AlertProps extends ViewProps {
+  title: string;
+  description?: string;
+  children?: ReactNode;
+  tone?: StatusTone;
+  announce?: 'off' | 'polite' | 'assertive';
+  className?: string;
+}
+export function Alert({ title, description, children, tone = 'info', announce = 'off', className, ...props }: AlertProps) {
+  return <View {...props} accessibilityLiveRegion={announce === 'off' ? 'none' : announce} aria-live={announce} className={cn('gap-2 rounded-xl p-4', paints[tone], className)}>
+    <Text className={cn('font-semibold', texts[tone])}>{title}</Text>
+    {description ? <Text className={texts[tone]}>{description}</Text> : null}
+    {children}
+  </View>;
+}
+
+export interface ToastProps extends Omit<AlertProps, 'announce'> {
+  open?: boolean;
+  defaultOpen?: boolean;
+  onOpenChange?: (open: boolean) => void;
+  /** Zero keeps the notification until explicitly dismissed. */
+  duration?: number;
+  dismissLabel?: string;
+}
+/** Nonmodal inline notification. The consumer chooses its location. */
+export function Toast({ open, defaultOpen = true, onOpenChange, duration = 0, dismissLabel = 'Dismiss notification', className, children, ...props }: ToastProps) {
+  const [visible, setVisible] = useControllableState({ value: open, defaultValue: defaultOpen, onChange: onOpenChange });
+  useEffect(() => {
+    if (!visible || duration <= 0) return;
+    const timer = setTimeout(() => setVisible(false), duration);
+    return () => clearTimeout(timer);
+  }, [duration, visible, setVisible]);
+  if (!visible) return null;
+  return <Alert {...props} accessibilityRole="alert" announce="polite" className={className}>
+    {children}
+    <Pressable accessibilityRole="button" accessibilityLabel={dismissLabel} onPress={() => setVisible(false)} className={cn('min-h-[44px] min-w-[44px] self-start justify-center rounded px-2', focusRing)}><Text variant="small" className="font-semibold underline">Dismiss</Text></Pressable>
+  </Alert>;
+}
+
+export interface SpinnerProps extends ViewProps { label?: string; size?: 'small' | 'large'; className?: string }
+export function Spinner({ label = 'Loading', size = 'small', className, ...props }: SpinnerProps) {
+  const { colors } = useTheme();
+  return <View {...props} accessibilityRole="progressbar" accessibilityLabel={label} accessibilityState={{ busy: true }} aria-busy className={cn('self-start', className)}><ActivityIndicator accessible={false} color={colors.text} size={size} /></View>;
+}
+
+export interface ProgressProps extends ViewProps { value: number; max?: number; label: string; className?: string; indicatorClassName?: string }
+export function Progress({ value, max = 100, label, className, indicatorClassName, ...props }: ProgressProps) {
+  const maximum = Number.isFinite(max) && max > 0 ? max : 100;
+  const current = Math.min(maximum, Math.max(0, Number.isFinite(value) ? value : 0));
+  return <View {...props} accessibilityRole="progressbar" accessibilityLabel={label} accessibilityValue={{ min: 0, max: maximum, now: current }} aria-valuemin={0} aria-valuemax={maximum} aria-valuenow={current} className={cn('h-2 w-full overflow-hidden rounded-full bg-ui-selected', className)}>
+    <View className={cn('h-full bg-bubba-red', indicatorClassName)} style={{ width: `${current / maximum * 100}%` }} />
+  </View>;
+}
+
+export interface SkeletonProps extends ViewProps { className?: string }
+/** Static placeholder; avoids forcing motion on either platform. */
+export function Skeleton({ className, ...props }: SkeletonProps) { return <View {...props} accessible={false} aria-hidden importantForAccessibility="no-hide-descendants" className={cn('h-4 w-full rounded bg-ui-selected', className)} />; }

package/src/components/forms/Choice.tsx

@@ -0,0 +1,112 @@
+'use client';
+
+import { forwardRef, useId, type ElementRef, type KeyboardEvent, type SyntheticEvent } from 'react';
+import { Platform, Pressable, Text, View, type GestureResponderEvent, type PressableProps } from 'react-native';
+import { cn, focusRing, useControllableState } from '../../internal/utils';
+import { useFormField } from './FormField';
+
+/** RNW's Enter activation forwards a raw DOM keyup, without React event methods. */
+export interface ChoiceDOMKeyboardEvent {
+  readonly key: string;
+  readonly code: string;
+  readonly repeat: boolean;
+  readonly type: string;
+  readonly defaultPrevented: boolean;
+  readonly target: unknown;
+  readonly currentTarget: unknown;
+  preventDefault(): void;
+  stopPropagation(): void;
+}
+export type ChoicePressEvent = GestureResponderEvent | SyntheticEvent<unknown, unknown> | ChoiceDOMKeyboardEvent;
+export interface ChoiceProps extends Omit<PressableProps, 'children' | 'onPress'> {
+  checked?: boolean;
+  defaultChecked?: boolean;
+  onCheckedChange?: (checked: boolean) => void;
+  /** Web supplies React keyboard events for Space and raw DOM keyup for Enter. */
+  onPress?: ((event: ChoicePressEvent) => void) | null;
+  label?: string;
+  description?: string;
+  invalid?: boolean;
+  required?: boolean;
+  className?: string;
+  textClassName?: string;
+}
+
+export interface CheckboxProps extends ChoiceProps {
+  /** A mixed checkbox becomes checked on its next activation. */
+  indeterminate?: boolean;
+}
+export interface SwitchProps extends ChoiceProps { }
+
+interface ChoiceControlProps extends CheckboxProps { kind: 'checkbox' | 'switch' }
+
+/** RNW Pressable handles Enter; non-button roles need an explicit Space handler. */
+function spaceKeyHandler(disabled: boolean, activate: (event: KeyboardEvent<unknown>) => void) {
+  return Platform.OS === 'web' ? {
+    onKeyDown(event: KeyboardEvent<unknown>) {
+      const key = event.key;
+      if (key === ' ' || key === 'Spacebar') {
+        event.preventDefault();
+        if (!disabled && !event.repeat) activate(event);
+      }
+    },
+  } : {};
+}
+
+const ChoiceControl = forwardRef<ElementRef<typeof Pressable>, ChoiceControlProps>(function ChoiceControl({
+  kind, checked, defaultChecked = false, onCheckedChange, indeterminate = false, label, description, invalid, required,
+  disabled, className, textClassName, onPress, accessibilityLabel, accessibilityHint, accessibilityState,
+  'aria-label': ariaLabel, 'aria-disabled': ariaDisabled, nativeID, ...props
+}, ref) {
+  const field = useFormField();
+  const generatedID = useId().replace(/:/g, '');
+  const id = nativeID ?? field?.controlID ?? `bui-choice-${generatedID}`;
+  const isDisabled = Boolean(disabled || ariaDisabled || accessibilityState?.disabled || field?.disabled);
+  const [isChecked, setChecked] = useControllableState({ value: checked, defaultValue: defaultChecked, onChange: onCheckedChange });
+  const mixed = kind === 'checkbox' && indeterminate;
+  const state = mixed ? 'mixed' : isChecked;
+  const name = accessibilityLabel ?? ariaLabel ?? label ?? field?.label;
+  const isRequired = required ?? field?.required ?? false;
+  const isInvalid = invalid ?? field?.invalid ?? false;
+  const hint = [accessibilityHint ?? description ?? field?.hint, field?.error && `Error: ${field.error}`,
+    isRequired && 'Required'].filter(Boolean).join('. ') || undefined;
+  const activate = (event: ChoicePressEvent) => {
+    if (isDisabled) return;
+    setChecked(mixed || !isChecked);
+    onPress?.(event);
+  };
+  const descriptions = [description && `${id}-description`, field?.descriptionID].filter(Boolean).join(' ') || undefined;
+
+  return <Pressable {...props} {...spaceKeyHandler(isDisabled, activate)} ref={ref} nativeID={id}
+    accessibilityRole={kind} accessibilityLabel={name} accessibilityHint={hint}
+    accessibilityState={{ ...accessibilityState, checked: state, disabled: isDisabled }}
+    aria-checked={state} aria-disabled={isDisabled} disabled={isDisabled}
+    {...(Platform.OS === 'web' ? { 'aria-describedby': descriptions, 'aria-required': isRequired,
+      'aria-invalid': isInvalid } : {})}
+    onPress={activate}
+    className={cn('min-h-[44px] min-w-[44px] flex-row items-center gap-3 rounded-[4px] py-2', focusRing,
+      isDisabled && 'opacity-50', className)}>
+    {kind === 'checkbox' ? <View accessible={false} importantForAccessibility="no-hide-descendants"
+      className={cn('h-5 w-5 items-center justify-center rounded-[4px] border-2 border-ui-border',
+        (isChecked || mixed) && 'border-bubba-red bg-bubba-red', isInvalid && 'border-ui-error')}>
+      {mixed ? <View className="h-0.5 w-3 bg-white" /> : isChecked ?
+        <View className="h-[10px] w-[6px] -translate-y-px rotate-45 border-b-2 border-r-2 border-white" /> : null}
+    </View> : <View accessible={false} importantForAccessibility="no-hide-descendants"
+      className={cn('h-[26px] w-[44px] rounded-full border border-ui-border bg-ui-selected p-[2px]',
+        isChecked && 'border-bubba-red bg-bubba-red', isInvalid && 'border-ui-error')}>
+      <View className={cn('h-5 w-5 rounded-full', isChecked ? 'translate-x-[18px] bg-white' : 'translate-x-0 bg-ui-muted')} />
+    </View>}
+    {label || description ? <View className="min-w-0 flex-1 gap-1">
+      {label ? <Text className={cn('text-base font-medium text-ui-text', textClassName)}>{label}</Text> : null}
+      {description ? <Text nativeID={`${id}-description`} className="text-sm leading-5 text-ui-muted">{description}</Text> : null}
+    </View> : null}
+  </Pressable>;
+});
+
+export const Checkbox = forwardRef<ElementRef<typeof Pressable>, CheckboxProps>(function Checkbox(props, ref) {
+  return <ChoiceControl {...props} ref={ref} kind="checkbox" />;
+});
+
+export const Switch = forwardRef<ElementRef<typeof Pressable>, SwitchProps>(function Switch(props, ref) {
+  return <ChoiceControl {...props} ref={ref} kind="switch" />;
+});

package/src/components/forms/FormField.tsx

@@ -0,0 +1,58 @@
+'use client';
+
+import { createContext, forwardRef, useContext, useId, type ElementRef, type ReactNode } from 'react';
+import { Platform, Text, View, type ViewProps } from 'react-native';
+import { cn } from '../../internal/utils';
+
+interface FieldContextValue {
+  controlID: string;
+  labelID: string;
+  label: string;
+  descriptionID?: string;
+  hint?: string;
+  error?: string;
+  invalid: boolean;
+  required: boolean;
+  disabled: boolean;
+}
+
+const FieldContext = createContext<FieldContextValue | undefined>(undefined);
+export function useFormField() { return useContext(FieldContext); }
+
+export interface FormFieldProps extends ViewProps {
+  label: string;
+  hint?: string;
+  error?: string;
+  required?: boolean;
+  disabled?: boolean;
+  /** Opt into announcing errors that change during interaction. */
+  announceError?: boolean;
+  children: ReactNode;
+  className?: string;
+  labelClassName?: string;
+}
+
+/** Associates a visible label, hint, and error with the enclosed form control. */
+export const FormField = forwardRef<ElementRef<typeof View>, FormFieldProps>(function FormField({ label, hint, error, required = false, disabled = false,
+  announceError = false, children, nativeID, className, labelClassName, ...props }, ref) {
+  const generatedID = useId().replace(/:/g, '');
+  const id = nativeID ?? `bui-field-${generatedID}`;
+  const descriptionID = [hint && `${id}-hint`, error && `${id}-error`].filter(Boolean).join(' ') || undefined;
+  const field: FieldContextValue = { controlID: `${id}-control`, labelID: `${id}-label`,
+    label, descriptionID, hint, error, invalid: Boolean(error), required, disabled };
+
+  return (
+    <FieldContext.Provider value={field}>
+      <View {...props} ref={ref} nativeID={nativeID} className={cn('gap-2', className)}>
+        <Text nativeID={field.labelID} className={cn('text-base font-semibold text-ui-text', labelClassName)}>
+          {label}{required ? ' *' : ''}
+        </Text>
+        {children}
+        {hint ? <Text nativeID={`${id}-hint`} className="text-sm leading-5 text-ui-muted">{hint}</Text> : null}
+        {error ? <Text nativeID={`${id}-error`} accessibilityLiveRegion={announceError ? 'polite' : 'none'}
+          {...(Platform.OS === 'web' ? { 'aria-live': announceError ? 'polite' as const : 'off' as const } : {})}
+          className="text-sm leading-5 text-ui-error">{error}</Text> : null}
+      </View>
+    </FieldContext.Provider>
+  );
+});

package/src/components/forms/Input.tsx

@@ -0,0 +1,55 @@
+'use client';
+
+import { forwardRef } from 'react';
+import { Platform, TextInput, type TextInputProps } from 'react-native';
+import { cn, focusRing } from '../../internal/utils';
+import { useTheme } from '../../theme';
+import { useFormField } from './FormField';
+
+export interface InputProps extends TextInputProps {
+  disabled?: boolean;
+  invalid?: boolean;
+  required?: boolean;
+  className?: string;
+}
+
+/** Native TextInput with field association and matching light/dark paint. */
+export const Input = forwardRef<TextInput, InputProps>(function Input({ disabled, invalid, required,
+  readOnly = false, editable, className, nativeID, accessibilityLabel, accessibilityHint,
+  accessibilityState, 'aria-label': ariaLabel, 'aria-disabled': ariaDisabled, placeholderTextColor, selectionColor, ...props }, ref) {
+  const field = useFormField();
+  const { colors } = useTheme();
+  const isDisabled = Boolean(disabled || ariaDisabled || accessibilityState?.disabled || field?.disabled);
+  const isReadOnly = readOnly || (editable === false && !isDisabled);
+  const isInvalid = invalid ?? field?.invalid ?? false;
+  const isRequired = required ?? field?.required ?? false;
+  const explicitLabel = accessibilityLabel ?? ariaLabel;
+  const nativeHint = [accessibilityHint ?? field?.hint, field?.error && `Error: ${field.error}`,
+    isRequired && 'Required', isReadOnly && 'Read only'].filter(Boolean).join('. ') || undefined;
+  const webProps = Platform.OS === 'web' ? {
+    disabled: isDisabled,
+    readOnly: isReadOnly,
+    'aria-describedby': field?.descriptionID,
+    'aria-labelledby': explicitLabel ? undefined : field?.labelID,
+    'aria-invalid': isInvalid,
+    'aria-required': isRequired,
+    'aria-readonly': isReadOnly || undefined,
+  } : {};
+
+  return <TextInput {...props} {...webProps} ref={ref} nativeID={nativeID ?? field?.controlID}
+    accessibilityLabel={explicitLabel ?? (Platform.OS === 'web' ? undefined : field?.label)}
+    accessibilityHint={nativeHint} accessibilityState={{ ...accessibilityState, disabled: isDisabled }}
+    aria-disabled={isDisabled} editable={!isDisabled && !isReadOnly}
+    placeholderTextColor={placeholderTextColor ?? colors.muted} selectionColor={selectionColor ?? colors.selection}
+    className={cn('min-h-[48px] rounded-[4px] border border-ui-border bg-ui-surface px-3 py-3 text-base text-ui-text',
+      focusRing, isInvalid && 'border-ui-error', isDisabled && 'bg-ui-disabled-surface text-ui-disabled-text', className)} />;
+});
+
+export interface TextareaProps extends InputProps { }
+
+/** A multiline Input; numberOfLines and style/minHeight remain native props. */
+export const Textarea = forwardRef<TextInput, TextareaProps>(function Textarea({ className,
+  numberOfLines = 4, textAlignVertical = 'top', ...props }, ref) {
+  return <Input {...props} ref={ref} multiline numberOfLines={numberOfLines} textAlignVertical={textAlignVertical}
+    className={cn('min-h-[120px]', className)} />;
+});

package/src/components/forms/RadioGroup.tsx

@@ -0,0 +1,87 @@
+'use client';
+
+import { forwardRef, useId, type ElementRef } from 'react';
+import { Platform, Pressable, Text, View, type ViewProps } from 'react-native';
+import { cn, focusRing, useControllableState } from '../../internal/utils';
+import { useFormField } from './FormField';
+import { useSelectionNavigation } from './selection';
+
+export interface RadioOption {
+  value: string;
+  label: string;
+  description?: string;
+  disabled?: boolean;
+}
+
+export interface RadioGroupProps extends Omit<ViewProps, 'children'> {
+  options: readonly RadioOption[];
+  value?: string;
+  defaultValue?: string;
+  onValueChange?: (value: string) => void;
+  label?: string;
+  disabled?: boolean;
+  required?: boolean;
+  invalid?: boolean;
+  orientation?: 'horizontal' | 'vertical';
+  className?: string;
+  optionClassName?: string;
+  textClassName?: string;
+}
+
+/** Single selection with roving web focus and native radio accessibility. */
+export const RadioGroup = forwardRef<ElementRef<typeof View>, RadioGroupProps>(function RadioGroup({
+  options, value, defaultValue, onValueChange, label, disabled = false, required, invalid,
+  orientation = 'vertical', className, optionClassName, textClassName, nativeID,
+  accessibilityLabel, accessibilityHint, accessibilityState, 'aria-label': ariaLabel, 'aria-disabled': ariaDisabled, ...props
+}, ref) {
+  const field = useFormField();
+  const generatedID = useId().replace(/:/g, '');
+  const id = nativeID ?? field?.controlID ?? `bui-radio-${generatedID}`;
+  const isDisabled = Boolean(disabled || ariaDisabled || accessibilityState?.disabled || field?.disabled);
+  const isRequired = required ?? field?.required ?? false;
+  const isInvalid = invalid ?? field?.invalid ?? false;
+  const [selected, setSelected] = useControllableState<string | undefined>({
+    value, defaultValue, onChange: (next) => { if (next !== undefined) onValueChange?.(next); },
+  });
+  const select = (next: string) => {
+    if (!isDisabled && options.some((option) => option.value === next && !option.disabled)) setSelected(next);
+  };
+  const navigation = useSelectionNavigation(options, selected, select, orientation, isDisabled);
+  const labelID = label ? `${id}-label` : field?.labelID;
+  const explicitLabel = accessibilityLabel ?? ariaLabel;
+  const name = explicitLabel ?? label ?? field?.label;
+  const hint = [accessibilityHint ?? field?.hint, field?.error && `Error: ${field.error}`,
+    isRequired && 'Required'].filter(Boolean).join('. ') || undefined;
+
+  return <View {...props} ref={ref} nativeID={id} className={cn('gap-2', className)}>
+    {label ? <Text nativeID={labelID} className="text-base font-semibold text-ui-text">{label}</Text> : null}
+    <View accessibilityRole="radiogroup" accessibilityLabel={Platform.OS === 'web' && labelID && !explicitLabel ? undefined : name}
+      accessibilityHint={hint} accessibilityState={{ ...accessibilityState, disabled: isDisabled }} aria-disabled={isDisabled}
+      {...(Platform.OS === 'web' ? { 'aria-labelledby': explicitLabel ? undefined : labelID,
+        'aria-describedby': field?.descriptionID, 'aria-required': isRequired, 'aria-invalid': isInvalid,
+        'aria-orientation': orientation } : {})}
+      className={cn('gap-1', orientation === 'horizontal' && 'flex-row flex-wrap gap-x-6')}>
+      {options.map((option, index) => {
+        const checked = selected === option.value;
+        const optionDisabled = isDisabled || Boolean(option.disabled);
+        const optionID = `${id}-option-${index}`;
+        return <Pressable key={option.value} {...navigation(index)} nativeID={optionID}
+          accessibilityRole="radio" accessibilityLabel={option.label} accessibilityHint={option.description}
+          accessibilityState={{ checked, disabled: optionDisabled }} aria-checked={checked} aria-disabled={optionDisabled}
+          {...(Platform.OS === 'web' ? { 'aria-describedby': option.description ? `${optionID}-description` : undefined } : {})}
+          disabled={optionDisabled} onPress={() => select(option.value)}
+          className={cn('min-h-[44px] min-w-[44px] flex-row items-center gap-3 rounded-[4px] py-2',
+            focusRing, optionDisabled && 'opacity-50', optionClassName)}>
+          <View accessible={false} importantForAccessibility="no-hide-descendants"
+            className={cn('h-5 w-5 items-center justify-center rounded-full border-2 border-ui-border', checked && 'border-bubba-red')}>
+            {checked ? <View className="h-2.5 w-2.5 rounded-full bg-bubba-red" /> : null}
+          </View>
+          <View className="min-w-0 flex-1 gap-1">
+            <Text className={cn('text-base font-medium text-ui-text', textClassName)}>{option.label}</Text>
+            {option.description ? <Text nativeID={`${optionID}-description`} className="text-sm leading-5 text-ui-muted">{option.description}</Text> : null}
+          </View>
+        </Pressable>;
+      })}
+    </View>
+  </View>;
+});