@bubbasfw/ui 0.0.0-stage → 0.2.0

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();
+      },
+    } : {}),
+  });
+}

package/src/components/layout.tsx

@@ -0,0 +1,35 @@
+'use client';
+
+import { forwardRef, type ElementRef } from 'react';
+import { View, type ViewProps } from 'react-native';
+import { cn } from '../internal/utils';
+
+const gaps = { 0: 'gap-0', 1: 'gap-1', 2: 'gap-2', 3: 'gap-3', 4: 'gap-4', 6: 'gap-6', 8: 'gap-8', 12: 'gap-12', 16: 'gap-16' };
+const alignments = { start: 'items-start', center: 'items-center', end: 'items-end', stretch: 'items-stretch' };
+const justifications = { start: 'justify-start', center: 'justify-center', end: 'justify-end', between: 'justify-between' };
+export interface StackProps extends ViewProps {
+  gap?: keyof typeof gaps;
+  align?: keyof typeof alignments;
+  justify?: keyof typeof justifications;
+  className?: string;
+}
+export const Stack = forwardRef<ElementRef<typeof View>, StackProps>(function Stack({ gap = 4, align = 'stretch', justify = 'start', className, ...props }, ref) {
+  return <View {...props} ref={ref} className={cn('flex-col', gaps[gap], alignments[align], justifications[justify], className)} />;
+});
+export interface InlineProps extends StackProps { wrap?: boolean }
+export const Inline = forwardRef<ElementRef<typeof View>, InlineProps>(function Inline({ gap = 3, align = 'center', justify = 'start', wrap = true, className, ...props }, ref) {
+  return <View {...props} ref={ref} className={cn('flex-row', gaps[gap], alignments[align], justifications[justify], wrap ? 'flex-wrap' : 'flex-nowrap', className)} />;
+});
+export interface ContainerProps extends ViewProps { reading?: boolean; className?: string }
+export const Container = forwardRef<ElementRef<typeof View>, ContainerProps>(function Container({ reading = false, className, ...props }, ref) {
+  return <View {...props} ref={ref} className={cn('mx-auto w-full px-4 sm:px-6 lg:px-8', reading ? 'max-w-[720px]' : 'max-w-[1200px]', className)} />;
+});
+export interface CardProps extends ViewProps { className?: string; padding?: keyof typeof gaps }
+const paddings = { 0: 'p-0', 1: 'p-1', 2: 'p-2', 3: 'p-3', 4: 'p-4', 6: 'p-6', 8: 'p-8', 12: 'p-12', 16: 'p-16' };
+export const Card = forwardRef<ElementRef<typeof View>, CardProps>(function Card({ padding = 6, className, ...props }, ref) {
+  return <View {...props} ref={ref} className={cn('rounded-xl border border-ui-line bg-ui-surface', paddings[padding], className)} />;
+});
+export interface DividerProps extends ViewProps { orientation?: 'horizontal' | 'vertical'; className?: string }
+export function Divider({ orientation = 'horizontal', className, ...props }: DividerProps) {
+  return <View {...props} accessible={false} className={cn('bg-ui-line', orientation === 'horizontal' ? 'h-px w-full' : 'w-px self-stretch', className)} />;
+}

package/src/components/navigation.tsx

