expo-interface 0.2.0 → 0.3.0

package/src/fab/types.ts

@@ -0,0 +1,39 @@
+import type {IconToken} from '../icons';
+import type {MenuItem} from '../menu/types';
+
+/**
+ * Size of a `Fab`. `regular`, `small` and `large` are circles (56, 40 and
+ * 96 points); `extended` is a capsule that shows the label beside the icon.
+ */
+export type FabSize = 'small' | 'regular' | 'large' | 'extended';
+
+/**
+ * Floating action button: the screen's primary action, floating over its
+ * content at the bottom trailing corner (`Screen`'s `fab` slot places it).
+ *
+ * Android renders the Material 3 `FloatingActionButton` family; iOS, which
+ * has no such control, draws the same geometry in SwiftUI (a circle or
+ * capsule filled with the tint, the icon in `onTint`, a soft shadow); web
+ * renders a DOM button with that geometry. With `items` the button opens a
+ * menu instead of pressing: the same menu `Menu` renders, only the trigger
+ * differs.
+ */
+export interface FabProps {
+  /** Accessibility name of the button, and the text of an `extended` one. */
+  label: string;
+  /** The icon. */
+  icon: IconToken;
+  /** Called when the button is pressed (ignored when `items` are given). */
+  onPress?: () => void;
+  /** With items the button opens a menu instead of pressing. */
+  items?: MenuItem[];
+  /**
+   * The size.
+   * @default 'regular'
+   */
+  size?: FabSize;
+  /** Disables interaction and dims the button. */
+  disabled?: boolean;
+  /** Identifier used to locate the button in end-to-end tests. */
+  testID?: string;
+}

package/src/field-group/index.android.tsx

@@ -1,12 +1,8 @@
 import type {ReactNode, ReactElement} from 'react';
-import type {
-  FieldGroupProps,
-  FieldSectionProps,
-  FieldSectionHeaderProps,
-  FieldSectionFooterProps,
-} from '@expo/ui';
+import type {FieldSectionHeaderProps, FieldSectionFooterProps} from '@expo/ui';
+import type {FieldGroupProps, FieldGroupSectionProps} from './types';
 import {Children, Fragment, isValidElement} from 'react';
-import {Box, Column, LazyColumn, Text} from '@expo/ui/jetpack-compose';
+import {Box, Column, Text} from '@expo/ui/jetpack-compose';
 import {
   background,
   clip,
@@ -15,6 +11,7 @@ import {
   padding,
   Shapes,
   testID as testIDModifier,
+  verticalScroll,
   type ModifierConfig,
 } from '@expo/ui/jetpack-compose/modifiers';
 import {useColor} from '../theme';
@@ -22,6 +19,12 @@ import {useColor} from '../theme';
 /**
  * Android `FieldGroup`. Mirrors `@expo/ui`'s Material 3 connected-list
  * layout, with app deviations for web parity:
+ * - the group is a scrolling `Column`, not a `LazyColumn`: a lazy list
+ *   disposes and recomposes its items as it scrolls and on any state change,
+ *   and every React Native view hosted inside an item is then added to the
+ *   view tree a second time while still attached ("The specified child
+ *   already has a parent"). A settings form has a dozen rows and does not
+ *   need laziness; composed once, its rows can hold anything the kit offers;
  * - the group has no background (the universal one paints the Host palette's
  *   `surface`, a grey panel over the app's screen background);
  * - rows use the `backgroundElement` token instead of the seeded
@@ -33,16 +36,13 @@ import {useColor} from '../theme';
  */
 function FieldGroupBase({children, style, hidden, testID}: FieldGroupProps) {
   if (hidden) return null;
-  const modifiers: ModifierConfig[] = [];
+  const modifiers: ModifierConfig[] = [fillMaxWidth(), verticalScroll(), padding(16, 16, 16, 16)];
   if (style?.backgroundColor) modifiers.push(background(String(style.backgroundColor)));
   if (testID) modifiers.push(testIDModifier(testID));
   return (
-    <LazyColumn
-      verticalArrangement={{spacedBy: 24}}
-      contentPadding={{start: 16, end: 16, top: 16, bottom: 16}}
-      modifiers={modifiers}>
+    <Column verticalArrangement={{spacedBy: 24}} modifiers={modifiers}>
       {groupChildren(children)}
-    </LazyColumn>
+    </Column>
   );
 }
 
@@ -56,9 +56,10 @@ function SectionFooter(props: FieldSectionFooterProps) {
   return <>{props.children}</>;
 }
 
-function Section({children, title, titleUppercase = false, hidden}: FieldSectionProps) {
+function Section({children, title, titleUppercase = false, hidden, footer: footerText, footerColor = 'secondaryLabel'}: FieldGroupSectionProps) {
   const card = useColor('backgroundElement');
   const subtle = useColor('secondaryLabel');
+  const danger = useColor('destructive');
   const label = useColor('label');
   if (hidden) return null;
 
@@ -70,6 +71,11 @@ function Section({children, title, titleUppercase = false, hidden}: FieldSection
       {titleUppercase ? title.toUpperCase() : title}
     </Text>
   ) : null);
+  const footerNode = footer ?? (footerText != null ? (
+    <Text color={footerColor === 'destructive' ? danger : subtle} style={{typography: 'bodySmall'}}>
+      {footerText}
+    </Text>
+  ) : null);
 
   return (
     <Column verticalArrangement={{spacedBy: 4}} modifiers={[fillMaxWidth()]}>
@@ -94,7 +100,7 @@ function Section({children, title, titleUppercase = false, hidden}: FieldSection
           ))}
         </Column>
       ) : null}
