react-native-platform-components 1.3.0 → 1.4.0

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**, **Button**, **ButtonGroup**, **FloatingToolbar** and **LiquidGlass** for React Native. Every component is the real platform widget on both iOS and Android (UIKit and SwiftUI 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, 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, Button, 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
@@ -57,10 +45,12 @@ That renders `UISegmentedControl` on iOS and Material 3 segmented buttons (`Mate
 
 | You need              | This library                                                                                                                                             | Common alternative                                                                                                                                                                         |
 | --------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| Text field            | Material 3 `TextInputLayout` on Android (floating label, outlined or filled, supporting text, error state, icons, counter); `UITextField` on iOS with Writing Tools, inline predictions and smart punctuation. Same `value` / `onChangeText` contract as `TextInput`. | `TextInput`: a bare `EditText` on Android, no Material field; the iOS 17 and 18 text traits are not exposed. `react-native-paper`: Material 3 drawn in JavaScript. |
 | 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.                                                                   |
+| Buttons and toolbars  | Material 3 Expressive `MaterialButton`, button groups and `FloatingToolbarLayout` on Android (five sizes, shape morphing); `UIButton` configurations and a Liquid Glass toolbar on iOS. | `react-native-paper`: Material 3 (not Expressive) drawn in JavaScript on both platforms.                                                                                                   |
 | 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.                                                                                                      |
 
@@ -68,10 +58,14 @@ That renders `UISegmentedControl` on iOS and Material 3 segmented buttons (`Mate
 
 | Component            | iOS                        | Android                                                          | Docs                                                                                                             |
 | -------------------- | -------------------------- | ---------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
+| **TextField**        | `UITextField` / `UITextView` | `TextInputLayout` (Material 3: outlined or filled, label, supporting text, icons, counter) | [TextField](https://jarx-concepts.github.io/react-native-platform-components/components/textfield)             |
 | **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) |
+| **SegmentedControl** | `UISegmentedControl`       | `MaterialButtonToggleGroup` (Material 3 Expressive connected buttons, or classic) | [SegmentedControl](https://jarx-concepts.github.io/react-native-platform-components/components/segmentedcontrol) |
+| **Button**           | `UIButton` (configurations) | `MaterialButton` (Material 3 Expressive: five sizes, round or square, shape morph) | [Button](https://jarx-concepts.github.io/react-native-platform-components/components/button)                     |
+| **ButtonGroup**      | Row of `UIButton`s         | `MaterialButtonGroup` / `MaterialButtonToggleGroup` (Material 3 Expressive) | [ButtonGroup](https://jarx-concepts.github.io/react-native-platform-components/components/buttongroup)           |
+| **FloatingToolbar**  | `UIGlassEffect` capsule (iOS 26+), blur below | `FloatingToolbarLayout` (Material 3 Expressive)               | [FloatingToolbar](https://jarx-concepts.github.io/react-native-platform-components/components/floatingtoolbar)   |
 | **LiquidGlass**      | `UIGlassEffect` (iOS 26+)  | Fallback `View`                                                  | [LiquidGlass](https://jarx-concepts.github.io/react-native-platform-components/components/liquidglass)           |
 
 **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.
@@ -140,7 +134,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

package/android/src/main/java/com/platformcomponents/PCButtonGroupView.kt

@@ -0,0 +1,498 @@
+package com.platformcomponents
+
+import android.content.Context
+import android.text.TextUtils
+import android.view.ContextThemeWrapper
+import android.view.View
+import android.view.ViewGroup.MarginLayoutParams
+import android.widget.FrameLayout
+import com.facebook.react.bridge.WritableNativeMap
+import com.facebook.react.uimanager.PixelUtil
+import com.facebook.react.uimanager.ReactCompoundViewGroup
+import com.facebook.react.uimanager.StateWrapper
+import com.facebook.react.views.scroll.ReactScrollViewHelper
+import com.google.android.material.button.MaterialButton
+import com.google.android.material.button.MaterialButtonGroup
+import com.google.android.material.button.MaterialButtonToggleGroup
+
+/**
+ * A Material 3 Expressive button group: MaterialButtonGroup for plain actions,
+ * MaterialButtonToggleGroup for single / multiple selection. Rebuilt whenever
+ * a prop the widgets read at construction changes.
+ */
+class PCButtonGroupView(context: Context) :
+  FrameLayout(context),
+  ReactScrollViewHelper.HasStateWrapper,
+  ReactCompoundViewGroup {
+
+  data class Item(
+    val label: String,
+    val value: String,
+    val disabled: Boolean,
+    val icon: PCButtonSupport.Icon,
+    val accessibilityLabel: String
+  ) {
+    /** What TalkBack announces for the button. */
+    val spokenLabel: String get() = accessibilityLabel.ifEmpty { label }
+  }
+
+  companion object {
+    private const val TAG = "PCButtonGroup"
+  }
+
+  // --- State Wrapper for Fabric state updates ---
+  override var stateWrapper: StateWrapper? = null
+
+  private var lastReportedWidth: Float = 0f
+  private var lastReportedHeight: Float = 0f
+
+  // --- Props ---
+  var items: List<Item> = emptyList()
+  var variant: PCExpressive.Variant = PCExpressive.Variant.OUTLINED
+  var size: String = "small"
+  var shape: String = "round"
+  var connected: Boolean = false
+  var spacing: Float = -1f // dp; negative = style default
+  var selection: String = "none" // "none" | "single" | "multiple"
+  var selectedValues: List<String> = emptyList()
+  var selectionRequired: Boolean = false
+  var interactivity: String = "enabled" // "enabled" | "disabled"
+  var overflow: String = "none" // "none" | "menu" | "wrap"
+  var expressive: Boolean = true // android.material: "expressive" | "m3"
+
+  // --- Styling (null / empty = Material theme default) ---
+  var containerColor: Int? = null
+  var foregroundColor: Int? = null
+  var rippleColor: Int? = null
+  var strokeColor: Int? = null
+  var labelFontFamily: String = ""
+  var labelFontSize: Float = 0f
+  var labelFontWeight: String = ""
+  var labelFontStyle: String = ""
+
+  // --- Events ---
+  var onPress: ((index: Int, value: String) -> Unit)? = null
+  var onSelectionChange: ((values: List<String>) -> Unit)? = null
+
+  // --- UI ---
+  private var group: MaterialButtonGroup? = null
+  private val buttonIdToIndex: MutableMap<Int, Int> = mutableMapOf()
+  private var suppressCallbacks = false
+  private var selectionEmitPending = false
+
+  /** Bumped on every rebuild so late image loads can't touch stale buttons. */
+  private var rebuildGeneration = 0
+
+  // --- Native theme ---
+  private var builtThemeVersion = PCNativeTheme.version
+  private val nativeThemeListener = PCNativeTheme.Listener {
+    PCThemeSupport.clearColorStateListCaches(this)
+    rebuildUI()
+  }
+
+  init {
+    clipChildren = false
+    clipToPadding = false
+    rebuildUI()
+  }
+
+  // ---- Public apply* (called by manager) ----
+
+  fun applyItems(value: List<Item>) {
+    if (items == value) return
+    items = value
+    rebuildUI()
+  }
+
+  fun applyVariant(value: String?) {
+    val parsed = PCExpressive.parseVariant(value)
+    if (variant == parsed) return
+    variant = parsed
+    rebuildUI()
+  }
+
+  fun applySize(value: String?) {
+    val parsed = PCExpressive.parseSize(value)
+    if (size == parsed) return
+    size = parsed
+    rebuildUI()
+  }
+
+  fun applyShape(value: String?) {
+    val parsed = PCExpressive.parseShape(value)
+    if (shape == parsed) return
+    shape = parsed
+    rebuildUI()
+  }
+
+  fun applyConnected(value: Boolean) {
+    if (connected == value) return
+    connected = value
+    rebuildUI()
+  }
+
+  fun applySpacing(value: Float) {
+    if (spacing == value) return
+    spacing = value
+    rebuildUI()
+  }
+
+  fun applySelection(value: String?) {
+    val parsed = when (value) {
+      "single", "multiple" -> value
+      else -> "none"
+    }
+    if (selection == parsed) return
+    selection = parsed
+    rebuildUI()
+  }
+
+  fun applySelectedValues(value: List<String>) {
+    if (selectedValues == value) return
+    selectedValues = value
+    updateSelection()
+  }
+
+  fun applySelectionRequired(value: Boolean) {
+    if (selectionRequired == value) return
+    selectionRequired = value
+    (group as? MaterialButtonToggleGroup)?.isSelectionRequired = value
+  }
+
+  fun applyInteractivity(value: String?) {
+    val newValue = if (value == "disabled") "disabled" else "enabled"
+    if (interactivity == newValue) return
+    interactivity = newValue
+    updateEnabled()
+  }
+
+  fun applyOverflow(value: String?) {
+    val parsed = when (value) {
+      "menu", "wrap" -> value
+      else -> "none"
+    }
+    if (overflow == parsed) return
+    overflow = parsed
+    rebuildUI()
+  }
+
+  fun applyMaterial(value: String?) {
+    val parsed = PCExpressive.parseExpressive(value)
+    if (expressive == parsed) return
+    expressive = parsed
+    rebuildUI()
+  }
+
+  fun applyColors(container: Int?, foreground: Int?, ripple: Int?, stroke: Int?) {
+    if (containerColor == container && foregroundColor == foreground &&
+      rippleColor == ripple && strokeColor == stroke
+    ) return
+    containerColor = container
+    foregroundColor = foreground
+    rippleColor = ripple
+    strokeColor = stroke
+    rebuildUI()
+  }
+
+  fun applyLabelStyle(fontFamily: String, fontSize: Float, fontWeight: String, fontStyle: String) {
+    if (labelFontFamily == fontFamily && labelFontSize == fontSize &&
+      labelFontWeight == fontWeight && labelFontStyle == fontStyle
+    ) return
+    labelFontFamily = fontFamily
+    labelFontSize = fontSize
+    labelFontWeight = fontWeight
+    labelFontStyle = fontStyle
+    rebuildUI()
+  }
+
+  // The buttons have generated view ids, which React Native's touch handling would
+  // take for React tags and dispatch JS touch events to unrelated views. Claim the
+  // touch for this view instead; the buttons still receive it natively.
+  override fun interceptsTouchEvent(touchX: Float, touchY: Float): Boolean = true
+
+  override fun reactTagForTouch(touchX: Float, touchY: Float): Int = id
+
+  override fun onAttachedToWindow() {
+    super.onAttachedToWindow()
+    PCNativeTheme.addListener(nativeThemeListener)
+    PCNativeTheme.attach(context)
+    if (builtThemeVersion != PCNativeTheme.version) nativeThemeListener.onNativeThemeChanged()
+  }
+
+  override fun onDetachedFromWindow() {
+    PCNativeTheme.removeListener(nativeThemeListener)
+    super.onDetachedFromWindow()
+  }
+
+  // ---- UI Building ----
+
+  private fun rebuildUI() {
+    builtThemeVersion = PCNativeTheme.version
+    removeAllViews()
+    buttonIdToIndex.clear()
+    rebuildGeneration += 1
+    val generation = rebuildGeneration
+
+    // Material widgets need a Material theme; fall back to Material 3 defaults instead of crashing.
+    val base = PCThemeSupport.materialContext(context, "ButtonGroup")
+    val toggle = selection != "none"
+
+    // The group styles: a standard group (spacing, press size morph) or a
+    // connected one (shared outline, small inner corners), Expressive or
+    // classic Material 3.
+    val overlay = when {
+      expressive && toggle && !connected -> R.style.PCExpressiveOverlay_StandardToggleGroup
+      expressive && !toggle && connected -> R.style.PCExpressiveOverlay_ConnectedGroup
+      expressive -> R.style.PCExpressiveOverlay
+      toggle && !connected -> R.style.PCM3Overlay_StandardToggleGroup
+      !toggle && connected -> R.style.PCM3Overlay_ConnectedGroup
+      else -> 0
+    }
+    val groupContext = if (overlay != 0) ContextThemeWrapper(base, overlay) else base
+
+    val g: MaterialButtonGroup =
+      if (toggle) {
+        MaterialButtonToggleGroup(groupContext).apply {
+          isSingleSelection = selection == "single"
+          isSelectionRequired = selectionRequired
+        }
+      } else {
+        MaterialButtonGroup(groupContext)
+      }
+    g.layoutParams = LayoutParams(LayoutParams.WRAP_CONTENT, LayoutParams.WRAP_CONTENT)
+    g.clipChildren = false
+    g.clipToPadding = false
+    if (spacing >= 0) {
+      g.spacing = (spacing * resources.displayMetrics.density).toInt()
+    }
+    g.overflowMode = when (overflow) {
+      "menu" -> MaterialButtonGroup.OVERFLOW_MODE_MENU
+      "wrap" -> MaterialButtonGroup.OVERFLOW_MODE_WRAP
+      else -> MaterialButtonGroup.OVERFLOW_MODE_NONE
+    }
+
+    for ((index, item) in items.withIndex()) {
+      val iconOnly = item.label.isEmpty() && item.icon.isPresent
+
+      val button = PCExpressive.createButton(
+        base, variant, size, shape, iconOnly, 0, expressive
+      ).apply {
+        id = View.generateViewId()
+        text = item.label
+        isAllCaps = false // Preserve original text casing
+        ellipsize = TextUtils.TruncateAt.END
+        maxLines = 1
+        contentDescription = item.spokenLabel.ifEmpty { null }
+        isEnabled = !item.disabled && interactivity == "enabled"
+        if (iconOnly) {
+          // Centre the icon instead of leaving it at the start edge
+          iconGravity = MaterialButton.ICON_GRAVITY_TEXT_START
+        }
+        setOnClickListener { onPress?.invoke(index, item.value) }
+      }
+
+      PCButtonSupport.applyIcon(button, item.icon, { generation == rebuildGeneration }) { requestLayout() }
+      PCButtonSupport.applyFont(button, labelFontFamily, labelFontSize, labelFontWeight, labelFontStyle)
+      PCButtonSupport.applyColors(button, containerColor, foregroundColor, rippleColor, strokeColor, item.icon.tinted)
+
+      buttonIdToIndex[button.id] = index
+      // Buttons size to their content. Connected buttons also share any extra
+      // width when the group is stretched (and any shortfall when it is
+      // squeezed) equally; standard buttons keep their own width.
+      val params = MaterialButtonGroup.LayoutParams(
+        LayoutParams.WRAP_CONTENT,
+        LayoutParams.WRAP_CONTENT,
+        if (connected) 1f else 0f
+      )
+      params.overflowText = item.spokenLabel
+      g.addView(button, params)
+    }
+
+    if (g is MaterialButtonToggleGroup) {
+      g.addOnButtonCheckedListener { _, _, _ ->
+        if (suppressCallbacks) return@addOnButtonCheckedListener
+        // A single-selection switch reports the old button unchecked and the
+        // new one checked in turn; report the final selection once.
+        scheduleSelectionEmit()
+      }
+    }
+
+    addView(g)
+    group = g
+
+    updateSelection()
+    updateEnabled()
+    requestLayout()
+  }
+
+  private fun scheduleSelectionEmit() {
+    if (selectionEmitPending) return
+    selectionEmitPending = true
+    post {
+      selectionEmitPending = false
+      emitSelection()
+    }
+  }
+
+  private fun emitSelection() {
+    val g = group as? MaterialButtonToggleGroup ?: return
+    val values = g.checkedButtonIds
+      .mapNotNull { buttonIdToIndex[it] }
+      .sorted()
+      .map { items[it].value }
+    onSelectionChange?.invoke(values)
+  }
+
+  private fun updateSelection() {
+    val g = group as? MaterialButtonToggleGroup ?: return
+    suppressCallbacks = true
+    for ((id, index) in buttonIdToIndex) {
+      val checked = selectedValues.contains(items[index].value)
+      if (checked) g.check(id) else g.uncheck(id)
+    }
+    suppressCallbacks = false
+  }
+
+  private fun updateEnabled() {
+    val enabled = interactivity == "enabled"
+    alpha = if (enabled) 1f else 0.5f
+
+    val g = group ?: return
+    for (i in 0 until g.childCount) {
+      val button = g.getChildAt(i) as? MaterialButton ?: continue
+      val index = buttonIdToIndex[button.id] ?: continue
+      button.isEnabled = enabled && !items[index].disabled
+    }
+  }
+
+  // ---- Layout ----
+
+  private var manualLayoutPending = false
+
+  /**
+   * React Native's root view ignores requestLayout after the initial pass, so
+   * a native view that changes its own subtree later has to measure and lay
+   * itself out. Coalesced to one pass per frame.
+   */
+  override fun requestLayout() {
+    super.requestLayout()
+    if (!manualLayoutPending) {
+      manualLayoutPending = true
+      post { runManualLayout() }
+    }
+  }
+
+  private fun runManualLayout() {
+    manualLayoutPending = false
+    // Nothing to do until Yoga has placed us; the regular pass covers that.
+    if (width == 0 || height == 0) return
+    measure(
+      MeasureSpec.makeMeasureSpec(width, MeasureSpec.EXACTLY),
+      MeasureSpec.makeMeasureSpec(height, MeasureSpec.EXACTLY)
+    )
+    layout(left, top, right, bottom)
+  }
+
+  // ---- Measurement ----
+
+  private val unspecified = MeasureSpec.makeMeasureSpec(0, MeasureSpec.UNSPECIFIED)
+
+  /**
+   * The group's natural width: every button on one row. MaterialButtonGroup
+   * answers that itself, except in the "wrap" overflow mode, which refuses an
+   * AT_MOST width and lays every button on its own row for UNSPECIFIED; there
+   * the buttons are summed instead.
+   */
+  private fun naturalWidth(child: MaterialButtonGroup): Int {
+    if (overflow != "wrap") {
+      child.measure(unspecified, unspecified)
+      return child.measuredWidth
+    }
+    var total = child.paddingLeft + child.paddingRight
+    var visible = 0
+    for (i in 0 until child.childCount) {
+      val button = child.getChildAt(i)
+      if (button.visibility == View.GONE) continue
+      button.measure(unspecified, unspecified)
+      val params = button.layoutParams as? MarginLayoutParams
+      total += button.measuredWidth + (params?.leftMargin ?: 0) + (params?.rightMargin ?: 0)
+      visible++
+    }
+    if (visible > 1) total += child.spacing * (visible - 1)
+    return total
+  }
+
+  override fun onMeasure(widthMeasureSpec: Int, heightMeasureSpec: Int) {
+    val child = group
+    if (child == null) {
+      setMeasuredDimension(0, 0)
+      return
+    }
+
+    val natural = naturalWidth(child)
+    val width = resolveDimension(widthMeasureSpec, natural)
+    child.measure(MeasureSpec.makeMeasureSpec(minOf(width, natural), MeasureSpec.EXACTLY), unspecified)
+    val height = resolveDimension(heightMeasureSpec, child.measuredHeight)
+
+    child.measure(
+      MeasureSpec.makeMeasureSpec(width, MeasureSpec.EXACTLY),
+      MeasureSpec.makeMeasureSpec(height, MeasureSpec.EXACTLY)
+    )
+    setMeasuredDimension(width, height)
+  }
+
+  private fun resolveDimension(spec: Int, desired: Int): Int {
+    val size = MeasureSpec.getSize(spec)
+    return when (MeasureSpec.getMode(spec)) {
+      // Fabric may give us 0 before the state is applied; keep the natural size then.
+      MeasureSpec.EXACTLY -> if (size > 0) size else desired
+      MeasureSpec.AT_MOST -> minOf(desired, size)
+      else -> desired
+    }
+  }
+
+  override fun onLayout(changed: Boolean, left: Int, top: Int, right: Int, bottom: Int) {
+    super.onLayout(changed, left, top, right, bottom)
+    updateFrameSizeState()
+  }
+
+  /** Reports the intrinsic size to Fabric; called as soon as the state wrapper is available. */
+  fun reportIntrinsicSize() = updateFrameSizeState()
+
+  /**
+   * Update Fabric state with the group's natural size, so the shadow node
+   * wraps its content in Yoga layout.
+   */
+  private fun updateFrameSizeState() {
+    val wrapper = stateWrapper ?: return
+    val child = group ?: return
+
+    // The natural width, and the height at the width we actually have when
+    // that is narrower (an overflow "wrap" group grows taller then).
+    val naturalWidth = naturalWidth(child)
+    val fittedWidth = if (width in 1 until naturalWidth) width else naturalWidth
+    child.measure(MeasureSpec.makeMeasureSpec(fittedWidth, MeasureSpec.EXACTLY), unspecified)
+    val widthDp = PixelUtil.toDIPFromPixel(naturalWidth.toFloat())
+    val heightDp = PixelUtil.toDIPFromPixel(child.measuredHeight.toFloat())
+
+    // Measuring re-wraps the labels; restore the laid-out size so they are
+    // ellipsized to the bounds they are drawn in.
+    if (child.width > 0 && child.height > 0) {
+      child.measure(
+        MeasureSpec.makeMeasureSpec(child.width, MeasureSpec.EXACTLY),
+        MeasureSpec.makeMeasureSpec(child.height, MeasureSpec.EXACTLY)
+      )
+    }
+
+    if (widthDp != lastReportedWidth || heightDp != lastReportedHeight) {
+      lastReportedWidth = widthDp
+      lastReportedHeight = heightDp
+
+      val stateData = WritableNativeMap().apply {
+        putDouble("width", widthDp.toDouble())
+        putDouble("height", heightDp.toDouble())
+      }
+      wrapper.updateState(stateData)
+    }
+  }
+}