@@ -0,0 +1,27 @@
+'use client';
+
+import { View, type ViewProps } from 'react-native';
+import { cn } from '../internal/utils';
+import { Button } from './Button';
+import { Link } from './actions';
+import { Text } from './typography';
+
+export interface BreadcrumbItem { label: string; href?: string }
+export interface BreadcrumbsProps extends ViewProps { items: BreadcrumbItem[]; label?: string; className?: string }
+export function Breadcrumbs({ items, label = 'Breadcrumb', className, ...props }: BreadcrumbsProps) {
+  return <View {...props} role="navigation" accessibilityLabel={label} className={cn('flex-row flex-wrap items-center gap-2', className)}>{items.map((item, index) => <View key={`${item.label}-${index}`} className="flex-row items-center gap-2">
+    {index > 0 ? <View accessible={false} className="h-2 w-2 rotate-[-45deg] border-b border-r border-ui-muted" /> : null}
+    {item.href && index !== items.length - 1 ? <Link href={item.href} textClassName="text-sm">{item.label}</Link> : <Text variant="small" {...(index === items.length - 1 ? { 'aria-current': 'page' as const } : {})}>{item.label}</Text>}
+  </View>)}</View>;
+}
+
+export interface PaginationProps extends ViewProps { page: number; count: number; onPageChange: (page: number) => void; label?: string; className?: string }
+export function Pagination({ page, count, onPageChange, label = 'Pagination', className, ...props }: PaginationProps) {
+  const total = Math.max(1, Math.floor(Number.isFinite(count) ? count : 1));
+  const current = Math.min(total, Math.max(1, Math.floor(Number.isFinite(page) ? page : 1)));
+  return <View {...props} role="navigation" accessibilityLabel={label} className={cn('flex-row flex-wrap items-center gap-3', className)}>
+    <Button variant="outline" size="sm" disabled={current === 1} onPress={() => onPageChange(current - 1)} accessibilityLabel="Previous page">Previous</Button>
+    <Text variant="small" accessibilityLiveRegion="polite" aria-live="polite">{`Page ${current} of ${total}`}</Text>
+    <Button variant="outline" size="sm" disabled={current === total} onPress={() => onPageChange(current + 1)} accessibilityLabel="Next page">Next</Button>
+  </View>;
+}

package/src/components/overlays.tsx

@@ -0,0 +1,64 @@
+'use client';
+
+import { useEffect, useId, useReducer, useState, type ReactNode } from 'react';
+import { Modal, Platform, Pressable, ScrollView, View, type ViewProps } from 'react-native';
+import { cn, focusRing, useControllableState } from '../internal/utils';
+import { useWebScrollLock } from '../internal/scroll-lock';
+import { useTheme } from '../theme';
+import { Heading, Text } from './typography';
+
+export interface DialogProps extends Omit<ViewProps, 'children'> {
+  open?: boolean;
+  defaultOpen?: boolean;
+  onOpenChange?: (open: boolean) => void;
+  title: string;
+  description?: string;
+  children: ReactNode;
+  closeLabel?: string;
+  dismissOnBackdropPress?: boolean;
+  className?: string;
+  contentClassName?: string;
+}
+
+function Overlay({ open, defaultOpen = false, onOpenChange, title, description, children, closeLabel = 'Close', dismissOnBackdropPress = true, className, contentClassName, testID, style, sheet = false, ...props }: DialogProps & { sheet?: boolean }) {
+  const [isOpen, setOpen] = useControllableState({ value: open, defaultValue: defaultOpen, onChange: onOpenChange });
+  const { variables } = useTheme();
+  const titleID = useId();
+  const descriptionID = useId();
+  const [webMounted, setWebMounted] = useState(false);
+  useEffect(() => {
+    // RNW has no server portal; keep the initial hydration render identical.
+    if (Platform.OS === 'web') setWebMounted(true);
+  }, []);
+  const [, refreshPortal] = useReducer((count: number) => count + 1, 0);
+  useEffect(() => {
+    // RNW 0.21.4 StrictMode cleanup can clear its render-created portal ref.
+    // One ordinary rerender recreates it while preserving the Modal's identity.
+    if (Platform.OS === 'web' && isOpen && webMounted) refreshPortal();
+  }, [isOpen, webMounted]);
+  const canRender = Platform.OS !== 'web' || webMounted;
+  useWebScrollLock(isOpen && canRender);
+  // RNW captures the current trigger on mount and restores it on unmount.
+  if (!isOpen || !canRender) return null;
+  return <Modal transparent visible animationType="none" onRequestClose={() => setOpen(false)} accessibilityLabel={title} aria-labelledby={titleID} {...(description ? { 'aria-describedby': descriptionID } : {})}>
+    <View className={cn('flex-1 px-4 py-6', sheet ? 'justify-end' : 'justify-center')} style={variables}>
+      <View testID={testID ? `${testID}-backdrop` : undefined} accessible={false} onStartShouldSetResponder={() => dismissOnBackdropPress} onResponderRelease={() => { if (dismissOnBackdropPress) setOpen(false); }} className="absolute inset-0 bg-black/50" />
+      <View {...props} testID={testID} accessibilityViewIsModal className={cn('w-full self-center bg-ui-surface p-6', sheet ? 'max-h-[85%] max-w-[720px] rounded-t-xl' : 'max-h-[85%] max-w-[560px] rounded-xl', className)} style={style}>
+        <View className="mb-4 flex-row items-start justify-between gap-4">
+          <View className="min-w-0 flex-1 gap-2">
+            <Heading nativeID={titleID} level={2}>{title}</Heading>
+            {description ? <Text nativeID={descriptionID} tone="muted">{description}</Text> : null}
+          </View>
+          <Pressable accessibilityRole="button" accessibilityLabel={closeLabel} onPress={() => setOpen(false)} className={cn('min-h-[44px] min-w-[44px] items-center justify-center rounded px-2', focusRing)}><Text variant="small" className="font-semibold text-ui-link">{closeLabel}</Text></Pressable>
+        </View>
+        <ScrollView keyboardShouldPersistTaps="handled" className={cn('shrink', contentClassName)}>{children}</ScrollView>
+      </View>
+    </View>
+  </Modal>;
+}
+
+/** Controlled or initially open modal dialog; supplies no hidden trigger. */
+export function Dialog(props: DialogProps) { return <Overlay {...props} />; }
+export type SheetProps = DialogProps;
+/** Bottom-aligned, scrollable modal sheet with the same dismissal contract. */
+export function Sheet(props: SheetProps) { return <Overlay {...props} sheet />; }