-      {footer ? <Column modifiers={[padding(16, 4, 16, 0)]}>{footer}</Column> : null}
+      {footerNode ? <Column modifiers={[padding(16, 4, 16, 0)]}>{footerNode}</Column> : null}
     </Column>
   );
 }
@@ -105,7 +111,7 @@ export const FieldGroup = Object.assign(FieldGroupBase, {
   SectionFooter,
 });
 
-export type {FieldGroupProps};
+export type {FieldGroupProps, FieldGroupSectionProps};
 
 /**
  * Per-position corner radii producing the Material 3 grouped-list look:

package/src/field-group/index.tsx

@@ -1,8 +1,39 @@
+import type {FieldGroupProps, FieldGroupSectionProps, FieldSectionFooterColor} from './types';
+import {FieldGroup as Base} from '@expo/ui';
+import {Text} from '@expo/ui/swift-ui';
+import {font, foregroundStyle} from '@expo/ui/swift-ui/modifiers';
+import {useColor} from '../theme';
+import {baseSection, mapSections} from './shared';
+
 /**
  * App `FieldGroup`: a scrollable container of grouped settings-style rows.
- * iOS uses `@expo/ui`'s SwiftUI `Form`. Android (`index.android.tsx`) keeps
- * the Material 3 connected-list look with app palette colors. Web
- * (`index.web.tsx` + `field-group.css`) re-themes the universal component via
- * CSS instead of forking its layout.
+ * iOS (this file) uses `@expo/ui`'s SwiftUI `Form`, whose `Section` gains
+ * the `footer` prop as the native section footer slot. Android
+ * (`index.android.tsx`) keeps the Material 3 connected-list look with app
+ * palette colors. Web (`index.web.tsx` + `field-group.css`) re-themes the
+ * universal component via CSS instead of forking its layout.
  */
