# React Native VisuallyHidden, Slot and Portal

> Accessibility and composition primitives for React Native, Expo and the web: VisuallyHidden text for screen readers, a Radix-style Slot for asChild props, and a Portal that draws over the app without a native Modal.

# Primitives

Three small pieces the rest of the library is built from, exported for your own components.

```tsx
import { Portal, PortalHost, Slot, VisuallyHidden } from 'patine-ui';
```

## Example: a cart button

A shop header's cart button shows its count as a small badge, which a screen reader can't make sense of. The badge is hidden from it, and `VisuallyHidden` gives the button the full sentence instead.

```tsx live
import { useState } from 'react';
import { View } from 'react-native';
import { Badge, Button, HStack, Text, VisuallyHidden } from 'patine-ui';
import { Icon } from '@patine-ui/icons';

export default function Example() {
  const [items, setItems] = useState(2);
  return (
    <HStack gap="md" justify="space-between" style={{ width: '100%', maxWidth: 400 }}>
      <Text weight="semibold">Juniper & Co.</Text>
      <HStack gap="sm">
        <Button size="sm" variant="ghost" onPress={() => setItems((n) => n + 1)}>
          Add one
        </Button>
        <View>
          <Button size="icon" variant="outline">
            <Icon name="bag" />
            <VisuallyHidden>{`Cart, ${items} items`}</VisuallyHidden>
          </Button>
          <Badge variant="destructive" style={{ position: 'absolute', top: -6, right: -8 }} accessibilityElementsHidden importantForAccessibility="no-hide-descendants">
            {String(items)}
          </Badge>
        </View>
      </HStack>
    </HStack>
  );
}
```

## VisuallyHidden

Text only screen readers get: a name for an icon, the meaning of a symbol, a hint. It's clipped to nothing rather than hidden, so VoiceOver, TalkBack and browser screen readers all read it.

```tsx live
import { Button, HStack, Text, VisuallyHidden } from 'patine-ui';
import { Icon } from '@patine-ui/icons';

export default function Example() {
  return (
    <HStack gap="sm">
      <Button variant="outline" size="icon">
        <Icon name="bell" />
        <VisuallyHidden>Notifications, 3 unread</VisuallyHidden>
      </Button>
      <Text>
        $199<VisuallyHidden> per year</VisuallyHidden>
        <Text color="textSecondary">/yr</Text>
      </Text>
    </HStack>
  );
}
```

## Slot

Renders its one child with the Slot's props merged in, as Radix's `Slot` does: the way to give your own component an `asChild` prop. Handlers on both run (the child's first), styles stack (the child's on top), and anything else the child sets wins.

```tsx live
import { Button, Slot } from 'patine-ui';

const Trigger = ({ asChild, children, ...props }) => (asChild ? <Slot {...props}>{children}</Slot> : <Button {...props}>{children}</Button>);

export default function Example() {
  const [count, setCount] = React.useState(0);
  return (
    <Trigger asChild onPress={() => setCount((c) => c + 1)}>
      <Button variant="secondary">Pressed {count} times</Button>
    </Trigger>
  );
}
```

## Portal

Draws its children over the rest of the app, in the nearest `PortalHost`, so a floating panel isn't clipped by a scroll view or covered by a sibling. Wrap the app in `PortalHost` once, under `PatineProvider`. Without a host, a `Portal` draws its children where it is.

```tsx
<PatineProvider>
  <PortalHost>
    <App />
  </PortalHost>
</PatineProvider>
```

```tsx live
import { Box, Button, Portal, PortalHost, Text } from 'patine-ui';

export default function Example() {
  const [open, setOpen] = React.useState(false);
  return (
    <PortalHost>
      <Box padding="lg" border radius="md" style={{ height: 160, overflow: 'hidden' }}>
        <Button onPress={() => setOpen(!open)}>{open ? 'Hide' : 'Show'} banner</Button>
        {open ? (
          <Portal>
            <Box padding="md" background="primary" radius="md" margin="sm" style={{ position: 'absolute', bottom: 0, left: 0, right: 0 }}>
              <Text color="onPrimary">Drawn in the host, outside the clipped box.</Text>
            </Box>
          </Portal>
        ) : null}
      </Box>
    </PortalHost>
  );
}
```

Portals stack in the order they mount. The layer passes touches through to the app except where a portal draws. Dialogs, sheets and menus use a native `Modal` and don't need a host.

## Building your own components

The views the library itself draws with are exported from `patine-ui/core` too, with its defaults built in, so your components
never import a view or `Animated` from `react-native`:

```tsx
import { AnimatedView, Input, Pressable, Scroll, Span, ThemeScope, Touchable, VirtualList } from 'patine-ui/core';
```

- `Touchable` for anything pressed: `role` is required, and the hover tint, press feedback, keyboard focus ring, disabled state
  and 44pt target come with it. `hover={false}` drops the tint, for a photo or a selected row.
- `Scroll` and `VirtualList`: taps work while the keyboard is up, and the web shows no scrollbar track.
- `Input`: the theme's type and colours, with font scaling capped.
- `Span`: a run of text inside a `Text` that takes its look from it (a bold word, a link, a code span), adding no size or colour of its own.
- `Pressable`: a surface that isn't a control, such as a backdrop or a drag area.
- `AnimatedView`, `AnimatedText`, `createAnimatedValue` and `createAnimatedComponent` with the animation hooks, which keep still
  when the OS reduces motion.
- `ThemeScope` passes a component's `theme` or `design` to everything inside it; `useFocusVisible` gives a ring for the
  keyboard only.

## Props

| Component | Prop | Type | Description |
| --- | --- | --- | --- |
| `VisuallyHidden` | `children` | `ReactNode` | What screen readers read. Also takes `Text` props. |
| `Slot` | `children` | `ReactElement` | One element, which gets every other prop. |
| `PortalHost` | `children` | `ReactNode` | The app, or the part portals cover. |
| `Portal` | `children` | `ReactNode` | Drawn on top, inside the nearest host. |