package/src/components/typography.tsx

@@ -0,0 +1,31 @@
+'use client';
+
+import { forwardRef, type ElementRef } from 'react';
+import { Text as NativeText, Platform, type TextProps as NativeTextProps } from 'react-native';
+import { cn } from '../internal/utils';
+
+export type TextTone = 'default' | 'muted' | 'info' | 'success' | 'warning' | 'error';
+export type TextVariant = 'body' | 'lead' | 'small' | 'label' | 'caption' | 'code';
+const tones = { default: 'text-ui-text', muted: 'text-ui-muted', info: 'text-ui-info', success: 'text-ui-success', warning: 'text-ui-warning', error: 'text-ui-error' };
+const variants = { body: 'text-base leading-6', lead: 'text-lg leading-7', small: 'text-sm leading-5', label: 'text-base leading-6 font-semibold', caption: 'text-xs leading-4', code: 'font-mono text-sm leading-6' };
+
+export interface TextProps extends NativeTextProps {
+  tone?: TextTone;
+  variant?: TextVariant;
+  className?: string;
+}
+
+export const Text = forwardRef<ElementRef<typeof NativeText>, TextProps>(function Text({ tone = 'default', variant = 'body', className, ...props }, ref) {
+  return <NativeText {...props} ref={ref} className={cn(variants[variant], tones[tone], className)} />;
+});
+
+export interface HeadingProps extends NativeTextProps {
+  level?: 1 | 2 | 3 | 4 | 5 | 6;
+  className?: string;
+}
+const levels = { 1: 'text-3xl leading-10', 2: 'text-2xl leading-8', 3: 'text-xl leading-7', 4: 'text-lg leading-6', 5: 'text-base leading-6', 6: 'text-sm leading-5' };
+
+export const Heading = forwardRef<ElementRef<typeof NativeText>, HeadingProps>(function Heading({ level = 2, className, ...props }, ref) {
+  const webLevel = Platform.OS === 'web' ? { 'aria-level': level } : {};
+  return <NativeText {...props} {...webLevel} ref={ref} accessibilityRole="header" className={cn('font-bold text-ui-heading', levels[level], className)} />;
+});

package/src/index.ts

@@ -0,0 +1,25 @@
+'use client';
+
+export { Button } from './components/Button';
+export type { ButtonProps, ButtonSize, ButtonVariant } from './components/Button';
+export { Text, Heading } from './components/typography';
+export type { TextProps, TextTone, TextVariant, HeadingProps } from './components/typography';
+export { Stack, Inline, Container, Card, Divider } from './components/layout';
+export type { StackProps, InlineProps, ContainerProps, CardProps, DividerProps } from './components/layout';
+export { IconButton, Link } from './components/actions';
+export type { IconButtonProps, LinkProps } from './components/actions';
+export { Badge, Avatar, ListItem, EmptyState } from './components/content';
+export type { BadgeProps, AvatarProps, ListItemProps, EmptyStateProps, StatusTone } from './components/content';
+export { Accordion } from './components/disclosure';
+export type { AccordionProps, AccordionItem } from './components/disclosure';
+export { Dialog, Sheet } from './components/overlays';
+export type { DialogProps, SheetProps } from './components/overlays';
+export { Alert, Toast, Spinner, Progress, Skeleton } from './components/feedback';
+export type { AlertProps, ToastProps, SpinnerProps, ProgressProps, SkeletonProps } from './components/feedback';
+export { Breadcrumbs, Pagination } from './components/navigation';
+export type { BreadcrumbItem, BreadcrumbsProps, PaginationProps } from './components/navigation';
+export { ThemeProvider, useTheme, themeVariables } from './theme';
+export type { ThemeProviderProps, Appearance, ResolvedAppearance, ThemeColor, ThemeColors } from './theme';
+export * from './components/forms';
+export { tokens } from './tokens';
+export type { BubbaTokens } from './tokens';