-export {FieldGroup, type FieldGroupProps} from '@expo/ui';
+
+/** The section `footer` as SwiftUI text, in the footnote size and the token's color. */
+function FooterText({color, children}: {color: FieldSectionFooterColor; children: string}) {
+  const resolved = useColor(color);
+  return <Text modifiers={[foregroundStyle({type: 'color', color: resolved}), font({size: 13})]}>{children}</Text>;
+}
+
+const renderFooter = (footer: string, color: FieldSectionFooterColor) => <FooterText color={color}>{footer}</FooterText>;
+
+function Section(props: FieldGroupSectionProps) {
+  return baseSection(props, renderFooter);
+}
+
+function FieldGroupBase({children, ...props}: FieldGroupProps) {
+  return <Base {...props}>{mapSections(children, Section, renderFooter)}</Base>;
+}
+
+export const FieldGroup = Object.assign(FieldGroupBase, {
+  Section,
+  SectionHeader: Base.SectionHeader,
+  SectionFooter: Base.SectionFooter,
+});
+
+export type {FieldGroupProps, FieldGroupSectionProps};

package/src/field-group/index.web.tsx

@@ -1,24 +1,40 @@
 import './field-group.css';
-import {FieldGroup as BaseFieldGroup, type FieldGroupProps} from '@expo/ui';
+import type {FieldGroupProps, FieldGroupSectionProps, FieldSectionFooterColor} from './types';
+import {FieldGroup as Base} from '@expo/ui';
+import {Footnote} from '../typography';
+import {baseSection, mapSections} from './shared';
+
+const renderFooter = (footer: string, color: FieldSectionFooterColor) => <Footnote color={color}>{footer}</Footnote>;
+
+/**
+ * Web: the universal `FieldGroup.Section` with the `footer` prop as its
+ * footer slot, drawn as the kit's `Footnote`.
+ */
+function Section(props: FieldGroupSectionProps) {
+  return baseSection(props, renderFooter);
+}
 
 /**
  * Web hook for `field-group.css`. Clears the universal component's hardcoded
  * scroll background so the wrapper supplies the app palette; section cards
  * and row dividers are recolored to the kit tokens in the CSS.
  */
