@bubbasfw/ui 0.1.0 → 0.2.0

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

package/src/components/forms/Select.tsx

@@ -0,0 +1,102 @@
+'use client';
+
+import { forwardRef, useEffect, useId, useState, type ElementRef } from 'react';
+import { Platform, Pressable, Text, View, type PressableProps } from 'react-native';
+import { cn, focusRing, useControllableState } from '../../internal/utils';
+import { Dialog } from '../overlays';
+import { useFormField } from './FormField';
+import type { RadioOption } from './RadioGroup';
+import { useSelectionNavigation } from './selection';
+
+export type SelectOption = RadioOption;
+export interface SelectProps extends Omit<PressableProps, 'children'> {
+  options: readonly SelectOption[];
+  value?: string;
+  defaultValue?: string;
+  onValueChange?: (value: string) => void;
+  label?: string;
+  placeholder?: string;
+  required?: boolean;
+  invalid?: boolean;
+  className?: string;
+  textClassName?: string;
+}
+
+/** A labelled button opens a single-choice dialog on web and native. */
+export const Select = forwardRef<ElementRef<typeof Pressable>, SelectProps>(function Select({
+  options, value, defaultValue, onValueChange, label, placeholder = 'Choose an option',
+  required, invalid, disabled, className, textClassName, nativeID, testID, onPress,
+  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-select-${generatedID}`;
+  const isDisabled = Boolean(disabled || ariaDisabled || accessibilityState?.disabled || field?.disabled);
+  const isInvalid = invalid ?? field?.invalid ?? false;
+  const isRequired = required ?? field?.required ?? false;
+  const [selected, setSelected] = useControllableState<string | undefined>({ value, defaultValue,
+    onChange: (next) => { if (next !== undefined) onValueChange?.(next); },
+  });
+  const [open, setOpen] = useState(false);
+  const [pending, setPending] = useState(selected);
+  useEffect(() => { if (isDisabled) setOpen(false); }, [isDisabled]);
+  const selectedOption = options.find((option) => option.value === selected);
+  const title = label ?? field?.label ?? 'Choose an option';
+  const labelID = label ? `${id}-label` : field?.labelID;
+  const explicitLabel = accessibilityLabel ?? ariaLabel;
+  const hint = [accessibilityHint ?? field?.hint, field?.error && `Error: ${field.error}`,
+    isRequired && 'Required', 'Opens a list of choices'].filter(Boolean).join('. ');
+  const commit = (next: string) => {
+    if (isDisabled || !options.some((option) => option.value === next && !option.disabled)) return;
+    setSelected(next);
+    setOpen(false);
+  };
+  const navigation = useSelectionNavigation(options, pending, setPending, 'vertical', isDisabled, commit);
+
+  return <View className="gap-2">
+    {label ? <Text nativeID={labelID} className="text-base font-semibold text-ui-text">{label}</Text> : null}
+    <Pressable {...props} ref={ref} nativeID={id} testID={testID} accessibilityRole="button"
+      accessibilityLabel={explicitLabel ?? (Platform.OS === 'web' ? undefined : `${title}: ${selectedOption?.label ?? placeholder}`)}
+      accessibilityHint={hint} accessibilityState={{ ...accessibilityState, disabled: isDisabled, expanded: open }}
+      aria-disabled={isDisabled} aria-expanded={open} disabled={isDisabled}
+      {...(Platform.OS === 'web' ? { 'aria-haspopup': 'dialog',
+        'aria-labelledby': !explicitLabel && labelID ? `${labelID} ${id}-value` : undefined,
+        'aria-describedby': field?.descriptionID, 'aria-invalid': isInvalid } : {})}
+      onPress={(event) => { if (!isDisabled) { setPending(selected); setOpen(true); } onPress?.(event); }}
+      className={cn('min-h-[48px] flex-row items-center justify-between gap-4 rounded-[4px] border border-ui-border bg-ui-surface px-3 py-3',
+        focusRing, isInvalid && 'border-ui-error', isDisabled && 'bg-ui-disabled-surface', className)}>
+      <Text nativeID={`${id}-value`} className={cn('min-w-0 flex-1 text-base', selectedOption ? 'text-ui-text' : 'text-ui-muted',
+        isDisabled && 'text-ui-disabled-text', textClassName)}>{selectedOption?.label ?? placeholder}</Text>
+      <View accessible={false} importantForAccessibility="no-hide-descendants"
+        className="mr-1 h-2 w-2 rotate-45 border-b-2 border-r-2 border-ui-muted" />
+    </Pressable>
+    <Dialog open={open} onOpenChange={setOpen} title={title} closeLabel="Cancel"
+      testID={testID ? `${testID}-dialog` : undefined}>
+      <View accessibilityRole="radiogroup" accessibilityLabel={title}
+        {...(Platform.OS === 'web' ? { 'aria-required': isRequired } : {})} className="gap-1">
+        {options.map((option, index) => {
+          const checked = pending === option.value;
+          const optionID = `${id}-option-${index}`;
+          return <Pressable key={option.value} {...navigation(index)} nativeID={optionID}
+            testID={testID ? `${testID}-option-${option.value}` : undefined}
+            accessibilityRole="radio" accessibilityLabel={option.label} accessibilityHint={option.description}
+            accessibilityState={{ checked, disabled: Boolean(option.disabled) }}
+            aria-checked={checked} aria-disabled={Boolean(option.disabled)} disabled={option.disabled}
+            {...(Platform.OS === 'web' ? { 'aria-describedby': option.description ? `${optionID}-description` : undefined } : {})}
+            onPress={() => commit(option.value)} className={cn('min-h-[48px] min-w-[44px] flex-row items-center gap-3 rounded-[4px] px-3 py-3',
+              focusRing, checked && 'bg-ui-selected', option.disabled && 'opacity-50')}>
+            <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="text-base font-medium text-ui-text">{option.label}</Text>
+              {option.description ? <Text nativeID={`${optionID}-description`} className="text-sm leading-5 text-ui-muted">{option.description}</Text> : null}
+            </View>
+          </Pressable>;
+        })}
+        {options.length === 0 ? <Text className="px-3 py-4 text-base text-ui-muted">No options available.</Text> : null}
+      </View>
+    </Dialog>
+  </View>;
+});

package/src/components/forms/Tabs.tsx

@@ -0,0 +1,70 @@
+'use client';
+
+import { forwardRef, useId, type ElementRef, type ReactNode } from 'react';
+import { Platform, Pressable, Text, View, type ViewProps } from 'react-native';
+import { cn, focusRing, useControllableState } from '../../internal/utils';
+import { useSelectionNavigation } from './selection';
+
+export interface TabItem {
+  value: string;
+  label: string;
+  content: ReactNode;
+  disabled?: boolean;
+}
+
+export interface TabsProps extends Omit<ViewProps, 'children'> {
+  items: readonly TabItem[];
+  value?: string;
+  defaultValue?: string;
+  onValueChange?: (value: string) => void;
+  label?: string;
+  orientation?: 'horizontal' | 'vertical';
+  className?: string;
+  tabListClassName?: string;
+  tabClassName?: string;
+  textClassName?: string;
+  panelClassName?: string;
+}
+
+/** Automatically activates tabs with arrow keys; inactive panels are unmounted. */
+export const Tabs = forwardRef<ElementRef<typeof View>, TabsProps>(function Tabs({
+  items, value, defaultValue, onValueChange, label = 'Content sections', orientation = 'horizontal',
+  className, tabListClassName, tabClassName, textClassName, panelClassName, nativeID, ...props
+}, ref) {
+  const generatedID = useId().replace(/:/g, '');
+  const id = nativeID ?? `bui-tabs-${generatedID}`;
+  const [selected, setSelected] = useControllableState<string | undefined>({ value,
+    defaultValue: defaultValue ?? items.find((item) => !item.disabled)?.value,
+    onChange: (next) => { if (next !== undefined) onValueChange?.(next); },
+  });
+  const select = (next: string) => {
+    if (items.some((item) => item.value === next && !item.disabled)) setSelected(next);
+  };
+  const navigation = useSelectionNavigation(items, selected, select, orientation);
+  const activeIndex = items.findIndex((item) => item.value === selected && !item.disabled);
+  const active = items[activeIndex];
+
+  return <View {...props} ref={ref} nativeID={id} className={cn('gap-4', className)}>
+    <View accessibilityRole="tablist" accessibilityLabel={label}
+      {...(Platform.OS === 'web' ? { 'aria-orientation': orientation } : {})}
+      className={cn('gap-1 rounded-md border border-ui-border bg-ui-selected p-1',
+        orientation === 'horizontal' && 'flex-row flex-wrap', tabListClassName)}>
+      {items.map((item, index) => {
+        const isSelected = index === activeIndex;
+        return <Pressable key={item.value} {...navigation(index)} nativeID={`${id}-tab-${index}`}
+          accessibilityRole="tab" accessibilityLabel={item.label}
+          accessibilityState={{ selected: isSelected, disabled: Boolean(item.disabled) }}
+          aria-selected={isSelected} aria-disabled={Boolean(item.disabled)} disabled={item.disabled}
+          {...(Platform.OS === 'web' ? { 'aria-controls': isSelected ? `${id}-panel-${index}` : undefined } : {})}
+          onPress={() => select(item.value)} className={cn('min-h-[44px] min-w-[44px] items-center justify-center rounded-[4px] px-4 py-2',
+            focusRing, isSelected && 'bg-ui-surface', item.disabled && 'opacity-50', tabClassName)}>
+          <Text className={cn('text-base font-semibold', isSelected ? 'text-ui-text' : 'text-ui-muted', textClassName)}>{item.label}</Text>
+        </Pressable>;
+      })}
+    </View>
+    {active ? <View key={active.value} nativeID={`${id}-panel-${activeIndex}`} role="tabpanel"
+      accessibilityLabel={Platform.OS === 'web' ? undefined : active.label} tabIndex={0}
+      {...(Platform.OS === 'web' ? { 'aria-labelledby': `${id}-tab-${activeIndex}` } : {})}
+      className={cn('rounded-[4px]', focusRing, panelClassName)}>{active.content}</View> : null}
+  </View>;
+});

package/src/components/forms/index.ts

@@ -0,0 +1,6 @@
+export { FormField, type FormFieldProps } from './FormField';
+export { Input, Textarea, type InputProps, type TextareaProps } from './Input';
+export { Checkbox, Switch, type ChoiceProps, type ChoicePressEvent, type ChoiceDOMKeyboardEvent, type CheckboxProps, type SwitchProps } from './Choice';
+export { RadioGroup, type RadioGroupProps, type RadioOption } from './RadioGroup';
+export { Select, type SelectProps, type SelectOption } from './Select';
+export { Tabs, type TabsProps, type TabItem } from './Tabs';

package/src/components/forms/selection.ts

@@ -0,0 +1,48 @@
+'use client';
+
+import { useRef, type ElementRef } from 'react';
+import { Platform, Pressable } from 'react-native';
+
+interface SelectionKeyEvent {
+  key?: string;
+  nativeEvent?: { key?: string };
+  repeat?: boolean;
+  preventDefault(): void;
+}
+
+/** One tab stop, native touch activation, and actual focus movement on web. */
+export function useSelectionNavigation<T extends { value: string; disabled?: boolean }>(
+  items: readonly T[], value: string | undefined, onSelect: (value: string) => void,
+  orientation: 'horizontal' | 'vertical', disabled = false, onActivate = onSelect,
+) {
+  const refs = useRef<Array<ElementRef<typeof Pressable> | null>>([]);
+  const enabled = items.map((item, index) => !disabled && !item.disabled ? index : -1).filter((index) => index !== -1);
+  const selectedIndex = items.findIndex((item) => item.value === value && !item.disabled);
+  const tabStop = selectedIndex >= 0 && !disabled ? selectedIndex : enabled[0];
+
+  return (index: number) => ({
+    ref: (node: ElementRef<typeof Pressable> | null) => { refs.current[index] = node; },
+    tabIndex: (Platform.OS === 'web' && index !== tabStop ? -1 : 0) as 0 | -1,
+    ...(Platform.OS === 'web' ? {
+      onKeyDown(event: SelectionKeyEvent) {
+        if (disabled || items[index]?.disabled) return;
+        const key = event.key ?? event.nativeEvent?.key;
+        if (key === ' ' || key === 'Spacebar') {
+          event.preventDefault();
+          if (!event.repeat) onActivate(items[index].value);
+          return;
+        }
+        const forward = key === (orientation === 'horizontal' ? 'ArrowRight' : 'ArrowDown');
+        const backward = key === (orientation === 'horizontal' ? 'ArrowLeft' : 'ArrowUp');
+        if (!forward && !backward && key !== 'Home' && key !== 'End') return;
+        event.preventDefault();
+        const position = enabled.indexOf(index);
+        const next = key === 'Home' ? enabled[0] : key === 'End' ? enabled[enabled.length - 1]
+          : enabled[(position + (forward ? 1 : -1) + enabled.length) % enabled.length];
+        if (next === undefined) return;
+        onSelect(items[next].value);
+        refs.current[next]?.focus();
+      },
+    } : {}),
+  });
+}