package/src/internal/scroll-lock.ts

@@ -0,0 +1,101 @@
+import { useEffect } from 'react';
+import { Platform } from 'react-native';
+
+// Structural browser types keep the native package independent of lib.dom.
+interface InlineStyle {
+  getPropertyValue(name: string): string;
+  getPropertyPriority(name: string): string;
+  setProperty(name: string, value: string, priority?: string): void;
+  removeProperty(name: string): string;
+}
+interface StyledElement { style: InlineStyle }
+interface ScrollDocument {
+  body: StyledElement | null;
+  documentElement: StyledElement & { clientWidth: number };
+  defaultView: {
+    scrollX: number;
+    scrollY: number;
+    getComputedStyle(element: StyledElement): { paddingRight: string };
+    scrollTo(x: number, y: number): void;
+  } | null;
+}
+interface ScrollLock { count: number; restore: () => void }
+const locks = new WeakMap<ScrollDocument, ScrollLock>();
+const overflowProperties = ['overflow', 'overflow-x', 'overflow-y'];
+const overscrollProperties = ['overscroll-behavior', 'overscroll-behavior-x', 'overscroll-behavior-y'];
+
+function preserve(style: InlineStyle, properties: string[]) {
+  const previous = properties.map((property) => ({
+    property,
+    value: style.getPropertyValue(property),
+    priority: style.getPropertyPriority(property),
+  }));
+  return () => {
+    for (const { property, value, priority } of previous) {
+      if (value) style.setProperty(property, value, priority);
+      else style.removeProperty(property);
+    }
+  };
+}
+
+function acquire(document: ScrollDocument) {
+  let lock = locks.get(document);
+  if (!lock) {
+    const body = document.body;
+    const view = document.defaultView;
+    if (!body || !view) return;
+    const root = document.documentElement;
+    const { scrollX, scrollY } = view;
+    const width = root.clientWidth;
+    const paddingRight = Number.parseFloat(view.getComputedStyle(body).paddingRight) || 0;
+    const restoreRoot = preserve(root.style, [...overflowProperties, ...overscrollProperties]);
+    const restoreBody = preserve(body.style, [
+      ...overflowProperties, ...overscrollProperties, 'position', 'top', 'left', 'right', 'padding-right',
+    ]);
+    const restoreScrollBehavior = preserve(root.style, ['scroll-behavior']);
+
+    root.style.setProperty('scroll-behavior', 'auto', 'important');
+    root.style.setProperty('overflow', 'hidden', 'important');
+    root.style.setProperty('overscroll-behavior', 'none', 'important');
+    body.style.setProperty('overflow', 'hidden', 'important');
+    body.style.setProperty('overscroll-behavior', 'none', 'important');
+    body.style.setProperty('position', 'fixed', 'important');
+    body.style.setProperty('top', `${-scrollY}px`, 'important');
+    body.style.setProperty('left', `${-scrollX}px`, 'important');
+    body.style.setProperty('right', `${scrollX}px`, 'important');
+    // Measure the actual change so existing stable/thin scrollbar styling is respected.
+    const compensation = Math.max(0, root.clientWidth - width);
+    if (compensation > 0) body.style.setProperty('padding-right', `${paddingRight + compensation}px`, 'important');
+
+    lock = {
+      count: 0,
+      restore: () => {
+        restoreRoot();
+        restoreBody();
+        view.scrollTo(scrollX, scrollY);
+        restoreScrollBehavior();
+      },
+    };
+    locks.set(document, lock);
+  }
+  lock.count += 1;
+  let released = false;
+  return () => {
+    if (released) return;
+    released = true;
+    lock.count -= 1;
+    if (lock.count === 0) {
+      lock.restore();
+      locks.delete(document);
+    }
+  };
+}
+
+/** One page lock survives nested dialogs; modal ScrollViews remain scrollable. */
+export function useWebScrollLock(active: boolean) {
+  useEffect(() => {
+    if (!active || Platform.OS !== 'web') return;
+    const document = (globalThis as unknown as { document?: ScrollDocument }).document;
+    return document ? acquire(document) : undefined;
+  }, [active]);
+}