-function FieldGroup({style, ...props}: FieldGroupProps) {
+function FieldGroupBase({style, children, ...props}: FieldGroupProps) {
   return (
     <div className="field-group">
-      <BaseFieldGroup
+      <Base
         {...props}
-        style={{...style, backgroundColor: 'transparent'}}
-      />
+        style={{...style, backgroundColor: 'transparent'}}>
+        {mapSections(children, Section, renderFooter)}
+      </Base>
     </div>
   );
 }
 
-FieldGroup.Section = BaseFieldGroup.Section;
-FieldGroup.SectionHeader = BaseFieldGroup.SectionHeader;
-FieldGroup.SectionFooter = BaseFieldGroup.SectionFooter;
+export const FieldGroup = Object.assign(FieldGroupBase, {
+  Section,
+  SectionHeader: Base.SectionHeader,
+  SectionFooter: Base.SectionFooter,
+});
 
-export {FieldGroup, type FieldGroupProps};
+export type {FieldGroupProps, FieldGroupSectionProps};

package/src/field-group/shared.tsx

@@ -0,0 +1,49 @@
+import type {ComponentType, ReactElement, ReactNode} from 'react';
+import type {FieldGroupSectionProps, FieldSectionFooterColor} from './types';
+import {Children, Fragment, isValidElement} from 'react';
+import {FieldGroup as Base} from '@expo/ui';
+
+/** Renders the `footer` prop's text in the platform's own text control. */
+export type FooterRenderer = (footer: string, color: FieldSectionFooterColor) => ReactNode;
+
+/** Whether the section's children already carry a `SectionFooter` slot. */
+export function hasFooterSlot(children: ReactNode): boolean {
+  return Children.toArray(children).some(child => isValidElement(child) && child.type === Base.SectionFooter);
+}
+
+/**
+ * The universal `FieldGroup.Section` with the `footer` prop turned into a
+ * `SectionFooter` slot (unless the children carry one already).
+ */
+export function baseSection(
+  {footer, footerColor = 'secondaryLabel', children, ...props}: FieldGroupSectionProps,
+  renderFooter: FooterRenderer,
+): ReactElement {
+  const note = footer != null && !hasFooterSlot(children) ? (
+    <Base.SectionFooter>{renderFooter(footer, footerColor)}</Base.SectionFooter>
+  ) : null;
+  return (
+    <Base.Section {...props}>
+      {children}
+      {note}
+    </Base.Section>
+  );
+}
+
+/**
+ * The universal `FieldGroup` groups loose rows into implicit sections by
+ * checking each child's type against its own `Section`, so a kit `Section`
+ * wrapping it would be grouped as a row. The kit sections are therefore
+ * replaced by the universal ones (with the footer slot) before the children
+ * reach the group; fragments are walked like the group walks them.
+ */
+export function mapSections(children: ReactNode, Section: ComponentType<FieldGroupSectionProps>, renderFooter: FooterRenderer): ReactNode {
+  return Children.map(children, child => {
+    if (!isValidElement(child)) return child;
+    if (child.type === Section) return baseSection(child.props as FieldGroupSectionProps, renderFooter);
+    if (child.type === Fragment) {
+      return <Fragment>{mapSections((child.props as {children?: ReactNode}).children, Section, renderFooter)}</Fragment>;
+    }
+    return child;
+  });
+}

package/src/field-group/types.ts

@@ -0,0 +1,25 @@
+import type {FieldGroupProps, FieldSectionProps} from '@expo/ui';
+
+/** Color of a section's `footer` text. */
+export type FieldSectionFooterColor = 'secondaryLabel' | 'destructive';
+
+/**
+ * Props of `FieldGroup.Section`: `@expo/ui`'s, plus a plain-text footer.
+ * SwiftUI's `Section` has a footer, the web draws a caption under the group
+ * and Android under the rows, so a note under a section (what a setting
+ * does, why it failed) is one prop on every platform.
+ */
+export interface FieldGroupSectionProps extends FieldSectionProps {
+  /**
+   * A note under the rows, in the secondary color. Ignored when a
+   * `<FieldGroup.SectionFooter>` child is given.
+   */
+  footer?: string;
+  /**
+   * Color of the footer text: `destructive` for an error.
+   * @default 'secondaryLabel'
+   */
+  footerColor?: FieldSectionFooterColor;
+}
+
+export type {FieldGroupProps};

package/src/header-menu/index.tsx

@@ -0,0 +1,76 @@
+import type {ButtonTone} from '../button/types';
+import type {IconToken} from '../icons';
+import type {MenuItem} from '../menu/types';
+import {Platform} from 'react-native';
+import {useIsFocused} from 'expo-router';
+import {NativeHost} from '../host';
+import {Menu} from '../menu';
+
+export interface HeaderMenuProps {
+  /** Trigger text (kept for accessibility when `hideLabel` is set). */
+  label: string;
+  /** Trigger icon. */
+  icon?: IconToken;
+  /** Entries shown when the menu opens. */
+  items: MenuItem[];
+  /** Show only the icon; `label` is kept for accessibility. */
+  hideLabel?: boolean;
+  /**
+   * Color of the trigger: the accent, or the label color like the header's
+   * own buttons.
+   * @default 'accent'
+   */
+  tone?: ButtonTone;
+  /** Disables the trigger. */
+  disabled?: boolean;
+  /** Identifier used to locate the trigger in end-to-end tests. */
+  testID?: string;
+}
+
+/**
+ * A `Menu` for a stack header's trailing slot (`TabStack`'s `headerRight`,
+ * a `Stack.Screen`'s `headerRight` option): a small text trigger in its own
+ * accent-seeded host, so it can live in the React Native header.
+ *
+ * On Android the native stack re-parents the header's views on a tab switch,
+ * and a Compose view refuses a second parent ("The specified child already
+ * has a parent"). The host is therefore keyed on the screen's focus, so the
+ * Compose view is created afresh each time the header is rebuilt rather
+ * than re-added. Needs a navigator above it on Android (it reads the
+ * screen's focus); on web it is the plain `Menu` trigger, for a custom
+ * header such as `ConstrainedStackHeader`.
+ */
+export function HeaderMenu(props: HeaderMenuProps) {
+  if (Platform.OS === 'web') return <HeaderMenuTrigger {...props}/>;
+  if (Platform.OS === 'android') return <AndroidHeaderMenu {...props}/>;
+  return (
+    <NativeHost fit>
+      <HeaderMenuTrigger {...props}/>
+    </NativeHost>
+  );
+}
+
+function HeaderMenuTrigger({label, icon, items, hideLabel, tone = 'accent', disabled, testID}: HeaderMenuProps) {
+  return (
+    <Menu
+      label={label}
+      icon={icon}
+      items={items}
+      hideLabel={hideLabel}
+      tone={tone}
+      disabled={disabled}
+      variant="text"
+      size="small"
+      testID={testID}
+    />
+  );
+}
+
+function AndroidHeaderMenu(props: HeaderMenuProps) {
+  // Keyed on the screen's focus: a fresh host, and Compose view, per rebuild.
+  return (
+    <NativeHost key={useIsFocused() ? 'focused' : 'blurred'} fit>
+      <HeaderMenuTrigger {...props}/>
+    </NativeHost>
+  );
+}

package/src/host/index.tsx

@@ -0,0 +1,32 @@
+import type {PropsWithChildren} from 'react';
+import type {StyleProp, ViewStyle} from 'react-native';
+import {Host} from '@expo/ui';
+import {useAccentSeed} from '../accent';
+import {hostAccentProps} from '../screen/host-accent';
+
+export interface NativeHostProps extends PropsWithChildren {
+  style?: StyleProp<ViewStyle>;
+  /**
+   * Size the host to its content on both axes (a group of buttons in a row);
+   * by default only vertically, the width filling its container.
+   * @default false
+   */
+  fit?: boolean;
+}
+
+/**
+ * An accent-seeded `@expo/ui` `Host` for controls that sit inside a React
+ * Native layout: a toolbar next to a canvas, a search row, a floating
+ * button. `Screen native` mounts the same host around a whole screen; this
+ * one is for the places a screen cannot be native, sized to its content and
+ * seeded like the screen would be (`hostAccentProps`). On web it is a plain
+ * view carrying the `@expo/ui` palette.
+ */
+export function NativeHost({children, style, fit = false}: NativeHostProps) {
+  const seed = useAccentSeed();
+  return (
+    <Host matchContents={fit ? true : {vertical: true}} style={style} {...hostAccentProps(seed)}>
+      {children}
+    </Host>
+  );
+}

package/src/index.ts

@@ -4,22 +4,36 @@ export * from './theme';
 export * from './accent';
 export * from './icons';
 export {fillWidth} from './fill';
+export {
+  SCHEME_STORAGE_KEY,
+  getColorSchemeMode,
+  getThemeBootScript,
+  setColorScheme,
+  useColorScheme,
+} from './scheme';
+export type {ColorScheme, ColorSchemeMode} from './scheme';
 
 // Layout
 export {Screen} from './screen';
+export type {ScreenProps} from './screen';
 export {ScreenHeader} from './screen/header';
 export {hostAccentProps} from './screen/host-accent';
+export {NativeHost} from './host';
+export type {NativeHostProps} from './host';
 export {Sheet} from './sheet';
 export {ConstrainedStackHeader} from './stack-header';
 export {TabStack} from './tab-stack';
+export type {TabStackProps} from './tab-stack';
 export {Tabs} from './tabs';
 export type {TabBarProps, TabRoute, WebLogo} from './tabs/types';
+export {KeyboardBar} from './keyboard';
+export type {KeyboardBarProps, KeyboardLibrary, KeyboardState} from './keyboard';
 
 // Components
 export {Alert} from './alert';
 export type {AlertAction, AlertActionRole, AlertProps} from './alert/types';
 export {Button} from './button';
-export type {ButtonProps, ButtonRole, ButtonShape, ButtonSize, ButtonVariant} from './button/types';
+export type {ButtonProps, ButtonRole, ButtonShape, ButtonSize, ButtonTone, ButtonVariant} from './button/types';
 export {Checkbox} from './checkbox';
 export type {CheckboxProps} from './checkbox/types';
 export {Collapsible} from './collapsible';
@@ -31,13 +45,18 @@ export {DateTimePicker} from './date-time';
 export type {DateTimeMode, DateTimePickerProps} from './date-time/types';
 export {Divider} from './divider';
 export type {DividerProps} from './divider/types';
-export {FieldGroup, type FieldGroupProps} from './field-group';
+export {Fab} from './fab';
+export type {FabProps, FabSize} from './fab/types';
+export {FieldGroup} from './field-group';
+export type {FieldGroupProps, FieldGroupSectionProps, FieldSectionFooterColor} from './field-group/types';
 export {Gauge} from './gauge';
 export type {GaugeProps, GaugeVariant} from './gauge/types';
+export {HeaderMenu} from './header-menu';
+export type {HeaderMenuProps} from './header-menu';
 export {ListItem} from './list-item';
-export type {ListItemProps} from './list-item/types';
+export type {ListItemAction, ListItemProps} from './list-item/types';
 export {Menu} from './menu';
-export type {ContextMenuProps, MenuItem, MenuProps} from './menu/types';
+export type {ContextMenuProps, MenuItem, MenuPoint, MenuProps, MenuTrigger} from './menu/types';
 export {Picker} from './picker';
 export type {PickerItemProps, PickerOption, PickerProps, PickerValue} from './picker/types';
 export {Progress} from './progress';
@@ -53,7 +72,14 @@ export type {SwitchProps} from './switch/types';
 export {Tooltip} from './tooltip';
 export type {TooltipProps} from './tooltip/types';
 export {TextField} from './text-field';
-export type {TextFieldCapitalize, TextFieldKeyboard, TextFieldProps} from './text-field/types';
+export type {
+  TextFieldCapitalize,
+  TextFieldKeyboard,
+  TextFieldProps,
+  TextFieldReturnKey,
+  TextFieldSubmitBehavior,
+  TextFieldVariant,
+} from './text-field/types';
 export {ExternalLink} from './router/external-link';
 
 // Typography

package/src/keyboard/index.tsx

@@ -0,0 +1,81 @@
+import type {PropsWithChildren} from 'react';
+import type {StyleProp, ViewStyle} from 'react-native';
+import type {KeyboardLibrary} from './types';
+import {useCallback, useEffect, useRef, useState} from 'react';
+import {StyleSheet, useWindowDimensions, View} from 'react-native';
+import {useColor} from '../theme';
+import {loadKeyboardController} from './library';
+
+/** The keyboard library, when the app has it: loaded once, natively only. */
+const library = loadKeyboardController();
+
+export interface KeyboardBarProps extends PropsWithChildren {
+  /**
+   * The keyboard's height from the screen's bottom edge once it is up, `0`
+   * once it is away, for the screen's content to pad or scroll by (it is
+   * not resized: the bar rides over it).
+   */
+  onKeyboard?: (height: number) => void;
+  /** Style of the bar (its background is the screen's, opaque). */
+  style?: StyleProp<ViewStyle>;
+}
+
+/**
+ * A bottom bar that sticks to the keyboard: it rides up on it by a
+ * transform animated with the keyboard on the UI thread, so the layout never
+ * changes (no resize, no lines shaking with the animation), and reports the
+ * keyboard's height instead so the content can keep its caret above it.
+ * Opaque in `background`, since it rides over the content's bottom.
+ *
+ * Needs `react-native-keyboard-controller` (an optional peer, whose
+ * `KeyboardProvider` the kit's `AccentProvider` mounts natively); without it,
+ * and on web, where the browser keeps the page above the keyboard itself,
+ * the bar is a plain view.
+ */
+export function KeyboardBar({children, onKeyboard, style}: KeyboardBarProps) {
+  const background = useColor('background');
+  if (!library) {
+    return <View style={[{backgroundColor: background}, style]}>{children}</View>;
+  }
+  return (
+    <Sticky library={library} background={background} onKeyboard={onKeyboard} style={style}>
+      {children}
+    </Sticky>
+  );
+}
+
+interface StickyProps extends KeyboardBarProps {
+  library: KeyboardLibrary;
+  background: string;
+}
+
+function Sticky({library: {KeyboardStickyView, useKeyboardState}, background, children, onKeyboard, style}: StickyProps) {
+  const height = useKeyboardState(s => (s.isVisible ? s.height : 0));
+  useEffect(() => {
+    onKeyboard?.(height);
+  }, [height, onKeyboard]);
+  // The keyboard's height is from the window's bottom edge, the bar sits
+  // above the navigation inset: the sticky translation is corrected by what
+  // lies under the bar, measured while the keyboard is away (a measure while
+  // it is up would see the bar moved).
+  const window = useWindowDimensions().height;
+  const view = useRef<View>(null);
+  const [below, setBelow] = useState(0);
+  const onLayout = useCallback(() => {
+    if (height > 0) return;
+    view.current?.measureInWindow((_x, y, _w, h) => setBelow(Math.max(0, window - (y + h))));
+  }, [height, window]);
+  return (
+    <KeyboardStickyView offset={{opened: below}}>
+      <View ref={view} onLayout={onLayout} style={[styles.bar, {backgroundColor: background}, style]}>
+        {children}
+      </View>
+    </KeyboardStickyView>
+  );
+}
+
+const styles = StyleSheet.create({
+  bar: {width: '100%'},
+});
+
+export type {KeyboardLibrary, KeyboardState} from './types';

package/src/keyboard/library.native.ts

@@ -0,0 +1,17 @@
+import type {KeyboardLibrary} from './types';
+
+/**
+ * iOS and Android: `react-native-keyboard-controller` when the app has it
+ * installed (an optional peer), `null` otherwise. The `require` sits in a
+ * `try` so Metro treats the dependency as optional and a bundle without the
+ * library still builds; `KeyboardBar` and `AccentProvider` then fall back to
+ * plain views.
+ */
+export function loadKeyboardController(): KeyboardLibrary | null {
+  try {
+    // eslint-disable-next-line typescript/no-require-imports -- optional peer, resolved only when installed.
+    return require('react-native-keyboard-controller') as KeyboardLibrary;
+  } catch {
+    return null;
+  }
+}

package/src/keyboard/library.ts

@@ -0,0 +1,12 @@
+import type {KeyboardLibrary} from './types';
+
+/**
+ * Web (and any platform without a native keyboard): nothing is loaded. The
+ * browser keeps the page above the keyboard itself, and
+ * `react-native-keyboard-controller` must never reach the web bundle: it is
+ * built on Reanimated, whose server render (the static export) calls
+ * `requestAnimationFrame` and dies. `library.native.ts` loads it natively.
+ */
+export function loadKeyboardController(): KeyboardLibrary | null {
+  return null;
+}

package/src/keyboard/types.ts

@@ -0,0 +1,20 @@
+import type {ComponentType, PropsWithChildren} from 'react';
+
+/** What `react-native-keyboard-controller` reports about the keyboard. */
+export interface KeyboardState {
+  isVisible: boolean;
+  /** The keyboard's height from the window's bottom edge. */
+  height: number;
+}
+
+/**
+ * The pieces of `react-native-keyboard-controller` the kit uses. The library
+ * is an optional peer: `KeyboardBar` sticks to the keyboard through it when
+ * it is installed and is a plain view otherwise (and always on web, where
+ * the library's Reanimated cannot render on the server).
+ */
+export interface KeyboardLibrary {
+  KeyboardProvider: ComponentType<PropsWithChildren>;
+  KeyboardStickyView: ComponentType<PropsWithChildren<{offset?: {closed?: number; opened?: number}}>>;
+  useKeyboardState: <T>(selector: (state: KeyboardState) => T) => T;
+}