react-native-platform-components 1.3.0 → 1.5.0

package/PlatformComponents.podspec

@@ -11,7 +11,7 @@ Pod::Spec.new do |s|
   s.authors      = package["author"]
 
   s.platforms    = { :ios => min_ios_version_supported }
-  s.source       = { :git => "https://github.com/JarX-Concepts/react-native-platform-components.git", :tag => "#{s.version}" }
+  s.source       = { :git => "https://github.com/JarX-Concepts/react-native-platform-components.git", :tag => "v#{s.version}" }
 
   s.source_files = ["ios/**/*.{h,m,mm,swift,cpp}", "shared/**/*.{h,m,mm,swift,cpp}"]
   s.private_header_files = ["ios/**/*.h", "shared/**/*.h"]

package/README.md

@@ -5,34 +5,22 @@
 [![CI](https://github.com/JarX-Concepts/react-native-platform-components/actions/workflows/ci.yml/badge.svg)](https://github.com/JarX-Concepts/react-native-platform-components/actions/workflows/ci.yml)
 [![license](https://img.shields.io/npm/l/react-native-platform-components.svg)](./LICENSE)
 
-Native **DatePicker**, **ContextMenu**, **SelectionMenu**, **SegmentedControl** and **LiquidGlass** for React Native. Every component is the real platform widget on both iOS and Android (UIKit and SwiftUI on iOS, Material 3 on Android), behind one typed, declarative API. No JavaScript re-implementations.
-
-<table>
-  <tr>
-    <td align="center"><a href="https://jarx-concepts.github.io/react-native-platform-components/components/datepicker">DatePicker</a></td>
-    <td align="center"><a href="https://jarx-concepts.github.io/react-native-platform-components/components/contextmenu">ContextMenu</a></td>
-    <td align="center"><a href="https://jarx-concepts.github.io/react-native-platform-components/components/selectionmenu">SelectionMenu</a></td>
-    <td align="center"><a href="https://jarx-concepts.github.io/react-native-platform-components/components/segmentedcontrol">SegmentedControl</a></td>
-    <td align="center"><a href="https://jarx-concepts.github.io/react-native-platform-components/components/liquidglass">LiquidGlass</a></td>
-    <td align="center"><a href="https://jarx-concepts.github.io/react-native-platform-components/guides/theming">Theme</a></td>
-  </tr>
-  <tr>
-    <td align="center"><a href="https://jarx-concepts.github.io/react-native-platform-components/components/datepicker"><img src="https://raw.githubusercontent.com/JarX-Concepts/react-native-platform-components/main/assets/ios-datepicker.gif" width="100" alt="DatePicker on iOS" /></a></td>
-    <td align="center"><a href="https://jarx-concepts.github.io/react-native-platform-components/components/contextmenu"><img src="https://raw.githubusercontent.com/JarX-Concepts/react-native-platform-components/main/assets/ios-contextmenu.gif" width="100" alt="ContextMenu on iOS" /></a></td>
-    <td align="center"><a href="https://jarx-concepts.github.io/react-native-platform-components/components/selectionmenu"><img src="https://raw.githubusercontent.com/JarX-Concepts/react-native-platform-components/main/assets/ios-selectionmenu.gif" width="100" alt="SelectionMenu on iOS" /></a></td>
-    <td align="center"><a href="https://jarx-concepts.github.io/react-native-platform-components/components/segmentedcontrol"><img src="https://raw.githubusercontent.com/JarX-Concepts/react-native-platform-components/main/assets/ios-segmentedcontrol.gif" width="100" alt="SegmentedControl on iOS" /></a></td>
-    <td align="center"><a href="https://jarx-concepts.github.io/react-native-platform-components/components/liquidglass"><img src="https://raw.githubusercontent.com/JarX-Concepts/react-native-platform-components/main/assets/ios-liquidglass.gif" width="100" alt="LiquidGlass on iOS" /></a></td>
-    <td align="center"><a href="https://jarx-concepts.github.io/react-native-platform-components/guides/theming"><img src="https://raw.githubusercontent.com/JarX-Concepts/react-native-platform-components/main/assets/ios-theme.gif" width="100" alt="Brand color and dark mode on iOS" /></a></td>
-  </tr>
-  <tr>
-    <td align="center"><a href="https://jarx-concepts.github.io/react-native-platform-components/components/datepicker"><img src="https://raw.githubusercontent.com/JarX-Concepts/react-native-platform-components/main/assets/android-datepicker.gif" width="100" alt="DatePicker on Android" /></a></td>
-    <td align="center"><a href="https://jarx-concepts.github.io/react-native-platform-components/components/contextmenu"><img src="https://raw.githubusercontent.com/JarX-Concepts/react-native-platform-components/main/assets/android-contextmenu.gif" width="100" alt="ContextMenu on Android" /></a></td>
-    <td align="center"><a href="https://jarx-concepts.github.io/react-native-platform-components/components/selectionmenu"><img src="https://raw.githubusercontent.com/JarX-Concepts/react-native-platform-components/main/assets/android-selectionmenu.gif" width="100" alt="SelectionMenu on Android" /></a></td>
-    <td align="center"><a href="https://jarx-concepts.github.io/react-native-platform-components/components/segmentedcontrol"><img src="https://raw.githubusercontent.com/JarX-Concepts/react-native-platform-components/main/assets/android-segmentedcontrol.gif" width="100" alt="SegmentedControl on Android" /></a></td>
-    <td align="center" valign="middle"><sub>iOS 26+ only.<br/>Plain View on Android.</sub></td>
-    <td align="center"><a href="https://jarx-concepts.github.io/react-native-platform-components/guides/theming"><img src="https://raw.githubusercontent.com/JarX-Concepts/react-native-platform-components/main/assets/android-theme.gif" width="100" alt="Brand color and dark mode on Android" /></a></td>
-  </tr>
-</table>
+Native **TextField**, **DatePicker**, **ContextMenu**, **SelectionMenu**, **SegmentedControl**, **TabBar**, **NavigationRail**, **Button**, **ButtonGroup**, **FloatingActionButton**, **FloatingToolbar** and **LiquidGlass** for React Native. Every component is the real platform widget on both iOS and Android (UIKit on iOS, Material 3 Expressive on Android), behind one typed, declarative API. No JavaScript re-implementations.
+
+<p align="center">
+  <a href="https://jarx-concepts.github.io/react-native-platform-components">
+    <picture>
+      <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/JarX-Concepts/react-native-platform-components/main/assets/hero-dark.webp" />
+      <img src="https://raw.githubusercontent.com/JarX-Concepts/react-native-platform-components/main/assets/hero-light.webp" alt="DatePicker, TextField, SegmentedControl, Button, TabBar, NavigationRail, FloatingActionButton, ContextMenu, LiquidGlass, FloatingToolbar and SelectionMenu on iOS and Android, and the dark mode from useNativeTheme" />
+    </picture>
+  </a>
+</p>
+<p align="center"><sub>Every tile is the platform's own widget, captured from the example app. The <a href="https://jarx-concepts.github.io/react-native-platform-components">docs site</a> has full recordings of each component on both platforms; <a href="https://jarx-concepts.github.io/react-native-platform-components/components/liquidglass">LiquidGlass</a> is iOS 26 only.</sub></p>
+
+<p align="center">
+  <a href="https://jarx-concepts.github.io/react-native-platform-components"><img src="https://raw.githubusercontent.com/JarX-Concepts/react-native-platform-components/main/assets/showreel.gif" width="640" alt="Showreel: the native theme changing brand color and switching to dark mode, then DatePicker, TextField, SegmentedControl, TabBar, NavigationRail, Button, FloatingActionButton, ContextMenu, SelectionMenu, FloatingToolbar and LiquidGlass in use, iOS on the left and Android on the right" /></a>
+</p>
+<p align="center"><sub>iOS on the left, Android on the right. Recorded by the Detox suite in <code>example/</code>.</sub></p>
 
 ```sh
 npm install react-native-platform-components
@@ -53,26 +41,24 @@ import { SegmentedControl } from 'react-native-platform-components';
 
 That renders `UISegmentedControl` on iOS and Material 3 segmented buttons (`MaterialButtonToggleGroup`) on Android. The library needs the New Architecture: React Native 0.81+, or Expo SDK 54+ with a dev client (not Expo Go). See [Installation](#installation) and the [documentation site](https://jarx-concepts.github.io/react-native-platform-components).
 
-## Why this library
-
-| You need              | This library                                                                                                                                             | Common alternative                                                                                                                                                                         |
-| --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| Date and time pickers | `UIDatePicker` on iOS; `MaterialDatePicker` / `MaterialTimePicker` or the AppCompat dialogs on Android. Declarative `visible` prop, modal or embedded.   | `@react-native-community/datetimepicker`: platform dialogs on Android; Material 3 pickers are an [open request](https://github.com/react-native-datetimepicker/datetimepicker/issues/790). |
-| Segmented control     | `UISegmentedControl` on iOS; Material 3 segmented buttons on Android. Icons and badges on both.                                                          | `@react-native-segmented-control/segmented-control`: native on iOS, drawn in JavaScript on Android.                                                                                        |
-| Context menu          | `UIContextMenuInteraction` on iOS; `PopupMenu` on Android. Long-press gesture or modal trigger, icons on both.                                           | `zeego`: native on both platforms, through two additional native dependencies (`react-native-ios-context-menu`, `@react-native-menu/menu`).                                                |
-| Selection menu        | System menus on iOS; Material exposed dropdown or `Spinner` on Android. Headless or inline.                                                              | `@react-native-picker/picker`: wheel picker on iOS, dialog or dropdown `Spinner` on Android; no menu-style presentation.                                                                   |
-| Liquid glass          | `UIGlassEffect` on iOS 26+, a fallback `View` elsewhere, `isLiquidGlassSupported` flag.                                                                  | `@callstack/liquid-glass`, `expo-glass-effect`: same idea on iOS; here it ships with the components above.                                                                                 |
-| All of the above      | One package, one API shape (platform-only props under `ios={{ }}` and `android={{ }}`), Fabric + Codegen typed bindings, Expo config plugin, TypeScript. | Four or five packages with different conventions, install steps and upgrade cadences.                                                                                                      |
-
 ## Components
 
-| Component            | iOS                        | Android                                                          | Docs                                                                                                             |
-| -------------------- | -------------------------- | ---------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
-| **DatePicker**       | `UIDatePicker`             | `MaterialDatePicker` / `MaterialTimePicker` or AppCompat dialogs | [DatePicker](https://jarx-concepts.github.io/react-native-platform-components/components/datepicker)             |
-| **ContextMenu**      | `UIContextMenuInteraction` | `PopupMenu`                                                      | [ContextMenu](https://jarx-concepts.github.io/react-native-platform-components/components/contextmenu)           |
-| **SelectionMenu**    | System menus               | Material exposed dropdown or `Spinner`                           | [SelectionMenu](https://jarx-concepts.github.io/react-native-platform-components/components/selectionmenu)       |
-| **SegmentedControl** | `UISegmentedControl`       | `MaterialButtonToggleGroup` (Material 3 segmented buttons)       | [SegmentedControl](https://jarx-concepts.github.io/react-native-platform-components/components/segmentedcontrol) |
-| **LiquidGlass**      | `UIGlassEffect` (iOS 26+)  | Fallback `View`                                                  | [LiquidGlass](https://jarx-concepts.github.io/react-native-platform-components/components/liquidglass)           |
+| Component                                                                                                                    | iOS                                                                                                | Android                                                                                                 | Instead of                                                                                      |
+| ---------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
+| [**TextField**](https://jarx-concepts.github.io/react-native-platform-components/components/textfield)                       | `UITextField` / `UITextView`, with Writing Tools and the iOS 17–18 text traits                     | Material 3 `TextInputLayout`: outlined or filled, floating label, supporting text, counter              | `TextInput` (a bare `EditText` on Android); `react-native-paper` (drawn in JavaScript)          |
+| [**DatePicker**](https://jarx-concepts.github.io/react-native-platform-components/components/datepicker)                     | `UIDatePicker`, modal or embedded                                                                  | `MaterialDatePicker` / `MaterialTimePicker`, or the AppCompat dialogs                                   | `@react-native-community/datetimepicker` (no Material 3 pickers)                                |
+| [**SelectionMenu**](https://jarx-concepts.github.io/react-native-platform-components/components/selectionmenu)               | System menus                                                                                       | Material exposed dropdown or `Spinner`                                                                  | `@react-native-picker/picker` (wheel or dialog, no menu)                                        |
+| [**ContextMenu**](https://jarx-concepts.github.io/react-native-platform-components/components/contextmenu)                   | `UIContextMenuInteraction`                                                                         | `PopupMenu`                                                                                             | `zeego` (through two more native packages)                                                      |
+| [**SegmentedControl**](https://jarx-concepts.github.io/react-native-platform-components/components/segmentedcontrol)         | `UISegmentedControl`                                                                               | Material 3 Expressive connected buttons, or classic segmented buttons                                   | `@react-native-segmented-control/segmented-control` (JavaScript on Android)                     |
+| [**TabBar**](https://jarx-concepts.github.io/react-native-platform-components/components/tabbar)                             | `UITabBar`, the floating Liquid Glass bar on iOS 26                                                | Material 3 navigation bar                                                                               | React Navigation's bottom tabs (JavaScript); `react-native-bottom-tabs` (tied to its navigator) |
+| [**NavigationRail**](https://jarx-concepts.github.io/react-native-platform-components/components/navigationrail)             | A column of tab-style `UIButton`s (iOS has no rail; use TabBar on iPhone)                          | Material 3 Expressive `NavigationRailView`: header, badges, menu gravity, expanded rail                 | React Navigation's drawer or a custom view (JavaScript)                                         |
+| [**Button**](https://jarx-concepts.github.io/react-native-platform-components/components/button)                             | `UIButton` configurations, Liquid Glass variants on iOS 26                                         | Material 3 Expressive `MaterialButton`: five sizes, shape morph                                         | `react-native-paper` (Material 3, not Expressive, in JavaScript)                                |
+| [**ButtonGroup**](https://jarx-concepts.github.io/react-native-platform-components/components/buttongroup)                   | A row of `UIButton`s with a "…" overflow menu; SplitButton: a button and a chevron `UIMenu` button | Material 3 Expressive button groups, single or multiple selection, overflow menu; `MaterialSplitButton` | `react-native-paper` segmented buttons (JavaScript)                                             |
+| [**FloatingActionButton**](https://jarx-concepts.github.io/react-native-platform-components/components/floatingactionbutton) | A round prominent `UIButton`, Liquid Glass on iOS 26 (iOS has no FAB)                              | Material `FloatingActionButton` / `ExtendedFloatingActionButton`: four sizes, shrink on scroll          | `react-native-paper` FAB (drawn in JavaScript)                                                  |
+| [**FloatingToolbar**](https://jarx-concepts.github.io/react-native-platform-components/components/floatingtoolbar)           | Liquid Glass capsule on iOS 26, blur before                                                        | Material 3 Expressive `FloatingToolbarLayout`                                                           | A custom view                                                                                   |
+| [**LiquidGlass**](https://jarx-concepts.github.io/react-native-platform-components/components/liquidglass)                   | `UIGlassEffect` on iOS 26+; `LiquidGlassContainer` merges and morphs it (`UIGlassContainerEffect`) | A fallback `View`                                                                                       | `@callstack/liquid-glass`, `expo-glass-effect`                                                  |
+
+One package and one API shape: platform-only props go under `ios={{ }}` and `android={{ }}`, with Fabric + Codegen typed bindings, an Expo config plugin and TypeScript, instead of four or five packages with their own conventions, install steps and upgrade cadences.
 
 **Have a component request?** If there's a native UI component you'd like to see added, [open an issue](https://github.com/JarX-Concepts/react-native-platform-components/issues/new) describing the component and its native APIs on iOS and Android.
 
@@ -80,6 +66,16 @@ That renders `UISegmentedControl` on iOS and Material 3 segmented buttons (`Mate
 
 ---
 
+## Web
+
+Connect your existing web UI through `PlatformComponentsProvider`: register typed
+web adapters once, then keep the same component imports, props and callbacks in
+shared screens. Override only the controls you need; the others keep the existing
+web fallbacks. iOS and Android continue using their native widgets.
+
+See the [web integration guide](https://jarx-concepts.github.io/react-native-platform-components/guides/web)
+for setup, adapter examples, field refs and current fallback limitations.
+
 ## Installation
 
 ```sh
@@ -128,10 +124,10 @@ The library is built for the New Architecture (Fabric + Codegen) and does not su
 | iOS          | 15.1 (LiquidGlass needs iOS 26)                           |
 | Android      | API 24 (Android 7.0); Material Components 1.14 is bundled |
 
-iOS sets that minimum. LiquidGlass uses iOS 26 APIs, so the library has to be
-built with Xcode 26, and React Native's bundled `fmt` only compiles under Xcode
-26 from 0.81 on. The Android code itself builds against React Native 0.76, and
-CI keeps it that way.
+React Native 0.81 / Expo SDK 54 is the supported minimum. CI builds that
+combination with both Xcode 26 and Xcode 16.4; Liquid Glass is compiled out
+when the iOS 26 SDK is unavailable. Android is also built against React
+Native 0.76 in CI to check native compatibility below the supported minimum.
 
 Full details: [Installation](https://jarx-concepts.github.io/react-native-platform-components/installation).
 
@@ -140,7 +136,7 @@ Full details: [Installation](https://jarx-concepts.github.io/react-native-platfo
 Everything else lives on the documentation site:
 
 - [Quick Start](https://jarx-concepts.github.io/react-native-platform-components/quick-start): copy-paste examples for every component
-- [DatePicker](https://jarx-concepts.github.io/react-native-platform-components/components/datepicker), [ContextMenu](https://jarx-concepts.github.io/react-native-platform-components/components/contextmenu), [SelectionMenu](https://jarx-concepts.github.io/react-native-platform-components/components/selectionmenu), [SegmentedControl](https://jarx-concepts.github.io/react-native-platform-components/components/segmentedcontrol), [LiquidGlass](https://jarx-concepts.github.io/react-native-platform-components/components/liquidglass): props, platform options and behavior
+- [DatePicker](https://jarx-concepts.github.io/react-native-platform-components/components/datepicker), [ContextMenu](https://jarx-concepts.github.io/react-native-platform-components/components/contextmenu), [SelectionMenu](https://jarx-concepts.github.io/react-native-platform-components/components/selectionmenu), [SegmentedControl](https://jarx-concepts.github.io/react-native-platform-components/components/segmentedcontrol), [Button](https://jarx-concepts.github.io/react-native-platform-components/components/button), [ButtonGroup](https://jarx-concepts.github.io/react-native-platform-components/components/buttongroup), [FloatingToolbar](https://jarx-concepts.github.io/react-native-platform-components/components/floatingtoolbar), [LiquidGlass](https://jarx-concepts.github.io/react-native-platform-components/components/liquidglass): props, platform options and behavior
 - [Android Theme Configuration](https://jarx-concepts.github.io/react-native-platform-components/guides/android-theme): Material 3 setup and what happens without it
 - [Icons](https://jarx-concepts.github.io/react-native-platform-components/guides/icons): SF Symbols, drawables and images
 - [Theming and Colors](https://jarx-concepts.github.io/react-native-platform-components/guides/theming): light/dark mode and your brand color from JavaScript (`useNativeTheme`), accepted color formats