package/src/internal/utils.ts

@@ -0,0 +1,32 @@
+import { useCallback, useRef, useState } from 'react';
+import { twMerge } from 'tailwind-merge';
+
+export function cn(...values: (string | false | null | undefined)[]) {
+  return twMerge(values.filter(Boolean).join(' '));
+}
+
+export const focusRing = 'web:focus-visible:outline web:focus-visible:outline-2 web:focus-visible:outline-offset-2 web:focus-visible:outline-ui-focus';
+
+/** Controlled values are never silently copied into local state. */
+export function useControllableState<T>({ value, defaultValue, onChange }: {
+  value?: T;
+  defaultValue: T;
+  onChange?: (value: T) => void;
+}) {
+  const [local, setLocal] = useState(defaultValue);
+  const controlled = value !== undefined;
+  const current = controlled ? value : local;
+  const currentRef = useRef(current);
+  currentRef.current = current;
+  const onChangeRef = useRef(onChange);
+  onChangeRef.current = onChange;
+  const setValue = useCallback((next: T) => {
+    if (Object.is(currentRef.current, next)) return;
+    if (!controlled) {
+      currentRef.current = next;
+      setLocal(next);
+    }
+    onChangeRef.current?.(next);
+  }, [controlled]);
+  return [current, setValue] as const;
+}

package/src/theme.tsx

@@ -0,0 +1,56 @@
+'use client';
+
+import { createContext, useContext, useMemo, type ReactNode } from 'react';
+import { View, useColorScheme, type ViewProps } from 'react-native';
+import { vars } from 'nativewind';
+import { tokens } from './tokens';
+import { cn } from './internal/utils';
+
+export type Appearance = 'light' | 'dark' | 'system';
+export type ResolvedAppearance = 'light' | 'dark';
+export type ThemeColor = Exclude<keyof typeof tokens.themes.light, `shadow-${string}`>;
+export type ThemeColors = { [Key in ThemeColor]: string };
+
+function rgb(hex: string) {
+  return [1, 3, 5].map((start) => parseInt(hex.slice(start, start + 2), 16)).join(' ');
+}
+
+export function themeVariables(appearance: ResolvedAppearance) {
+  return vars(Object.fromEntries(Object.entries(tokens.themes[appearance])
+    .filter(([, value]) => value.startsWith('#'))
+    .map(([key, value]) => [`--bui-${key}`, rgb(value)])));
+}
+
+function themeValue(appearance: Appearance, resolvedAppearance: ResolvedAppearance) {
+  return {
+    appearance,
+    resolvedAppearance,
+    colors: Object.fromEntries(Object.entries(tokens.themes[resolvedAppearance])
+      .filter(([, value]) => value.startsWith('#'))) as ThemeColors,
+    variables: themeVariables(resolvedAppearance),
+  };
+}
+
+const ThemeContext = createContext(themeValue('light', 'light'));
+
+export interface ThemeProviderProps extends ViewProps {
+  children: ReactNode;
+  appearance?: Appearance;
+  className?: string;
+}
+
+/** Scoped variables support nested themes without changing global appearance. */
+export function ThemeProvider({ appearance = 'light', children, className, style, ...props }: ThemeProviderProps) {
+  const system = useColorScheme();
+  const resolved = appearance === 'system' ? system === 'dark' ? 'dark' : 'light' : appearance;
+  const value = useMemo(() => themeValue(appearance, resolved), [appearance, resolved]);
+  return (
+    <ThemeContext.Provider value={value}>
+      <View {...props} className={cn('bg-ui-canvas', className)} style={[value.variables, style]}>
+        {children}
+      </View>
+    </ThemeContext.Provider>
+  );
+}
+
+export function useTheme() { return useContext(ThemeContext); }