@butternutbox/pawprint-native 1.6.2 → 2.0.0

package/.turbo/turbo-build.log

@@ -7,12 +7,12 @@
 CJS Build start
 ESM Build start
 DTS Build start
-CJS dist/index.cjs     575.22 KB
-CJS dist/index.cjs.map 1.13 MB
-CJS ⚡️ Build success in 7644ms
-ESM dist/index.js     543.22 KB
-ESM dist/index.js.map 1.13 MB
-ESM ⚡️ Build success in 7647ms
-DTS ⚡️ Build success in 21210ms
-DTS dist/index.d.cts 114.88 KB
-DTS dist/index.d.ts  114.88 KB
+CJS dist/index.cjs     576.02 KB
+CJS dist/index.cjs.map 1.12 MB
+CJS ⚡️ Build success in 9246ms
+ESM dist/index.js     544.36 KB
+ESM dist/index.js.map 1.12 MB
+ESM ⚡️ Build success in 9245ms
+DTS ⚡️ Build success in 22535ms
+DTS dist/index.d.cts 113.84 KB
+DTS dist/index.d.ts  113.84 KB

package/CHANGELOG.md

@@ -1,5 +1,65 @@
 # @butternutbox/pawprint-native
 
+## 2.0.0
+
+### Major Changes
+
+- 2a71e7a: Rebuild the native select as two components sharing one core, and fix the
+  Drawer's backdrop and keyboard handling.
+
+  `SelectField` is now a combobox: the Pawprint InputField with a dropdown
+  rendered through a Portal and positioned from measured window coordinates,
+  replacing `@rn-primitives/select`. `SelectDrawerField` is new — the same field
+  opening a Drawer with a pinned search input, for long or searchable lists.
+  Both take `options` as data, use plain string ids, and support async search
+  via `onSearchQuery` with debouncing, a minimum query length and
+  stale-response handling.
+
+  `InputField` gains an optional `onPress`, which turns it into a value display
+  that opens something else rather than focusing its input.
+
+  `Drawer.Overlay` now renders and dismisses from anywhere outside the panel.
+  It mounted but painted nothing and took touches only above the panel:
+  `DrawerContent`'s animated wrapper spans the full width while the panel inside
+  is max-width centred, so it swallowed taps in the side gutters, and the
+  overlay's `absoluteFillObject` collapsed to zero size against a container with
+  no box. The wrapper is now `box-none` and the overlay is sized from the window.
+
+  The Drawer now lifts its content above the keyboard instead of padding its
+  scroll content by the keyboard's height, which left a block of empty space
+  inside the list and grew the panel a frame after the keyboard arrived. The
+  panel keeps its place at the bottom of the screen and carries an animated
+  spacer beneath its content, so the content clears the keyboard while the
+  panel's background still reaches the screen edge. On iOS the spacer travels
+  with the keyboard, using the will-show/will-hide event's own duration; Android
+  has no will-events and falls back to the did-events and a default duration.
+
+  `SelectDrawerField` takes an optional `listMaxHeight`. Its option list is
+  otherwise capped at half the window height, to 480pt, so a long list on a
+  tablet stops rather than filling the screen.
+
+  Breaking: `useDrawerKeyboardAvoidance` and `Drawer.Body`'s
+  `ignoreKeyboardAvoidance` prop are removed, along with the `hooks` barrel that
+  only existed to export the former. Both are redundant now the panel handles
+  the keyboard itself; neither has a replacement because neither is needed.
+
+  Breaking: `SelectField.Root`, `.Trigger`, `.Value`, `.Content`, `.Item` and the
+  `useSelectField` hook are removed. Pass `options` and use `value`/`onValueChange`
+  with string ids. The previous compound API threw on mount, so no working consumer
+  code depends on it.
+
+  Consumers must set `keyboardShouldPersistTaps` and `keyboardDismissMode` on their
+  outermost scroll container, and mount a `<PortalHost />` at the app root. See
+  COMPONENT_GUIDELINES.md section 18.
+
+## 1.6.3
+
+### Patch Changes
+
+- Updated dependencies [b6fcfff]
+  - @butternutbox/pawprint-tokens@0.6.0
+  - @butternutbox/pawprint-fonts@2.0.1
+
 ## 1.6.2
 
 ### Patch Changes

package/COMPONENT_GUIDELINES.md

@@ -664,7 +664,63 @@ Native components should mirror the web API where possible:
 - Web uses `styled()` from `@mui/system` — native uses `styled()` from `@emotion/native`
 - Web has `shouldForwardProp` — native relies on prop name prefixing
 
-### **18. Documentation Standards**
+### **18. Components That Render Outside Their Parent**
+
+A dropdown, popover or sheet has to paint over whatever follows it. Two platform
+rules make that harder than it looks, and both have bitten real components.
+
+**Touches are not delivered outside a parent's bounds.** Absolutely positioning a
+dropdown inside the field that owns it will paint (iOS does not clip by default)
+but will not receive taps, because the rows sit outside the parent's box. Render
+through `Portal` from `@rn-primitives/portal` and position from
+`measureInWindow` coordinates instead.
+
+```tsx
+// ❌ BAD: paints, but rows are untappable and later siblings cover them
+;<View>
+  <InputField />
+  {open && <Dropdown style={{ position: "absolute", top: "100%" }} />}
+</View>
+
+// ✅ GOOD: escapes the parent box, the sibling stack and any overflow: hidden
+{
+  open && anchorRect && (
+    <Portal name={portalName}>
+      <Dropdown anchor={anchorRect} />
+    </Portal>
+  )
+}
+```
+
+**Portalled components require a `<PortalHost />` at the app root.** `Tooltip`,
+`SelectField` and anything else using `Portal` render nothing without it. Say so
+in the component's docs.
+
+**Memoise portal children.** `Portal` writes its children into a global store from
+an effect keyed on `children` identity, so unmemoised children rewrite that store
+on every render of the host component.
+
+#### Consumer requirements to document
+
+Both of these live on the _consumer's_ scroll container, not the component, so
+they must be stated in the component's documentation or they will be missed:
+
+| Prop                                  | Why                                                                                                                                |
+| ------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
+| `keyboardShouldPersistTaps="handled"` | Without it the first tap near a focused input is swallowed to dismiss the keyboard, and never reaches the row                      |
+| `keyboardDismissMode="on-drag"`       | Dismisses the keyboard on scroll, which blurs the field and closes the overlay rather than leaving it stranded at a stale position |
+
+`keyboardShouldPersistTaps` must be set on the **outermost** scroll container.
+React Native's responder capture follows the React tree root-downwards, so an
+outer `ScrollView` left at the default `"never"` captures the touch before any
+inner one is consulted — and a `Modal` does not isolate its contents, because the
+React tree is unchanged by it.
+
+In DirectSalesApp, `WizardScrollView` and `app/(auth)/log-in.tsx` set these.
+
+---
+
+### **19. Documentation Standards**
 
 **Add JSDoc comments for all exported components:**